CameraFollow.core.ts

CameraFollow core — pure, deterministic, renderer-free.

Given the target's world position each frame, the core returns a smoothed camera-target position that approaches the target exponentially. The curve is frame-rate independent: doubling the frame rate produces the same arc.

Zero imports from @babylonjs, three, solid-js, or the DOM.

CameraFollow.core.ts

export interface CameraFollowParams {
  /**
   * Rate of exponential approach in 1/sec. Higher = snappier.
   * alpha_per_frame = 1 - exp(-smoothing * dt).
   * 0 locks the camera in place (no follow). 6 feels natural; 12 is tight.
   */
  smoothing: number;
  /** Added to target position each frame; useful for looking above the head. */
  offsetX: number;
  offsetY: number;
  offsetZ: number;
}

export interface CameraFollowInputs {
  targetX: number;
  targetY: number;
  targetZ: number;
}

export interface CameraFollowOutputs {
  camX: number;
  camY: number;
  camZ: number;
}

export interface CameraFollowInstance {
  update(inputs: CameraFollowInputs, dt: number): CameraFollowOutputs;
  setParams(partial: Partial<CameraFollowParams>): void;
  getParams(): Readonly<CameraFollowParams>;
  /** Snap the internal position to `pos`, or to the origin if omitted. */
  reset(pos?: CameraFollowOutputs): void;
}

export const DEFAULT_CAMERA_FOLLOW_PARAMS: CameraFollowParams = {
  smoothing: 6,
  offsetX: 0,
  offsetY: 1.2,
  offsetZ: 0,
};

export function createCameraFollow(
  params: Partial<CameraFollowParams> = {},
  initial: CameraFollowOutputs = { camX: 0, camY: 0, camZ: 0 },
): CameraFollowInstance {
  const active: CameraFollowParams = { ...DEFAULT_CAMERA_FOLLOW_PARAMS, ...params };
  let x = initial.camX;
  let y = initial.camY;
  let z = initial.camZ;

  return {
    update(inputs, dt) {
      const tx = inputs.targetX + active.offsetX;
      const ty = inputs.targetY + active.offsetY;
      const tz = inputs.targetZ + active.offsetZ;

      if (active.smoothing > 0 && dt > 0) {
        const alpha = 1 - Math.exp(-active.smoothing * dt);
        x += (tx - x) * alpha;
        y += (ty - y) * alpha;
        z += (tz - z) * alpha;
      }

      return { camX: x, camY: y, camZ: z };
    },
    setParams(partial) {
      Object.assign(active, partial);
    },
    getParams() {
      return active;
    },
    reset(pos) {
      x = pos?.camX ?? 0;
      y = pos?.camY ?? 0;
      z = pos?.camZ ?? 0;
    },
  };
}

CameraFollow.defs.ts

CameraFollow — definitions.

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

CameraFollow.defs.ts

import { Component } from '@babylonjsmarket/ecs';
import { type CameraFollowInstance, type CameraFollowParams, DEFAULT_CAMERA_FOLLOW_PARAMS } from './CameraFollow.core';

export const CameraFollowEvents = {
  TARGET_CHANGED: 'cameraFollow.targetChanged',
} as const;

export interface CameraFollowInput extends Partial<CameraFollowParams> {
  /** Entity id of the thing to follow. Must own a MeshPrimitive. */
  target?: string;
}

export class CameraFollowComponent extends Component {
  params: CameraFollowParams;
  target: string;
  instance: CameraFollowInstance | null = null;

  constructor(data: CameraFollowInput = {}) {
    super();
    const { target, ...params } = data;
    this.target = target ?? '';
    this.params = { ...DEFAULT_CAMERA_FOLLOW_PARAMS, ...params };
  }

  serialize(): CameraFollowInput {
    return { target: this.target, ...this.params };
  }
}

CameraFollow.panel.tsx

Renderer-free Solid panel for live-tuning CameraFollow params. Binds to the pure core. No imports from @babylonjs or three.

CameraFollow.panel.tsx

import { Component as SolidComponent } from 'solid-js';
import { createStore } from 'solid-js/store';
import { Slider, ResetButton, Section } from '../_shared/ui';
import {
  DEFAULT_CAMERA_FOLLOW_PARAMS,
  type CameraFollowInstance,
  type CameraFollowParams,
} from './CameraFollow.core';

export interface CameraFollowPanelProps {
  core: CameraFollowInstance;
}

export const CameraFollowPanel: SolidComponent<CameraFollowPanelProps> = (props) => {
  const [params, setParams] = createStore<CameraFollowParams>({ ...props.core.getParams() });

  const push = <K extends keyof CameraFollowParams>(key: K, value: CameraFollowParams[K]) => {
    setParams(key, value);
    props.core.setParams({ [key]: value } as Partial<CameraFollowParams>);
  };

  const reset = () => {
    setParams({ ...DEFAULT_CAMERA_FOLLOW_PARAMS });
    props.core.setParams(DEFAULT_CAMERA_FOLLOW_PARAMS);
  };

  return (
    <div style={{ 'font-family': 'system-ui, sans-serif', color: '#ddd', 'min-width': '240px' }}>
      <Section title="Smoothing">
        <Slider
          label="smoothing (1/sec)"
          value={params.smoothing}
          min={0}
          max={30}
          step={0.1}
          onChange={(v) => push('smoothing', v)}
        />
        <div style={{ 'font-size': '11px', color: '#8b949e', 'margin-top': '4px' }}>
          0 = locked · 6 = natural · 20+ = snappy
        </div>
      </Section>

      <Section title="Look-at offset">
        <Slider
          label="offsetY (up/down)"
          value={params.offsetY}
          min={-3}
          max={4}
          step={0.05}
          onChange={(v) => push('offsetY', v)}
        />
        <Slider
          label="offsetX (left/right)"
          value={params.offsetX}
          min={-4}
          max={4}
          step={0.05}
          onChange={(v) => push('offsetX', v)}
        />
        <Slider
          label="offsetZ (forward/back)"
          value={params.offsetZ}
          min={-4}
          max={4}
          step={0.05}
          onChange={(v) => push('offsetZ', v)}
        />
      </Section>

      <ResetButton onClick={reset} />
    </div>
  );
};

CameraFollow.ts

CameraFollow.ts — renderer-agnostic System.

Math lives in CameraFollow.core.ts. This System watches for a target entity (by id) to register its MeshHandle via the meshprimitive.created event, then each frame reads that mesh's world position through the active RendererAdapter and nudges the arc camera's target toward it.

Zero imports from @babylonjs or three; all 3D access goes through world.renderer.

CameraFollow.ts

import { System } from '@babylonjsmarket/ecs';
import type { EventBus } from '@babylonjsmarket/ecs';
import type { Entity } from '@babylonjsmarket/ecs';
import type { CameraHandle, MeshHandle, Vec3 } from '@babylonjsmarket/ecs/renderer-types';
import { ArcCameraComponent } from '../ArcCamera/ArcCamera.defs';
import { MeshPrimitiveComponent } from '../MeshPrimitive/MeshPrimitive.defs';
import { createCameraFollow } from './CameraFollow.core';
import { CameraFollowComponent, CameraFollowEvents } from './CameraFollow.defs';

export class CameraFollowSystem extends System {
  private unsubscribes: Array<() => void> = [];
  private targetHandles = new Map<string, MeshHandle>();
  private primed = new Set<string>();
  private _tmpPos: Vec3 = [0, 0, 0];

  constructor(eventBus: EventBus) {
    super(eventBus);
    this.query = { required: [CameraFollowComponent] };
    this._pauseable = false;
  }

  protected onInitialize(): void {
    this.unsubscribes.push(
      this.eventBus.on(
        'meshprimitive.created',
        (data: { entityId: string; handle: MeshHandle }) => {
          if (data?.entityId && data.handle) {
            this.targetHandles.set(data.entityId, data.handle);
          }
        },
      ),
    );

    // MeshPrimitiveSystem.onEntityAdded runs during world.addSystem and can
    // emit `meshprimitive.created` before this System's subscription above
    // exists. Scan existing entities to pick up anything we missed.
    if (this.world) {
      for (const entity of this.world.getEntities()) {
        const mesh = entity.get(MeshPrimitiveComponent);
        if (mesh?.handle) {
          this.targetHandles.set(entity.id, mesh.handle);
        }
      }
    }

    for (const entity of this.entities) {
      this.ensureInstance(entity);
    }
  }

  protected onShutdown(): void {
    this.unsubscribes.forEach((u) => u());
    this.unsubscribes = [];
    this.targetHandles.clear();
    this.primed.clear();
  }

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

  protected onEntityRemoved(entity: Entity): void {
    this.primed.delete(entity.id);
  }

  private ensureInstance(entity: Entity): void {
    const comp = entity.get(CameraFollowComponent);
    if (!comp || comp.instance) return;
    comp.instance = createCameraFollow(comp.params);
  }

  protected onUpdate(deltaTime: number): void {
    const r = this.world?.renderer;
    if (!r) return;
    const cameraHandle = this.findArcCameraHandle();
    if (!cameraHandle) return;

    for (const entity of this.entities) {
      const comp = entity.get(CameraFollowComponent);
      if (!comp?.instance || !comp.target) continue;

      const targetHandle = this.targetHandles.get(comp.target);
      if (!targetHandle) continue;

      r.getMeshWorldPosition(targetHandle, this._tmpPos);

      // On the first frame we can read the target, snap the core there so
      // the camera doesn't swoop in from the origin.
      if (!this.primed.has(entity.id)) {
        comp.instance.reset({
          camX: this._tmpPos[0] + comp.params.offsetX,
          camY: this._tmpPos[1] + comp.params.offsetY,
          camZ: this._tmpPos[2] + comp.params.offsetZ,
        });
        this.primed.add(entity.id);
      }

      // The core is the source of truth for live params — the panel writes
      // directly to it. Pushing comp.params in here would clobber panel edits
      // each frame.
      const out = comp.instance.update(
        {
          targetX: this._tmpPos[0],
          targetY: this._tmpPos[1],
          targetZ: this._tmpPos[2],
        },
        deltaTime,
      );

      r.setCameraTarget(cameraHandle, out.camX, out.camY, out.camZ);

      this.eventBus.emit(CameraFollowEvents.TARGET_CHANGED, {
        entityId: entity.id,
        camX: out.camX,
        camY: out.camY,
        camZ: out.camZ,
      });
    }
  }

  private findArcCameraHandle(): CameraHandle | undefined {
    if (!this.world) return undefined;
    for (const entity of this.world.getEntities()) {
      const arc = entity.get(ArcCameraComponent);
      if (arc?.handle) return arc.handle;
    }
    return undefined;
  }
}

The definitions live in CameraFollow.defs.ts; re-exported so existing importers keep working. New code should import them from './CameraFollow.defs' directly.

CameraFollow.ts

export { CameraFollowComponent, CameraFollowEvents, type CameraFollowInput } from './CameraFollow.defs';

CameraFollow.viz.tsx

CameraFollow.viz.tsx — ECS wrapper that registers the renderer-free CameraFollowPanel with vizStore. The Panel itself is in CameraFollow.panel.tsx and holds no Babylon/Three imports.

CameraFollow.viz.tsx

import { Component } from '@babylonjsmarket/ecs';
import { System } from '@babylonjsmarket/ecs';
import type { EventBus } from '@babylonjsmarket/ecs';
import type { Entity } from '@babylonjsmarket/ecs';
import { vizStore } from '../_shared/viz';
import { CameraFollowPanel } from './CameraFollow.panel';
import { CameraFollowComponent } from './CameraFollow';
import type { CameraFollowInstance } from './CameraFollow.core';

export interface CameraFollowDebuggerInput {
  visible?: boolean;
  activationKey?: string;
  position?: 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right';
}

export class CameraFollowDebuggerComponent extends Component {
  visible: boolean;
  activationKey: string;
  position: 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right';

  constructor(data: CameraFollowDebuggerInput = {}) {
    super();
    this.visible = data.visible ?? false;
    this.activationKey = data.activationKey ?? 'Digit1';
    this.position = data.position ?? 'top-right';
  }

  serialize(): CameraFollowDebuggerInput {
    return {
      visible: this.visible,
      activationKey: this.activationKey,
      position: this.position,
    };
  }
}

const PANEL_ID = 'camera-follow-debugger';

export class CameraFollowDebuggerSystem extends System {
  private component: CameraFollowDebuggerComponent | null = null;
  private keydownHandler: ((e: KeyboardEvent) => void) | null = null;
  private panelRegistered = false;

  constructor(eventBus: EventBus) {
    super(eventBus);
    this.query = { required: [CameraFollowDebuggerComponent] };
    this._pauseable = false;
  }

  protected onInitialize(): void {
    for (const entity of this.entities) {
      const comp = entity.get(CameraFollowDebuggerComponent);
      if (comp) {
        this.component = comp;
        break;
      }
    }
    this.setupKeyboardListener();
    this.tryRegisterPanel();
  }

  protected onUpdate(_dt: number): void {
    if (!this.panelRegistered) this.tryRegisterPanel();
  }

  private tryRegisterPanel(): void {
    if (this.panelRegistered || !this.component || !this.world) return;
    const core = this.findCoreInstance();
    if (!core) return;

    vizStore.registerPanel({
      id: PANEL_ID,
      title: 'Camera Follow',
      position: this.component.position,
      titleColor: '#66ccff',
      content: () => <CameraFollowPanel core={core} />,
    });

    this.panelRegistered = true;
    if (this.component.visible) {
      vizStore.showPanel(PANEL_ID);
    }
  }

  private findCoreInstance(): CameraFollowInstance | null {
    if (!this.world) return null;
    for (const entity of this.world.getEntities()) {
      const comp = entity.get(CameraFollowComponent);
      if (comp?.instance) return comp.instance;
    }
    return null;
  }

  private setupKeyboardListener(): void {
    if (this.keydownHandler) return;
    this.keydownHandler = (e: KeyboardEvent) => {
      if (!this.component) return;
      if (e.code === this.component.activationKey) {
        e.preventDefault();
        vizStore.togglePanel(PANEL_ID);
        this.component.visible = vizStore.isVisible(PANEL_ID);
      }
    };
    window.addEventListener('keydown', this.keydownHandler);
  }

  protected onEntityAdded(entity: Entity): void {
    const comp = entity.get(CameraFollowDebuggerComponent);
    if (comp && !this.component) {
      this.component = comp;
      this.tryRegisterPanel();
    }
  }

  protected onShutdown(): void {
    vizStore.unregisterPanel(PANEL_ID);
    this.panelRegistered = false;
    if (this.keydownHandler) {
      window.removeEventListener('keydown', this.keydownHandler);
      this.keydownHandler = null;
    }
  }
}

CameraFollow.contract.test.ts

13 ✓

ArcadeECS contract: CameraFollow

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-08-22

CameraFollow.contract.test.ts

import { runMechanicContract } from '@babylonjsmarket/ecs/testing';
import {
  CameraFollowComponent,
  CameraFollowSystem,
  CameraFollowEvents,
} from './CameraFollow';
import { ArcCameraComponent } from '../ArcCamera/ArcCamera.defs';

runMechanicContract({
  name: 'CameraFollow',
  componentClass: CameraFollowComponent,
  systemClass: CameraFollowSystem,
  sampleInput: { offsetY: 5, target: 'Hero' },
  events: {
    // CameraFollow subscribes to 'meshprimitive.created' — declared here so
    // the "Registers a listener for each declared input event" check runs.
    input: ['meshprimitive.created'],
    output: [CameraFollowEvents.TARGET_CHANGED],
  },
  makeInputPayload(event) {
    if (event === 'meshprimitive.created') {
      return { entityId: 'Hero', handle: { __mockHandle: 'mesh:Hero' } };
    }
    return {};
  },
  setup({ world, renderer }) {
    // The mechanic needs: (a) an active ArcCamera handle and (b) a target
    // MeshHandle mapped to the Follow component's `target` id. We pre-create
    // both so the update path doesn't bail before emitting TARGET_CHANGED.
    const arcEntity = world.createEntity();
    const arc = new ArcCameraComponent();
    arc.handle = renderer.createArcCamera(arcEntity.id, arc.toSpec());
    arc.initialized = true;
    arcEntity.add(arc);

    // Stub a world position the mesh handle reports through the adapter.
    const targetHandle = renderer.createMesh('Hero', { kind: 'box' });
    renderer.meshWorldPositions.set(targetHandle, [0, 1, 0]);
    // Announce the mesh so CameraFollowSystem latches onto it under id 'Hero'.
    world.getEventBus().emit('meshprimitive.created', {
      entityId: 'Hero',
      handle: targetHandle,
    });
  },
});

CameraFollow.core.test.ts

8 ✓

CameraFollow core

produces its seeded position when dt is zero
moves toward the target but never past it
adds the configured offset on top of the target position
is frame-rate independent: same total time converges to the same value
setParams changes smoothing on the next update
reset places the camera at the supplied position
zero smoothing locks the camera in place even with a moving target
getParams reflects defaults when none are supplied

Last run 2026-08-22

CameraFollow.core.test.ts

import { describe, it, expect } from 'vitest';
import { createCameraFollow, DEFAULT_CAMERA_FOLLOW_PARAMS } from './CameraFollow.core';

describe('CameraFollow core', () => {
  it('produces its seeded position when dt is zero', () => {
    const f = createCameraFollow({ smoothing: 10, offsetY: 0 }, { camX: 5, camY: 2, camZ: 3 });
    const out = f.update({ targetX: 100, targetY: 100, targetZ: 100 }, 0);
    expect(out.camX).toBe(5);
    expect(out.camY).toBe(2);
    expect(out.camZ).toBe(3);
  });

  it('moves toward the target but never past it', () => {
    const f = createCameraFollow({ smoothing: 6, offsetY: 0 });
    let prev = 0;
    for (let i = 0; i < 600; i++) {
      const out = f.update({ targetX: 10, targetY: 0, targetZ: 0 }, 1 / 60);
      expect(out.camX).toBeLessThanOrEqual(10 + 1e-9);
      expect(out.camX).toBeGreaterThanOrEqual(prev - 1e-9);
      prev = out.camX;
    }
    expect(prev).toBeGreaterThan(9.9);
  });

  it('adds the configured offset on top of the target position', () => {
    const f = createCameraFollow({ smoothing: 1000, offsetX: 1, offsetY: 2, offsetZ: -3 });
    const out = f.update({ targetX: 10, targetY: 5, targetZ: 7 }, 1);
    expect(out.camX).toBeCloseTo(11, 2);
    expect(out.camY).toBeCloseTo(7, 2);
    expect(out.camZ).toBeCloseTo(4, 2);
  });

  it('is frame-rate independent: same total time converges to the same value', () => {
    const fine = createCameraFollow({ smoothing: 4, offsetX: 0, offsetY: 0, offsetZ: 0 });
    const coarse = createCameraFollow({ smoothing: 4, offsetX: 0, offsetY: 0, offsetZ: 0 });
    const input = { targetX: 100, targetY: 0, targetZ: 0 };
    for (let i = 0; i < 600; i++) fine.update(input, 1 / 600);
    for (let i = 0; i < 60; i++) coarse.update(input, 1 / 60);
    const a = fine.update(input, 0);
    const b = coarse.update(input, 0);
    expect(a.camX).toBeCloseTo(b.camX, 2);
  });

  it('setParams changes smoothing on the next update', () => {
    const f = createCameraFollow({ smoothing: 0.001, offsetY: 0 });
    f.update({ targetX: 100, targetY: 0, targetZ: 0 }, 1 / 60);
    f.setParams({ smoothing: 1000 });
    const out = f.update({ targetX: 100, targetY: 0, targetZ: 0 }, 1);
    expect(out.camX).toBeCloseTo(100, 1);
  });

  it('reset places the camera at the supplied position', () => {
    const f = createCameraFollow({ smoothing: 100, offsetY: 0 });
    f.update({ targetX: 50, targetY: 0, targetZ: 0 }, 1);
    f.reset({ camX: -3, camY: 4, camZ: 5 });
    const out = f.update({ targetX: 0, targetY: 0, targetZ: 0 }, 0);
    expect(out.camX).toBe(-3);
    expect(out.camY).toBe(4);
    expect(out.camZ).toBe(5);
  });

  it('zero smoothing locks the camera in place even with a moving target', () => {
    const f = createCameraFollow({ smoothing: 0, offsetY: 0 }, { camX: 1, camY: 2, camZ: 3 });
    for (let i = 0; i < 10; i++) {
      const out = f.update({ targetX: 99, targetY: 99, targetZ: 99 }, 1 / 60);
      expect(out.camX).toBe(1);
      expect(out.camY).toBe(2);
      expect(out.camZ).toBe(3);
    }
  });

  it('getParams reflects defaults when none are supplied', () => {
    const f = createCameraFollow();
    expect(f.getParams()).toEqual(DEFAULT_CAMERA_FOLLOW_PARAMS);
  });
});

CameraFollow.test.ts

10 ✓

CameraFollowComponent

applies defaults when no params are supplied
merges overrides on top of defaults and keeps target separate
serialize round-trips

CameraFollowSystem

creates a core instance on entity add
is non-pauseable
does nothing without a target mesh handle registered
calls setCameraTarget once the target mesh is registered
applies the configured offset on top of the target position

CameraFollowSystem.onInitialize scan

latches a pre-existing MeshPrimitive handle and primes the follower set up before init
skips meshes whose handle has not been created yet during the scan

Last run 2026-08-22

CameraFollow.test.ts

import { describe, it, expect, beforeEach } from 'vitest';
import { CameraFollowComponent, CameraFollowSystem } from './CameraFollow';
import { ArcCameraComponent } from '../ArcCamera/ArcCamera.defs';
import { MeshPrimitiveComponent } from '../MeshPrimitive/MeshPrimitive.defs';
import { EventBus, World } from '@babylonjsmarket/ecs';
import { MockRendererAdapter } from '@babylonjsmarket/ecs';
import type { MeshHandle } from '@babylonjsmarket/ecs/renderer-types';

describe('CameraFollowComponent', () => {
  it('applies defaults when no params are supplied', () => {
    const comp = new CameraFollowComponent();
    expect(comp.target).toBe('');
    expect(comp.params.smoothing).toBe(6);
    expect(comp.params.offsetY).toBe(1.2);
    expect(comp.instance).toBeNull();
  });

  it('merges overrides on top of defaults and keeps target separate', () => {
    const comp = new CameraFollowComponent({ target: 'Player', smoothing: 12, offsetY: 2 });
    expect(comp.target).toBe('Player');
    expect(comp.params.smoothing).toBe(12);
    expect(comp.params.offsetY).toBe(2);
  });

  it('serialize round-trips', () => {
    const orig = new CameraFollowComponent({ target: 'Hero', smoothing: 8, offsetZ: -1 });
    const copy = new CameraFollowComponent(orig.serialize());
    expect(copy.target).toBe('Hero');
    expect(copy.params).toEqual(orig.params);
  });
});

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

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

  it('creates a core instance on entity add', () => {
    const entity = world.createEntity();
    const comp = new CameraFollowComponent({ target: 'Player', smoothing: 4 });
    entity.add(comp);
    expect(comp.instance).not.toBeNull();
    expect(comp.instance!.getParams().smoothing).toBe(4);
  });

  it('is non-pauseable', () => {
    expect((system as unknown as { _pauseable: boolean })._pauseable).toBe(false);
  });

  it('does nothing without a target mesh handle registered', () => {
    const arcEntity = world.createEntity('Camera');
    const arcComp = new ArcCameraComponent();
    arcComp.handle = renderer.createArcCamera(arcEntity.id, arcComp.toSpec());
    arcComp.initialized = true;
    arcEntity.add(arcComp);

    const followEntity = world.createEntity('Follow');
    followEntity.add(new CameraFollowComponent({ target: 'Ghost' }));

    renderer.calls.length = 0;
    world.update(1 / 60);
    expect(renderer.calls.some((c) => c.method === 'setCameraTarget')).toBe(false);
  });

  it('calls setCameraTarget once the target mesh is registered', () => {
    // Mimic a camera and an ArcCamera handle
    const arcEntity = world.createEntity('Camera');
    const arcComp = new ArcCameraComponent();
    arcComp.handle = renderer.createArcCamera(arcEntity.id, arcComp.toSpec());
    arcComp.initialized = true;
    arcEntity.add(arcComp);

    // Fake a Player mesh and emit the creation event the system listens for.
    const fakeHandle = renderer.createMesh('Player', { kind: 'capsule' });
    renderer.meshWorldPositions.set(fakeHandle as MeshHandle, [3, 1, 0]);

    const followEntity = world.createEntity('Follow');
    followEntity.add(
      new CameraFollowComponent({ target: 'Player', smoothing: 1000, offsetX: 0, offsetY: 0, offsetZ: 0 }),
    );

    eventBus.emit('meshprimitive.created', { entityId: 'Player', handle: fakeHandle });

    renderer.calls.length = 0;
    world.update(1 / 60);

    const setCalls = renderer.calls.filter((c) => c.method === 'setCameraTarget');
    expect(setCalls.length).toBe(1);
    // First frame snaps the core to the target position; read the target we set.
    const target = renderer.cameraTargets.get(arcComp.handle!)!;
    expect(target[0]).toBeCloseTo(3, 3);
    expect(target[1]).toBeCloseTo(1, 3);
    expect(target[2]).toBeCloseTo(0, 3);
  });

  it('applies the configured offset on top of the target position', () => {
    const arcEntity = world.createEntity('Camera');
    const arcComp = new ArcCameraComponent();
    arcComp.handle = renderer.createArcCamera(arcEntity.id, arcComp.toSpec());
    arcComp.initialized = true;
    arcEntity.add(arcComp);

    const fakeHandle = renderer.createMesh('Player', { kind: 'capsule' });
    renderer.meshWorldPositions.set(fakeHandle as MeshHandle, [0, 0, 0]);

    const followEntity = world.createEntity('Follow');
    followEntity.add(
      new CameraFollowComponent({ target: 'Player', smoothing: 1000, offsetY: 5 }),
    );

    eventBus.emit('meshprimitive.created', { entityId: 'Player', handle: fakeHandle });
    world.update(1 / 60);

    const target = renderer.cameraTargets.get(arcComp.handle!)!;
    expect(target[1]).toBeCloseTo(5, 2);
  });
});

describe('CameraFollowSystem.onInitialize scan', () => {
  // MeshPrimitiveSystem can emit `meshprimitive.created` while world.addSystem
  // is wiring CameraFollowSystem — before its subscription exists. To prove the
  // catch-up scan picks those up, we build the entities (mesh handle + follower)
  // FIRST, then add + initialize the system, so onInitialize runs against a
  // populated world (the path the per-test `beforeEach` never reaches).
  let eventBus: EventBus;
  let world: World;
  let renderer: MockRendererAdapter;

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

  it('latches a pre-existing MeshPrimitive handle and primes the follower set up before init', () => {
    // Camera so the update path has a handle to write.
    const arcEntity = world.createEntity('Camera');
    const arcComp = new ArcCameraComponent();
    arcComp.handle = renderer.createArcCamera(arcEntity.id, arcComp.toSpec());
    arcComp.initialized = true;
    arcEntity.add(arcComp);

    // A mesh whose handle is already set on the component (no event ever fired).
    const playerMesh = new MeshPrimitiveComponent({ primitive: 'capsule' });
    playerMesh.handle = renderer.createMesh('Player', { kind: 'capsule' });
    renderer.meshWorldPositions.set(playerMesh.handle as MeshHandle, [4, 2, -1]);
    world.createEntity('Player').add(playerMesh);

    // A follower already in the world before the system exists.
    const follow = new CameraFollowComponent({
      target: 'Player',
      smoothing: 1000,
      offsetX: 0,
      offsetY: 0,
      offsetZ: 0,
    });
    world.createEntity('Follow').add(follow);

    // Now wire the system: onInitialize must scan getEntities() for the handle
    // (lines 80-87) and ensureInstance over this.entities (lines 89-91).
    const system = new CameraFollowSystem(eventBus);
    world.addSystem(system);
    world.initialize();

    // The follower got its core instance from the init-time entities scan.
    expect(follow.instance).not.toBeNull();

    world.update(1 / 60);

    const target = renderer.cameraTargets.get(arcComp.handle!)!;
    expect(target[0]).toBeCloseTo(4, 3);
    expect(target[1]).toBeCloseTo(2, 3);
    expect(target[2]).toBeCloseTo(-1, 3);
  });

  it('skips meshes whose handle has not been created yet during the scan', () => {
    // Mesh component with NO handle → the scan must not register it.
    world.createEntity('Player').add(new MeshPrimitiveComponent({ primitive: 'box' }));

    const system = new CameraFollowSystem(eventBus);
    world.addSystem(system);
    world.initialize();

    const handles = (system as unknown as { targetHandles: Map<string, unknown> })
      .targetHandles;
    expect(handles.has('Player')).toBe(false);
  });
});

CameraFollow.viz.test.tsx

20 ✓

CameraFollowPanel

mounts without a renderer and shows the smoothing controls
seeds each slider from the core current params
moving the smoothing slider pushes the new value into the core
each offset slider pushes its own key into the core
reset button restores the defaults on the core

CameraFollowDebuggerComponent

uses defaults when no data is provided
initializes from provided values and round-trips through serialize()

CameraFollowDebuggerSystem

does not register a panel while no CameraFollow entity has a core yet
registers and (because visible) shows the panel once a follow core exists
registers but leaves the panel hidden when visible is false
renders the bound core into the panel content (live tuning is wired)
retries registration on a later onUpdate once a core appears
re-registration is skipped once panelRegistered (onUpdate short-circuit)
toggles the panel with the activation key and writes visibility back
ignores key presses that are not the activation key
the keydown handler is a no-op when no debugger component is bound
picks up a debugger added after initialize (onEntityAdded) and registers
does not re-bind a second debugger added after one is already set
unregisters the panel and removes the keydown listener on shutdown
setupKeyboardListener is idempotent across re-initialize

Last run 2026-08-22

CameraFollow.viz.test.tsx

// @vitest-environment jsdom
/**
 * CameraFollow.viz.test.tsx — coverage for the renderer-free Solid panel
 * (CameraFollowPanel) and the vizStore-backed debugger wrapper
 * (CameraFollowDebuggerComponent + CameraFollowDebuggerSystem).
 *
 * The panel binds three offset sliders and a smoothing slider straight to the
 * pure core. The debugger registers that panel with the shared vizStore once it
 * finds a CameraFollow-bearing entity whose core instance exists, and toggles
 * the panel from a window keydown. These tests stand up a headless World with a
 * MockRendererAdapter and drive registration, the activation key, late
 * onEntityAdded binding, the onUpdate retry, and shutdown teardown.
 */
import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
import { render, fireEvent } from '@solidjs/testing-library';
import { EventBus, World, MockRendererAdapter } from '@babylonjsmarket/ecs';
import { CameraFollowPanel } from './CameraFollow.panel';
import { createCameraFollow } from './CameraFollow.core';
import {
  CameraFollowDebuggerComponent,
  CameraFollowDebuggerSystem,
  type CameraFollowDebuggerInput,
} from './CameraFollow.viz.tsx';
import { CameraFollowComponent, CameraFollowSystem } from './CameraFollow';
import { vizStore } from '../_shared/viz';

const PANEL_ID = 'camera-follow-debugger';

describe('CameraFollowPanel', () => {
  it('mounts without a renderer and shows the smoothing controls', () => {
    const core = createCameraFollow();
    const { container } = render(() => <CameraFollowPanel core={core} />);
    expect(container.textContent).toContain('Smoothing');
    expect(container.textContent).toContain('offsetY');
  });

  it('seeds each slider from the core current params', () => {
    const core = createCameraFollow({ smoothing: 9, offsetX: -2, offsetY: 3, offsetZ: 1 });
    const { getAllByRole } = render(() => <CameraFollowPanel core={core} />);
    const sliders = getAllByRole('slider') as HTMLInputElement[];
    // Order matches the panel layout: smoothing, offsetY, offsetX, offsetZ.
    expect(sliders.map((s) => Number(s.value))).toEqual([9, 3, -2, 1]);
  });

  it('moving the smoothing slider pushes the new value into the core', () => {
    const core = createCameraFollow();
    const spy = vi.spyOn(core, 'setParams');
    const { getAllByRole } = render(() => <CameraFollowPanel core={core} />);
    const sliders = getAllByRole('slider') as HTMLInputElement[];
    fireEvent.input(sliders[0], { target: { value: '12' } });
    expect(spy).toHaveBeenCalledWith(expect.objectContaining({ smoothing: 12 }));
  });

  it('each offset slider pushes its own key into the core', () => {
    // Exercises the offsetY / offsetX / offsetZ onChange callbacks (the panel
    // funcs left uncovered when only the smoothing slider was driven).
    const core = createCameraFollow();
    const { getAllByRole } = render(() => <CameraFollowPanel core={core} />);
    const sliders = getAllByRole('slider') as HTMLInputElement[];

    fireEvent.input(sliders[1], { target: { value: '2.5' } }); // offsetY
    fireEvent.input(sliders[2], { target: { value: '-1.5' } }); // offsetX
    fireEvent.input(sliders[3], { target: { value: '0.5' } }); // offsetZ

    const p = core.getParams();
    expect(p.offsetY).toBeCloseTo(2.5, 5);
    expect(p.offsetX).toBeCloseTo(-1.5, 5);
    expect(p.offsetZ).toBeCloseTo(0.5, 5);
  });

  it('reset button restores the defaults on the core', () => {
    const core = createCameraFollow({ smoothing: 1, offsetY: 0 });
    const spy = vi.spyOn(core, 'setParams');
    const { getByText } = render(() => <CameraFollowPanel core={core} />);
    fireEvent.click(getByText(/Reset/i));
    expect(spy).toHaveBeenCalledWith(expect.objectContaining({ smoothing: 6, offsetY: 1.2 }));
  });
});

describe('CameraFollowDebuggerComponent', () => {
  it('uses defaults when no data is provided', () => {
    const c = new CameraFollowDebuggerComponent();
    expect(c.visible).toBe(false);
    expect(c.activationKey).toBe('Digit1');
    expect(c.position).toBe('top-right');
  });

  it('initializes from provided values and round-trips through serialize()', () => {
    const c = new CameraFollowDebuggerComponent({
      visible: true,
      activationKey: 'KeyC',
      position: 'bottom-left',
    });
    const s: CameraFollowDebuggerInput = c.serialize();
    expect(s).toEqual({ visible: true, activationKey: 'KeyC', position: 'bottom-left' });
    const rebuilt = new CameraFollowDebuggerComponent(s);
    expect(rebuilt.position).toBe('bottom-left');
    expect(rebuilt.activationKey).toBe('KeyC');
  });
});

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

  beforeEach(() => {
    // vizStore persists panel visibility to localStorage by scene+id, so a
    // previous test's saved state would otherwise bleed into the next mount.
    localStorage.clear();
    vizStore.clear();
    eventBus = new EventBus();
    renderer = new MockRendererAdapter();
    world = new World({ eventBus, renderer });
  });

  afterEach(() => {
    // onInitialize installs a window keydown listener — tear it down to avoid
    // leaking across tests, then clear the shared panel registry.
    world.shutdown();
    vizStore.clear();
  });

  /** A CameraFollow entity; the CameraFollowSystem gives it a core instance. */
  function seedFollow(target = 'Player'): CameraFollowComponent {
    const e = world.createEntity('Follow');
    const c = new CameraFollowComponent({ target, smoothing: 8 });
    e.add(c);
    return c;
  }

  function addDebugger(data: CameraFollowDebuggerInput = {}): CameraFollowDebuggerComponent {
    const e = world.createEntity('Dbg');
    const c = new CameraFollowDebuggerComponent(data);
    e.add(c);
    return c;
  }

  it('does not register a panel while no CameraFollow entity has a core yet', () => {
    addDebugger({ visible: true });
    world.addSystem(new CameraFollowDebuggerSystem(eventBus));
    world.initialize();
    world.update(0.016);
    expect(vizStore.panels[PANEL_ID]).toBeUndefined();
  });

  it('registers and (because visible) shows the panel once a follow core exists', () => {
    // CameraFollowSystem must run first so the follower gets its core instance.
    world.addSystem(new CameraFollowSystem(eventBus));
    world.addSystem(new CameraFollowDebuggerSystem(eventBus));
    seedFollow();
    addDebugger({ visible: true, position: 'bottom-left' });
    world.initialize();
    world.update(0.016);

    const panel = vizStore.panels[PANEL_ID];
    expect(panel).toBeDefined();
    expect(panel.title).toBe('Camera Follow');
    expect(panel.position).toBe('bottom-left');
    expect(vizStore.isVisible(PANEL_ID)).toBe(true);
  });

  it('registers but leaves the panel hidden when visible is false', () => {
    world.addSystem(new CameraFollowSystem(eventBus));
    world.addSystem(new CameraFollowDebuggerSystem(eventBus));
    seedFollow();
    addDebugger({ visible: false });
    world.initialize();
    world.update(0.016);

    expect(vizStore.panels[PANEL_ID]).toBeDefined();
    expect(vizStore.isVisible(PANEL_ID)).toBe(false);
  });

  it('renders the bound core into the panel content (live tuning is wired)', () => {
    world.addSystem(new CameraFollowSystem(eventBus));
    world.addSystem(new CameraFollowDebuggerSystem(eventBus));
    const follow = seedFollow();
    addDebugger({ visible: true });
    world.initialize();
    world.update(0.016);

    const content = vizStore.panels[PANEL_ID].content;
    const { getAllByRole } = render(() => content());
    const sliders = getAllByRole('slider') as HTMLInputElement[];
    // Drive the smoothing slider and confirm it mutates the entity's own core.
    fireEvent.input(sliders[0], { target: { value: '15' } });
    expect(follow.instance!.getParams().smoothing).toBe(15);
  });

  it('retries registration on a later onUpdate once a core appears', () => {
    // Debugger initializes first with no follow core present, so the first
    // tryRegisterPanel bails; onUpdate must retry and succeed.
    world.addSystem(new CameraFollowDebuggerSystem(eventBus));
    addDebugger({ visible: true });
    world.initialize();
    world.update(0.016);
    expect(vizStore.panels[PANEL_ID]).toBeUndefined();

    // Add the follow system + entity now; its core is created on entity add.
    world.addSystem(new CameraFollowSystem(eventBus));
    seedFollow();
    world.update(0.016); // onUpdate → tryRegisterPanel finds the core
    expect(vizStore.panels[PANEL_ID]).toBeDefined();
  });

  it('re-registration is skipped once panelRegistered (onUpdate short-circuit)', () => {
    world.addSystem(new CameraFollowSystem(eventBus));
    world.addSystem(new CameraFollowDebuggerSystem(eventBus));
    seedFollow();
    addDebugger({ visible: true });
    world.initialize();
    world.update(0.016);
    const firstContent = vizStore.panels[PANEL_ID].content;
    world.update(0.016);
    expect(vizStore.panels[PANEL_ID].content).toBe(firstContent);
  });

  it('toggles the panel with the activation key and writes visibility back', () => {
    world.addSystem(new CameraFollowSystem(eventBus));
    world.addSystem(new CameraFollowDebuggerSystem(eventBus));
    seedFollow();
    const comp = addDebugger({ visible: false, activationKey: 'KeyC' });
    world.initialize();
    world.update(0.016); // register panel (hidden)

    window.dispatchEvent(new KeyboardEvent('keydown', { code: 'KeyC' }));
    expect(vizStore.isVisible(PANEL_ID)).toBe(true);
    expect(comp.visible).toBe(true);

    window.dispatchEvent(new KeyboardEvent('keydown', { code: 'KeyC' }));
    expect(vizStore.isVisible(PANEL_ID)).toBe(false);
    expect(comp.visible).toBe(false);
  });

  it('ignores key presses that are not the activation key', () => {
    world.addSystem(new CameraFollowSystem(eventBus));
    world.addSystem(new CameraFollowDebuggerSystem(eventBus));
    seedFollow();
    addDebugger({ visible: false, activationKey: 'KeyC' });
    world.initialize();
    world.update(0.016);

    window.dispatchEvent(new KeyboardEvent('keydown', { code: 'KeyX' }));
    expect(vizStore.isVisible(PANEL_ID)).toBe(false);
  });

  it('the keydown handler is a no-op when no debugger component is bound', () => {
    // System initialized with no CameraFollowDebuggerComponent in the world.
    world.addSystem(new CameraFollowDebuggerSystem(eventBus));
    world.initialize();
    // component stays null → handler returns early, no throw.
    expect(() =>
      window.dispatchEvent(new KeyboardEvent('keydown', { code: 'Digit1' })),
    ).not.toThrow();
  });

  it('picks up a debugger added after initialize (onEntityAdded) and registers', () => {
    world.addSystem(new CameraFollowSystem(eventBus));
    world.addSystem(new CameraFollowDebuggerSystem(eventBus));
    seedFollow();
    world.initialize(); // no debugger yet → component stays null
    expect(vizStore.panels[PANEL_ID]).toBeUndefined();

    addDebugger({ visible: true }); // onEntityAdded → tryRegisterPanel
    expect(vizStore.panels[PANEL_ID]).toBeDefined();
  });

  it('does not re-bind a second debugger added after one is already set', () => {
    world.addSystem(new CameraFollowSystem(eventBus));
    world.addSystem(new CameraFollowDebuggerSystem(eventBus));
    seedFollow();
    addDebugger({ visible: true, activationKey: 'KeyC' });
    world.initialize();
    world.update(0.016);
    expect(vizStore.isVisible(PANEL_ID)).toBe(true);

    // A second debugger entity arrives; the first one stays bound (no re-bind).
    const second = world.createEntity('Dbg2');
    second.add(new CameraFollowDebuggerComponent({ activationKey: 'KeyZ' }));

    // The original activation key still drives the toggle.
    window.dispatchEvent(new KeyboardEvent('keydown', { code: 'KeyC' }));
    expect(vizStore.isVisible(PANEL_ID)).toBe(false);
  });

  it('unregisters the panel and removes the keydown listener on shutdown', () => {
    world.addSystem(new CameraFollowSystem(eventBus));
    world.addSystem(new CameraFollowDebuggerSystem(eventBus));
    seedFollow();
    addDebugger({ visible: true, activationKey: 'KeyC' });
    world.initialize();
    world.update(0.016);
    expect(vizStore.panels[PANEL_ID]).toBeDefined();

    world.shutdown();
    expect(vizStore.panels[PANEL_ID]).toBeUndefined();

    // Listener gone — a press must not re-show anything.
    window.dispatchEvent(new KeyboardEvent('keydown', { code: 'KeyC' }));
    expect(vizStore.panels[PANEL_ID]).toBeUndefined();
  });

  it('setupKeyboardListener is idempotent across re-initialize', () => {
    // A second initialize() must not double-install the keydown handler.
    const system = new CameraFollowDebuggerSystem(eventBus);
    world.addSystem(system);
    world.initialize();
    // Force a second onInitialize path; the guard (`if (this.keydownHandler)`)
    // returns early so no duplicate listener is attached.
    (system as unknown as { setupKeyboardListener(): void }).setupKeyboardListener();
    expect(() =>
      window.dispatchEvent(new KeyboardEvent('keydown', { code: 'Digit1' })),
    ).not.toThrow();
  });
});