GPU Particles

Spawn a world emitter #

// Run inside the board's bootstrap/default export.
const entityId = await Simulation.spawn({
  position: { x: 4, y: 2 },
  renderable: [{
    type: 'particles', layer: 10,
    texture: '/rom/effects/explosion.png',
    frameMode: 'over-lifetime',
    config: {
      main: { seed: 808, lifetime: { min: 1.0, max: 1.9 } },
      emission: { rate: 95 },
      shape: {
        type: 'ellipse', radius: { x: 0.35, y: 0.2 },
        innerRadius: 0.55, direction: 'outward', coneAngle: 0.3
      },
      motion: {
        speed: { min: 3.5, max: 7.5 },
        acceleration: { x: 0, y: 3.8 },
        velocityJitter: { x: 0.5, y: 0.2 },
        drag: [{ time: 0, value: 0 }, { time: 1, value: 2 }],
        noise: {
          seed: 91, strength: { x: 2.0, y: 0.7 }, frequency: 0.8,
          scrollSpeed: 0.65, octaves: 3, positionAmount: { x: 0.04, y: 0.02 }
        }
      },
      appearance: {
        size: [{ time: 0, value: 0.1 }, { time: 0.2, value: 0.38 }, { time: 1, value: 0.02 }],
        colour: [
          { time: 0, colour: { r: 1, g: 0.8, b: 0.15, a: 1 } },
          { time: 0.35, colour: { r: 1, g: 0.18, b: 0.02, a: 0.9 } },
          { time: 1, colour: { r: 0.3, g: 0.02, b: 0, a: 0 } }
        ],
        initialRotation: { min: -Math.PI, max: Math.PI },
        angularVelocity: { min: -6, max: 6 }
      }
    }
  }]
});

Runtime control #

const handle = await Entity.getRenderable(entityId, 0);

await Particles.setParticleTexture(handle, '/rom/effects/smoke.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: 'random'
});
await Particles.stopParticles(handle);   // live particles remain
await Particles.burstParticles(handle, 180); // works while stopped
await Particles.startParticles(handle);
await Particles.clearParticles(handle);  // removes this emitter's live particles

Entity.getRenderable(entityId, renderableIndex): 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>

Reconfigure an emitter #

await Particles.setParticleConfig(handle, {
  channel: 'world',
  main: { seed: 808, lifetime: { min: 0.5, max: 1.0 } },
  emission: { rate: 40 },
  shape: { type: 'box-edge', size: { x: 1.5, y: 0.8 }, direction: 'outward' },
  motion: {
    speed: { min: 2, max: 5 }, acceleration: { x: 0, y: 1 },
    drag: 1.2,
    noise: { strength: 1.5, frequency: 0.6, scrollSpeed: 0.4, octaves: 2 }
  },
  appearance: {
    size: [{ time: 0, value: 0.25 }, { time: 1, value: 0 }],
    colour: [
      { time: 0, colour: [1, 0.4, 0.1, 1] },
      { time: 1, colour: [0.3, 0, 0, 0] }
    ]
  }
});

Movement, camera, and draw order #

• Move emitter entities with normal board-owned systems such as locomotion, waypoints, or physics. Do not update entity positions from the orchestrator.
• The entity and renderable transforms are sampled only for new spawns. Existing particles remain at their detached world positions while the emitter moves.
• World particles use the attached window's camera transform, so camera movement affects them like other world content.
• All world particles share one batch drawn at the scene/UI boundary. They appear above ordinary world draws and below Koya UI. There is no per-particle or per-emitter layer sorting.
• World particles are rendered into the scene target and receive scene post-processing when that path is active.
• The overlay channel is intended for Koya UI emitters. Changing a world entity to channel: 'overlay' uses screen/UI coordinates and bypasses world-camera semantics.

Detached trail with locomotion #

await Entity.setLocomotion(entityId, {
  enabled: true,
  maxSpeed: 3.2,
  adjust: 12,
  turn: 10,
  arriveDistance: 0.35,
  directWaypointThrust: true,
  faceTravelDirection: true
});
await Entity.setWaypointOptions(entityId, {
  enabled: true,
  closeEnoughDistance: 0.18
});
await Entity.setWaypoints(entityId, [
  { x: 6, y: 2 },
  { x: 6, y: 5 },
  { x: 2, y: 5 },
  { x: 2, y: 2 }
]);

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. A texture path is decoded and appended on first use, cached by path, and never repacked. Repeated explosions reuse the same entry with no per-explosion texture upload or Vulkan allocation.
• 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 board/window setup to prewarm the atlas before latency-sensitive effects.
• Texture and frame changes affect new spawns only. Existing detached particles keep stable atlas coordinates until they expire.
• 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.
• The same emitter rendered in two windows has independent GPU state and capacity consumption in each renderer.
• When a pool is full, excess spawns are dropped. Existing particles are not replaced, and normal rendering performs no count readback.
• Expired and cleared slots are recycled on the GPU.
• Destroying an entity stops future emitter submissions but does not kill its detached live particles. For explicit cleanup, call clearParticles and keep the emitter entity alive and enabled until an attached window has processed another main renderer frame 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 GPU vendors is not guaranteed.
• Headless runs may construct particle renderable descriptions but create no Vulkan particle backend. Device/backend recreation discards transient live particles; continuous emitters resume without replaying historical 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 sorting, collision, local-space attachment, runtime atlas eviction/repacking, arbitrary material/layer batches, runtime pool growth, asynchronous compute, or CPU particle telemetry.
• Pool capacity is fixed at renderer initialization and cannot be resized from JavaScript.

Visual test #

Related pages #

• Render Descriptors
• Syncromesh/Simulation
• Syncromesh/Entity
• Syncromesh/Camera