Interface OrbitalSystemSceneProps

Notified whenever a body is selected (map click or dropdown) — lets a caller cross-reference the body id against its own data without this component needing to know anything about that data.

See ExternalFocusRequest. Null/undefined is a no-op.

See RoutePreview. Null draws nothing.

Light the scene from the system's actual star position (see StarLight.tsx) instead of the default fixed-direction light — every other body gets real day/night shading, the hemisphere facing the star lit and the far side dark, rather than a constant, position- independent light. Off by default: the fixed light is a simpler, always-available legibility aid that doesn't depend on the system having a real star body at all (a purely fixedPosition-based fictional system might not). If true and the system genuinely has no type: 'star' body, this safely renders no star-based light (falls back to just the ambient fill light) rather than guessing.

Natural bodies (planets, moons, dwarf planets — placeholder or real texture — and asteroids), ring discs and atmospheres are then shaded from the star's TRUE direction, with analytic eclipse shadows (a moon's on its planet, a planet's on its moons) and ring shadows (a planet's on its rings and its rings' on it) — see starLighting. Small bodies drawn instanced get the same day/night shading, without eclipses. A fly-to then settles on the body's day side, the star 30–50° off the camera's direction (see camera.ts's computeEndDirection). Real glTF models and the built placeholder shapes (stations, installations) are lit by a point light at the star.

Tunes lightFromStar (ignored without it). Every field is optional:

• nightSideBrightness (default 0.04) — how much of a body's full-sun brightness its night side keeps: a legibility floor, since a real airless night side is black. 0 is physically honest.
• ringShadows (default true) — a planet's shadow on its rings and the rings' on the planet (Saturn, Uranus).
• eclipseShadows (default true) — moons' shadows on their planets and planets' on their moons, umbra and penumbra. Changing it at runtime is a uniform write, not a rebuild.

Draws real ion and dust tails on every comet that orbits the system's star (see comets.ts for the physics): the ion tail straight out from the star, the dust tail curving behind the orbit, both growing as the comet nears the star and gone beyond ~5 AU. Default true — the alternative is a fixed streak that doesn't point anywhere in particular, which is what a comet without such an orbit still gets.

The simulated date to start at, instead of now — a Date or ms since the epoch (e.g. Halley's 1986 perihelion, or an eclipse). Only read on mount, like initialPlaying.

Renders a dev-only overlay panel (top-left) with live FPS, draw calls, triangle/GPU-memory counts, JS heap usage where the browser exposes it, and object counts (total vs. currently-visible/culled bodies, belt points, the selected/hovered body's current LOD tier) — see devStats.ts and PerfStats.tsx. Off by default: none of this is meaningful to an end user, only to someone debugging the scene's own performance.

Whether simulated time is playing on first load — defaults to false (paused). Time advancing by default used to make a fresh load's very first fly-to (or any fly-to a consumer triggers before the user has touched Play) susceptible to whatever's moving fastest in the loaded system (the ISS, say) — genuinely useful once the user has decided they want time playing, surprising as a default nobody asked for. Exposed here (rather than only user-toggleable via the Play/Pause button) so a consumer embedding this component gets the same choice — e.g. an app that only ever wants a static, paused viewer, or one that wants to start playing immediately for a demo.

Simulated days advanced per real second once playing — see timeScale.ts for the real-time-to-MAX_HOURS_PER_SECOND range this can usefully span (clamped via clampPlaybackSpeed, so an out-of-range value passed here is corrected rather than trusted directly — the Speed slider's own drag handler already stays in range by construction, but this prop comes from the consumer, e.g. a deep link or saved session, and has no such guarantee). Defaults to DEFAULT_DAYS_PER_SECOND. Only sets the STARTING speed; the user's own Speed slider still changes it from there like normal.

Fired for every recordable user interaction (selection, playback controls, camera zoom) — see actionLog.ts's ActionLogEntry. Lets a consumer build an exact reproduction log for bug reports: not just WHAT was done, but WHEN (relative to the start) and the simulated date at that moment (several real bugs in this camera code only reproduced at specific orbital alignments). The library only records and exposes these — it deliberately does NOT implement its own replay; reproducing a log means driving the same UI a real user would, which belongs in a browser-automation script, not this component.

How fly-tos are paced. A flight's duration is proportional to how much it really travels — zooming out far enough to see both ends, panning, zooming back in (van Wijk & Nuij's smooth zoom-and-pan path) — at speed (a multiplier on the default pace; 2 = twice as fast), clamped to [minMs, maxMs]. Defaults: { speed: 1, minMs: 1200, maxMs: 5000 }. Read when a flight starts, so a change applies to the next one.

What selecting a body flies to. 'body' (the default) frames the body itself — its diameter fills about 40% of the view's height, so a real surface texture is actually visible, with rings kept in frame. 'system' frames the body together with its whole local moon/station system (the behaviour before this prop existed). Either way, clicking the already-selected body again toggles to the other framing and back.