UI/Renderable: Particles

Create an emitter #

const emitter = await UI.createElement(win, {
  renderable: {
    type: 'particles',
    texture: '/rom/effects/sparks.png',
    frameMode: 'random',
    position: { x: 200, y: 240 },
    config: {
      running: true,
      main: { seed: 1001, lifetime: { min: 1.0, max: 1.8 } },
      emission: { rate: 90 },
      shape: {
        type: 'ellipse-edge', radius: { x: 12, y: 5 },
        arc: { start: 0, angle: Math.PI },
        direction: 'outward', coneAngle: 0.25
      },
      motion: {
        speed: { min: 75, max: 135 },
        acceleration: { x: 0, y: 105 },
        velocityJitter: { x: 15, y: 8 },
        drag: { curve: [{ time: 0, value: 0 }, { time: 1, value: 2.5 }] },
        noise: {
          strength: { x: 28, y: 10 }, frequency: 0.025,
          scrollSpeed: 0.8, octaves: 3,
          strengthOverLifetime: [{ time: 0, value: 0.2 }, { time: 0.4, value: 1 }, { time: 1, value: 0 }]
        }
      },
      appearance: {
        size: {
          minCurve: [{ time: 0, value: 7 }, { time: 0.25, value: 13 }, { time: 1, value: 1 }],
          maxCurve: [{ time: 0, value: 10 }, { time: 0.25, value: 17 }, { time: 1, value: 3 }]
        },
        colour: [
          { time: 0, colour: '#fff0a0ff' },
          { time: 0.35, colour: '#ff5c12ee' },
          { time: 1, colour: '#4d080000' }
        ],
        initialRotation: { min: -Math.PI, max: Math.PI },
        angularVelocity: { min: -5, max: 5 }
      }
    }
  }
});
await UI.attachRoot(win, emitter);

Runtime control #

const handle = await UI.getRenderable(win, emitter);

await Particles.setParticleTexture(handle, '/rom/effects/explosion.png');
await Particles.setParticleFrames(handle, {
  frames: [
    { min: { x: 0, y: 0 }, max: { x: 64, y: 64 } },
    { min: { x: 64, y: 0 }, max: { x: 128, y: 64 } }
  ],
  frameMode: 'over-lifetime'
});
await Particles.burstParticles(handle, 200);
await Particles.stopParticles(handle);  // live particles finish naturally
await Particles.startParticles(handle);
await Particles.clearParticles(handle); // immediately retires this emitter's live particles

UI.getRenderable(windowId, elementId): Promise<number>

Particles.setParticleConfig(handle, config): Promise<boolean>

Particles.setParticleTexture(handle, path): Promise<boolean>

Particles.setParticleFrames(handle, { frames, frameMode, frame }): Promise<boolean>

Particles.clearTexture(handle): Promise<boolean>

Particles.startParticles(handle): Promise<boolean>

Particles.stopParticles(handle): Promise<boolean>

Particles.burstParticles(handle, count): Promise<boolean>

Particles.clearParticles(handle): Promise<boolean>

Channels and composition #

• UI.createElement initially creates Koya emitters in overlay, regardless of a creation-time channel field.
• Overlay particles are deliberately outside element clipping, masks, sibling order, subtree compositing, and composite opacity. They can escape a clipped parent and draw above other UI.
• The element supplies only the emitter transform. A spawned particle is detached from the element, so moving or animating the element produces a trail instead of dragging existing particles.
• Rendering an element into an offscreen texture does not simulate or draw its particles. The emitter is submitted once to the next main window frame.

Lifecycle, capacity, and determinism #

• Each window/renderer owns an independent shared pool. The default capacity is 65,536 live particles across both channels and all emitters in that window.
• Each renderer also owns one fixed 1024×1024×8 RGBA atlas. Texture paths are decoded and appended on first use, cached by path, and never repacked, so repeated explosions do not upload or allocate the same texture again.
• Atlas entries are immutable for the renderer lifetime. If generated /ram image bytes change, publish them under a new asset path before calling setParticleTexture; reusing the same path deliberately reuses the existing atlas entry.
• First use decodes and uploads the image synchronously. Configure commonly used explosion and smoke textures during UI/window setup to prewarm the atlas before latency-sensitive effects.
• Texture and frame changes affect new spawns only. Live particles keep stable atlas coordinates, preventing an animation or explosion from changing underneath them.
• A source texture must fit within one 1022×1022 atlas page after padding. If loading, decoding, atlas space, or the 4096-frame table fails, future particles use the white fallback and rendering continues.
• When the pool is full, excess spawns are dropped. Existing particles are not replaced, and normal rendering performs no particle-count readback.
• Expired and explicitly cleared slots are recycled on the GPU.
• Destroying the element stops future submissions but does not kill particles already detached from it. For explicit cleanup, call clearParticles and keep the enabled emitter attached until a main renderer frame has processed the request before destroying it.
• The seed and logical spawn sequence determine sampled attributes independently of GPU slot allocation. Matching emitters given the same spawn timing and commands produce the same attribute stream; bit-identical floating-point motion across different GPU vendors is not guaranteed.
• Device/backend recreation discards transient live particles. A still-running emitter resumes continuous emission without replaying old bursts.

Current limitations #

• Textured particles use one image, optional sprite-sheet frames, colour tinting, and premultiplied-alpha blending. There are no per-particle material or sampler overrides.
• There is no depth or distance sorting, collision, local-space attachment, per-element clipping, runtime atlas eviction/repacking, arbitrary material batching, runtime pool growth, or CPU particle telemetry.
• The shared pool is fixed at renderer initialization; JavaScript cannot resize it at runtime.

Visual test #

Related pages #

• UI/Renderable: Shared properties
• UI/Animation
• Rendering, FPS & Frame Scheduling
• Helix/UserInterface