NeonSign.core.ts

NeonSign.core.ts — the renderer-agnostic side of the extruded-text seam, plus the sign geometry that is pure arithmetic.

No ecs import, no engine import. Holds the name the adapter plugin registers under, the contract both sides speak (plain numbers and strings only), and the little bits of trigonometry — which way a sign faces, where its spot aims, where an extruded slab sits — so the plugin is left with nothing but engine calls and the System with nothing but bookkeeping.

NeonSign.core.ts

/** Name the plugin registers under and the System looks up. */
export const NEON_TEXT_EXTENSION = 'neonText';

type Triple = [number, number, number];

/** Everything the plugin needs to build one sign's lettering. */
export interface NeonTextSpec {
  text: string;
  /** URL of a facetype.js font JSON. */
  fontUrl: string;
  /** Letter height, metres. */
  size: number;
  /** Extrusion depth, metres. */
  depth: number;
  /** The sign FACE — the plugin pushes the slab out from here by half its depth. */
  position: Triple;
  /** Euler rotation (radians); Y is the facing, 0 = faces +Z. */
  rotation: Triple;
  /** Tube colour, RGB 0..1. */
  color: Triple;
  /** Emissive intensity of the lettering. */
  intensity: number;
}

Shape of the registered adapter plugin.

create resolves to the mesh name once the lettering exists, or null when it cannot be built (no scene yet, the font failed to load, empty text) — the System then falls back to a label quad. Calling it again under the same id replaces the previous lettering. dispose is safe to call for an id that was never built or whose build is still in flight.

NeonSign.core.ts

export interface NeonTextExtension {
  create(id: string, spec: NeonTextSpec): Promise<string | null>;
  setColor(id: string, color: Triple, intensity: number): void;
  dispose(id: string): void;
}

/** The sign's outward normal for a facing `yaw`; 0 = faces +Z. */
export function signNormal(yaw: number): Triple {
  return [Math.sin(yaw), 0, Math.cos(yaw)];
}

Where the spot behind a sign points: out along the facing and tilted 0.4 down, normalized — the old room's aim, so the wash rakes down over the cabinet tops instead of only lighting their fronts.

NeonSign.core.ts

export function spotDirection(yaw: number): Triple {
  const n = signNormal(yaw);
  const len = Math.hypot(n[0], -0.4, n[2]);
  return [n[0] / len, -0.4 / len, n[2] / len];
}

Where an extruded slab of depth sits so it stands proud of the wall into the room: the sign face pushed along its normal by half the depth plus a centimetre (the slab is centred on its origin), turned to the sign's own facing. The extruder's readable side comes out at local +Z — the same side signNormal(0) points — so the slab's yaw IS the sign's yaw.

It used to add a half-turn. That constant came from the old raw-Babylon room, a LEFT-handed scene that drew everything as a mirror image; there the slab's back read correctly and its front read backwards. In this right-handed renderer the extra π shows the back, and every sign reads mirrored. (Hand a mirrored sign to any glTF-correct renderer and the same thing happens — the fix belongs here, not in a scene.)

NeonSign.core.ts

export function extrudedTextTransform(
  face: Triple,
  yaw: number,
  depth: number,
): { position: Triple; rotationY: number } {
  const n = signNormal(yaw);
  const push = depth / 2 + 0.01;
  return {
    position: [face[0] + n[0] * push, face[1] + n[1] * push, face[2] + n[2] * push],
    rotationY: yaw,
  };
}

/** True when every component of `a` and `b` is within `eps`. */
export function sameTriple(a: Triple | undefined, b: Triple, eps = 1e-6): boolean {
  return (
    !!a &&
    Math.abs(a[0] - b[0]) <= eps &&
    Math.abs(a[1] - b[1]) <= eps &&
    Math.abs(a[2] - b[2]) <= eps
  );
}

NeonSign.defs.ts

NeonSign — definitions.

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

NeonSign.defs.ts

import { Component } from '@babylonjsmarket/ecs';
import type { Color, Vec3 } from '@babylonjsmarket/ecs/renderer-types';
import { spotDirection } from './NeonSign.core';
export { NeonSignEvents } from './NeonSign.events';

/** What throws the sign's wash into the room. */
export type NeonSignLightKind = 'point' | 'spot';

export interface NeonSignInput {
  /** The words. */
  text?: string;
  /** Tube colour — drives BOTH the lettering and the light it casts. */
  color?: Color;
  /** World position of the sign face. */
  position?: Vec3;
  /** Euler rotation (radians). A sign on a wall faces into the room. */
  rotation?: Vec3;
  /** World height of the lettering, in metres. */
  size?: number;
  /** Brightness of the light it throws. 0 turns the glow off (tube only). */
  glow?: number;
  /** How far that light reaches, in metres. */
  range?: number;
  /**
   * How far in FRONT of the sign face the light sits. A light exactly on the
   * wall mostly lights the wall's back face.
   */
  glowOffset?: number;
  /** Text resolution in CSS pixels. Bigger = crisper up close. */
  fontSize?: number;
  /**
   * The light's shape. `'point'` (default) radiates every way from in front
   * of the sign; `'spot'` is a cone aimed along the sign's facing and tilted
   * down, so the wash lands on the cabinets and floor rather than the ceiling
   * and the wall the sign hangs on.
   */
  lightKind?: NeonSignLightKind;
  /** Spot only: full cone aperture, radians. Default 0.95π — almost a hemisphere. */
  spotAngle?: number;
  /** Spot only: edge falloff sharpness. Default 2, a soft rim. */
  spotExponent?: number;
  /**
   * Real extruded lettering instead of a rasterised quad. Needs the
   * `neonText` adapter plugin registered on the renderer
   * (`registerBabylonNeonTextExtension`); without one the sign quietly draws
   * the quad instead. Default false.
   */
  extruded?: boolean;
  /** Extruded only: slab depth in metres. Default 0.08. */
  depth?: number;
  /** Extruded only: URL of a facetype.js font JSON. Default `/fonts/neon.json`. */
  fontUrl?: string;
}

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

export class NeonSignComponent 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 = 'NeonSign';

  text: string;
  color: Color;
  position: Vec3;
  rotation: Vec3;
  size: number;
  glow: number;
  range: number;
  glowOffset: number;
  fontSize: number;
  lightKind: NeonSignLightKind;
  spotAngle: number;
  spotExponent: number;
  extruded: boolean;
  depth: number;
  fontUrl: string;

  constructor(data: NeonSignInput = {}) {
    super();
    this.text = data.text ?? '';
    this.color = data.color ? cloneVec3(data.color) : [1, 0.15, 0.55];
    this.position = data.position ? cloneVec3(data.position) : [0, 2.5, 0];
    this.rotation = data.rotation ? cloneVec3(data.rotation) : [0, 0, 0];
    this.size = data.size ?? 0.45;
    this.glow = data.glow ?? 6;
    this.range = data.range ?? 7;
    this.glowOffset = data.glowOffset ?? 0.35;
    this.fontSize = data.fontSize ?? 96;
    this.lightKind = data.lightKind ?? 'point';
    this.spotAngle = data.spotAngle ?? Math.PI * 0.95;
    this.spotExponent = data.spotExponent ?? 2;
    this.extruded = data.extruded ?? false;
    this.depth = data.depth ?? 0.08;
    this.fontUrl = data.fontUrl ?? '/fonts/neon.json';
  }

  /**
   * Where the glow light sits: `glowOffset` metres out along the sign's facing.
   * Rotation Y of 0 means the sign faces +Z, matching the rest of the package.
   */
  glowPosition(): Vec3 {
    const yaw = this.rotation[1];
    return [
      this.position[0] + Math.sin(yaw) * this.glowOffset,
      this.position[1],
      this.position[2] + Math.cos(yaw) * this.glowOffset,
    ];
  }

  /** Where a spot aims: along the facing, tilted 0.4 down, unit length. */
  spotDirection(): Vec3 {
    return spotDirection(this.rotation[1]);
  }

  serialize(): NeonSignInput {
    return {
      text: this.text,
      color: cloneVec3(this.color),
      position: cloneVec3(this.position),
      rotation: cloneVec3(this.rotation),
      size: this.size,
      glow: this.glow,
      range: this.range,
      glowOffset: this.glowOffset,
      fontSize: this.fontSize,
      lightKind: this.lightKind,
      spotAngle: this.spotAngle,
      spotExponent: this.spotExponent,
      extruded: this.extruded,
      depth: this.depth,
      fontUrl: this.fontUrl,
    };
  }
}

NeonSign.events.ts

NeonSign — event names.

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

NeonSign.events.ts

// NeonSignEvents — from NeonSign
export const NeonSignEvents = {
  CREATED: 'neonsign.created',
  /** The sign's text changed; payload `{ entityId, text }`. */
  TEXT_CHANGED: 'neonsign.text.changed',
  /**
   * The tube colour changed — lettering and light recoloured together.
   * Payload `{ entityId, color }`.
   */
  COLOR_CHANGED: 'neonsign.color.changed',
  /**
   * The lettering is real extruded geometry: the `neonText` adapter plugin
   * built it. With no plugin registered (a Three host, a bootstrap that
   * forgot) the sign quietly falls back to a label quad and this never fires.
   * Payload `{ entityId, text }`.
   */
  EXTRUDED: 'neonsign.extruded',
} as const;

NeonSign.ts

NeonSign.ts — renderer-agnostic System that turns a NeonSign into glowing words plus the light they throw.

The lettering is either a world-FIXED label (billboard: false — a sign screwed to a wall doesn't swivel to follow you, and being edge-on from the side is correct) or, with extruded: true, real slab geometry built by the neonText adapter plugin (adapter/NeonSign.babylon.ts). The plugin is a Route-B seam: a host registers it at bootstrap (registerBabylonNeonTextExtension(adapter)), and where it is absent — a Three project, headless tests, a bootstrap that forgot — an extruded sign quietly draws the label quad instead. No warning: the quad IS the sign, just flatter.

The glow is a light sharing the sign's colour, sitting slightly in front of the face so it washes the room rather than the wall's far side: a point light by default, or a spot aimed along the facing and tilted down.

Every field is diffed per frame, so a settings slider or an editor can recolour, move, resize or re-letter a live sign and the lettering and the light follow together.

NeonSign.ts

import { NeonSignEvents } from './NeonSign.events';
import { System } from '@babylonjsmarket/ecs';
import type { Entity, EventBus } from '@babylonjsmarket/ecs';
import type { Color, LabelHandle, LightHandle, Vec3 } from '@babylonjsmarket/ecs/renderer-types';
import {
  NEON_TEXT_EXTENSION,
  sameTriple,
  type NeonTextExtension,
  type NeonTextSpec,
} from './NeonSign.core';
import { cloneVec3, NeonSignComponent, type NeonSignInput, type NeonSignLightKind } from './NeonSign.defs';

export { NeonSignComponent, type NeonSignInput, type NeonSignLightKind };
export {
  NEON_TEXT_EXTENSION,
  extrudedTextTransform,
  signNormal,
  spotDirection,
  type NeonTextExtension,
  type NeonTextSpec,
} from './NeonSign.core';

/** Everything the per-frame diff compares — a plain copy of the component. */
interface NeonSignSnapshot {
  text: string;
  color: Vec3;
  position: Vec3;
  rotation: Vec3;
  size: number;
  glow: number;
  range: number;
  glowOffset: number;
  fontSize: number;
  lightKind: NeonSignLightKind;
  spotAngle: number;
  spotExponent: number;
  extruded: boolean;
  depth: number;
  fontUrl: string;
}

interface NeonSignRuntime {
  label?: LabelHandle;
  light?: LightHandle;
  /** The plugin has this sign's extruded lettering live under the entity id. */
  extruded: boolean;
  /**
   * Bumped on every build and every teardown, so a plugin `create` that
   * resolves after the sign was rebuilt or removed is recognised as stale.
   */
  generation: number;
  initialized: boolean;
  last?: NeonSignSnapshot;
}

function snapshot(c: NeonSignComponent): NeonSignSnapshot {
  return {
    text: c.text,
    color: cloneVec3(c.color),
    position: cloneVec3(c.position),
    rotation: cloneVec3(c.rotation),
    size: c.size,
    glow: c.glow,
    range: c.range,
    glowOffset: c.glowOffset,
    fontSize: c.fontSize,
    lightKind: c.lightKind,
    spotAngle: c.spotAngle,
    spotExponent: c.spotExponent,
    extruded: c.extruded,
    depth: c.depth,
    fontUrl: c.fontUrl,
  };
}

/** The lettering's emissive intensity: follows `glow`, but a tube is never dimmer than lit. */
function tubeIntensity(glow: number): number {
  return Math.max(1, glow);
}

export class NeonSignSystem extends System {
  protected query = { required: [NeonSignComponent] };
  private runtime = new WeakMap<NeonSignComponent, NeonSignRuntime>();

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

  private getRuntime(comp: NeonSignComponent): NeonSignRuntime {
    let rt = this.runtime.get(comp);
    if (!rt) {
      rt = { extruded: false, generation: 0, initialized: false };
      this.runtime.set(comp, rt);
    }
    return rt;
  }

  private extension(): NeonTextExtension | undefined {
    return this.world?.renderer?.extension<NeonTextExtension>(NEON_TEXT_EXTENSION);
  }

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

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

  protected onEntityRemoved(entity: Entity): void {
    const comp = entity.get(NeonSignComponent);
    if (!comp) return;
    const rt = this.getRuntime(comp);
    this.disposeLettering(entity, rt);
    this.disposeLight(rt);
    rt.initialized = false;
    rt.last = undefined;
  }

  /**
   * Push any change made from outside (a panel, an editor, an event handler)
   * to the renderer: lettering and light are rebuilt or retuned as the change
   * demands, and nothing is touched while nothing moved.
   */
  protected onUpdate(): void {
    for (const entity of this.entities) {
      const comp = entity.get(NeonSignComponent);
      if (!comp) continue;
      const rt = this.getRuntime(comp);
      if (!rt.initialized || !rt.last) continue;
      const r = this.world?.renderer;
      if (!r) continue;

      const now = snapshot(comp);
      const prev = rt.last;
      const recoloured = !sameTriple(prev.color, now.color);
      const moved = !sameTriple(prev.position, now.position);
      const turned = !sameTriple(prev.rotation, now.rotation);
      // Anything that changes the lettering's shape means new geometry: the
      // label re-rasterises, the slab is re-extruded. A moved extruded slab
      // rebuilds too — the plugin's contract has no "move" on purpose.
      const reshaped =
        now.text !== prev.text ||
        now.size !== prev.size ||
        now.depth !== prev.depth ||
        now.fontSize !== prev.fontSize ||
        now.fontUrl !== prev.fontUrl ||
        now.extruded !== prev.extruded ||
        turned ||
        (moved && rt.extruded);

      if (reshaped) {
        this.buildLettering(entity, comp, rt);
      } else {
        if (moved && rt.label) r.setLabelPosition(rt.label, now.position[0], now.position[1], now.position[2]);
        if (recoloured && rt.label) r.setLabelColor(rt.label, now.color[0], now.color[1], now.color[2]);
        if ((recoloured || now.glow !== prev.glow) && rt.extruded) {
          this.extension()?.setColor(entity.id, cloneVec3(now.color), tubeIntensity(now.glow));
        }
      }

      // The light: a change of kind, reach or cone shape is a new light; a
      // glow crossing zero adds or removes one; everything else retunes.
      const lit = now.glow > 0;
      const relit =
        now.lightKind !== prev.lightKind ||
        now.range !== prev.range ||
        now.spotAngle !== prev.spotAngle ||
        now.spotExponent !== prev.spotExponent ||
        lit !== prev.glow > 0;
      if (relit) {
        this.disposeLight(rt);
        this.buildLight(entity, comp, rt);
      } else if (rt.light) {
        if (now.glow !== prev.glow) r.updateLightIntensity(rt.light, now.glow);
        if (moved || turned || now.glowOffset !== prev.glowOffset) {
          const at = comp.glowPosition();
          r.setLightPosition(rt.light, at[0], at[1], at[2]);
        }
        if (turned && now.lightKind === 'spot') {
          const d = comp.spotDirection();
          r.setLightDirection(rt.light, d[0], d[1], d[2]);
        }
        if (recoloured) r.setLightColor(rt.light, now.color[0], now.color[1], now.color[2]);
      }

      if (now.text !== prev.text) {
        this.eventBus.emit(NeonSignEvents.TEXT_CHANGED, { entityId: entity.id, text: now.text });
      }
      if (recoloured) {
        this.eventBus.emit(NeonSignEvents.COLOR_CHANGED, {
          entityId: entity.id,
          color: cloneVec3(now.color) as Color,
        });
      }
      rt.last = now;
    }
  }

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

    this.buildLettering(entity, comp, rt);
    this.buildLight(entity, comp, rt);

    rt.initialized = true;
    rt.last = snapshot(comp);
    this.eventBus.emit(NeonSignEvents.CREATED, { entityId: entity.id, text: comp.text });
  }

  /**
   * Build the lettering afresh: extruded through the plugin when asked for
   * and available, the label quad otherwise. A plugin build is asynchronous
   * (the font has to arrive); if it comes back empty the quad steps in, and
   * if the sign was rebuilt or removed in the meantime the result is dropped.
   */
  private buildLettering(entity: Entity, comp: NeonSignComponent, rt: NeonSignRuntime): void {
    this.disposeLettering(entity, rt);
    const ext = comp.extruded ? this.extension() : undefined;
    if (!ext) {
      this.buildLabel(entity, comp, rt);
      return;
    }
    const gen = rt.generation;
    const spec: NeonTextSpec = {
      text: comp.text,
      fontUrl: comp.fontUrl,
      size: comp.size,
      depth: comp.depth,
      position: cloneVec3(comp.position),
      rotation: cloneVec3(comp.rotation),
      color: cloneVec3(comp.color),
      intensity: tubeIntensity(comp.glow),
    };
    ext.create(entity.id, spec).then(
      (meshId) => {
        if (rt.generation !== gen) return; // superseded or torn down meanwhile
        if (meshId === null) {
          this.buildLabel(entity, comp, rt);
          return;
        }
        rt.extruded = true;
        this.eventBus.emit(NeonSignEvents.EXTRUDED, { entityId: entity.id, text: comp.text });
      },
      () => {
        if (rt.generation !== gen) return;
        this.buildLabel(entity, comp, rt);
      },
    );
  }

  private buildLabel(entity: Entity, comp: NeonSignComponent, rt: NeonSignRuntime): void {
    const r = this.world?.renderer;
    if (!r) return;
    rt.label = r.createLabel(entity.id, {
      text: comp.text,
      color: comp.color,
      fontSize: comp.fontSize,
      fontWeight: 'bold',
      scale: comp.size,
      billboard: false,
      rotation: comp.rotation,
    });
    r.setLabelPosition(rt.label, comp.position[0], comp.position[1], comp.position[2]);
  }

  /** Tear down whichever lettering is up, and invalidate any build in flight. */
  private disposeLettering(entity: Entity, rt: NeonSignRuntime): void {
    rt.generation += 1;
    const r = this.world?.renderer;
    if (rt.label) {
      r?.disposeLabel(rt.label);
      rt.label = undefined;
    }
    // Dispose through the plugin whether or not the slab has landed yet: a
    // build still in flight is cancelled by the same call.
    this.extension()?.dispose(entity.id);
    rt.extruded = false;
  }

  private buildLight(entity: Entity, comp: NeonSignComponent, rt: NeonSignRuntime): void {
    const r = this.world?.renderer;
    // glow 0 = tube only. Useful for a sign that shouldn't add to the light
    // budget (a small one, or a room that already has enough lamps).
    if (!r || comp.glow <= 0) return;
    const glowAt = comp.glowPosition();
    if (comp.lightKind === 'spot') {
      rt.light = r.createSpotLight(`${entity.id}_glow`, {
        position: glowAt,
        direction: comp.spotDirection(),
        angle: comp.spotAngle,
        exponent: comp.spotExponent,
        intensity: comp.glow,
        diffuse: cloneVec3(comp.color),
        // A coloured pool on the carpet, not a pinpoint glint on the walls.
        specular: [0, 0, 0],
        range: comp.range,
      });
      return;
    }
    rt.light = r.createPointLight(`${entity.id}_glow`, {
      position: glowAt,
      diffuse: comp.color,
      intensity: comp.glow,
      range: comp.range,
    });
  }

  private disposeLight(rt: NeonSignRuntime): void {
    if (!rt.light) return;
    this.world?.renderer?.disposeLight(rt.light);
    rt.light = undefined;
  }
}
export { NeonSignEvents } from './NeonSign.events';

adapter/NeonSign.babylon.ts

NeonSign.babylon.ts — the Babylon adapter plugin for NeonSign's extruded lettering.

The one place in this bundle allowed to import the engine. Builds each sign's words as real slab geometry with MeshBuilder.CreateText (Babylon's font-outline extruder, which needs a facetype.js font JSON and the earcut triangulator) on the adapter's live scene, reached through the getScene() host accessor, and dresses it in an unlit emissive PBR material so the tubes read as light sources rather than lit plastic.

Bootstrap once, right after creating the Babylon adapter:

const adapter = new BabylonAdapter(); await registerBabylonNeonTextExtension(adapter); // adapter/register.ts const game = new ArcadeGame(adapter, ...); // any NeonSign with extruded: true now gets real lettering.

The font is fetched once per URL and shared: nine signs on one font cost one request. Where the font cannot be had, create resolves null and the System falls back to its label quad — nothing here throws.

earcut only enters a bundle through this file, i.e. when a host imports the plugin; the main @babylonjsmarket/arcade entry stays clear of it.

adapter/NeonSign.babylon.ts

import { Color3, MeshBuilder, PBRMaterial } from '@babylonjs/core';
import type { IFontData, Mesh, Scene } from '@babylonjs/core';
import earcut from 'earcut';
import { extrudedTextTransform, type NeonTextExtension, type NeonTextSpec } from '../NeonSign.core';

/** The host surface the plugin needs from a Babylon adapter. */
export interface BabylonNeonTextHost {
  getScene(): Scene | null;
}

export interface BabylonNeonTextOptions {
  /**
   * How a font URL becomes font data. Defaults to `fetch` + `.json()`;
   * injectable so a test (or a host with its fonts bundled) can skip the
   * network.
   */
  fetchFont?: (url: string) => Promise<IFontData | null>;
}

/** Glyph outlines resolution handed to CreateText — the old room's setting. */
const TEXT_RESOLUTION = 8;

async function fetchFontJson(url: string): Promise<IFontData | null> {
  const res = await fetch(url, { cache: 'force-cache' });
  return res.ok ? ((await res.json()) as IFontData) : null;
}

Build the plugin for one host. Kept separate from registration so a test can drive create/setColor/dispose directly against a fake scene.

adapter/NeonSign.babylon.ts

export function createBabylonNeonText(
  host: BabylonNeonTextHost,
  opts: BabylonNeonTextOptions = {},
): NeonTextExtension {
  const fetchFont = opts.fetchFont ?? fetchFontJson;
  // One in-flight-or-done promise per URL. A failure is cached too: nine
  // signs asking for a font that isn't there should fail once, not nine times.
  const fonts = new Map<string, Promise<IFontData | null>>();
  const meshes = new Map<string, Mesh>();
  // Per-id build sequence. A `create` that was overtaken by a newer `create`
  // or a `dispose` while it awaited the font builds nothing — otherwise a
  // sign removed mid-load would leave an orphan slab on the wall.
  const seqs = new Map<string, number>();

  const loadFont = (url: string): Promise<IFontData | null> => {
    let p = fonts.get(url);
    if (!p) {
      p = fetchFont(url).catch(() => null);
      fonts.set(url, p);
    }
    return p;
  };

  const bump = (id: string): number => {
    const seq = (seqs.get(id) ?? 0) + 1;
    seqs.set(id, seq);
    return seq;
  };

  const dispose = (id: string): void => {
    bump(id);
    const mesh = meshes.get(id);
    if (!mesh) return;
    mesh.material?.dispose();
    mesh.dispose();
    meshes.delete(id);
  };

  return {
    async create(id: string, spec: NeonTextSpec): Promise<string | null> {
      const seq = bump(id);
      const font = await loadFont(spec.fontUrl);
      if (seqs.get(id) !== seq) return null; // overtaken while the font loaded
      const scene = host.getScene();
      // Replace whatever this id had before; `dispose` bumps the sequence,
      // so re-stamp ours afterwards.
      dispose(id);
      seqs.set(id, seq);
      if (!font || !scene || !spec.text) return null;

      const mesh = MeshBuilder.CreateText(
        `${id}_neonText`,
        spec.text,
        font,
        { size: spec.size, resolution: TEXT_RESOLUTION, depth: spec.depth },
        scene,
        earcut,
      );
      if (!mesh) return null;

      // CreateText bakes a -π/2 X-rotation in so the letters stand upright,
      // centred on the origin with the readable face at local +Z (in this
      // right-handed scene — the old left-handed room saw the mirror image).
      // The core's transform yaws the slab to the sign's facing and pushes it
      // out of the wall by half its depth so the front stands proud.
      const t = extrudedTextTransform(spec.position, spec.rotation[1], spec.depth);
      mesh.rotation.y = t.rotationY;
      mesh.position.set(t.position[0], t.position[1], t.position[2]);

      const mat = new PBRMaterial(`${id}_neonText_mat`, scene);
      mat.albedoColor = Color3.Black();
      mat.emissiveColor = new Color3(spec.color[0], spec.color[1], spec.color[2]);
      mat.emissiveIntensity = spec.intensity;
      mat.unlit = true;
      mat.backFaceCulling = true;
      mat.maxSimultaneousLights = 6;
      mesh.material = mat;
      // A sign is scenery: it must not sit in front of a cabinet's click.
      mesh.isPickable = false;

      meshes.set(id, mesh);
      return mesh.name;
    },

    setColor(id: string, color: [number, number, number], intensity: number): void {
      const mat = meshes.get(id)?.material as PBRMaterial | null | undefined;
      if (!mat) return;
      mat.emissiveColor = new Color3(color[0], color[1], color[2]);
      mat.emissiveIntensity = intensity;
    },

    dispose,
  };
}

adapter/register.ts

Called once at bootstrap and awaited before the scene loads. Switches on the adapter's kind: only the full Babylon adapter has a scene to extrude text into, so a Lite or Three host registers nothing and every extruded sign quietly draws its label quad instead. The parameter is the minimal host surface, not the whole RendererAdapter — getScene() is a Babylon-only accessor and shouldn't widen the interface.

The kind check runs FIRST and the Babylon half is imported only after it passes, so a Lite or Three game never downloads @babylonjs/core for it.

adapter/register.ts

import { NEON_TEXT_EXTENSION } from '../NeonSign.core';
import type { BabylonNeonTextHost, BabylonNeonTextOptions } from './NeonSign.babylon';

/** The slice of a renderer adapter this plugin registers against. */
export interface NeonTextHost extends Partial<BabylonNeonTextHost> {
  readonly kind: string;
  registerExtension(name: string, impl: object): void;
}

Register the extruded-text plugin. Idempotent — a second call just replaces the impl. On a non-Babylon host this is a no-op that loads nothing.

adapter/register.ts

export async function registerBabylonNeonTextExtension(
  host: NeonTextHost,
  opts: BabylonNeonTextOptions = {},
): Promise<void> {
  if (host.kind !== 'babylon' || typeof host.getScene !== 'function') return;
  const { createBabylonNeonText } = await import('./NeonSign.babylon');
  host.registerExtension(
    NEON_TEXT_EXTENSION,
    createBabylonNeonText({ getScene: () => host.getScene!() }, opts),
  );
}

NeonSign.contract.test.ts

12 ✓

ArcadeECS contract: NeonSign

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

NeonSign.contract.test.ts

import { NeonSignEvents } from './NeonSign.events';
import { runMechanicContract } from '@babylonjsmarket/ecs/testing';
import { NeonSignComponent, NeonSignSystem } from './NeonSign';

runMechanicContract({
  name: 'NeonSign',
  componentClass: NeonSignComponent,
  systemClass: NeonSignSystem,
  sampleInput: { text: 'PLAY', color: [0.15, 0.9, 1], size: 0.4, glow: 3, lightKind: 'spot' },
  events: {
    // TEXT_CHANGED / COLOR_CHANGED need a later mutation and EXTRUDED needs
    // the adapter plugin; NeonSign.test.ts covers those.
    output: [NeonSignEvents.CREATED],
  },
});

NeonSign.core.test.ts

5 ✓

NeonSign.core

names the extension the System looks up
signNormal faces +Z at yaw 0 and +X at yaw π/2
spotDirection aims along the facing, tilted 0.4 down, unit length
extrudedTextTransform pushes the slab out by depth/2 + 1 cm and keeps the sign's own yaw
sameTriple compares within an epsilon and treats undefined as different

Last run 2026-10-08

NeonSign.core.test.ts

import { describe, expect, it } from 'vitest';
import {
  NEON_TEXT_EXTENSION,
  extrudedTextTransform,
  sameTriple,
  signNormal,
  spotDirection,
} from './NeonSign.core';

describe('NeonSign.core', () => {
  it('names the extension the System looks up', () => {
    expect(NEON_TEXT_EXTENSION).toBe('neonText');
  });

  it('signNormal faces +Z at yaw 0 and +X at yaw π/2', () => {
    expect(signNormal(0)).toEqual([0, 0, 1]);
    const n = signNormal(Math.PI / 2);
    expect(n[0]).toBeCloseTo(1, 10);
    expect(n[2]).toBeCloseTo(0, 10);
  });

  it('spotDirection aims along the facing, tilted 0.4 down, unit length', () => {
    const d = spotDirection(0);
    const len = Math.hypot(1, 0.4);
    expect(d[0]).toBeCloseTo(0, 10);
    expect(d[1]).toBeCloseTo(-0.4 / len, 10);
    expect(d[2]).toBeCloseTo(1 / len, 10);
    expect(Math.hypot(d[0], d[1], d[2])).toBeCloseTo(1, 10);
    // A sign on the right wall (facing -X) throws its light toward -X.
    const left = spotDirection(-Math.PI / 2);
    expect(left[0]).toBeCloseTo(-1 / len, 10);
    expect(left[1]).toBeCloseTo(-0.4 / len, 10);
  });

  it('extrudedTextTransform pushes the slab out by depth/2 + 1 cm and keeps the sign\'s own yaw', () => {
    const t = extrudedTextTransform([0, 2.75, -5.86], 0, 0.088);
    expect(t.position[0]).toBeCloseTo(0, 10);
    expect(t.position[1]).toBeCloseTo(2.75, 10);
    expect(t.position[2]).toBeCloseTo(-5.86 + 0.044 + 0.01, 10);
    // No half-turn: the extruded text's readable face is local +Z, the side
    // signNormal(yaw) points. A +π here shows the slab's back — mirrored
    // lettering in a right-handed scene (the old left-handed room's constant).
    expect(t.rotationY).toBeCloseTo(0, 10);
    const side = extrudedTextTransform([5.86, 1.95, 3.8], -Math.PI / 2, 0.088);
    expect(side.position[0]).toBeCloseTo(5.86 - 0.054, 10);
    expect(side.rotationY).toBeCloseTo(-Math.PI / 2, 10);
  });

  it('sameTriple compares within an epsilon and treats undefined as different', () => {
    expect(sameTriple([1, 2, 3], [1, 2, 3])).toBe(true);
    expect(sameTriple([1, 2, 3], [1, 2, 3.0000001])).toBe(true);
    expect(sameTriple([1, 2, 3], [1, 2, 3.1])).toBe(false);
    expect(sameTriple([1, 2, 3], [1, 2.1, 3])).toBe(false);
    expect(sameTriple([1, 2, 3], [1.1, 2, 3])).toBe(false);
    expect(sameTriple(undefined, [1, 2, 3])).toBe(false);
  });
});

NeonSign.test.ts

34 ✓

NeonSignComponent

defaults to hot pink with a point-light glow, a flat quad, and the neon font
puts the glow in FRONT of a sign facing +Z
follows the sign’s facing when it is on a side wall
aims a spot along the facing and 0.4 down
serialize round-trips, new fields included

NeonSignSystem

draws the words as a WORLD-FIXED label, not a billboard
gives the sign a light of the SAME colour as its lettering
lightKind "spot" throws a cone from in front of the sign, aimed along its facing and tilted down
glow 0 makes a tube-only sign — no light added to the budget
emits CREATED once, and does not rebuild on later frames
re-letters the sign when its text changes
stays quiet while nothing changes
disposes both halves when the sign goes away
builds signs that existed before the world was initialized
stays inert with no renderer

NeonSignSystem › live edits

recolours lettering AND light together, and says so
moves the label and the light when the sign is moved
a turned sign rebuilds its label (no label rotate) and re-aims its spot
a resized sign re-rasterises at the new scale
a glow change retunes the light in place
glow to 0 removes the light; back above 0 brings it back
switching lightKind swaps the light; a range or cone change rebuilds it too
a glowOffset change moves the light, not the lettering
a fontSize or fontUrl change rebuilds the lettering

NeonSignSystem — extruded lettering

with NO plugin registered, an extruded sign quietly draws the label quad
with the plugin, builds the slab from the sign’s fields and emits EXTRUDED
the tube is never dimmer than lit: glow 0 still extrudes at intensity 1
falls back to the label when the plugin cannot build (null), and when it rejects
a recolour or glow change on a live slab goes through setColor, not a rebuild
new text, size, depth or a move re-extrudes the slab
turning extruded off swaps the slab for the quad, and on again swaps back
a build that lands after the sign was rebuilt is dropped
a build that lands after the sign was removed is dropped, and a rejection too
removing an extruded sign disposes the slab through the plugin and the light

Last run 2026-10-08

NeonSign.test.ts

import { beforeEach, describe, expect, it, vi } from 'vitest';
import { EventBus, MockRendererAdapter, World } from '@babylonjsmarket/ecs';
import { NeonSignEvents } from './NeonSign.events';
import {
  NEON_TEXT_EXTENSION,
  NeonSignComponent,
  NeonSignSystem,
  type NeonTextExtension,
  type NeonTextSpec,
} from './NeonSign';

/** Flush the microtasks a plugin `create` resolves through. */
const flush = async () => {
  await Promise.resolve();
  await Promise.resolve();
  await Promise.resolve();
};

describe('NeonSignComponent', () => {
  it('defaults to hot pink with a point-light glow, a flat quad, and the neon font', () => {
    const c = new NeonSignComponent();
    expect(c.color).toEqual([1, 0.15, 0.55]);
    expect(c.glow).toBeGreaterThan(0);
    expect(c.lightKind).toBe('point');
    expect(c.spotAngle).toBeCloseTo(Math.PI * 0.95, 10);
    expect(c.spotExponent).toBe(2);
    expect(c.extruded).toBe(false);
    expect(c.depth).toBe(0.08);
    expect(c.fontUrl).toBe('/fonts/neon.json');
  });

  it('puts the glow in FRONT of a sign facing +Z', () => {
    const c = new NeonSignComponent({ position: [0, 2.5, -5], rotation: [0, 0, 0], glowOffset: 0.4 });
    const g = c.glowPosition();
    expect(g[0]).toBeCloseTo(0, 5);
    expect(g[1]).toBeCloseTo(2.5, 5);
    expect(g[2]).toBeCloseTo(-4.6, 5); // +Z of the wall, i.e. into the room
  });

  it('follows the sign’s facing when it is on a side wall', () => {
    const c = new NeonSignComponent({
      position: [-6, 2.5, 0],
      rotation: [0, Math.PI / 2, 0],
      glowOffset: 0.5,
    });
    const g = c.glowPosition();
    expect(g[0]).toBeCloseTo(-5.5, 5); // pushed along +X, into the room
    expect(g[2]).toBeCloseTo(0, 5);
  });

  it('aims a spot along the facing and 0.4 down', () => {
    const c = new NeonSignComponent({ rotation: [0, Math.PI / 2, 0] });
    const d = c.spotDirection();
    const len = Math.hypot(1, 0.4);
    expect(d[0]).toBeCloseTo(1 / len, 10);
    expect(d[1]).toBeCloseTo(-0.4 / len, 10);
    expect(d[2]).toBeCloseTo(0, 10);
  });

  it('serialize round-trips, new fields included', () => {
    const c = new NeonSignComponent({
      text: "BJ's Arcade",
      color: [0.1, 0.9, 1],
      size: 0.6,
      lightKind: 'spot',
      spotAngle: 2.5,
      spotExponent: 1,
      extruded: true,
      depth: 0.05,
      fontUrl: '/fonts/other.json',
    });
    const out = c.serialize();
    expect(out).toMatchObject({ lightKind: 'spot', spotAngle: 2.5, spotExponent: 1, extruded: true, depth: 0.05, fontUrl: '/fonts/other.json' });
    expect(new NeonSignComponent(out).serialize()).toEqual(out);
  });
});

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

  const calls = (method: string) => renderer.calls.filter((c) => c.method === method);

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

  const sign = (input = {}) => {
    const e = world.createEntity();
    e.add(new NeonSignComponent({ text: "BJ's Arcade", ...input }));
    world.update(1 / 60);
    return e;
  };

  it('draws the words as a WORLD-FIXED label, not a billboard', () => {
    // A sign screwed to a wall must not swivel to follow the camera.
    sign({ rotation: [0, Math.PI, 0] });
    const call = calls('createLabel')[0];
    const spec = call.args[1] as { text: string; billboard: boolean; rotation: number[] };
    expect(spec.text).toBe("BJ's Arcade");
    expect(spec.billboard).toBe(false);
    expect(spec.rotation).toEqual([0, Math.PI, 0]);
  });

  it('gives the sign a light of the SAME colour as its lettering', () => {
    sign({ color: [0.15, 0.9, 1] });
    const label = calls('createLabel')[0];
    const light = calls('createPointLight')[0];
    expect((label.args[1] as { color: number[] }).color).toEqual([0.15, 0.9, 1]);
    expect((light.args[1] as { diffuse: number[] }).diffuse).toEqual([0.15, 0.9, 1]);
  });

  it('lightKind "spot" throws a cone from in front of the sign, aimed along its facing and tilted down', () => {
    const e = sign({
      position: [-5.86, 1.95, -3.8],
      rotation: [0, Math.PI / 2, 0],
      glowOffset: 0.4,
      color: [1, 0.15, 0.55],
      glow: 3,
      range: 10,
      lightKind: 'spot',
      spotAngle: Math.PI * 0.95,
      spotExponent: 2,
    });
    expect(calls('createPointLight')).toHaveLength(0);
    const spot = calls('createSpotLight')[0];
    expect(spot.args[0]).toBe(`${e.id}_glow`);
    const spec = spot.args[1] as {
      position: number[]; direction: number[]; angle: number; exponent: number;
      intensity: number; diffuse: number[]; specular: number[]; range: number;
    };
    expect(spec.position[0]).toBeCloseTo(-5.46, 5); // 0.4 m off the wall, into the room
    expect(spec.position[1]).toBeCloseTo(1.95, 5);
    const len = Math.hypot(1, 0.4);
    expect(spec.direction[0]).toBeCloseTo(1 / len, 5);
    expect(spec.direction[1]).toBeCloseTo(-0.4 / len, 5);
    expect(spec.angle).toBeCloseTo(Math.PI * 0.95, 10);
    expect(spec.exponent).toBe(2);
    expect(spec.intensity).toBe(3);
    expect(spec.diffuse).toEqual([1, 0.15, 0.55]);
    expect(spec.specular).toEqual([0, 0, 0]);
    expect(spec.range).toBe(10);
  });

  it('glow 0 makes a tube-only sign — no light added to the budget', () => {
    sign({ glow: 0 });
    expect(calls('createPointLight')).toHaveLength(0);
    expect(calls('createSpotLight')).toHaveLength(0);
    expect(calls('createLabel')).toHaveLength(1);
  });

  it('emits CREATED once, and does not rebuild on later frames', () => {
    const spy = vi.fn();
    eventBus.on(NeonSignEvents.CREATED, spy);
    sign();
    world.update(1 / 60);
    world.update(1 / 60);
    expect(spy).toHaveBeenCalledTimes(1);
    expect(calls('createLabel')).toHaveLength(1);
  });

  it('re-letters the sign when its text changes', () => {
    const e = sign({ text: 'OPEN' });
    const spy = vi.fn();
    eventBus.on(NeonSignEvents.TEXT_CHANGED, spy);
    e.get(NeonSignComponent)!.text = 'CLOSED';
    world.update(1 / 60);
    // New text is new geometry: the old label goes, a fresh one is rasterised.
    expect(calls('disposeLabel')).toHaveLength(1);
    expect((calls('createLabel').at(-1)!.args[1] as { text: string }).text).toBe('CLOSED');
    expect(spy).toHaveBeenCalledTimes(1);
    expect(spy).toHaveBeenCalledWith({ entityId: e.id, text: 'CLOSED' });
  });

  it('stays quiet while nothing changes', () => {
    sign();
    renderer.calls.length = 0;
    world.update(1 / 60);
    world.update(1 / 60);
    expect(renderer.calls).toHaveLength(0);
  });

  describe('live edits', () => {
    it('recolours lettering AND light together, and says so', () => {
      const e = sign({ color: [1, 0.15, 0.55] });
      const spy = vi.fn();
      eventBus.on(NeonSignEvents.COLOR_CHANGED, spy);
      renderer.calls.length = 0;
      e.get(NeonSignComponent)!.color = [0.15, 0.9, 1];
      world.update(1 / 60);
      expect(calls('setLabelColor')[0].args.slice(1)).toEqual([0.15, 0.9, 1]);
      expect(calls('setLightColor')[0].args.slice(1)).toEqual([0.15, 0.9, 1]);
      expect(calls('createLabel')).toHaveLength(0); // a recolour is not a rebuild
      expect(spy).toHaveBeenCalledWith({ entityId: e.id, color: [0.15, 0.9, 1] });
    });

    it('moves the label and the light when the sign is moved', () => {
      const e = sign({ position: [0, 2, -5], glowOffset: 0.4 });
      renderer.calls.length = 0;
      e.get(NeonSignComponent)!.position = [1, 2.5, -5];
      world.update(1 / 60);
      expect(calls('setLabelPosition')[0].args.slice(1)).toEqual([1, 2.5, -5]);
      const light = calls('setLightPosition')[0].args.slice(1) as number[];
      expect(light[0]).toBeCloseTo(1, 5);
      expect(light[2]).toBeCloseTo(-4.6, 5);
      expect(calls('createLabel')).toHaveLength(0);
    });

    it('a turned sign rebuilds its label (no label rotate) and re-aims its spot', () => {
      const e = sign({ rotation: [0, 0, 0], lightKind: 'spot' });
      renderer.calls.length = 0;
      e.get(NeonSignComponent)!.rotation = [0, Math.PI / 2, 0];
      world.update(1 / 60);
      expect(calls('disposeLabel')).toHaveLength(1);
      expect((calls('createLabel')[0].args[1] as { rotation: number[] }).rotation).toEqual([0, Math.PI / 2, 0]);
      const dir = calls('setLightDirection')[0].args.slice(1) as number[];
      expect(dir[0]).toBeCloseTo(1 / Math.hypot(1, 0.4), 5);
      expect(calls('setLightPosition')).toHaveLength(1);
      expect(calls('createSpotLight')).toHaveLength(0);
    });

    it('a resized sign re-rasterises at the new scale', () => {
      const e = sign({ size: 0.4 });
      renderer.calls.length = 0;
      e.get(NeonSignComponent)!.size = 0.8;
      world.update(1 / 60);
      expect((calls('createLabel')[0].args[1] as { scale: number }).scale).toBe(0.8);
    });

    it('a glow change retunes the light in place', () => {
      const e = sign({ glow: 3 });
      renderer.calls.length = 0;
      e.get(NeonSignComponent)!.glow = 6;
      world.update(1 / 60);
      expect(calls('updateLightIntensity')[0].args[1]).toBe(6);
      expect(calls('createPointLight')).toHaveLength(0);
    });

    it('glow to 0 removes the light; back above 0 brings it back', () => {
      const e = sign({ glow: 3 });
      renderer.calls.length = 0;
      e.get(NeonSignComponent)!.glow = 0;
      world.update(1 / 60);
      expect(calls('disposeLight')).toHaveLength(1);
      e.get(NeonSignComponent)!.glow = 2;
      world.update(1 / 60);
      expect(calls('createPointLight')).toHaveLength(1);
      expect((calls('createPointLight')[0].args[1] as { intensity: number }).intensity).toBe(2);
    });

    it('switching lightKind swaps the light; a range or cone change rebuilds it too', () => {
      const e = sign({ lightKind: 'point', range: 7 });
      renderer.calls.length = 0;
      const c = e.get(NeonSignComponent)!;
      c.lightKind = 'spot';
      world.update(1 / 60);
      expect(calls('disposeLight')).toHaveLength(1);
      expect(calls('createSpotLight')).toHaveLength(1);
      c.range = 12;
      world.update(1 / 60);
      expect(calls('createSpotLight')).toHaveLength(2);
      expect((calls('createSpotLight')[1].args[1] as { range: number }).range).toBe(12);
      c.spotAngle = 1;
      world.update(1 / 60);
      expect(calls('createSpotLight')).toHaveLength(3);
      c.spotExponent = 5;
      world.update(1 / 60);
      expect(calls('createSpotLight')).toHaveLength(4);
      expect(calls('disposeLight')).toHaveLength(4);
    });

    it('a glowOffset change moves the light, not the lettering', () => {
      const e = sign({ glowOffset: 0.35 });
      renderer.calls.length = 0;
      e.get(NeonSignComponent)!.glowOffset = 1;
      world.update(1 / 60);
      expect(calls('setLightPosition')).toHaveLength(1);
      expect(calls('setLabelPosition')).toHaveLength(0);
    });

    it('a fontSize or fontUrl change rebuilds the lettering', () => {
      const e = sign({ fontSize: 96 });
      renderer.calls.length = 0;
      e.get(NeonSignComponent)!.fontSize = 128;
      world.update(1 / 60);
      expect(calls('createLabel')).toHaveLength(1);
      e.get(NeonSignComponent)!.fontUrl = '/fonts/other.json';
      world.update(1 / 60);
      expect(calls('createLabel')).toHaveLength(2);
    });
  });

  it('disposes both halves when the sign goes away', () => {
    const e = sign();
    world.removeEntity(e.id);
    world.update(1 / 60);
    expect(calls('disposeLabel')).toHaveLength(1);
    expect(calls('disposeLight')).toHaveLength(1);
  });

  it('builds signs that existed before the world was initialized', () => {
    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 NeonSignComponent({ text: 'PLAY' }));
    w.addSystem(new NeonSignSystem(bus));
    w.initialize();
    expect(r.calls.filter((c) => c.method === 'createLabel')).toHaveLength(1);
    expect(e.get(NeonSignComponent)!.text).toBe('PLAY');
  });

  it('stays inert with no renderer', () => {
    const bus = new EventBus();
    const w = new World({ eventBus: bus, detectRaces: false });
    w.addSystem(new NeonSignSystem(bus));
    w.initialize();
    const e = w.createEntity();
    e.add(new NeonSignComponent({ text: 'X' }));
    expect(() => { w.update(1 / 60); w.update(1 / 60); }).not.toThrow();
    e.get(NeonSignComponent)!.text = 'Y';
    expect(() => w.update(1 / 60)).not.toThrow();
    expect(() => w.removeEntity(e.id)).not.toThrow();
  });
});

describe('NeonSignSystem — extruded lettering', () => {
  let eventBus: EventBus;
  let world: World;
  let renderer: MockRendererAdapter;
  const calls = (method: string) => renderer.calls.filter((c) => c.method === method);

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

  /** A recording plugin whose `create` resolves to what the test decides. */
  function fakePlugin(result: string | null | Error = 'mesh') {
    const created: { id: string; spec: NeonTextSpec }[] = [];
    const colours: { id: string; color: number[]; intensity: number }[] = [];
    const disposed: string[] = [];
    const ext: NeonTextExtension & { result: string | null | Error } = {
      result,
      create: vi.fn(async (id: string, spec: NeonTextSpec) => {
        created.push({ id, spec });
        if (ext.result instanceof Error) throw ext.result;
        return ext.result;
      }),
      setColor: vi.fn((id: string, color: [number, number, number], intensity: number) => {
        colours.push({ id, color, intensity });
      }),
      dispose: vi.fn((id: string) => {
        disposed.push(id);
      }),
    };
    renderer.registerExtension(NEON_TEXT_EXTENSION, ext);
    return { ext, created, colours, disposed };
  }

  const extrudedSign = (input = {}) => {
    const e = world.createEntity();
    e.add(new NeonSignComponent({ text: 'PLAY', extruded: true, ...input }));
    world.update(1 / 60);
    return e;
  };

  it('with NO plugin registered, an extruded sign quietly draws the label quad', () => {
    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
    const extruded = vi.fn();
    eventBus.on(NeonSignEvents.EXTRUDED, extruded);
    extrudedSign();
    world.update(1 / 60);
    expect(calls('createLabel')).toHaveLength(1);
    expect(extruded).not.toHaveBeenCalled();
    expect(warn).not.toHaveBeenCalled(); // silent by design — the quad IS the sign
    warn.mockRestore();
  });

  it('with the plugin, builds the slab from the sign’s fields and emits EXTRUDED', async () => {
    const { created } = fakePlugin('Neon_neonText');
    const extruded = vi.fn();
    eventBus.on(NeonSignEvents.EXTRUDED, extruded);
    const e = extrudedSign({
      color: [0.75, 0.3, 1],
      position: [5.86, 2.75, 0],
      rotation: [0, -Math.PI / 2, 0],
      size: 0.4,
      depth: 0.088,
      glow: 3,
      fontUrl: '/fonts/neon.json',
    });
    await flush();
    expect(created).toHaveLength(1);
    expect(created[0].id).toBe(e.id);
    expect(created[0].spec).toEqual({
      text: 'PLAY',
      fontUrl: '/fonts/neon.json',
      size: 0.4,
      depth: 0.088,
      position: [5.86, 2.75, 0],
      rotation: [0, -Math.PI / 2, 0],
      color: [0.75, 0.3, 1],
      intensity: 3,
    });
    expect(calls('createLabel')).toHaveLength(0); // real geometry, no quad
    expect(extruded).toHaveBeenCalledWith({ entityId: e.id, text: 'PLAY' });
  });

  it('the tube is never dimmer than lit: glow 0 still extrudes at intensity 1', async () => {
    const { created } = fakePlugin();
    extrudedSign({ glow: 0 });
    await flush();
    expect(created[0].spec.intensity).toBe(1);
  });

  it('falls back to the label when the plugin cannot build (null), and when it rejects', async () => {
    const plugin = fakePlugin(null);
    const extruded = vi.fn();
    eventBus.on(NeonSignEvents.EXTRUDED, extruded);
    extrudedSign();
    await flush();
    expect(calls('createLabel')).toHaveLength(1);
    expect(extruded).not.toHaveBeenCalled();

    plugin.ext.result = new Error('font exploded');
    extrudedSign({ text: 'ENTER' });
    await flush();
    expect(calls('createLabel')).toHaveLength(2);
    expect(extruded).not.toHaveBeenCalled();
  });

  it('a recolour or glow change on a live slab goes through setColor, not a rebuild', async () => {
    const { ext, colours } = fakePlugin();
    const e = extrudedSign({ color: [1, 0.15, 0.55], glow: 3 });
    await flush();
    const c = e.get(NeonSignComponent)!;
    c.color = [0.15, 0.9, 1];
    world.update(1 / 60);
    expect(colours).toEqual([{ id: e.id, color: [0.15, 0.9, 1], intensity: 3 }]);
    c.glow = 6;
    world.update(1 / 60);
    expect(colours.at(-1)).toEqual({ id: e.id, color: [0.15, 0.9, 1], intensity: 6 });
    expect(ext.create).toHaveBeenCalledTimes(1);
  });

  it('new text, size, depth or a move re-extrudes the slab', async () => {
    const { ext, disposed } = fakePlugin();
    const e = extrudedSign();
    await flush();
    const c = e.get(NeonSignComponent)!;
    c.text = 'WIN';
    world.update(1 / 60);
    await flush();
    expect(ext.create).toHaveBeenCalledTimes(2);
    expect(disposed).toEqual([e.id, e.id]); // the first build's clean-up, then the rebuild's
    c.depth = 0.2;
    world.update(1 / 60);
    await flush();
    expect(ext.create).toHaveBeenCalledTimes(3);
    c.position = [1, 2, 3];
    world.update(1 / 60);
    await flush();
    expect(ext.create).toHaveBeenCalledTimes(4);
    expect(calls('createLabel')).toHaveLength(0);
  });

  it('turning extruded off swaps the slab for the quad, and on again swaps back', async () => {
    const { ext } = fakePlugin();
    const e = extrudedSign();
    await flush();
    const c = e.get(NeonSignComponent)!;
    c.extruded = false;
    world.update(1 / 60);
    expect(calls('createLabel')).toHaveLength(1);
    c.extruded = true;
    world.update(1 / 60);
    await flush();
    expect(calls('disposeLabel')).toHaveLength(1);
    expect(ext.create).toHaveBeenCalledTimes(2);
  });

  it('a build that lands after the sign was rebuilt is dropped', async () => {
    let release!: (v: string | null) => void;
    const first = new Promise<string | null>((r) => (release = r));
    const ext: NeonTextExtension = {
      create: vi.fn()
        .mockReturnValueOnce(first)
        .mockResolvedValue('mesh'),
      setColor: vi.fn(),
      dispose: vi.fn(),
    };
    renderer.registerExtension(NEON_TEXT_EXTENSION, ext);
    const extruded = vi.fn();
    eventBus.on(NeonSignEvents.EXTRUDED, extruded);
    const e = extrudedSign();
    e.get(NeonSignComponent)!.text = 'ENTER'; // rebuild while the first is in flight
    world.update(1 / 60);
    await flush();
    expect(extruded).toHaveBeenCalledTimes(1); // the second build
    release(null); // the stale first build resolves as "couldn't" …
    await flush();
    expect(calls('createLabel')).toHaveLength(0); // … and must NOT put up a quad
    expect(extruded).toHaveBeenCalledTimes(1);
  });

  it('a build that lands after the sign was removed is dropped, and a rejection too', async () => {
    let release!: (v: string | null) => void;
    let reject!: (e: Error) => void;
    const pending = new Promise<string | null>((r, j) => {
      release = r;
      reject = j;
    });
    const ext: NeonTextExtension = {
      create: vi.fn().mockReturnValue(pending),
      setColor: vi.fn(),
      dispose: vi.fn(),
    };
    renderer.registerExtension(NEON_TEXT_EXTENSION, ext);
    const extruded = vi.fn();
    eventBus.on(NeonSignEvents.EXTRUDED, extruded);
    const e = extrudedSign();
    world.removeEntity(e.id);
    expect(ext.dispose).toHaveBeenCalledWith(e.id); // cancels the in-flight build
    release('mesh');
    await flush();
    expect(extruded).not.toHaveBeenCalled();
    expect(calls('createLabel')).toHaveLength(0);

    const f = extrudedSign({ text: 'TWO' });
    world.removeEntity(f.id);
    reject(new Error('late'));
    await flush();
    expect(calls('createLabel')).toHaveLength(0);
  });

  it('removing an extruded sign disposes the slab through the plugin and the light', async () => {
    const { disposed } = fakePlugin();
    const e = extrudedSign();
    await flush();
    world.removeEntity(e.id);
    expect(disposed).toContain(e.id);
    expect(calls('disposeLight')).toHaveLength(1);
    expect(calls('disposeLabel')).toHaveLength(0);
  });
});

adapter/NeonSign.babylon.test.ts

12 ✓

createBabylonNeonText — extrudes a sign through MeshBuilder.CreateText

builds the slab with the old room’s CreateText settings and facing correction
fetches a font once per URL, however many signs use it
resolves null — and builds nothing — when the font cannot be had
resolves null with no scene yet, with empty text, and when CreateText declines
a second create under the same id replaces the first slab
setColor recolours the live slab and ignores an unknown id
dispose frees the slab and its material, and is harmless for an unknown id
a dispose while the font is still loading cancels the build — no orphan slab
a newer create overtakes an older one still waiting on its font
uses fetch + json for the font by default

registerBabylonNeonTextExtension

registers the plugin on a Babylon host
registers nothing on a Lite or Three host, or a Babylon host with no scene accessor

Last run 2026-10-08

adapter/NeonSign.babylon.test.ts

import { beforeEach, describe, expect, it, vi } from 'vitest';

// The plugin is the one file allowed to import the engine; the test swaps
// that engine for recording doubles so no WebGL is needed. `vi.hoisted`
// because `vi.mock` is lifted above every import — the fakes must be too.
const { FakeColor3, FakeMaterial, FakeMesh, createText } = vi.hoisted(() => {
  class FakeColor3 {
    constructor(
      public r = 0,
      public g = 0,
      public b = 0,
    ) {}
    static Black() {
      return new FakeColor3(0, 0, 0);
    }
  }
  class FakeMaterial {
    static instances: FakeMaterial[] = [];
    albedoColor: FakeColor3 | null = null;
    emissiveColor: FakeColor3 | null = null;
    emissiveIntensity = 0;
    unlit = false;
    backFaceCulling = false;
    maxSimultaneousLights = 4;
    disposed = false;
    constructor(
      public name: string,
      public scene: unknown,
    ) {
      FakeMaterial.instances.push(this);
    }
    dispose() {
      this.disposed = true;
    }
  }
  class FakeMesh {
    static instances: FakeMesh[] = [];
    rotation = { x: 0, y: 0, z: 0 };
    position = {
      x: 0,
      y: 0,
      z: 0,
      set(x: number, y: number, z: number) {
        this.x = x;
        this.y = y;
        this.z = z;
      },
    };
    material: FakeMaterial | null = null;
    isPickable = true;
    disposed = false;
    constructor(public name: string) {
      FakeMesh.instances.push(this);
    }
    dispose() {
      this.disposed = true;
    }
  }
  const createText = vi.fn((...args: unknown[]) => new FakeMesh(args[0] as string));
  return { FakeColor3, FakeMaterial, FakeMesh, createText };
});
vi.mock('@babylonjs/core', () => ({
  Color3: FakeColor3,
  MeshBuilder: { CreateText: createText },
  PBRMaterial: FakeMaterial,
}));
vi.mock('earcut', () => ({ default: function earcut() { return []; } }));

import { createBabylonNeonText } from './NeonSign.babylon';
import { registerBabylonNeonTextExtension } from './register';
import { NEON_TEXT_EXTENSION, type NeonTextExtension, type NeonTextSpec } from '../NeonSign.core';

const FONT = { glyphs: {}, resolution: 1000 } as never;
const SPEC: NeonTextSpec = {
  text: 'PLAY',
  fontUrl: '/fonts/neon.json',
  size: 0.4,
  depth: 0.088,
  position: [-5.86, 1.95, -3.8],
  rotation: [0, Math.PI / 2, 0],
  color: [1, 0.15, 0.55],
  intensity: 3,
};

/** Resolve-on-demand font loader so a test can hold the fetch open. */
function deferredFont() {
  let resolve!: (f: unknown) => void;
  const promise = new Promise<unknown>((r) => (resolve = r));
  const fetchFont = vi.fn(() => promise as Promise<never>);
  return { fetchFont, resolve };
}

describe('createBabylonNeonText — extrudes a sign through MeshBuilder.CreateText', () => {
  const scene = { id: 'scene' };
  let fetchFont: ReturnType<typeof vi.fn>;
  let ext: NeonTextExtension;

  beforeEach(() => {
    FakeMesh.instances = [];
    FakeMaterial.instances = [];
    createText.mockClear();
    fetchFont = vi.fn(async () => FONT);
    ext = createBabylonNeonText({ getScene: () => scene as never }, { fetchFont });
  });

  it('builds the slab with the old room’s CreateText settings and facing correction', async () => {
    const name = await ext.create('Neon_Middle_0', SPEC);
    expect(name).toBe('Neon_Middle_0_neonText');
    expect(createText).toHaveBeenCalledTimes(1);
    const [meshName, text, font, options, hostScene, earcutRef] = createText.mock.calls[0] as unknown[];
    expect(meshName).toBe('Neon_Middle_0_neonText');
    expect(text).toBe('PLAY');
    expect(font).toBe(FONT);
    expect(options).toEqual({ size: 0.4, resolution: 8, depth: 0.088 });
    expect(hostScene).toBe(scene);
    expect(typeof earcutRef).toBe('function');

    const mesh = FakeMesh.instances[0];
    // The sign's own facing — the extruded text reads on its local +Z, which
    // is where signNormal(yaw) points. (A half-turn here shows the back.)
    expect(mesh.rotation.y).toBeCloseTo(Math.PI / 2, 10);
    // Pushed out from the wall face along +X (the facing) by depth/2 + 1 cm.
    expect(mesh.position.x).toBeCloseTo(-5.86 + 0.044 + 0.01, 10);
    expect(mesh.position.y).toBeCloseTo(1.95, 10);
    expect(mesh.position.z).toBeCloseTo(-3.8, 10);
    expect(mesh.isPickable).toBe(false);

    const mat = mesh.material!;
    expect(mat.name).toBe('Neon_Middle_0_neonText_mat');
    expect(mat.albedoColor).toEqual(new FakeColor3(0, 0, 0));
    expect(mat.emissiveColor).toEqual(new FakeColor3(1, 0.15, 0.55));
    expect(mat.emissiveIntensity).toBe(3);
    expect(mat.unlit).toBe(true);
    expect(mat.backFaceCulling).toBe(true);
    expect(mat.maxSimultaneousLights).toBe(6);
  });

  it('fetches a font once per URL, however many signs use it', async () => {
    await Promise.all([
      ext.create('a', SPEC),
      ext.create('b', SPEC),
      ext.create('c', { ...SPEC, fontUrl: '/fonts/other.json' }),
    ]);
    expect(fetchFont).toHaveBeenCalledTimes(2);
    expect(fetchFont).toHaveBeenCalledWith('/fonts/neon.json');
    expect(fetchFont).toHaveBeenCalledWith('/fonts/other.json');
    expect(FakeMesh.instances).toHaveLength(3);
  });

  it('resolves null — and builds nothing — when the font cannot be had', async () => {
    fetchFont.mockImplementation(async () => null);
    expect(await ext.create('a', SPEC)).toBeNull();
    // A rejected fetch is the same story, and is not retried per sign.
    fetchFont.mockImplementation(async () => {
      throw new Error('404');
    });
    expect(await ext.create('b', { ...SPEC, fontUrl: '/fonts/missing.json' })).toBeNull();
    expect(await ext.create('c', { ...SPEC, fontUrl: '/fonts/missing.json' })).toBeNull();
    expect(fetchFont).toHaveBeenCalledTimes(2);
    expect(createText).not.toHaveBeenCalled();
  });

  it('resolves null with no scene yet, with empty text, and when CreateText declines', async () => {
    const noScene = createBabylonNeonText({ getScene: () => null }, { fetchFont });
    expect(await noScene.create('a', SPEC)).toBeNull();
    expect(await ext.create('b', { ...SPEC, text: '' })).toBeNull();
    createText.mockImplementationOnce(() => null as never);
    expect(await ext.create('c', SPEC)).toBeNull();
    expect(FakeMesh.instances).toHaveLength(0);
  });

  it('a second create under the same id replaces the first slab', async () => {
    await ext.create('a', SPEC);
    await ext.create('a', { ...SPEC, text: 'ENTER' });
    expect(FakeMesh.instances).toHaveLength(2);
    expect(FakeMesh.instances[0].disposed).toBe(true);
    expect(FakeMesh.instances[0].material!.disposed).toBe(true);
    expect(FakeMesh.instances[1].disposed).toBe(false);
  });

  it('setColor recolours the live slab and ignores an unknown id', async () => {
    await ext.create('a', SPEC);
    ext.setColor('a', [0.15, 0.9, 1], 5);
    const mat = FakeMesh.instances[0].material!;
    expect(mat.emissiveColor).toEqual(new FakeColor3(0.15, 0.9, 1));
    expect(mat.emissiveIntensity).toBe(5);
    expect(() => ext.setColor('nobody', [1, 1, 1], 1)).not.toThrow();
  });

  it('dispose frees the slab and its material, and is harmless for an unknown id', async () => {
    await ext.create('a', SPEC);
    ext.dispose('a');
    expect(FakeMesh.instances[0].disposed).toBe(true);
    expect(FakeMesh.instances[0].material!.disposed).toBe(true);
    expect(() => ext.dispose('a')).not.toThrow();
    expect(() => ext.dispose('never')).not.toThrow();
  });

  it('a dispose while the font is still loading cancels the build — no orphan slab', async () => {
    const { fetchFont: slow, resolve } = deferredFont();
    const lazy = createBabylonNeonText({ getScene: () => scene as never }, { fetchFont: slow as never });
    const pending = lazy.create('a', SPEC);
    lazy.dispose('a'); // the sign went away before its font arrived
    resolve(FONT);
    expect(await pending).toBeNull();
    expect(createText).not.toHaveBeenCalled();
  });

  it('a newer create overtakes an older one still waiting on its font', async () => {
    const { fetchFont: slow, resolve } = deferredFont();
    const lazy = createBabylonNeonText({ getScene: () => scene as never }, { fetchFont: slow as never });
    const first = lazy.create('a', SPEC);
    const second = lazy.create('a', { ...SPEC, text: 'ENTER' });
    resolve(FONT);
    expect(await first).toBeNull();
    expect(await second).toBe('a_neonText');
    expect(createText).toHaveBeenCalledTimes(1);
    expect(createText.mock.calls[0][1]).toBe('ENTER');
  });

  it('uses fetch + json for the font by default', async () => {
    const fetchSpy = vi.fn(async () => ({ ok: true, json: async (): Promise<unknown> => FONT }));
    vi.stubGlobal('fetch', fetchSpy);
    try {
      const plain = createBabylonNeonText({ getScene: () => scene as never });
      expect(await plain.create('a', SPEC)).toBe('a_neonText');
      expect(fetchSpy).toHaveBeenCalledWith('/fonts/neon.json', { cache: 'force-cache' });
      // A non-OK response is "no font".
      fetchSpy.mockResolvedValueOnce({ ok: false, json: async () => null });
      expect(await plain.create('b', { ...SPEC, fontUrl: '/fonts/nope.json' })).toBeNull();
    } finally {
      vi.unstubAllGlobals();
    }
  });
});

describe('registerBabylonNeonTextExtension', () => {
  it('registers the plugin on a Babylon host', async () => {
    const registered: Record<string, object> = {};
    const scene = { id: 'scene' };
    await registerBabylonNeonTextExtension(
      {
        kind: 'babylon',
        registerExtension: (name, impl) => {
          registered[name] = impl;
        },
        getScene: () => scene as never,
      },
      { fetchFont: async () => FONT },
    );
    const ext = registered[NEON_TEXT_EXTENSION] as NeonTextExtension;
    expect(ext).toBeDefined();
    expect(await ext.create('a', SPEC)).toBe('a_neonText');
  });

  it('registers nothing on a Lite or Three host, or a Babylon host with no scene accessor', async () => {
    const registerExtension = vi.fn();
    await registerBabylonNeonTextExtension({ kind: 'three', registerExtension });
    await registerBabylonNeonTextExtension({ kind: 'babylon-lite', registerExtension, getScene: () => null });
    await registerBabylonNeonTextExtension({ kind: 'babylon', registerExtension });
    expect(registerExtension).not.toHaveBeenCalled();
  });
});