# Binary Stars — `binary-stars@1.0.0`

Two stars in orbit, a stream of plasma pulled between them and spiralling into a glowing disc. Loops perfectly.

Two stars locked in orbit about their common centre: a large, cool, boiling orange giant and a small, hot blue companion wearing a spinning accretion disc, with a bright stream of plasma pulled across the gap and spiralling into the disc, against a field of distant stars. The surfaces churn with granulation and spots, the coronas flare, the disc swirls. Choose the star colours (classic, twin, ember or jade), how many orbits a loop holds, how much plasma flows, the disc and the seed.

- Kind: object; status: published; digest sha256:dda611d6d9047247abcf6ed56437302cd57ce4addd03a16c38786c7c4610ebfd
- Role: Object (3D, three.js): a dramatic astronomy backdrop for science, sci-fi and music content.
- Implementation: three; entry `src/binary-stars.js`
- Files: https://aipixelwizard.com/registry/binary-stars/1.0.0/<path> (`LICENSE`, `asset.json`, `demo.js`, `index.html`, `src/binary-stars.js`)
- Manifest JSON: https://aipixelwizard.com/api/v1/visuals/binary-stars/versions/1.0.0
- Runnable demo: https://aipixelwizard.com/registry/binary-stars/1.0.0/index.html (open over http; it imports sibling packages by relative path)
- Dependencies (exact): `three@0.185.1` (source) — Renderer, geometry and shader materials.; `apw-runtime@1.0.0` (demo) — Demo harness.

## Exports
- `createBinaryStars({ palette?, orbits?, stream?, disc?, seed? }) => { group, setProgress(progress), dispose() }` — The two stars, their coronas, the disc, the plasma stream and a star field as a group; render through createBloomPass.
- `createBloomPass(renderer, { width, height, glow?, exposure?, grain? }) => { render(scene, camera, output?), dispose() }` — A small bloom with filmic tone mapping and an anti-aliased, depth-tested scene target.
- `PALETTES: { classic, twin, ember, jade }` — Star colours (sRGB hex).

## Parameters
- `palette` (select one of classic | twin | ember | jade, default "classic") — Stars
- `orbits` (integer 1–3, default 1) — Orbits per loop
- `stream` (number 0–1.6, default 1) — Plasma
- `disc` (number 0–1.5, default 1) — Accretion disc
- `seed` (integer 1–999, default 4) — Seed

## Composition
- Inputs: Time within the loop; the colours, orbits, plasma, disc and seed.
- Outputs: A full frame rendered in 3D through an anti-aliased bloom.
- Coordinates: The centre of mass is the origin; the giant (radius 1.15) orbits at 1.5 and the companion (0.62) at 3.1 in the xz plane; the camera looks down at about 22°.
- Lighting: Self-lit shaders; the bloom gives the coronas and the glare.
- Timing: setProgress(progress) places the stars, the plasma and the swirl; frames render in any order.
- Works with: kinetic-title, number-reveal
- Granulation is three crossed lookups in a baked noise texture with offsets on circles; the disc is a polar swirl with spiral arms turning faster inside; the plasma is 900 points along a cubic Bezier with a helical spread.

## Output and loop
- 1080×1080, 30 fps, 16 s, procedural
- Seamless loop: yes — The pair goes a whole number of times round its orbit per loop, the plasma particles flow a whole number of times along the stream, the surface noise and the disc's spiral turn in whole turns, so the last frame meets the first.
- Verified 2026-10-06 in Chrome 154.0.8037.97 headless on Linux 7.0.0-38-generic (x64), Node 22.14.0 (WebGL 2 via SwiftShader (software)); deterministic: yes; loop check: Frame 0 vs end state (progress 1): mean |Δ| 0.0000, max |Δ| 1 of 255.

## Use it
New project: Create a WebGLRenderer, createBinaryStars() and createBloomPass(renderer, { width, height }); each frame call stars.setProgress(progress) and bloom.render(scene, camera).

Existing project: Copy src/binary-stars.js; add stars.group to your scene and render it through createBloomPass.

Reuse ideas:
- Astronomy explainer: Orange giant and blue dwarf.
- Sci-fi title: Red and amber, fast.
- Calm backdrop: Green and cyan.

## Limitations
- The orbit is a circle with a fixed mass ratio: no eccentricity, no tides, no real Roche lobe.
- The plasma is a particle stream along a curve, not a fluid simulation.

## License
MIT. Copyright (c) 2026 AI Pixel Wizard. Released under the MIT License. See LICENSE in this folder.

Provenance: Adapted from the owner's threejs-sketches/space-cosmic/binary-stars (MIT) and rebuilt for AI Pixel Wizard in October 2026 as an original scene: granulated star shaders, an additive accretion disc, a Bezier plasma stream and whole-turn motion for an exact loop.