SpotLight.defs.ts

SpotLight — definitions.

Holds the SpotLightComponent class and the shapes its data and events travel in. No System lives here, which is the point: another component can name SpotLight in a query, or type an event it listens for, without pulling SpotLight's behaviour into its own bundle. Import from here, not from SpotLight.ts.

SpotLight.defs.ts

import { Component } from '@babylonjsmarket/ecs';
import type { Color, SpotLightSpec, Vec3 } from '@babylonjsmarket/ecs/renderer-types';
export { SpotLightEvents } from './SpotLight.events';

export interface SpotLightInput {
  /** Where the cone starts. Default [0, 3, 0] — a ceiling can-light. */
  position?: Vec3;
  /** Which way it points (need not be unit). Default [0, -1, 0], straight down. */
  direction?: Vec3;
  /**
   * Full cone aperture in radians — the whole cone, not the half-angle. Default
   * π/3 (60°): a tidy puddle on one machine. Push it toward π for a wash that
   * lights the wall around a sign rather than a beam.
   */
  angle?: number;
  /**
   * How hard the edge of the pool is. Higher = a crisp circle, lower = a soft
   * fade from centre to rim. Default 2.
   */
  exponent?: number;
  intensity?: number;
  diffuse?: Color;
  specular?: Color;
  /**
   * Distance at which the light stops contributing. Default 10 — bounded on
   * purpose: a spot is a LOCAL accent, and an unbounded one would leak down
   * a whole corridor while still counting against every material's light cap.
   */
  range?: number;
}

function cloneVec3(v: Vec3): Vec3 {
  return [v[0], v[1], v[2]];
}

export class SpotLightComponent extends Component {
  // Declared, not read off the class name: a minified build renames classes,
  // and the scene file still has to find this class by name.
  static componentType = 'SpotLight';

  position: Vec3;
  direction: Vec3;
  angle: number;
  exponent: number;
  intensity: number;
  diffuse: Color;
  specular: Color;
  range: number;

  constructor(data: SpotLightInput = {}) {
    super();
    this.position = data.position ? cloneVec3(data.position) : [0, 3, 0];
    this.direction = data.direction ? cloneVec3(data.direction) : [0, -1, 0];
    this.angle = data.angle ?? Math.PI / 3;
    this.exponent = data.exponent ?? 2;
    this.intensity = data.intensity ?? 1;
    this.diffuse = data.diffuse ? cloneVec3(data.diffuse) : [1, 1, 1];
    // A spot in a stylized room is a coloured pool on the floor, not a glint
    // on the cabinet's chrome, so specular defaults off — matching how the
    // other light components in this package default it.
    this.specular = data.specular ? cloneVec3(data.specular) : [0, 0, 0];
    this.range = data.range ?? 10;
  }

  toSpec(): SpotLightSpec {
    return {
      position: cloneVec3(this.position),
      direction: cloneVec3(this.direction),
      angle: this.angle,
      exponent: this.exponent,
      intensity: this.intensity,
      diffuse: cloneVec3(this.diffuse),
      specular: cloneVec3(this.specular),
      range: this.range,
    };
  }

  serialize(): SpotLightInput {
    return {
      position: cloneVec3(this.position),
      direction: cloneVec3(this.direction),
      angle: this.angle,
      exponent: this.exponent,
      intensity: this.intensity,
      diffuse: cloneVec3(this.diffuse),
      specular: cloneVec3(this.specular),
      range: this.range,
    };
  }
}

SpotLight.events.ts

SpotLight — event names.

The EventBus contract for SpotLight: what it emits and what it listens for. A listener imports these names from here, never from SpotLight.ts, so it can hear SpotLight without carrying SpotLight's System. bjs download hands this file out free with any component that imports it, and it does not make SpotLight a dependency to buy.

SpotLight.events.ts

// SpotLightEvents — from SpotLight
export const SpotLightEvents = {
  CREATED: 'spotlight.created',
  INTENSITY_CHANGED: 'spotlight.intensity.changed',
  MOVED: 'spotlight.moved',
} as const;

SpotLight.ts

SpotLight.ts — renderer-agnostic System for aimed cones of light. Pure data lives in SpotLight.defs.ts. This System drives world.renderer.

SpotLight.ts

import { SpotLightEvents } from './SpotLight.events';
import { System } from '@babylonjsmarket/ecs';
import type { EventBus } from '@babylonjsmarket/ecs';
import type { Entity } from '@babylonjsmarket/ecs';
import type { LightHandle, Vec3 } from '@babylonjsmarket/ecs/renderer-types';
import { SpotLightComponent, type SpotLightInput } from './SpotLight.defs';

export { SpotLightComponent, type SpotLightInput };

interface SpotLightRuntime {
  handle?: LightHandle;
  initialized: boolean;
}

/** True when any component of `a` and `b` differ by more than a thousandth. */
function moved(a: Vec3 | undefined, b: Vec3): boolean {
  return (
    !a ||
    Math.abs(a[0] - b[0]) > 0.001 ||
    Math.abs(a[1] - b[1]) > 0.001 ||
    Math.abs(a[2] - b[2]) > 0.001
  );
}

export class SpotLightSystem extends System {
  protected query = { required: [SpotLightComponent] };
  private lastIntensities = new WeakMap<SpotLightComponent, number>();
  private lastPositions = new WeakMap<SpotLightComponent, Vec3>();
  private lastDirections = new WeakMap<SpotLightComponent, Vec3>();
  private lastColors = new WeakMap<SpotLightComponent, Vec3>();
  private runtime = new WeakMap<SpotLightComponent, SpotLightRuntime>();

  private getRuntime(comp: SpotLightComponent): SpotLightRuntime {
    let rt = this.runtime.get(comp);
    if (!rt) {
      rt = { initialized: false };
      this.runtime.set(comp, rt);
    }
    return rt;
  }

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

  protected onInitialize(): void {
    for (const entity of this.entities) {
      this.ensureLight(entity);
    }
  }

  protected onEntityAdded(entity: Entity): void {
    this.ensureLight(entity);
  }

  protected onEntityRemoved(entity: Entity): void {
    const comp = entity.get(SpotLightComponent);
    if (!comp) return;
    const rt = this.getRuntime(comp);
    if (rt.handle) {
      this.world?.renderer?.disposeLight(rt.handle);
      rt.handle = undefined;
      rt.initialized = false;
    }
  }

  protected onUpdate(_deltaTime: number): void {
    // Diff intensity, position, aim and colour each frame so an outside
    // mutation (a control panel, a sweeping searchlight, a sign that cycles
    // hue) reaches the adapter without anyone having to call us.
    for (const entity of this.entities) {
      const comp = entity.get(SpotLightComponent);
      if (!comp) continue;
      const rt = this.getRuntime(comp);
      if (!rt.initialized || !rt.handle) continue;
      const r = this.world?.renderer;
      if (!r) continue;

      const prev = this.lastIntensities.get(comp);
      if (prev === undefined || Math.abs(prev - comp.intensity) > 0.001) {
        r.updateLightIntensity(rt.handle, comp.intensity);
        this.lastIntensities.set(comp, comp.intensity);
        if (prev !== undefined) {
          this.eventBus.emit(SpotLightEvents.INTENSITY_CHANGED, {
            entityId: entity.id,
            intensity: comp.intensity,
          });
        }
      }

      const p = comp.position;
      const prevPos = this.lastPositions.get(comp);
      if (moved(prevPos, p)) {
        r.setLightPosition(rt.handle, p[0], p[1], p[2]);
        this.lastPositions.set(comp, [p[0], p[1], p[2]]);
        if (prevPos) {
          this.eventBus.emit(SpotLightEvents.MOVED, {
            entityId: entity.id,
            position: [p[0], p[1], p[2]] as Vec3,
          });
        }
      }

      const d = comp.direction;
      if (moved(this.lastDirections.get(comp), d)) {
        r.setLightDirection(rt.handle, d[0], d[1], d[2]);
        this.lastDirections.set(comp, [d[0], d[1], d[2]]);
      }

      const c = comp.diffuse;
      if (moved(this.lastColors.get(comp), c)) {
        r.setLightColor(rt.handle, c[0], c[1], c[2]);
        this.lastColors.set(comp, [c[0], c[1], c[2]]);
      }
    }
  }

  private ensureLight(entity: Entity): void {
    const comp = entity.get(SpotLightComponent);
    if (!comp) return;
    const rt = this.getRuntime(comp);
    if (rt.initialized) return;
    const r = this.world?.renderer;
    if (!r) return;

    rt.handle = r.createSpotLight(entity.id, comp.toSpec());
    rt.initialized = true;
    // Seed every diff from the spec we just sent, so the first frame stays quiet.
    this.lastIntensities.set(comp, comp.intensity);
    this.lastPositions.set(comp, [comp.position[0], comp.position[1], comp.position[2]]);
    this.lastDirections.set(comp, [comp.direction[0], comp.direction[1], comp.direction[2]]);
    this.lastColors.set(comp, [comp.diffuse[0], comp.diffuse[1], comp.diffuse[2]]);

    this.eventBus.emit(SpotLightEvents.CREATED, {
      entityId: entity.id,
      intensity: comp.intensity,
    });
  }
}
export { SpotLightEvents } from './SpotLight.events';

SpotLight.contract.test.ts

12 ✓

ArcadeECS contract: SpotLight

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
Emits at least one declared output event during an update

Last run 2026-10-08

SpotLight.contract.test.ts

import { SpotLightEvents } from './SpotLight.events';
import { runMechanicContract } from '@babylonjsmarket/ecs/testing';
import { SpotLightComponent, SpotLightSystem } from './SpotLight';

runMechanicContract({
  name: 'SpotLight',
  componentClass: SpotLightComponent,
  systemClass: SpotLightSystem,
  sampleInput: { position: [1, 3, 2], direction: [0, -1, 0.2], angle: 1.2, intensity: 2 },
  events: {
    output: [SpotLightEvents.CREATED],
  },
});

SpotLight.test.ts

15 ✓

SpotLightComponent

defaults to a bounded, non-specular white can-light pointing down
copies input arrays rather than aliasing the caller’s
serialize round-trips through the constructor
toSpec hands the adapter a detached copy

SpotLightSystem

creates one adapter spot per entity and emits CREATED
does not recreate the light on later frames
pushes an intensity change made from outside
pushes a position change and emits MOVED
re-aims the light when direction changes
recolours the light when diffuse changes
stays quiet while nothing changes
disposes the adapter light when the entity goes away
creates lights for entities that already existed before initialize
stays inert when the world has no renderer
nine signs each get their own spot

Last run 2026-10-08

SpotLight.test.ts

import { beforeEach, describe, expect, it, vi } from 'vitest';
import { EventBus, MockRendererAdapter, World } from '@babylonjsmarket/ecs';
import { SpotLightEvents } from './SpotLight.events';
import { SpotLightComponent, SpotLightSystem } from './SpotLight';

describe('SpotLightComponent', () => {
  it('defaults to a bounded, non-specular white can-light pointing down', () => {
    const c = new SpotLightComponent();
    expect(c.position).toEqual([0, 3, 0]);
    expect(c.direction).toEqual([0, -1, 0]);
    expect(c.angle).toBeCloseTo(Math.PI / 3);
    expect(c.exponent).toBe(2);
    expect(c.intensity).toBe(1);
    expect(c.diffuse).toEqual([1, 1, 1]);
    // Coloured pools, not glints.
    expect(c.specular).toEqual([0, 0, 0]);
    // A spot is a local accent; bounded so it never leaks down a corridor.
    expect(c.range).toBe(10);
  });

  it('copies input arrays rather than aliasing the caller’s', () => {
    const position: [number, number, number] = [1, 2, 3];
    const direction: [number, number, number] = [0, 0, 1];
    const c = new SpotLightComponent({ position, direction });
    position[0] = 99;
    direction[2] = 99;
    expect(c.position).toEqual([1, 2, 3]);
    expect(c.direction).toEqual([0, 0, 1]);
  });

  it('serialize round-trips through the constructor', () => {
    const c = new SpotLightComponent({
      position: [-5.5, 2.35, 0.4],
      direction: [1, -0.2, 0],
      angle: Math.PI * 0.95,
      exponent: 1,
      intensity: 3,
      diffuse: [1, 0.15, 0.55],
      specular: [0.1, 0.1, 0.1],
      range: 6,
    });
    expect(new SpotLightComponent(c.serialize()).serialize()).toEqual(c.serialize());
  });

  it('toSpec hands the adapter a detached copy', () => {
    const c = new SpotLightComponent({ position: [1, 2, 3], direction: [0, -1, 0] });
    const spec = c.toSpec();
    spec.position[0] = 99;
    spec.direction[1] = 99;
    expect(c.position[0]).toBe(1);
    expect(c.direction[1]).toBe(-1);
    expect(spec.angle).toBeCloseTo(Math.PI / 3);
    expect(spec.exponent).toBe(2);
  });
});

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

  beforeEach(() => {
    eventBus = new EventBus();
    renderer = new MockRendererAdapter();
    world = new World({ eventBus, renderer, detectRaces: false });
    world.addSystem(new SpotLightSystem(eventBus));
    world.initialize();
  });

  const add = (input = {}) => {
    const e = world.createEntity();
    e.add(new SpotLightComponent(input));
    world.update(1 / 60);
    return e;
  };

  it('creates one adapter spot per entity and emits CREATED', () => {
    const spy = vi.fn();
    eventBus.on(SpotLightEvents.CREATED, spy);
    const e = add({ position: [2, 3, -3], direction: [0, -1, 1], intensity: 3 });
    const calls = renderer.calls.filter((c) => c.method === 'createSpotLight');
    expect(calls).toHaveLength(1);
    expect(calls[0].args[0]).toBe(e.id);
    const spec = calls[0].args[1] as { position: number[]; direction: number[] };
    expect(spec.position).toEqual([2, 3, -3]);
    expect(spec.direction).toEqual([0, -1, 1]);
    expect(spy).toHaveBeenCalledWith({ entityId: e.id, intensity: 3 });
  });

  it('does not recreate the light on later frames', () => {
    add();
    world.update(1 / 60);
    world.update(1 / 60);
    expect(renderer.calls.filter((c) => c.method === 'createSpotLight')).toHaveLength(1);
  });

  it('pushes an intensity change made from outside', () => {
    const e = add({ intensity: 1 });
    const spy = vi.fn();
    eventBus.on(SpotLightEvents.INTENSITY_CHANGED, spy);
    e.get(SpotLightComponent)!.intensity = 4;
    world.update(1 / 60);
    const calls = renderer.calls.filter((c) => c.method === 'updateLightIntensity');
    expect(calls.at(-1)!.args[1]).toBe(4);
    expect(spy).toHaveBeenCalledWith({ entityId: e.id, intensity: 4 });
  });

  it('pushes a position change and emits MOVED', () => {
    const e = add({ position: [0, 3, 0] });
    const spy = vi.fn();
    eventBus.on(SpotLightEvents.MOVED, spy);
    e.get(SpotLightComponent)!.position = [5, 1, -2];
    world.update(1 / 60);
    const calls = renderer.calls.filter((c) => c.method === 'setLightPosition');
    expect(calls.at(-1)!.args.slice(1)).toEqual([5, 1, -2]);
    expect(spy).toHaveBeenCalledWith({ entityId: e.id, position: [5, 1, -2] });
  });

  it('re-aims the light when direction changes', () => {
    const e = add({ direction: [0, -1, 0] });
    e.get(SpotLightComponent)!.direction = [1, 0, 0];
    world.update(1 / 60);
    const calls = renderer.calls.filter((c) => c.method === 'setLightDirection');
    expect(calls).toHaveLength(1);
    expect(calls[0].args.slice(1)).toEqual([1, 0, 0]);
  });

  it('recolours the light when diffuse changes', () => {
    const e = add({ diffuse: [1, 1, 1] });
    e.get(SpotLightComponent)!.diffuse = [1, 0.15, 0.55];
    world.update(1 / 60);
    const calls = renderer.calls.filter((c) => c.method === 'setLightColor');
    expect(calls).toHaveLength(1);
    expect(calls[0].args.slice(1)).toEqual([1, 0.15, 0.55]);
  });

  it('stays quiet while nothing changes', () => {
    add({ intensity: 2, position: [1, 1, 1], direction: [0, -1, 0], diffuse: [0.2, 0.9, 1] });
    renderer.calls.length = 0;
    world.update(1 / 60);
    world.update(1 / 60);
    const touched = ['updateLightIntensity', 'setLightPosition', 'setLightDirection', 'setLightColor'];
    expect(renderer.calls.some((c) => touched.includes(c.method))).toBe(false);
  });

  it('disposes the adapter light when the entity goes away', () => {
    const e = add();
    world.removeEntity(e.id);
    world.update(1 / 60);
    expect(renderer.calls.some((c) => c.method === 'disposeLight')).toBe(true);
  });

  it('creates lights for entities that already existed before initialize', () => {
    // The scene-loader path: entities are built first, then the world starts.
    // onInitialize has to sweep them, not just react to later additions.
    const bus = new EventBus();
    const r = new MockRendererAdapter();
    const w = new World({ eventBus: bus, renderer: r, detectRaces: false });
    const e = w.createEntity();
    e.add(new SpotLightComponent({ position: [1, 2, 3] }));
    w.addSystem(new SpotLightSystem(bus));
    w.initialize();
    const created = r.calls.filter((c) => c.method === 'createSpotLight');
    expect(created).toHaveLength(1);
    expect(created[0].args[0]).toBe(e.id);
  });

  it('stays inert when the world has no renderer', () => {
    const bus = new EventBus();
    const w = new World({ eventBus: bus, detectRaces: false });
    w.addSystem(new SpotLightSystem(bus));
    w.initialize();
    const e = w.createEntity();
    e.add(new SpotLightComponent());
    expect(() => {
      w.update(1 / 60);
      w.update(1 / 60);
    }).not.toThrow();
  });

  it('nine signs each get their own spot', () => {
    const ids = Array.from({ length: 9 }, (_, i) => add({ position: [i, 2, 0] }).id);
    const created = renderer.calls.filter((c) => c.method === 'createSpotLight');
    expect(created.map((c) => c.args[0])).toEqual(ids);
  });
});