Flash

A short-lived entity that pops for a moment, then removes itself.

What it does

Flash is data-only: it holds a single lifetime countdown in seconds. Each frame FlashSystem subtracts dt from lifetime, and the instant it hits zero the system removes the whole host entity from the world. There is no fade, no animation, and no event — the effect is "brief, bright, gone." The system requires both Flash and MeshPrimitive on the entity, so a flash always has geometry to render, and bare Flash: {} marker entities (used elsewhere just to make SceneLoader instantiate the system) are never matched and destroyed. You spawn a flash from another system — muzzle fire, an impact burst, a pickup pop — by creating an entity with an emissive MeshPrimitive plus a Flash set to a small lifetime, and let the timer clean it up.

Use it in a scene

A scene is just data — a list of entities, each with its components. At startup the SceneLoader turns this JSON into a live world; edit the file and reload to rebuild it.

Build it from scratch with the bjs CLI:

1Scaffold a project
```
npm create @babylonjsmarket/arcade@latest my-game
```
World, renderer, and dev server — ready to run.
2Install dependencies
```
cd my-game && npm install
```
3Add Flash
```
bjs download Flash
```
Copies its source into src/ so the scene resolves.
First time? Run bjs login once.
4Paste the scene into src/scenes/arcade-room.ts and run
```
npm run dev
```
SceneLoader builds the world from the JSON; reload to rebuild.

JSON

{
  "MuzzleFlash": {
    "components": {
      "MeshPrimitive": {
        "primitive": "sphere",
        "diameter": 0.7,
        "segments": 8,
        "position": [0, 1, 0],
        "material": { "diffuseColor": [1, 1, 0.6], "emissiveColor": [1, 1, 0.6] }
      },
      "Flash": { "lifetime": 0.08 }
    }
  }
}

Props

lifetime (number, default 0.08) — seconds before the host entity is removed. The system decrements it by dt each frame and removes the entity when it reaches 0.

Events

None. Flash is event-silent — it neither emits nor listens; it only ticks its own timer and removes the entity.

Dependencies

None declared in dependencies, but FlashSystem requires a MeshPrimitive component on the same entity (it queries [FlashComponent, MeshPrimitiveComponent]). Without a MeshPrimitive sibling the entity is never matched, so it neither renders nor gets cleaned up.

Notes

The countdown is frame-rate independent — it subtracts real elapsed dt, so lifetime: 0.08 is roughly 80 ms regardless of frame rate.
Removal is all-or-nothing: when the timer expires the entire entity is removed, including its MeshPrimitive, so the visual disappears with it. Flash is not a "hide" — don't attach it to something you want to keep.
Because a flash is usually spawned in code (e.g. world.createEntity() then add a MeshPrimitive and a FlashComponent), the scene-JSON form above is mainly for demoing the effect; in a real game you emit them dynamically at impact points.
serialize() round-trips just { lifetime }, so a flash in flight survives a save/load with its remaining time intact.

Flash.core.ts

Flash — pure core (data only).

Short-lived visual entity. Spawned by other systems (e.g. TwinStickShooter for muzzle flash, an impact handler for hit bursts). Carries a lifetime countdown; the system removes the entity when the timer expires. No animation by default — the FX is "brief, bright, gone." Pair it with MeshPrimitive on the same entity for visuals.

Typical use: const e = world.createEntity() e.add(new MeshPrimitiveComponent({ primitive: 'sphere', diameter: 0.7, segments: 8, position: [...spawnPos], material: { diffuseColor: [1,1,0.6], emissiveColor: [1,1,0.6] }, })) e.add(new FlashComponent({ lifetime: 0.08 }))

Flash.core.ts

import { Component } from '@babylonjsmarket/ecs'

export interface FlashInput {
  /** Seconds before the host entity is removed. */
  lifetime?: number
}

export class FlashComponent extends Component {
  lifetime: number

  constructor(data: FlashInput = {}) {
    super()
    this.lifetime = data.lifetime ?? 0.08
  }

  serialize(): FlashInput {
    return { lifetime: this.lifetime }
  }
}

Flash.ts

Flash.ts — renderer-agnostic System.

The core (Flash.core.ts) owns the FlashComponent data class. This System ticks the lifetime down each frame and removes the host entity when the timer expires.

Flash.ts

import { System } from '@babylonjsmarket/ecs'
import type { EventBus } from '@babylonjsmarket/ecs'
import { MeshPrimitiveComponent } from '../MeshPrimitive/MeshPrimitive'
import { FlashComponent, type FlashInput } from './Flash.core'

export class FlashSystem extends System {
  // Require a mesh: a flash is a visual effect, so a real flash always has a
  // MeshPrimitive. This also stops the system from matching — and then
  // destroying — a bare `Flash: {}` marker entity used only to make
  // SceneLoader instantiate this system; such markers must never be consumed
  // as if they were real flashes.
  protected query = { required: [FlashComponent, MeshPrimitiveComponent] }

  constructor(eventBus: EventBus) {
    super(eventBus)
  }

  protected onUpdate(dt: number): void {
    const w = this.world
    if (!w) return
    const toRemove: string[] = []
    for (const entity of this.entities) {
      const f = entity.get(FlashComponent)
      if (!f) continue
      f.lifetime -= dt
      if (f.lifetime <= 0) toRemove.push(entity.id)
    }
    for (const id of toRemove) w.removeEntity(id)
  }
}

export { FlashComponent, type FlashInput } from './Flash.core'

Flash.contract.test.ts

11 ✓

ArcadeECS contract: Flash

Component() with no args constructs and applies defaults
Component merges sample input on top of defaults
Component.serialize() round-trips into a constructor input
System constructor signature is exactly (eventBus)
System declares a non-empty query.required
world.addSystem + initialize + update runs clean with no entity
adding the Component attaches the entity to the System
world.update(dt) does not throw with the entity attached
Adapter handles: create/dispose balance across entity lifecycle
EventBus has no lingering listeners after world.destroy()
Declared event names follow the "{domain}.{action}" convention

Last run 2026-07-17

Flash.contract.test.ts

import { runMechanicContract } from '@babylonjsmarket/ecs/testing';
import { FlashComponent, FlashSystem } from './Flash';
import { MeshPrimitiveComponent } from '../MeshPrimitive/MeshPrimitive.core';

runMechanicContract({
  name: 'Flash',
  componentClass: FlashComponent,
  systemClass: FlashSystem,
  sampleInput: { lifetime: 0.1 },
  // A flash is a visual effect, so the system requires a MeshPrimitive sibling
  // (this also keeps it from consuming bare `Flash: {}` marker entities).
  companions: [MeshPrimitiveComponent],
  // Event-silent: Flash just ticks its lifetime down and removes the host
  // entity. No inputs, no outputs.
});

Flash.core.test.ts

3 ✓

FlashComponent

applies defaults
merges input on top of defaults
serialize round-trips

Last run 2026-07-17

Flash.core.test.ts

import { describe, it, expect } from 'vitest';
import { FlashComponent } from './Flash.core';

describe('FlashComponent', () => {
  it('applies defaults', () => {
    const c = new FlashComponent();
    expect(c.lifetime).toBe(0.08);
  });

  it('merges input on top of defaults', () => {
    const c = new FlashComponent({ lifetime: 0.25 });
    expect(c.lifetime).toBe(0.25);
  });

  it('serialize round-trips', () => {
    const a = new FlashComponent({ lifetime: 0.12 });
    const b = new FlashComponent(a.serialize());
    expect(b.lifetime).toBe(a.lifetime);
    expect(b.serialize()).toEqual(a.serialize());
  });
});

Flash.test.ts

2 ✓

FlashSystem

removes the entity once its lifetime expires
keeps a flash with remaining lifetime

Last run 2026-07-17

Flash.test.ts

import { describe, it, expect, beforeEach } from 'vitest';
import { EventBus, World, MockRendererAdapter } from '@babylonjsmarket/ecs';
import { FlashComponent, FlashSystem } from './Flash';
import { MeshPrimitiveComponent } from '../MeshPrimitive/MeshPrimitive.core';

describe('FlashSystem', () => {
  let eventBus: EventBus;
  let world: World;
  let renderer: MockRendererAdapter;

  beforeEach(() => {
    eventBus = new EventBus();
    renderer = new MockRendererAdapter();
    world = new World({ eventBus, renderer });
    world.addSystem(new FlashSystem(eventBus));
    world.initialize();
  });

  function makeFlash(lifetime: number) {
    const e = world.createEntity();
    e.add(new MeshPrimitiveComponent({ primitive: 'sphere', position: [0, 0, 0] }));
    e.add(new FlashComponent({ lifetime }));
    return e;
  }

  it('removes the entity once its lifetime expires', () => {
    const e = makeFlash(0.05);
    // Not enough elapsed time yet.
    world.update(0.02);
    expect(world.getEntity(e.id)).toBeDefined();

    // Tick past the lifetime → removed.
    world.update(0.05);
    expect(world.getEntity(e.id)).toBeUndefined();
  });

  it('keeps a flash with remaining lifetime', () => {
    const e = makeFlash(1.0);
    world.update(0.1);
    const f = e.get(FlashComponent)!;
    expect(f.lifetime).toBeCloseTo(0.9, 5);
    expect(world.getEntity(e.id)).toBeDefined();
  });
});

Babylon.js Market

Flash

Flash

What it does

Use it in a scene

Props

Events

Dependencies

Notes

Flash.core.ts

Flash.ts

Flash.contract.test.ts

Flash.contract.test.ts

Flash.core.test.ts

Flash.core.test.ts

Flash.test.ts

Flash.test.ts

Was this page helpful?