three-nebula

To ensure a simulation is reproducible (same seed + same step count = byte-identical particle state), the simulation must follow a strict determinism contract. This is required for features like reproducible rendering, offline rendering, seek/scrub functionality, and programmatic iteration.

Core Requirements for Determinism:

• Seeded PRNG: Replace all Math.random() calls with an injected, seedable generator (e.g., mulberry32 or xoshiro128**). The PRNG instance must be passed down to every initializer, behaviour, and renderer to avoid shared state between multiple systems.
• Seed Derivation Hierarchy: Randomness must be addressable via a hierarchy so that reordering emitters does not change output. The hierarchy follows:
  • systemSeed (user-set or random at creation)
    • emitterSeed = hash(systemSeed, emitterId)
      • particleSeed = hash(emitterSeed, particleId)
        • childEmitterSeed = hash(systemSeed, childEmitterId, particleId)
• Fixed Timestep: Decouple simulation advancement from requestAnimationFrame (rAF). Use an accumulator pattern to consume simulation steps in fixed increments (e.g., 1/60s) to ensure identical results across different refresh rates (60Hz vs 144Hz).
• Stable IDs: Particles must have monotonic, stable IDs that survive pooling (recycled particles must receive new IDs) to prevent iteration order from affecting state.

In three-nebula, emitters can be organized into a tree structure rather than a flat list. This allows for effects that ride individual particles (e.g., a spark leaving a smoke trail).

Key Concepts:

• Instancing: A child emitter is instantiated once per parent particle at the moment of spawn.
• Origin: The child instance's origin is the parent particle, not the system.
• Lifecycle: A child instance is destroyed when its parent particle dies.
• Orphan Policy: You can control what happens to particles already emitted by a child when the parent dies using the orphanPolicy flag:
  • kill: Child particles die immediately with the parent.
  • detach: Child particles live out their own lifetimes (default behavior).
• Update Order: Updates are topological (depth-first), ensuring parent particles resolve their transforms before children read them.

Implementation Note:

A child instance is treated as a full emitter, not a special particle type. To ensure determinism, child instance seeds are derived from hash(systemSeed, emitterId, parentParticleId).

{
  "version": 2,
  "emitters": [
    {
      "id": "sparks",
      "rate": { /* ... */ },
      "renderer": { "type": "sprite" },
      "children": [
        {
          "id": "spark-smoke",
          "inherit": { "position": "always", "rotation": "none", "scale": "none" },
          "rate": { /* ... */ },
          "renderer": { "type": "sprite" },
          "children": []
        }
      ]
    }
  ]
}

Three-nebula uses a monotonic integer version field within its JSON systems to manage schema evolution. This allows the library to maintain backward compatibility by running a migration chain whenever a system's version is lower than the current supported version.

Key Rules:

• Legacy Support: If the version field is missing, it is treated as version 0. This ensures existing systems created before versioning was implemented remain compatible.
• Future Versions: If the version in the JSON is higher than the version supported by the current library, the parser must throw a clear, actionable error (e.g., "This system was created with a newer version of three-nebula (v5). This build supports up to v3. Update three-nebula.") rather than crashing or silently failing.
• Migration: If the version is lower than the current version, the system automatically runs a sequence of migration functions to bring the JSON up to date.

{
  "version": 2,
  "emitters": [ /* ... */ ]
}

To support headless environments (Web Workers, OffscreenCanvas, or headless Chromium), the library must follow a strict contract that separates simulation from the environment.

Mandatory Constraints:

• No Internal Loops: The library must not own a loop (no internal requestAnimationFrame). The caller must supply the delta time (dt) and control when to advance.
• No Wall-Clock Reads: The simulation path must not use Date.now(), performance.now(), or new Date().
• Separation of Concerns: Simulation and rendering must be separable. A caller must be able to step the simulation $N$ times without rendering, or render the same state multiple times.
• No DOM Access: The simulation path must not access document, window, or HTMLImageElement. Textures must be provided as decoded data via a resolver.
• Canvas Agnostic: Any component requiring a canvas must support OffscreenCanvas in addition to HTMLCanvasElement.