GlowLayer.defs.ts

GlowLayer — definitions.

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

GlowLayer.defs.ts

import { Component } from '@babylonjsmarket/ecs';
import type { GlowSpec } from '@babylonjsmarket/ecs/renderer-types';
export { GlowLayerEvents } from './GlowLayer.events';

export interface GlowLayerInput {
  /** How far the bloom bleeds. Default 0.45 — enough for a CRT, short of a smear. */
  intensity?: number;
  /**
   * Size of the glow's render target relative to the screen. Lower is cheaper
   * and blurrier — 0.25 is plenty for tubes and screens. Default 0.25.
   */
  textureRatio?: number;
  /** MSAA samples on the glow target. Leave unset for the engine default (1). */
  samples?: number;
  /** Off switch that keeps the settings. Default true. */
  enabled?: boolean;
  /**
   * Enrol every mesh the scene creates (MeshPrimitive boxes, loaded GLBs) so
   * anything with an emissive material blooms. Default true. Set false to run
   * an empty layer and whitelist meshes yourself from another system.
   */
  includeEmissive?: boolean;
}

export class GlowLayerComponent 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 = 'GlowLayer';

  intensity: number;
  textureRatio: number;
  samples?: number;
  includeEmissive: boolean;

  constructor(data: GlowLayerInput = {}) {
    super();
    this.intensity = data.intensity ?? 0.45;
    this.textureRatio = data.textureRatio ?? 0.25;
    this.samples = data.samples;
    // `enabled` is the base Component accessor; setting it here (no bus yet) is silent.
    this.enabled = data.enabled ?? true;
    this.includeEmissive = data.includeEmissive ?? true;
  }

  toSpec(): GlowSpec {
    const spec: GlowSpec = { intensity: this.intensity, textureRatio: this.textureRatio };
    if (this.samples !== undefined) spec.samples = this.samples;
    return spec;
  }

  serialize(): GlowLayerInput {
    const out: GlowLayerInput = {
      intensity: this.intensity,
      textureRatio: this.textureRatio,
      enabled: this.enabled,
      includeEmissive: this.includeEmissive,
    };
    if (this.samples !== undefined) out.samples = this.samples;
    return out;
  }
}

GlowLayer.events.ts

GlowLayer — event names.

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

GlowLayer.events.ts

// GlowLayerEvents — from GlowLayer
export const GlowLayerEvents = {
  /** The glow pass is up with the component's intensity. `{ entityId, intensity }`. */
  APPLIED: 'glowlayer.applied',
  /**
   * A mesh was whitelisted into the glow pass. The adapter's layer starts EMPTY,
   * so this fires once per mesh the system enrols — it is the only way a
   * screen or a neon tube gets to bloom. `{ entityId, meshEntityId }`.
   */
  MESH_ENROLLED: 'glowlayer.mesh.enrolled',
  /** The glow pass was torn down. `{ entityId }`. */
  CLEARED: 'glowlayer.cleared',
} as const;

GlowLayer.ts

GlowLayer.ts — renderer-agnostic System for the scene-wide emissive bloom.

Scene-global: one glow pass per scene, switched on with renderer.setGlowLayer(spec) when the component attaches and off with setGlowLayer(null) when it goes; intensity is diffed per frame so a slider drives it live.

The part that makes this more than a one-liner: the adapter's glow layer starts from an EMPTY whitelist. Nothing blooms — not a CRT screen, not a neon tube — until addGlowMesh(handle) enrols it. That is deliberate at the adapter (a space shooter wants its sun to glow and its bullet trails not to), but a room full of lit cabinets wants the opposite: everything emissive, in. So with includeEmissive on, this System listens for meshes as they appear — MeshPrimitive's CREATED and Mesh's LOADED both carry the renderer handle — and enrols each one. Handles are remembered whether or not the layer is up yet, so the order the scene lists its entities in does not matter, and removeGlowMesh can undo every enrolment on detach.

GlowLayer.ts

import { GlowLayerEvents } from './GlowLayer.events';
import { MeshEvents } from '../Mesh/Mesh.events';
import { MeshPrimitiveEvents } from '../MeshPrimitive/MeshPrimitive.events';
import { System } from '@babylonjsmarket/ecs';
import type { EventBus, Entity } from '@babylonjsmarket/ecs';
import type { MeshHandle } from '@babylonjsmarket/ecs/renderer-types';
import { GlowLayerComponent, type GlowLayerInput } from './GlowLayer.defs';

export { GlowLayerComponent, type GlowLayerInput };

interface GlowLayerRuntime {
  /** True while the adapter has this component's layer up. */
  applied: boolean;
  lastIntensity?: number;
  lastEnabled?: boolean;
}

/** Payload shape shared by MeshPrimitive CREATED and Mesh LOADED. */
interface MeshHandleEvent {
  entityId: string;
  handle?: MeshHandle;
}

export class GlowLayerSystem extends System {
  protected query = { required: [GlowLayerComponent] };
  private runtime = new WeakMap<GlowLayerComponent, GlowLayerRuntime>();
  /** Every mesh handle the scene has told us about, by owning entity. */
  private meshHandles = new Map<string, MeshHandle>();
  /** The subset currently whitelisted into the live layer. */
  private enrolled = new Set<string>();
  /** The entity whose component owns the live layer, if any. */
  private activeEntity: Entity | null = null;

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

  private getRuntime(comp: GlowLayerComponent): GlowLayerRuntime {
    let rt = this.runtime.get(comp);
    if (!rt) {
      rt = { applied: false };
      this.runtime.set(comp, rt);
    }
    return rt;
  }

  protected onInitialize(): void {
    const onMesh = (e: MeshHandleEvent) => {
      if (!e?.handle) return;
      this.meshHandles.set(e.entityId, e.handle);
      this.enrol(e.entityId);
    };
    this.listen(MeshPrimitiveEvents.CREATED, onMesh);
    this.listen(MeshEvents.LOADED, onMesh);
    this.listen(MeshPrimitiveEvents.DISPOSED, (e: { entityId: string }) => {
      this.forget(e.entityId);
    });
    for (const entity of this.entities) this.apply(entity);
  }

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

  protected onEntityRemoved(entity: Entity): void {
    const comp = entity.get(GlowLayerComponent);
    if (!comp) return;
    this.clear(entity, comp);
  }

  protected onUpdate(_dt: number): void {
    for (const entity of this.entities) {
      const comp = entity.get(GlowLayerComponent);
      if (!comp) continue;
      const rt = this.getRuntime(comp);

      if (rt.lastEnabled !== comp.enabled) {
        // A toggle: bring the layer up or take it down, then fall through so
        // a same-frame intensity edit is folded into the apply.
        if (comp.enabled) this.apply(entity);
        else this.clear(entity, comp);
        continue;
      }
      if (!rt.applied) continue;

      if (rt.lastIntensity === undefined || Math.abs(rt.lastIntensity - comp.intensity) > 0.001) {
        // The adapter updates an existing layer in place (whitelist intact),
        // so a slider costs one call, not a rebuild.
        this.world?.renderer?.setGlowLayer(comp.toSpec());
        rt.lastIntensity = comp.intensity;
      }
    }
  }

  private apply(entity: Entity): void {
    const comp = entity.get(GlowLayerComponent);
    if (!comp) return;
    const rt = this.getRuntime(comp);
    rt.lastEnabled = comp.enabled;
    if (rt.applied || !comp.enabled) return;
    const r = this.world?.renderer;
    if (!r) return;

    r.setGlowLayer(comp.toSpec());
    rt.applied = true;
    rt.lastIntensity = comp.intensity;
    this.activeEntity = entity;
    this.eventBus.emit(GlowLayerEvents.APPLIED, {
      entityId: entity.id,
      intensity: comp.intensity,
    });
    // Meshes that showed up before the layer did: enrol them now.
    for (const id of this.meshHandles.keys()) this.enrol(id);
  }

  private clear(entity: Entity, comp: GlowLayerComponent): void {
    const rt = this.getRuntime(comp);
    rt.lastEnabled = comp.enabled;
    if (!rt.applied) return;
    const r = this.world?.renderer;
    for (const id of this.enrolled) {
      const h = this.meshHandles.get(id);
      if (h) r?.removeGlowMesh(h);
    }
    this.enrolled.clear();
    r?.setGlowLayer(null);
    rt.applied = false;
    rt.lastIntensity = undefined;
    this.activeEntity = null;
    this.eventBus.emit(GlowLayerEvents.CLEARED, { entityId: entity.id });
  }

  /** Whitelist one remembered mesh, if a layer is up and wants emissives. */
  private enrol(meshEntityId: string): void {
    const owner = this.activeEntity;
    if (!owner) return;
    const comp = owner.get(GlowLayerComponent);
    if (!comp || !comp.includeEmissive) return;
    const rt = this.getRuntime(comp);
    if (!rt.applied || this.enrolled.has(meshEntityId)) return;
    const h = this.meshHandles.get(meshEntityId);
    if (!h) return;
    this.world?.renderer?.addGlowMesh(h);
    this.enrolled.add(meshEntityId);
    this.eventBus.emit(GlowLayerEvents.MESH_ENROLLED, {
      entityId: owner.id,
      meshEntityId,
    });
  }

  /** A mesh went away: drop it from the whitelist and from memory. */
  private forget(meshEntityId: string): void {
    const h = this.meshHandles.get(meshEntityId);
    if (h && this.enrolled.has(meshEntityId)) {
      this.world?.renderer?.removeGlowMesh(h);
      this.enrolled.delete(meshEntityId);
    }
    this.meshHandles.delete(meshEntityId);
  }
}
export { GlowLayerEvents } from './GlowLayer.events';

GlowLayer.contract.test.ts

13 ✓

ArcadeECS contract: GlowLayer

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
Registers a listener for each declared input event

Last run 2026-10-08

GlowLayer.contract.test.ts

import { GlowLayerEvents } from './GlowLayer.events';
import { MeshEvents } from '../Mesh/Mesh.events';
import { MeshPrimitiveEvents } from '../MeshPrimitive/MeshPrimitive.events';
import { runMechanicContract } from '@babylonjsmarket/ecs/testing';
import { GlowLayerComponent, GlowLayerSystem } from './GlowLayer';

runMechanicContract({
  name: 'GlowLayer',
  componentClass: GlowLayerComponent,
  systemClass: GlowLayerSystem,
  sampleInput: { intensity: 0.45, textureRatio: 0.25 },
  events: {
    // The mesh announcements it enrols from — other components' outputs, but
    // this System must subscribe to them, so they are its inputs.
    input: [MeshPrimitiveEvents.CREATED, MeshEvents.LOADED],
    output: [GlowLayerEvents.APPLIED],
  },
  makeInputPayload: () => ({ entityId: 'cabinet', handle: { __mockHandle: 'mesh:cabinet' } }),
});

GlowLayer.test.ts

17 ✓

GlowLayerComponent

defaults to a modest quarter-res bloom that enrols every mesh
serialize round-trips through the constructor (samples only when set)
toSpec carries samples only when set

GlowLayerSystem

brings the layer up through the adapter and emits APPLIED
enrols meshes that appear after the layer is up (the empty-whitelist rule)
enrols meshes that appeared BEFORE the layer, once it comes up
ignores mesh announcements with no handle (the Three adapter path)
never enrols twice for the same entity
with includeEmissive false the layer is up but stays empty
drops a disposed mesh from the whitelist
a disposed-but-never-enrolled mesh is just forgotten
pushes an intensity change live without rebuilding the whitelist
enabled=false takes the layer down (un-enrolling), true brings it back
a component that starts disabled never touches the adapter
tears the layer down when the entity is removed
applies to entities that already exist when the system initializes
no-ops on a renderer-less world

Last run 2026-10-08

GlowLayer.test.ts

import { beforeEach, describe, expect, it, vi } from 'vitest';
import { EventBus, MockRendererAdapter, World } from '@babylonjsmarket/ecs';
import type { MeshHandle } from '@babylonjsmarket/ecs/renderer-types';
import { GlowLayerEvents } from './GlowLayer.events';
import { MeshEvents } from '../Mesh/Mesh.events';
import { MeshPrimitiveEvents } from '../MeshPrimitive/MeshPrimitive.events';
import { GlowLayerComponent, GlowLayerSystem } from './GlowLayer';

const handle = (id: string) => ({ __mockHandle: `mesh:${id}` }) as unknown as MeshHandle;

describe('GlowLayerComponent', () => {
  it('defaults to a modest quarter-res bloom that enrols every mesh', () => {
    const c = new GlowLayerComponent();
    expect(c.intensity).toBe(0.45);
    expect(c.textureRatio).toBe(0.25);
    expect(c.samples).toBeUndefined();
    expect(c.enabled).toBe(true);
    expect(c.includeEmissive).toBe(true);
  });

  it('serialize round-trips through the constructor (samples only when set)', () => {
    const bare = new GlowLayerComponent({ intensity: 0.9, textureRatio: 0.5, enabled: false, includeEmissive: false });
    expect(new GlowLayerComponent(bare.serialize()).serialize()).toEqual(bare.serialize());
    expect('samples' in bare.serialize()).toBe(false);
    const sampled = new GlowLayerComponent({ samples: 4 });
    expect(sampled.serialize().samples).toBe(4);
    expect(new GlowLayerComponent(sampled.serialize()).samples).toBe(4);
  });

  it('toSpec carries samples only when set', () => {
    expect(new GlowLayerComponent().toSpec()).toEqual({ intensity: 0.45, textureRatio: 0.25 });
    expect(new GlowLayerComponent({ samples: 2 }).toSpec()).toEqual({ intensity: 0.45, textureRatio: 0.25, samples: 2 });
  });
});

describe('GlowLayerSystem', () => {
  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 GlowLayerSystem(eventBus));
    world.initialize();
  });

  const calls = (m: string) => renderer.calls.filter((c) => c.method === m);
  const addLayer = (input = {}) => {
    const e = world.createEntity();
    e.add(new GlowLayerComponent(input));
    return e;
  };

  it('brings the layer up through the adapter and emits APPLIED', () => {
    const spy = vi.fn();
    eventBus.on(GlowLayerEvents.APPLIED, spy);
    const e = addLayer({ intensity: 0.45, textureRatio: 0.25 });
    expect(calls('setGlowLayer')).toHaveLength(1);
    expect(calls('setGlowLayer')[0].args[0]).toEqual({ intensity: 0.45, textureRatio: 0.25 });
    expect(spy).toHaveBeenCalledWith({ entityId: e.id, intensity: 0.45 });
  });

  it('enrols meshes that appear after the layer is up (the empty-whitelist rule)', () => {
    const enrolled = vi.fn();
    eventBus.on(GlowLayerEvents.MESH_ENROLLED, enrolled);
    const e = addLayer();
    eventBus.emit(MeshPrimitiveEvents.CREATED, { entityId: 'wall', primitive: 'box', handle: handle('wall') });
    eventBus.emit(MeshEvents.LOADED, { entityId: 'cabinet', meshId: 'cabinet', animationNames: [], handle: handle('cabinet') });
    expect(calls('addGlowMesh').map((c) => c.args[0])).toEqual([handle('wall'), handle('cabinet')]);
    expect(enrolled).toHaveBeenCalledTimes(2);
    expect(enrolled).toHaveBeenLastCalledWith({ entityId: e.id, meshEntityId: 'cabinet' });
  });

  it('enrols meshes that appeared BEFORE the layer, once it comes up', () => {
    eventBus.emit(MeshPrimitiveEvents.CREATED, { entityId: 'floor', primitive: 'ground', handle: handle('floor') });
    expect(calls('addGlowMesh')).toHaveLength(0);
    addLayer();
    expect(calls('addGlowMesh')).toHaveLength(1);
    expect(calls('addGlowMesh')[0].args[0]).toEqual(handle('floor'));
  });

  it('ignores mesh announcements with no handle (the Three adapter path)', () => {
    addLayer();
    eventBus.emit(MeshPrimitiveEvents.CREATED, { entityId: 'ghost', primitive: 'box' });
    expect(calls('addGlowMesh')).toHaveLength(0);
  });

  it('never enrols twice for the same entity', () => {
    addLayer();
    eventBus.emit(MeshPrimitiveEvents.CREATED, { entityId: 'wall', primitive: 'box', handle: handle('wall') });
    eventBus.emit(MeshPrimitiveEvents.CREATED, { entityId: 'wall', primitive: 'box', handle: handle('wall') });
    expect(calls('addGlowMesh')).toHaveLength(1);
  });

  it('with includeEmissive false the layer is up but stays empty', () => {
    addLayer({ includeEmissive: false });
    eventBus.emit(MeshPrimitiveEvents.CREATED, { entityId: 'wall', primitive: 'box', handle: handle('wall') });
    expect(calls('setGlowLayer')).toHaveLength(1);
    expect(calls('addGlowMesh')).toHaveLength(0);
  });

  it('drops a disposed mesh from the whitelist', () => {
    addLayer();
    eventBus.emit(MeshPrimitiveEvents.CREATED, { entityId: 'wall', primitive: 'box', handle: handle('wall') });
    eventBus.emit(MeshPrimitiveEvents.DISPOSED, { entityId: 'wall' });
    expect(calls('removeGlowMesh')).toHaveLength(1);
    // Forgotten: a later layer does not resurrect it.
    eventBus.emit(MeshPrimitiveEvents.DISPOSED, { entityId: 'never-seen' });
    expect(calls('removeGlowMesh')).toHaveLength(1);
  });

  it('a disposed-but-never-enrolled mesh is just forgotten', () => {
    eventBus.emit(MeshPrimitiveEvents.CREATED, { entityId: 'early', primitive: 'box', handle: handle('early') });
    eventBus.emit(MeshPrimitiveEvents.DISPOSED, { entityId: 'early' });
    addLayer();
    expect(calls('removeGlowMesh')).toHaveLength(0);
    expect(calls('addGlowMesh')).toHaveLength(0);
  });

  it('pushes an intensity change live without rebuilding the whitelist', () => {
    const e = addLayer({ intensity: 0.45 });
    eventBus.emit(MeshPrimitiveEvents.CREATED, { entityId: 'wall', primitive: 'box', handle: handle('wall') });
    e.get(GlowLayerComponent)!.intensity = 0.9;
    world.update(1 / 60);
    expect(calls('setGlowLayer')).toHaveLength(2);
    expect((calls('setGlowLayer')[1].args[0] as { intensity: number }).intensity).toBe(0.9);
    expect(calls('addGlowMesh')).toHaveLength(1);
    world.update(1 / 60);
    expect(calls('setGlowLayer')).toHaveLength(2);
  });

  it('enabled=false takes the layer down (un-enrolling), true brings it back', () => {
    const cleared = vi.fn();
    eventBus.on(GlowLayerEvents.CLEARED, cleared);
    const e = addLayer();
    eventBus.emit(MeshPrimitiveEvents.CREATED, { entityId: 'wall', primitive: 'box', handle: handle('wall') });
    e.get(GlowLayerComponent)!.enabled = false;
    world.update(1 / 60);
    expect(calls('removeGlowMesh')).toHaveLength(1);
    expect(calls('setGlowLayer').at(-1)!.args[0]).toBeNull();
    expect(cleared).toHaveBeenCalledWith({ entityId: e.id });
    world.update(1 / 60);
    expect(calls('setGlowLayer')).toHaveLength(2);
    e.get(GlowLayerComponent)!.enabled = true;
    world.update(1 / 60);
    expect(calls('setGlowLayer')).toHaveLength(3);
    // The remembered mesh is enrolled again.
    expect(calls('addGlowMesh')).toHaveLength(2);
  });

  it('a component that starts disabled never touches the adapter', () => {
    addLayer({ enabled: false });
    world.update(1 / 60);
    expect(calls('setGlowLayer')).toHaveLength(0);
  });

  it('tears the layer down when the entity is removed', () => {
    const e = addLayer();
    eventBus.emit(MeshPrimitiveEvents.CREATED, { entityId: 'wall', primitive: 'box', handle: handle('wall') });
    world.removeEntity(e);
    expect(calls('removeGlowMesh')).toHaveLength(1);
    expect(calls('setGlowLayer').at(-1)!.args[0]).toBeNull();
    // Removing a component whose layer was already down is a no-op.
    const e2 = addLayer({ enabled: false });
    world.removeEntity(e2);
    expect(calls('setGlowLayer')).toHaveLength(2);
  });

  it('applies to entities that already exist when the system initializes', () => {
    const bus = new EventBus();
    const r = new MockRendererAdapter();
    const w = new World({ eventBus: bus, renderer: r, detectRaces: false });
    w.createEntity().add(new GlowLayerComponent({ intensity: 0.7 }));
    w.addSystem(new GlowLayerSystem(bus));
    w.initialize();
    expect(r.calls.filter((c) => c.method === 'setGlowLayer')).toHaveLength(1);
  });

  it('no-ops on a renderer-less world', () => {
    const bus = new EventBus();
    const w = new World({ eventBus: bus, detectRaces: false });
    w.addSystem(new GlowLayerSystem(bus));
    w.initialize();
    const e = w.createEntity();
    expect(() => {
      e.add(new GlowLayerComponent());
      bus.emit(MeshPrimitiveEvents.CREATED, { entityId: 'wall', primitive: 'box', handle: handle('wall') });
      w.update(1 / 60);
      w.removeEntity(e);
    }).not.toThrow();
  });
});