Mesh.core.ts

Mesh — pure core.

A tiny loader-state machine: idle → loading → (loaded | error). Records the source URL, transform params, and — once loaded — the handle id the renderer assigned plus the animation clip names it discovered.

No imports from @babylonjs, three, solid-js or the DOM. Transform fields are plain tuples. The System reads this and talks to world.renderer.

Mesh.core.ts

import type { Vec3 } from '@babylonjsmarket/ecs/renderer-types';

export type MeshLoadState = 'idle' | 'loading' | 'loaded' | 'error';

export interface MeshParams {
  /** URL or path to the .glb / .gltf. Required before a load can start. */
  src: string;
  /** World-space position applied after load. */
  position: Vec3;
  /** Euler rotation (radians) applied after load. */
  rotation: Vec3;
  /** Uniform scale. Three rolls it into a Vector3 internally. */
  scale: number;
  /** True = the System triggers a load automatically on entity attach. */
  autoLoad: boolean;
  /** Prepended to `src` when constructing the final URL. Defaults to "". */
  assetServerUrl: string;
  /**
   * When true, load via `loadModelTemplate` + `instantiateModel` (one shared
   * template per url, cheap per-entity clones) instead of `loadMesh`. Use for
   * pools of identical animated characters. Default false.
   */
  instanced: boolean;
  /**
   * When true, each frame copy the sibling `MeshPrimitiveComponent.position`
   * X/Z onto the mesh (the mesh's own Y stays `position[1]`, used as a
   * ground/feet offset) and yaw the mesh toward its movement direction.
   * Default false.
   */
  follow: boolean;
  /**
   * How the followed mesh decides its yaw:
   *   • 'velocity' (default) — face the proxy's travel direction (movement).
   *   • 'proxy' — copy the sibling MeshPrimitive's own yaw (rotation[1]). Use
   *     when a gameplay system already orients the proxy, e.g. a twin-stick
   *     player that faces its aim/fire direction rather than where it walks.
   */
  faceMode: 'velocity' | 'proxy';
  /** Added (radians) to the facing yaw in follow mode. Default 0. */
  yawOffset: number;
  /**
   * Strip baked horizontal root motion from the model's animations so every
   * clip plays "in place" at the entity's position (gameplay drives position
   * via the follow proxy). Without this, clips authored with root translation
   * — e.g. a "blown back" death — slide/teleport the character away. Vertical
   * motion is kept. Default false.
   */
  lockRootMotion: boolean;
}

export interface MeshOutputs {
  state: MeshLoadState;
  /** True the frame `state` transitioned. Read by tests + HUDs. */
  stateChanged: boolean;
  /** Populated once `state === 'loaded'`. */
  meshId: string | null;
  animationNames: readonly string[];
  /** Populated once `state === 'error'`. */
  errorMessage: string | null;
}

export interface MeshInstance {
  /** Begin the load. Idempotent — returns false if already in-flight/loaded. */
  beginLoad(): boolean;
  /** Record a successful load. Transitions idle/loading → loaded. */
  completeLoad(meshId: string, animationNames: string[]): void;
  /** Record a failed load. Transitions idle/loading → error. */
  failLoad(message: string): void;
  /** Read current state (non-destructive). */
  getState(): Readonly<MeshOutputs>;
  getParams(): Readonly<MeshParams>;
  setParams(partial: Partial<MeshParams>): void;
  /** Back to idle; forgets meshId and animationNames. */
  reset(): void;
  /** Full URL the System should pass to the adapter: assetServerUrl + src. */
  getResolvedUrl(): string;
}

export const DEFAULT_MESH_PARAMS: MeshParams = {
  src: '',
  position: [0, 0, 0],
  rotation: [0, 0, 0],
  scale: 1,
  autoLoad: true,
  assetServerUrl: '',
  instanced: false,
  follow: false,
  faceMode: 'velocity',
  yawOffset: 0,
  lockRootMotion: false,
};

export function createMesh(params: Partial<MeshParams> = {}): MeshInstance {
  const active: MeshParams = { ...DEFAULT_MESH_PARAMS, ...params };
  let state: MeshLoadState = 'idle';
  let stateChanged = false;
  let meshId: string | null = null;
  let animationNames: string[] = [];
  let errorMessage: string | null = null;

  const transition = (next: MeshLoadState): void => {
    if (state === next) return;
    state = next;
    stateChanged = true;
  };

  return {
    beginLoad() {
      if (state === 'loading' || state === 'loaded') return false;
      transition('loading');
      meshId = null;
      animationNames = [];
      errorMessage = null;
      return true;
    },
    completeLoad(id, names) {
      meshId = id;
      // Copy so callers mutating the array later can't clobber our snapshot.
      animationNames = [...names];
      errorMessage = null;
      transition('loaded');
    },
    failLoad(message) {
      meshId = null;
      animationNames = [];
      errorMessage = message;
      transition('error');
    },
    getState() {
      const snapshot: MeshOutputs = {
        state,
        stateChanged,
        meshId,
        animationNames,
        errorMessage,
      };
      // `stateChanged` is a one-frame edge — clear it on read so consumers
      // that poll every frame see the transition exactly once.
      stateChanged = false;
      return snapshot;
    },
    getParams() {
      return active;
    },
    setParams(partial) {
      Object.assign(active, partial);
    },
    reset() {
      meshId = null;
      animationNames = [];
      errorMessage = null;
      transition('idle');
    },
    getResolvedUrl() {
      return active.assetServerUrl + active.src;
    },
  };
}

Mesh.defs.ts

Mesh — definitions.

Holds the MeshComponent 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 Mesh in a query, or type an event it listens for, without pulling Mesh's behaviour into its own bundle. Import from here, not from Mesh.ts.

Mesh.defs.ts

import { Component } from '@babylonjsmarket/ecs';
import type { MeshHandle, Vec3 } from '@babylonjsmarket/ecs/renderer-types';
import { DEFAULT_MESH_PARAMS, type MeshInstance, type MeshParams } from './Mesh.core';

Events

Mesh.defs.ts

export const MeshEvents = {
  /** A load request has been dispatched to the renderer. */
  LOADING: 'mesh.loading',
  /**
   * The model finished loading — `meshId` is now valid for animation calls,
   * and `handle` is the renderer handle for the loaded root (Shadow attaches
   * its caster to this so a GLB can shadow in place of a hidden proxy).
   */
  LOADED: 'mesh.loaded',
  /** The renderer rejected the load. `error` has the message. */
  ERROR: 'mesh.error',
} as const;

export const MeshInputEvents = {
  /** Kick a load for the matching entity. Payload: `{ entityId, src? }`. */
  LOAD: 'mesh.load',
  /**
   * Show or hide the loaded model. Payload: `{ entityId, visible }`.
   *
   * The model is the vehicle's PICTURE now — the MeshPrimitive beside it is a
   * hidden gameplay proxy. So anything that wants to swap a silhouette (a boat
   * hull replacing a car, a cloaking device) has to hide this, not the proxy;
   * hiding the proxy achieves nothing visible and un-hiding it puts a bare
   * collision box on screen.
   */
  SET_VISIBLE: 'mesh.visible.set',
} as const;

export interface MeshSetVisibleEvent {
  entityId: string;
  visible: boolean;
}

export interface MeshLoadRequest {
  entityId: string;
  /** Optional override; if omitted the System uses the component's current `src`. */
  src?: string;
}

export interface MeshInput extends Omit<Partial<MeshParams>, 'position' | 'rotation'> {
  /** Accept Vec3 arrays or `{x, y, z}` objects for position/rotation. */
  position?: Vec3 | { x: number; y: number; z: number };
  rotation?: Vec3 | { x: number; y: number; z: number };
}

export function toVec3(input: unknown, fallback: Vec3): Vec3 {
  if (!input) return [...fallback] as Vec3;
  if (Array.isArray(input) && input.length === 3) {
    return [Number(input[0]) || 0, Number(input[1]) || 0, Number(input[2]) || 0];
  }
  const o = input as { x?: number; y?: number; z?: number };
  if (typeof o.x === 'number' && typeof o.y === 'number' && typeof o.z === 'number') {
    return [o.x, o.y, o.z];
  }
  return [...fallback] as Vec3;
}

Component

Mesh.defs.ts

export class MeshComponent extends Component {
  params: MeshParams;
  /** Populated by the System on first update. */
  instance: MeshInstance | null = null;

  constructor(data: MeshInput = {}) {
    super();
    this.params = {
      src: data.src ?? DEFAULT_MESH_PARAMS.src,
      position: toVec3(data.position, DEFAULT_MESH_PARAMS.position),
      rotation: toVec3(data.rotation, DEFAULT_MESH_PARAMS.rotation),
      scale: data.scale ?? DEFAULT_MESH_PARAMS.scale,
      autoLoad: data.autoLoad ?? DEFAULT_MESH_PARAMS.autoLoad,
      assetServerUrl: data.assetServerUrl ?? DEFAULT_MESH_PARAMS.assetServerUrl,
      instanced: data.instanced ?? DEFAULT_MESH_PARAMS.instanced,
      follow: data.follow ?? DEFAULT_MESH_PARAMS.follow,
      faceMode: data.faceMode ?? DEFAULT_MESH_PARAMS.faceMode,
      yawOffset: data.yawOffset ?? DEFAULT_MESH_PARAMS.yawOffset,
      lockRootMotion: data.lockRootMotion ?? DEFAULT_MESH_PARAMS.lockRootMotion,
    };
  }

  serialize(): MeshInput {
    return {
      src: this.params.src,
      position: [...this.params.position] as Vec3,
      rotation: [...this.params.rotation] as Vec3,
      scale: this.params.scale,
      autoLoad: this.params.autoLoad,
      assetServerUrl: this.params.assetServerUrl,
      instanced: this.params.instanced,
      follow: this.params.follow,
      faceMode: this.params.faceMode,
      yawOffset: this.params.yawOffset,
      lockRootMotion: this.params.lockRootMotion,
    };
  }
}

System

Mesh.defs.ts

export interface MeshRuntime {
  /** Renderer handle returned by `loadMesh` / `instantiateModel`. */
  handle: MeshHandle | null;
}

Per-entity follow bookkeeping for instanced + follow meshes. Lives on the System (keyed by entityId), never on the Component — it isn't serializable and is reused across park/unpark of a pooled entity.

Mesh.defs.ts

export interface MeshFollowState {
  prevX: number;
  prevZ: number;
  yaw: number;
}

Mesh.panel.tsx

Renderer-free Solid panel for the Mesh core. Binds directly to the loader instance and can be mounted over either the Babylon or Three.js demo. Zero imports from @babylonjs or three (including type-only).

Mesh.panel.tsx

import { Component as SolidComponent, createSignal, onCleanup, onMount } from 'solid-js';
import { For } from 'solid-js';
import { createStore } from 'solid-js/store';
import { Slider, ResetButton, Section } from '../_shared/ui';
import {
  DEFAULT_MESH_PARAMS,
  type MeshInstance,
  type MeshLoadState,
  type MeshParams,
} from './Mesh.core';

export interface MeshPanelProps {
  /** The live core instance for the demo target. */
  core: MeshInstance;
  /** Fired when the user clicks "Reload" — the System should dispatch a load. */
  onReload?: (src: string) => void;
}

const STATE_COLORS: Record<MeshLoadState, string> = {
  idle: '#888',
  loading: '#ffb74d',
  loaded: '#66cc55',
  error: '#f66',
};

export const MeshPanel: SolidComponent<MeshPanelProps> = (props) => {
  const [params, setParams] = createStore<MeshParams>({ ...props.core.getParams() });
  const [state, setState] = createSignal(props.core.getState());

  let pollId: ReturnType<typeof setInterval> | undefined;
  onMount(() => {
    pollId = setInterval(() => setState(props.core.getState()), 100);
  });
  onCleanup(() => {
    if (pollId) clearInterval(pollId);
  });

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

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

  const reload = () => {
    if (props.onReload) props.onReload(params.src);
  };

  const stateBadge = () => {
    const s = state();
    return (
      <span
        style={{
          color: STATE_COLORS[s.state],
          'font-weight': 'bold',
          'text-transform': 'uppercase',
          'font-size': '10px',
        }}
      >
        {s.state}
      </span>
    );
  };

  return (
    <div style={{ 'font-family': 'system-ui, sans-serif', color: '#ddd', 'min-width': '260px' }}>
      <Section title="Status">
        <div style={{ display: 'flex', 'justify-content': 'space-between', 'font-size': '11px' }}>
          <span>state:</span>
          {stateBadge()}
        </div>
        <div style={{ color: '#888', 'font-size': '10px', 'margin-top': '4px' }}>
          meshId: <span style={{ color: '#fff' }}>{state().meshId ?? '—'}</span>
        </div>
        <div style={{ color: '#888', 'font-size': '10px', 'margin-top': '2px' }}>
          animations: {state().animationNames.length}
        </div>
        {state().errorMessage && (
          <div style={{ color: '#f66', 'font-size': '10px', 'margin-top': '4px' }}>
            {state().errorMessage}
          </div>
        )}
      </Section>

      <Section title="Animations">
        {state().animationNames.length === 0 ? (
          <div style={{ color: '#666', 'font-size': '10px' }}>(none)</div>
        ) : (
          <ul style={{ 'padding-left': '16px', margin: '0', 'font-size': '10px' }}>
            <For each={state().animationNames}>
              {(name) => <li style={{ color: '#ccc' }}>{name}</li>}
            </For>
          </ul>
        )}
      </Section>

      <Section title="Source">
        <div style={{ 'font-size': '10px', color: '#aaa', 'margin-bottom': '4px' }}>
          src
        </div>
        <input
          type="text"
          value={params.src}
          onInput={(e) => push('src', e.currentTarget.value)}
          style={{
            width: '100%',
            background: '#111',
            border: '1px solid #333',
            color: '#ddd',
            padding: '4px',
            'font-size': '10px',
            'margin-bottom': '6px',
          }}
        />
        <button
          onClick={reload}
          style={{
            width: '100%',
            padding: '6px',
            background: '#222',
            color: '#66ccff',
            border: '1px solid #66ccff',
            cursor: 'pointer',
          }}
        >
          Reload
        </button>
      </Section>

      <Section title="Transform">
        <Slider
          label="scale"
          value={params.scale}
          min={0.05}
          max={5}
          step={0.05}
          onChange={(v) => push('scale', v)}
        />
        <Slider
          label="position.x"
          value={params.position[0]}
          min={-10}
          max={10}
          step={0.1}
          onChange={(v) => push('position', [v, params.position[1], params.position[2]])}
        />
        <Slider
          label="position.y"
          value={params.position[1]}
          min={-10}
          max={10}
          step={0.1}
          onChange={(v) => push('position', [params.position[0], v, params.position[2]])}
        />
        <Slider
          label="position.z"
          value={params.position[2]}
          min={-10}
          max={10}
          step={0.1}
          onChange={(v) => push('position', [params.position[0], params.position[1], v])}
        />
        <Slider
          label="rotation.y (rad)"
          value={params.rotation[1]}
          min={-Math.PI}
          max={Math.PI}
          step={0.05}
          onChange={(v) => push('rotation', [params.rotation[0], v, params.rotation[2]])}
        />
      </Section>

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

Mesh.ts

Mesh.ts — renderer-agnostic System for file-loaded meshes (GLB / glTF).

The state machine lives in Mesh.core.ts. This System is a thin driver: it observes entities with a MeshComponent, calls world.renderer.loadMesh(id, { url, position, rotation, scale }), and on the returned Promise records the assigned meshId + animation names back on the core. Events fire at each transition so HUDs / downstream systems (e.g., Animation) can react.

Zero imports from @babylonjs or three — the adapter handles the SceneLoader.ImportMeshAsync / GLTFLoader.loadAsync specifics.

Mesh.ts

import { System } from '@babylonjsmarket/ecs';
import type { EventBus } from '@babylonjsmarket/ecs';
import type { Entity } from '@babylonjsmarket/ecs';
import { MeshPrimitiveComponent } from '../MeshPrimitive/MeshPrimitive.defs';
import { createMesh } from './Mesh.core';
import { MeshComponent, MeshEvents, type MeshFollowState, MeshInputEvents, type MeshLoadRequest, type MeshRuntime, type MeshSetVisibleEvent } from './Mesh.defs';

export class MeshSystem extends System {
  /** Entities we've already dispatched a load for this session. */
  private dispatched = new Set<string>();
  /** Per-component runtime state (renderer handles). Never serialized. */
  private runtime = new WeakMap<MeshComponent, MeshRuntime>();
  /** Url-load bookkeeping shared across all entities cloning the same file. */
  private templateRequested = new Set<string>();
  private templateReady = new Set<string>();
  /** Animation names reported by `loadModelTemplate`, keyed by url. */
  private templateAnimationNames = new Map<string, string[]>();
  /** Per-entity follow state (instanced + follow). Keyed by entityId. */
  private followState = new Map<string, MeshFollowState>();

  /** Net visibility for entities parked / reacquired this frame. */
  private pendingVisible = new Map<string, boolean>();

  private flushVisibility(): void {
    if (!this.pendingVisible.size) return;
    const r = this.world?.renderer;
    for (const [id, visible] of this.pendingVisible) {
      const comp = this.world?.getEntity(id)?.get(MeshComponent);
      const handle = comp ? this.getRuntime(comp).handle : null;
      if (!handle || !r) continue;
      // Only instanced clones queue here — they are the ones a pool parks and
      // reacquires. A clone is a TransformNode whose whole subtree toggles.
      r.setModelVisible(handle, visible);
    }
    this.pendingVisible.clear();
  }

  private getRuntime(comp: MeshComponent): MeshRuntime {
    let rt = this.runtime.get(comp);
    if (!rt) {
      rt = { handle: null };
      this.runtime.set(comp, rt);
    }
    return rt;
  }

  protected query = { required: [MeshComponent] };

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

  protected onInitialize(): void {
    this.listen(MeshInputEvents.SET_VISIBLE, (e: MeshSetVisibleEvent) => {
      if (!e?.entityId || typeof e.visible !== 'boolean') return;
      const entity = this.findEntityById(e.entityId);
      const comp = entity?.get(MeshComponent);
      if (!comp) return;
      const handle = this.getRuntime(comp).handle;
      if (!handle) return;
      // Always the subtree toggle. `setMeshVisible` sets `isVisible`, which
      // Babylon applies to ONE mesh — and a loaded GLB's handle is a root node
      // with the actual geometry parented under it, so the car stayed on
      // screen while its root dutifully turned invisible.
      this.world?.renderer?.setModelVisible(handle, e.visible);
    });

    this.listen(MeshInputEvents.LOAD, (e: MeshLoadRequest) => {
      this.handleLoadRequest(e);
    });

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

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

    // Instanced re-acquire: if a clone handle already exists for this entity
    // (kept alive while parked), reveal it and reset prevX/prevZ to the
    // current proxy position so the first follow frame doesn't spin from the
    // stale pre-park position. At pool build time there's no clone yet → no-op.
    const id = (entity as unknown as { id: string }).id;
    const comp = entity.get(MeshComponent);
    if (!comp?.params.instanced) return;
    const rt = this.runtime.get(comp);
    if (!rt?.handle) return;
    // Queued, not written: a pooled entity parked and reacquired in one frame
    // otherwise gets a hide and a show from two different systems' windows —
    // two writers on one handle, which is a last-wins race.
    this.pendingVisible.set(id, true);
    // A reused clone may have been faded out on its last death — restore opacity.
    this.world?.renderer?.setModelAlpha(id, 1);
    const fs = this.followState.get(id);
    const mp = entity.get(MeshPrimitiveComponent);
    if (fs && mp) {
      fs.prevX = mp.position[0];
      fs.prevZ = mp.position[2];
    }
  }

  protected onEntityRemoved(entity: Entity): void {
    const id = (entity as unknown as { id: string }).id;
    const comp = entity.get(MeshComponent);
    if (comp) {
      const rt = this.getRuntime(comp);
      if (rt.handle) {
        const r = this.world?.renderer;
        if (comp.params.instanced) {
          // Park-aware: a parked (pooled) entity keeps its clone + follow state
          // for reuse, just hidden. A true destroy disposes the clone.
          if (!entity.active) {
            this.pendingVisible.set(id, false);
            // Keep handle, followState, and `dispatched` so re-acquire reuses
            // them; return early without clearing per-session load state.
            return;
          }
          r?.disposeModel(id, rt.handle);
          rt.handle = null;
          this.followState.delete(id);
        } else {
          r?.disposeMesh(rt.handle);
          rt.handle = null;
        }
      }
    }
    this.dispatched.delete(id);
  }

  protected onShutdown(): void {
    this.dispatched.clear();
    this.templateRequested.clear();
    this.templateReady.clear();
    this.templateAnimationNames.clear();
    this.followState.clear();
  }

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

  protected onUpdate(_dt: number): void {
    this.flushVisibility();
    for (const entity of this.entities) {
      const id = (entity as unknown as { id: string }).id;
      const comp = entity.get(MeshComponent);
      if (!comp?.instance) continue;

      // Instanced loads can't complete until the shared template finishes
      // loading, so they don't mark `dispatched` until the clone exists. Keep
      // retrying every frame while autoLoad is set and we haven't instantiated.
      if (comp.params.autoLoad && !this.dispatched.has(id)) {
        this.dispatchLoad(id, comp);
      }

      // Follow the sibling proxy each frame once the mesh handle exists.
      if (comp.params.follow) {
        this.updateFollow(id, comp, entity);
      }
    }
  }

  /**
   * Copy the sibling MeshPrimitive's XZ onto the loaded mesh (Y stays the
   * mesh's own `position[1]` ground/feet offset) and yaw it toward its travel
   * direction. No-op until the mesh handle is present + a sibling exists.
   */
  private updateFollow(entityId: string, comp: MeshComponent, entity: Entity): void {
    const handle = this.getRuntime(comp).handle;
    if (!handle) return;
    const mp = entity.get(MeshPrimitiveComponent);
    if (!mp) return;
    const r = this.world?.renderer;
    if (!r) return;

    const px = mp.position[0];
    const pz = mp.position[2];
    r.setMeshPosition(handle, px, comp.params.position[1], pz);

    let fs = this.followState.get(entityId);
    if (!fs) {
      fs = { prevX: px, prevZ: pz, yaw: comp.params.yawOffset };
      this.followState.set(entityId, fs);
    }
    if (comp.params.faceMode === 'proxy') {
      // The gameplay system already orients the proxy (e.g. a twin-stick player
      // faces its aim). Copy its yaw rather than inferring one from movement.
      fs.yaw = mp.rotation[1] + comp.params.yawOffset;
    } else {
      const dx = px - fs.prevX;
      const dz = pz - fs.prevZ;
      if (Math.hypot(dx, dz) > 1e-3) {
        fs.yaw = Math.atan2(dx, dz) + comp.params.yawOffset;
      }
    }
    fs.prevX = px;
    fs.prevZ = pz;
    r.setMeshRotation(handle, 0, fs.yaw, 0);
  }

  private handleLoadRequest(e: MeshLoadRequest): void {
    const entity = this.findEntityById(e.entityId);
    if (!entity) return;
    const comp = entity.get(MeshComponent);
    if (!comp?.instance) return;
    if (e.src) comp.instance.setParams({ src: e.src });
    // Reset loader state so a re-load after error / reset goes through.
    if (comp.instance.getState().state !== 'loading') {
      comp.instance.reset();
    }
    this.dispatchLoad(e.entityId, comp);
  }

  private dispatchLoad(entityId: string, comp: MeshComponent): void {
    const inst = comp.instance;
    if (!inst) return;
    if (!inst.getParams().src) return; // No src yet; wait for a LOAD event.

    if (comp.params.instanced) {
      this.dispatchInstancedLoad(entityId, comp);
      return;
    }

    const started = inst.beginLoad();
    if (!started) return;
    this.dispatched.add(entityId);

    const r = this.world?.renderer;
    const params = inst.getParams();
    this.eventBus.emit(MeshEvents.LOADING, {
      entityId,
      src: params.src,
    });

    if (!r) return; // No renderer attached (unit test); leave state as `loading`.

    r.loadMesh(entityId, {
      url: inst.getResolvedUrl(),
      position: params.position,
      rotation: params.rotation,
      scale: params.scale,
    })
      .then((res) => {
        inst.completeLoad(res.meshId, res.animationNames);
        this.getRuntime(comp).handle = res.handle;
        this.eventBus.emit(MeshEvents.LOADED, {
          entityId,
          meshId: res.meshId,
          animationNames: res.animationNames,
          handle: res.handle,
        });
      })
      .catch((err: unknown) => {
        const message = err instanceof Error ? err.message : String(err);
        inst.failLoad(message);
        this.eventBus.emit(MeshEvents.ERROR, {
          entityId,
          src: params.src,
          error: message,
        });
      });
  }

  /**
   * Instanced load path: one shared `loadModelTemplate` per url (deduped across
   * the whole pool), then a cheap `instantiateModel` clone per entity. Because
   * instantiate must wait for the async template, this does NOT mark `dispatched`
   * until the clone actually exists — `onUpdate` keeps retrying each frame, and
   * the core stays in `loading` until then. For a pool where N entities request
   * the same url in one tick: ONE loadModelTemplate, N instantiateModel.
   */
  private dispatchInstancedLoad(entityId: string, comp: MeshComponent): void {
    const inst = comp.instance;
    if (!inst) return;
    const params = inst.getParams();
    const url = inst.getResolvedUrl();
    const r = this.world?.renderer;

    // Move the core into `loading` (and emit LOADING) exactly once. beginLoad
    // returns false while already loading/loaded, so this guards the event.
    if (inst.beginLoad()) {
      this.eventBus.emit(MeshEvents.LOADING, {
        entityId,
        src: params.src,
      });
    }

    if (!r) return; // No renderer (unit test); leave state as `loading`.

    // Kick off the deduped template load once per url.
    if (!this.templateRequested.has(url)) {
      this.templateRequested.add(url);
      r.loadModelTemplate(url, { lockRootMotion: params.lockRootMotion })
        .then((res) => {
          this.templateAnimationNames.set(url, [...res.animationNames]);
          this.templateReady.add(url);
        })
        .catch(() => {
          // Allow a retry on a later frame if the template load failed.
          this.templateRequested.delete(url);
        });
    }

    // Wait until the template is ready before instantiating the clone.
    if (!this.templateReady.has(url)) return;

    const animationNames = this.templateAnimationNames.get(url) ?? [];
    const handle = r.instantiateModel(entityId, url, {
      position: params.position,
      rotation: params.rotation,
      scale: params.scale,
    });
    this.getRuntime(comp).handle = handle;
    // Clone starts hidden — reveal it.
    r.setModelVisible(handle, true);

    // Now the clone exists: complete the load + stop retrying.
    inst.completeLoad(entityId, animationNames);
    this.dispatched.add(entityId);
    this.eventBus.emit(MeshEvents.LOADED, {
      entityId,
      meshId: entityId,
      animationNames,
      handle,
    });
  }

  private findEntityById(entityId: string): Entity | undefined {
    for (const e of this.entities) {
      if ((e as unknown as { id: string }).id === entityId) return e;
    }
    return this.world?.getEntity(entityId);
  }
}

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

Mesh.ts

export { MeshComponent, MeshEvents, type MeshInput, MeshInputEvents, type MeshLoadRequest, type MeshSetVisibleEvent } from './Mesh.defs';

Mesh.viz.tsx

Mesh.viz.tsx — ECS wrapper that registers the renderer-free Panel with vizStore. The Panel lives in Mesh.panel.tsx and is what both renderers mount — this wrapper exists to wire the panel's callbacks through the EventBus.

Mesh.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 { MeshPanel } from './Mesh.panel';
import {
  MeshComponent,
  MeshInputEvents,
} from './Mesh';
import type { MeshInstance } from './Mesh.core';

export interface MeshDebuggerInput {
  visible?: boolean;
  activationKey?: string;
  position?: 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right';
  /** Entity id of the Mesh target the panel controls. */
  targetEntityId?: string;
}

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

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

  serialize(): MeshDebuggerInput {
    return {
      visible: this.visible,
      activationKey: this.activationKey,
      position: this.position,
      targetEntityId: this.targetEntityId ?? undefined,
    };
  }
}

const PANEL_ID = 'mesh-debugger';

export class MeshDebuggerSystem extends System {
  private component: MeshDebuggerComponent | null = null;
  private panelRegistered = false;
  protected query = { required: [MeshDebuggerComponent] };

  constructor(eventBus: EventBus) {
    super(eventBus);
    this._pauseable = false;
  }

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

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

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

    const found = this.findTarget();
    if (!found) return;
    const { entityId, core } = found;

    vizStore.registerPanel({
      id: PANEL_ID,
      title: 'Mesh',
      position: this.component.position,
      titleColor: '#66ccff',
      activationKey: this.component.activationKey,
      visible: this.component.visible,
      content: () => (
        <MeshPanel
          core={core}
          onReload={(src) =>
            this.eventBus.emit(MeshInputEvents.LOAD, { entityId, src })
          }
        />
      ),
    });

    this.panelRegistered = true;
  }

  private findTarget(): { entityId: string; core: MeshInstance } | null {
    if (!this.world || !this.component) return null;

    if (this.component.targetEntityId) {
      const entity = this.world.getEntity(this.component.targetEntityId);
      const comp = entity?.get(MeshComponent);
      if (comp?.instance) {
        return { entityId: this.component.targetEntityId, core: comp.instance };
      }
    }

    for (const entity of this.world.getEntities()) {
      const comp = entity.get(MeshComponent);
      if (comp?.instance) {
        return {
          entityId: (entity as unknown as { id: string }).id,
          core: comp.instance,
        };
      }
    }
    return null;
  }

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

  protected onShutdown(): void {
    vizStore.unregisterPanel(PANEL_ID);
    this.panelRegistered = false;
  }
}

Mesh.contract.test.ts

13 ✓

ArcadeECS contract: Mesh

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

Mesh.contract.test.ts

import { runMechanicContract } from '@babylonjsmarket/ecs/testing';
import type { MechanicContractContext } from '@babylonjsmarket/ecs/testing';
import {
  MeshComponent,
  MeshSystem,
  MeshEvents,
  MeshInputEvents,
} from './Mesh';

/**
 * Mesh routes LOAD requests by entityId. The contract battery spins a fresh
 * entity for its assertions — we hook `world.entity.created` so the most
 * recently-minted id is always available when `makeInputPayload` runs.
 */
let latestEntityId = 'contract-test';

runMechanicContract({
  name: 'Mesh',
  componentClass: MeshComponent,
  systemClass: MeshSystem,
  sampleInput: { src: '/contract.glb', scale: 2 },
  events: {
    input: [MeshInputEvents.LOAD],
    output: [MeshEvents.LOADING, MeshEvents.LOADED, MeshEvents.ERROR],
  },
  setup(ctx: MechanicContractContext) {
    ctx.eventBus.on('world.entity.created', (e: { entity: { id: string } }) => {
      latestEntityId = e.entity.id;
    });
  },
  makeInputPayload(event) {
    if (event === MeshInputEvents.LOAD) {
      return { entityId: latestEntityId, src: '/input.glb' };
    }
    return {};
  },
});

Mesh.core.test.ts

10 ✓

Mesh core

starts in the idle state with no mesh id and no animations
beginLoad transitions idle to loading and is idempotent
completeLoad records the mesh id and animation names
failLoad transitions to error and records the message
getResolvedUrl prepends assetServerUrl to src
stateChanged fires exactly once per transition and clears on read
beginLoad after loaded is a no-op — load once per session
reset returns the state to idle and forgets the mesh id
defaults match DEFAULT_MESH_PARAMS
setParams updates the resolved URL on the next read

Last run 2026-08-22

Mesh.core.test.ts

import { describe, it, expect } from 'vitest';
import { createMesh, DEFAULT_MESH_PARAMS } from './Mesh.core';

describe('Mesh core', () => {
  it('starts in the idle state with no mesh id and no animations', () => {
    const m = createMesh({ src: '/models/x.glb' });
    const s = m.getState();
    expect(s.state).toBe('idle');
    expect(s.meshId).toBeNull();
    expect(s.animationNames).toEqual([]);
    expect(s.errorMessage).toBeNull();
  });

  it('beginLoad transitions idle to loading and is idempotent', () => {
    const m = createMesh({ src: '/x.glb' });
    expect(m.beginLoad()).toBe(true);
    expect(m.getState().state).toBe('loading');
    // Second call while still in-flight is a no-op.
    expect(m.beginLoad()).toBe(false);
  });

  it('completeLoad records the mesh id and animation names', () => {
    const m = createMesh({ src: '/x.glb' });
    m.beginLoad();
    m.completeLoad('player', ['idle', 'walk', 'run']);
    const s = m.getState();
    expect(s.state).toBe('loaded');
    expect(s.meshId).toBe('player');
    expect(s.animationNames).toEqual(['idle', 'walk', 'run']);
    expect(s.errorMessage).toBeNull();
  });

  it('failLoad transitions to error and records the message', () => {
    const m = createMesh({ src: '/missing.glb' });
    m.beginLoad();
    m.failLoad('file not found');
    const s = m.getState();
    expect(s.state).toBe('error');
    expect(s.errorMessage).toBe('file not found');
    expect(s.meshId).toBeNull();
  });

  it('getResolvedUrl prepends assetServerUrl to src', () => {
    const m = createMesh({
      src: '/characters/hero.glb',
      assetServerUrl: 'https://cdn.example.com',
    });
    expect(m.getResolvedUrl()).toBe('https://cdn.example.com/characters/hero.glb');
  });

  it('stateChanged fires exactly once per transition and clears on read', () => {
    const m = createMesh({ src: '/x.glb' });
    // Read initial state: stateChanged should be false (no prior transition).
    expect(m.getState().stateChanged).toBe(false);
    m.beginLoad();
    // First read after transition is true.
    expect(m.getState().stateChanged).toBe(true);
    // Second read with no further transition is false.
    expect(m.getState().stateChanged).toBe(false);
  });

  it('beginLoad after loaded is a no-op — load once per session', () => {
    const m = createMesh({ src: '/x.glb' });
    m.beginLoad();
    m.completeLoad('e1', []);
    expect(m.beginLoad()).toBe(false);
    expect(m.getState().state).toBe('loaded');
  });

  it('reset returns the state to idle and forgets the mesh id', () => {
    const m = createMesh({ src: '/x.glb' });
    m.beginLoad();
    m.completeLoad('e1', ['clip']);
    m.reset();
    const s = m.getState();
    expect(s.state).toBe('idle');
    expect(s.meshId).toBeNull();
    expect(s.animationNames).toEqual([]);
  });

  it('defaults match DEFAULT_MESH_PARAMS', () => {
    const m = createMesh();
    expect(m.getParams()).toEqual(DEFAULT_MESH_PARAMS);
  });

  it('setParams updates the resolved URL on the next read', () => {
    const m = createMesh({ src: '/a.glb' });
    expect(m.getResolvedUrl()).toBe('/a.glb');
    m.setParams({ src: '/b.glb', assetServerUrl: 'https://cdn/' });
    expect(m.getResolvedUrl()).toBe('https://cdn//b.glb');
  });
});

Mesh.panel.test.tsx

9 ✓

MeshPanel (renderer-free)

mounts against a stub core and shows the status sections
moving the scale slider calls core.setParams with the new value
the Reload button fires onReload with the current src
the Reset button clears core params back to defaults
editing the src input pushes the new value to core.setParams
each position/rotation slider pushes the matching axis to core
renders the error message when the core is in error state
lists animation clip names when the core has loaded animations
clears its poll interval when unmounted

Last run 2026-08-22

Mesh.panel.test.tsx

// @vitest-environment jsdom
import { describe, it, expect, vi } from 'vitest';
import { render, fireEvent } from '@solidjs/testing-library';
import { MeshPanel } from './Mesh.panel';
import { createMesh } from './Mesh.core';

describe('MeshPanel (renderer-free)', () => {
  it('mounts against a stub core and shows the status sections', () => {
    const core = createMesh({ src: '/x.glb' });
    const { container } = render(() => <MeshPanel core={core} />);
    expect(container.textContent).toContain('Status');
    expect(container.textContent).toContain('Source');
    expect(container.textContent).toContain('Transform');
    // The default loader state is idle.
    expect(container.textContent?.toLowerCase()).toContain('idle');
  });

  it('moving the scale slider calls core.setParams with the new value', () => {
    const core = createMesh({ src: '/x.glb' });
    const spy = vi.spyOn(core, 'setParams');
    const { getAllByRole } = render(() => <MeshPanel core={core} />);
    const sliders = getAllByRole('slider') as HTMLInputElement[];
    // The first slider is scale.
    fireEvent.input(sliders[0], { target: { value: '2.5' } });
    expect(spy).toHaveBeenCalledWith(expect.objectContaining({ scale: 2.5 }));
  });

  it('the Reload button fires onReload with the current src', () => {
    const core = createMesh({ src: '/hero.glb' });
    const onReload = vi.fn();
    const { getByText } = render(() => <MeshPanel core={core} onReload={onReload} />);
    fireEvent.click(getByText(/reload/i));
    expect(onReload).toHaveBeenCalledWith('/hero.glb');
  });

  it('the Reset button clears core params back to defaults', () => {
    const core = createMesh({ src: '/x.glb', scale: 3 });
    const spy = vi.spyOn(core, 'setParams');
    const { getByText } = render(() => <MeshPanel core={core} />);
    fireEvent.click(getByText(/reset/i));
    expect(spy).toHaveBeenCalled();
  });

  it('editing the src input pushes the new value to core.setParams', () => {
    const core = createMesh({ src: '/x.glb' });
    const spy = vi.spyOn(core, 'setParams');
    const { getAllByRole } = render(() => <MeshPanel core={core} />);
    const input = getAllByRole('textbox')[0] as HTMLInputElement;
    fireEvent.input(input, { target: { value: '/new.glb' } });
    expect(spy).toHaveBeenCalledWith(expect.objectContaining({ src: '/new.glb' }));
  });

  it('each position/rotation slider pushes the matching axis to core', () => {
    const core = createMesh({ src: '/x.glb' });
    const spy = vi.spyOn(core, 'setParams');
    const { getAllByRole } = render(() => <MeshPanel core={core} />);
    const sliders = getAllByRole('slider') as HTMLInputElement[];
    // order: scale, position.x, position.y, position.z, rotation.y
    fireEvent.input(sliders[1], { target: { value: '1' } });
    expect(spy).toHaveBeenCalledWith(
      expect.objectContaining({ position: [1, 0, 0] })
    );
    fireEvent.input(sliders[2], { target: { value: '2' } });
    expect(spy).toHaveBeenCalledWith(
      expect.objectContaining({ position: [1, 2, 0] })
    );
    fireEvent.input(sliders[3], { target: { value: '3' } });
    expect(spy).toHaveBeenCalledWith(
      expect.objectContaining({ position: [1, 2, 3] })
    );
    fireEvent.input(sliders[4], { target: { value: '0.5' } });
    expect(spy).toHaveBeenCalledWith(
      expect.objectContaining({ rotation: [0, 0.5, 0] })
    );
  });

  it('renders the error message when the core is in error state', () => {
    const core = createMesh({ src: '/missing.glb' });
    core.beginLoad();
    core.failLoad('boom: file not found');
    const { container } = render(() => <MeshPanel core={core} />);
    expect(container.textContent).toContain('boom: file not found');
  });

  it('lists animation clip names when the core has loaded animations', () => {
    const core = createMesh({ src: '/hero.glb' });
    core.beginLoad();
    core.completeLoad('mesh-1', ['Idle', 'Run', 'Jump']);
    const { container } = render(() => <MeshPanel core={core} />);
    expect(container.textContent).toContain('Idle');
    expect(container.textContent).toContain('Run');
    expect(container.textContent).toContain('Jump');
    // count badge in the Status section reflects the three clips
    expect(container.textContent).toContain('animations: 3');
  });

  it('clears its poll interval when unmounted', () => {
    const core = createMesh({ src: '/x.glb' });
    const clearSpy = vi.spyOn(globalThis, 'clearInterval');
    const { unmount } = render(() => <MeshPanel core={core} />);
    unmount();
    expect(clearSpy).toHaveBeenCalled();
    clearSpy.mockRestore();
  });
});

Mesh.test.ts

21 ✓

MeshComponent

applies defaults
round-trips the instanced/follow/yawOffset fields through serialize
accepts position/rotation as arrays or {x,y,z} objects
falls back to the default vec3 when position is a malformed object
serialize round-trips through the constructor

MeshSystem

creates a core instance when an entity with MeshComponent is added
calls adapter.loadMesh once per entity when autoLoad is true
does not call loadMesh a second time on subsequent updates
does not call loadMesh when autoLoad is false
emits LOADING then LOADED events with the meshId
marks the component loaded after the adapter resolves
LOAD input event triggers a load when autoLoad is false
emits ERROR and transitions to error state when the adapter rejects
disposes the mesh handle when the entity is removed

MeshSystem — instanced clone + follow

loads the template once, instantiates a visible clone, and emits LOADED with the entityId + animationNames
only calls loadModelTemplate once for a pool sharing the same url, instantiating N clones
follows the sibling MeshPrimitive: moving the proxy drives setMeshPosition/setMeshRotation on the clone
faceMode 'proxy' copies the sibling's rotation[1] (+ yawOffset) instead of inferring yaw from movement
deletes the templateRequested entry when loadModelTemplate rejects, allowing a retry
parked (active=false) entity hides the clone but keeps it; true destroy disposes it
re-acquiring a parked instanced entity reveals the kept clone without re-instantiating

Last run 2026-08-22

Mesh.test.ts

import { describe, it, expect, beforeEach, vi } from 'vitest';
import {
  MeshComponent,
  MeshSystem,
  MeshEvents,
  MeshInputEvents,
} from './Mesh';
import { EventBus, World } from '@babylonjsmarket/ecs';
import { MockRendererAdapter } from '@babylonjsmarket/ecs';
import { MeshPrimitiveComponent } from '../MeshPrimitive/MeshPrimitive.defs';

describe('MeshComponent', () => {
  it('applies defaults', () => {
    const c = new MeshComponent();
    expect(c.params.src).toBe('');
    expect(c.params.autoLoad).toBe(true);
    expect(c.params.scale).toBe(1);
    expect(c.params.position).toEqual([0, 0, 0]);
    expect(c.params.instanced).toBe(false);
    expect(c.params.follow).toBe(false);
    expect(c.params.yawOffset).toBe(0);
    expect(c.instance).toBeNull();
  });

  it('round-trips the instanced/follow/yawOffset fields through serialize', () => {
    const original = new MeshComponent({
      src: '/enemy.glb',
      instanced: true,
      follow: true,
      yawOffset: Math.PI / 2,
    });
    const copy = new MeshComponent(original.serialize());
    expect(copy.params.instanced).toBe(true);
    expect(copy.params.follow).toBe(true);
    expect(copy.params.yawOffset).toBe(Math.PI / 2);
    expect(copy.params).toEqual(original.params);
  });

  it('accepts position/rotation as arrays or {x,y,z} objects', () => {
    const a = new MeshComponent({
      src: '/x.glb',
      position: [1, 2, 3],
      rotation: { x: 0, y: Math.PI, z: 0 },
    });
    expect(a.params.position).toEqual([1, 2, 3]);
    expect(a.params.rotation).toEqual([0, Math.PI, 0]);
  });

  it('falls back to the default vec3 when position is a malformed object', () => {
    // An object missing numeric x/y/z hits the toVec3 fallback (not an array,
    // not a complete {x,y,z}), so position/rotation stay at their defaults.
    const c = new MeshComponent({
      src: '/x.glb',
      position: { x: 1, y: 2 } as unknown as { x: number; y: number; z: number },
      rotation: {} as unknown as { x: number; y: number; z: number },
    });
    expect(c.params.position).toEqual([0, 0, 0]);
    expect(c.params.rotation).toEqual([0, 0, 0]);
  });

  it('serialize round-trips through the constructor', () => {
    const original = new MeshComponent({
      src: '/x.glb',
      scale: 2,
      autoLoad: false,
      position: [1, 2, 3],
    });
    const copy = new MeshComponent(original.serialize());
    expect(copy.params).toEqual(original.params);
  });
});

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

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

  it('creates a core instance when an entity with MeshComponent is added', () => {
    const entity = world.createEntity();
    entity.add(new MeshComponent({ src: '/a.glb' }));
    const comp = entity.get(MeshComponent);
    expect(comp?.instance).not.toBeNull();
    expect(comp?.instance?.getParams().src).toBe('/a.glb');
  });

  it('calls adapter.loadMesh once per entity when autoLoad is true', async () => {
    const entity = world.createEntity();
    entity.add(new MeshComponent({ src: '/a.glb' }));
    world.update(1 / 60);
    // Allow the promise to resolve.
    await Promise.resolve();
    await Promise.resolve();
    const loadCalls = renderer.calls.filter((c) => c.method === 'loadMesh');
    expect(loadCalls).toHaveLength(1);
    expect(loadCalls[0].args[0]).toBe(entity.id);
  });

  it('does not call loadMesh a second time on subsequent updates', async () => {
    const entity = world.createEntity();
    entity.add(new MeshComponent({ src: '/a.glb' }));
    world.update(1 / 60);
    await Promise.resolve();
    await Promise.resolve();
    const first = renderer.calls.filter((c) => c.method === 'loadMesh').length;
    world.update(1 / 60);
    world.update(1 / 60);
    const later = renderer.calls.filter((c) => c.method === 'loadMesh').length;
    expect(later).toBe(first);
  });

  it('does not call loadMesh when autoLoad is false', async () => {
    const entity = world.createEntity();
    entity.add(new MeshComponent({ src: '/a.glb', autoLoad: false }));
    world.update(1 / 60);
    await Promise.resolve();
    expect(renderer.calls.some((c) => c.method === 'loadMesh')).toBe(false);
  });

  it('emits LOADING then LOADED events with the meshId', async () => {
    const loadingSpy = vi.fn();
    const loadedSpy = vi.fn();
    eventBus.on(MeshEvents.LOADING, loadingSpy);
    eventBus.on(MeshEvents.LOADED, loadedSpy);

    const entity = world.createEntity();
    entity.add(new MeshComponent({ src: '/a.glb' }));
    world.update(1 / 60);
    await Promise.resolve();
    await Promise.resolve();

    expect(loadingSpy).toHaveBeenCalledWith(
      expect.objectContaining({ entityId: entity.id, src: '/a.glb' }),
    );
    expect(loadedSpy).toHaveBeenCalledWith(
      expect.objectContaining({ entityId: entity.id, meshId: entity.id }),
    );
  });

  it('marks the component loaded after the adapter resolves', async () => {
    const loadedSpy = vi.fn();
    eventBus.on(MeshEvents.LOADED, loadedSpy);
    const entity = world.createEntity();
    entity.add(new MeshComponent({ src: '/a.glb' }));
    world.update(1 / 60);
    await Promise.resolve();
    await Promise.resolve();
    const comp = entity.get(MeshComponent)!;
    expect(comp.instance?.getState().state).toBe('loaded');
    // The renderer handle now lives in System runtime state; LOADED firing
    // proves the adapter resolved and the handle was recorded.
    expect(loadedSpy).toHaveBeenCalled();
  });

  it('LOAD input event triggers a load when autoLoad is false', async () => {
    const entity = world.createEntity();
    entity.add(new MeshComponent({ src: '/a.glb', autoLoad: false }));
    world.update(1 / 60);
    eventBus.emit(MeshInputEvents.LOAD, { entityId: entity.id });
    await Promise.resolve();
    await Promise.resolve();
    const loadCalls = renderer.calls.filter((c) => c.method === 'loadMesh');
    expect(loadCalls).toHaveLength(1);
  });

  it('emits ERROR and transitions to error state when the adapter rejects', async () => {
    // Override loadMesh for this test to simulate failure.
    const fail = vi.spyOn(renderer, 'loadMesh').mockRejectedValueOnce(
      new Error('not found'),
    );
    const errorSpy = vi.fn();
    eventBus.on(MeshEvents.ERROR, errorSpy);

    const entity = world.createEntity();
    entity.add(new MeshComponent({ src: '/missing.glb' }));
    world.update(1 / 60);
    await Promise.resolve();
    await Promise.resolve();

    expect(fail).toHaveBeenCalled();
    expect(errorSpy).toHaveBeenCalledWith(
      expect.objectContaining({ entityId: entity.id, error: 'not found' }),
    );
    const comp = entity.get(MeshComponent)!;
    expect(comp.instance?.getState().state).toBe('error');
  });

  it('disposes the mesh handle when the entity is removed', async () => {
    const entity = world.createEntity();
    entity.add(new MeshComponent({ src: '/a.glb' }));
    world.update(1 / 60);
    await Promise.resolve();
    await Promise.resolve();
    renderer.calls.length = 0;
    world.removeEntity(entity.id);
    const disposeCalls = renderer.calls.filter((c) => c.method === 'disposeMesh');
    expect(disposeCalls).toHaveLength(1);
  });
});

describe('MeshSystem — instanced clone + follow', () => {
  let eventBus: EventBus;
  let world: World;
  let renderer: MockRendererAdapter;
  let system: MeshSystem;

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

  beforeEach(() => {
    eventBus = new EventBus();
    renderer = new MockRendererAdapter();
    renderer.modelTemplateAnimationNames = ['Walking', 'Idle'];
    world = new World({ eventBus, renderer, detectRaces: false });
    system = new MeshSystem(eventBus);
    world.addSystem(system);
    world.initialize();
  });

  it('loads the template once, instantiates a visible clone, and emits LOADED with the entityId + animationNames', async () => {
    const loadedSpy = vi.fn();
    eventBus.on(MeshEvents.LOADED, loadedSpy);

    const entity = world.createEntity('Enemy');
    entity.add(new MeshComponent({ src: 'enemy.glb', instanced: true, scale: 0.5 }));

    // First tick kicks off loadModelTemplate; template not ready → no clone yet.
    world.update(1 / 60);
    expect(callsOf('loadModelTemplate')).toHaveLength(1);
    expect(callsOf('instantiateModel')).toHaveLength(0);
    // No loadMesh in the instanced path.
    expect(callsOf('loadMesh')).toHaveLength(0);

    // Flush the template-load microtask so templateReady gets the url.
    await Promise.resolve();
    await Promise.resolve();

    // Second tick now instantiates the clone and reveals it.
    world.update(1 / 60);
    expect(callsOf('instantiateModel')).toHaveLength(1);
    expect(callsOf('instantiateModel')[0].args[0]).toBe(entity.id);
    expect(callsOf('setModelVisible').some((c) => c.args[1] === true)).toBe(true);

    // The Animation/SkeletonAnimator pipeline depends on LOADED carrying entityId.
    expect(loadedSpy).toHaveBeenCalledWith(
      expect.objectContaining({
        entityId: entity.id,
        meshId: entity.id,
        animationNames: ['Walking', 'Idle'],
      }),
    );
  });

  it('only calls loadModelTemplate once for a pool sharing the same url, instantiating N clones', async () => {
    const ids: string[] = [];
    for (let i = 0; i < 24; i++) {
      const e = world.createEntity(`Enemy${i}`);
      e.add(new MeshComponent({ src: 'enemy.glb', instanced: true }));
      ids.push(e.id);
    }

    world.update(1 / 60);
    expect(callsOf('loadModelTemplate')).toHaveLength(1);
    expect(callsOf('instantiateModel')).toHaveLength(0);

    await Promise.resolve();
    await Promise.resolve();

    world.update(1 / 60);
    // One template, one clone per entity.
    expect(callsOf('loadModelTemplate')).toHaveLength(1);
    expect(callsOf('instantiateModel')).toHaveLength(24);
  });

  it('follows the sibling MeshPrimitive: moving the proxy drives setMeshPosition/setMeshRotation on the clone', async () => {
    const entity = world.createEntity('Enemy');
    entity.add(new MeshComponent({ src: 'enemy.glb', instanced: true, follow: true, position: [0, 0.5, 0] }));
    const mp = new MeshPrimitiveComponent({ primitive: 'sphere', position: [0, 1, 0] });
    entity.add(mp);

    world.update(1 / 60);
    await Promise.resolve();
    await Promise.resolve();
    world.update(1 / 60); // instantiate the clone

    const posBefore = callsOf('setMeshPosition').length;
    const rotBefore = callsOf('setMeshRotation').length;

    // Move the proxy and tick again — the clone tracks XZ; Y stays the feet offset.
    mp.position[0] = 5;
    mp.position[2] = 3;
    world.update(1 / 60);

    const moves = callsOf('setMeshPosition');
    const rots = callsOf('setMeshRotation');
    expect(moves.length).toBeGreaterThan(posBefore);
    expect(rots.length).toBeGreaterThan(rotBefore);
    // XZ from the proxy, Y from the mesh's own position[1] (0.5).
    const placed = moves.some((c) => c.args[1] === 5 && c.args[2] === 0.5 && c.args[3] === 3);
    expect(placed).toBe(true);
    // Yaw from atan2(dx, dz) = atan2(5, 3) about the Y axis only.
    const expectedYaw = Math.atan2(5, 3);
    const yawed = rots.some(
      (c) => c.args[1] === 0 && c.args[2] === expectedYaw && c.args[3] === 0,
    );
    expect(yawed).toBe(true);
  });

  it("faceMode 'proxy' copies the sibling's rotation[1] (+ yawOffset) instead of inferring yaw from movement", async () => {
    const entity = world.createEntity('Enemy');
    entity.add(
      new MeshComponent({
        src: 'enemy.glb',
        instanced: true,
        follow: true,
        faceMode: 'proxy',
        yawOffset: Math.PI / 4,
        position: [0, 0.5, 0],
      }),
    );
    const mp = new MeshPrimitiveComponent({
      primitive: 'sphere',
      position: [0, 1, 0],
      rotation: [0, Math.PI / 2, 0],
    });
    entity.add(mp);

    world.update(1 / 60);
    await Promise.resolve();
    await Promise.resolve();
    world.update(1 / 60); // instantiate the clone

    // Move the proxy AND set its yaw. In 'proxy' mode the clone yaw must come
    // from the proxy's rotation[1] + yawOffset, not from atan2 of the movement.
    mp.position[0] = 5;
    mp.position[2] = 3;
    mp.rotation[1] = Math.PI / 2;
    world.update(1 / 60);

    const rots = callsOf('setMeshRotation');
    const expectedYaw = Math.PI / 2 + Math.PI / 4; // rotation[1] + yawOffset
    const yawed = rots.some(
      (c) => c.args[1] === 0 && c.args[2] === expectedYaw && c.args[3] === 0,
    );
    expect(yawed).toBe(true);
  });

  it('deletes the templateRequested entry when loadModelTemplate rejects, allowing a retry', async () => {
    // The mock rejects the FIRST template load only; the second call falls
    // through to the real MockRendererAdapter (which records + resolves).
    // NB: a rejecting mockRejectedValueOnce replaces the implementation, so the
    // failed call is NOT recorded in renderer.calls — count retries via the spy.
    const fail = vi
      .spyOn(renderer, 'loadModelTemplate')
      .mockRejectedValueOnce(new Error('template 404'));

    // setTimeout(0) is a macrotask: it runs only after the microtask queue has
    // fully drained, so the rejection's chained .then→.catch has settled and
    // templateRequested has been deleted before we re-tick.
    const flush = () => new Promise<void>((resolve) => setTimeout(resolve, 0));

    const entity = world.createEntity('Enemy');
    entity.add(new MeshComponent({ src: 'enemy.glb', instanced: true }));

    // First tick requests the template; the rejection clears templateRequested.
    world.update(1 / 60);
    expect(fail).toHaveBeenCalledTimes(1);
    // Await the rejected promise's microtask queue so the .catch runs and
    // deletes templateRequested BEFORE we assert the retry.
    await flush();

    // No clone instantiated yet (template never became ready).
    expect(callsOf('instantiateModel')).toHaveLength(0);

    // A later frame retries: loadModelTemplate is invoked a second time (now
    // succeeding), proving the failed url was removed from templateRequested.
    world.update(1 / 60);
    expect(fail).toHaveBeenCalledTimes(2);

    await flush();
    world.update(1 / 60);
    expect(callsOf('instantiateModel')).toHaveLength(1);

    fail.mockRestore();
  });

  it('parked (active=false) entity hides the clone but keeps it; true destroy disposes it', async () => {
    const parked = world.createEntity('ParkedEnemy');
    parked.add(new MeshComponent({ src: 'enemy.glb', instanced: true }));
    const destroyed = world.createEntity('DestroyedEnemy');
    destroyed.add(new MeshComponent({ src: 'enemy.glb', instanced: true }));

    world.update(1 / 60);
    await Promise.resolve();
    await Promise.resolve();
    world.update(1 / 60); // both clones instantiated

    expect(callsOf('instantiateModel')).toHaveLength(2);
    renderer.calls.length = 0;

    // Park: deactivating the entity removes it from the system with active=false
    // (the pooling path). The clone is hidden and kept for reuse.
    parked.active = false;
    expect(callsOf('disposeModel')).toHaveLength(0);
    // Visibility transitions are queued and flushed from our own update: a
    // pooled entity parked and reacquired in ONE frame would otherwise get a
    // hide and a show from two different systems' windows — a last-wins race.
    expect(callsOf('setModelVisible').some((c) => c.args[1] === false)).toBe(false);
    world.update(1 / 60);
    expect(callsOf('setModelVisible').some((c) => c.args[1] === false)).toBe(true);

    // True destroy: removeEntity on a non-pooled entity runs onEntityRemoved
    // with active still true → dispose the clone.
    world.removeEntity(destroyed.id);
    expect(callsOf('disposeModel')).toHaveLength(1);
    expect(callsOf('disposeModel')[0].args[0]).toBe(destroyed.id);
  });

  it('re-acquiring a parked instanced entity reveals the kept clone without re-instantiating', async () => {
    const entity = world.createEntity('Enemy');
    entity.add(new MeshComponent({ src: 'enemy.glb', instanced: true, follow: true }));
    entity.add(new MeshPrimitiveComponent({ primitive: 'sphere', position: [0, 1, 0] }));

    world.update(1 / 60);
    await Promise.resolve();
    await Promise.resolve();
    world.update(1 / 60); // instantiate

    // Park it (keeps the clone, hidden).
    entity.active = false;
    renderer.calls.length = 0;

    // Re-acquire: reactivating re-adds the entity to the system. The reveal is
    // queued with the rest of the visibility transitions and flushed from our
    // own update — park-then-reacquire inside one frame then resolves to a
    // single write with the correct net value.
    entity.active = true;
    expect(callsOf('setModelVisible').some((c) => c.args[1] === true)).toBe(false);
    world.update(1 / 60);
    expect(callsOf('setModelVisible').some((c) => c.args[1] === true)).toBe(true);
    // No new clone was created on re-acquire.
    expect(callsOf('instantiateModel')).toHaveLength(0);
  });
});

Mesh.viz.test.tsx

14 ✓

MeshDebuggerComponent

uses defaults when no data is provided
initializes from provided data
serializes to a round-trippable object
serializes a null targetEntityId as undefined

MeshDebuggerSystem

registers a panel once a Mesh target with a live instance exists
adopts a debugger component that already exists at initialize time
does not register a panel while no Mesh has a live instance
registers the panel hidden when the component starts not visible
targets the entity named by targetEntityId when present
falls back to scanning for any Mesh when targetEntityId is unknown
adopts a debugger component added after initialize
registers on a later frame once a Mesh instance appears
renders the live MeshPanel content into the registered panel
unregisters the panel on shutdown

Last run 2026-08-22

Mesh.viz.test.tsx

// @vitest-environment jsdom
import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
import { render, fireEvent } from '@solidjs/testing-library';
import { EventBus, World, MockRendererAdapter } from '@babylonjsmarket/ecs';
import {
  MeshDebuggerComponent,
  MeshDebuggerInput,
  MeshDebuggerSystem,
} from './Mesh.viz.tsx';
import { MeshComponent, MeshSystem, MeshInputEvents } from './Mesh';
import { vizStore } from '../_shared/viz';

const PANEL_ID = 'mesh-debugger';

// ----------------------------------------------------------------------------
// Component
// ----------------------------------------------------------------------------

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

  it('initializes from provided data', () => {
    const data: MeshDebuggerInput = {
      visible: true,
      activationKey: 'KeyM',
      position: 'bottom-left',
      targetEntityId: 'Hero',
    };
    const c = new MeshDebuggerComponent(data);
    expect(c.visible).toBe(true);
    expect(c.activationKey).toBe('KeyM');
    expect(c.position).toBe('bottom-left');
    expect(c.targetEntityId).toBe('Hero');
  });

  it('serializes to a round-trippable object', () => {
    const c = new MeshDebuggerComponent({
      visible: true,
      activationKey: 'Digit3',
      position: 'top-left',
      targetEntityId: 'Hero',
    });
    const s = c.serialize();
    expect(s).toEqual({
      visible: true,
      activationKey: 'Digit3',
      position: 'top-left',
      targetEntityId: 'Hero',
    });
    const round = new MeshDebuggerComponent(s);
    expect(round.visible).toBe(c.visible);
    expect(round.activationKey).toBe(c.activationKey);
    expect(round.position).toBe(c.position);
    expect(round.targetEntityId).toBe(c.targetEntityId);
  });

  it('serializes a null targetEntityId as undefined', () => {
    const c = new MeshDebuggerComponent();
    const s = c.serialize();
    expect(s.targetEntityId).toBeUndefined();
    expect('targetEntityId' in s).toBe(true);
  });
});

// ----------------------------------------------------------------------------
// System
// ----------------------------------------------------------------------------

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

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

  afterEach(() => {
    world.shutdown();
    vizStore.clear();
    localStorage.clear();
  });

  /** Add a Mesh entity and run a frame so its `.instance` core is created. */
  function addMeshEntity(id?: string) {
    const e = id ? world.createEntity(id) : world.createEntity();
    e.add(new MeshComponent({ src: '/hero.glb', autoLoad: false }));
    return e;
  }

  it('registers a panel once a Mesh target with a live instance exists', () => {
    world.addSystem(new MeshSystem(eventBus));
    world.addSystem(new MeshDebuggerSystem(eventBus));
    world.initialize();

    // Entity + component exist before the debugger entity; one frame builds
    // the MeshComponent.instance so the debugger can find a target.
    addMeshEntity();
    const dbg = world.createEntity();
    dbg.add(new MeshDebuggerComponent({ visible: true, position: 'top-left' }));

    world.update(1 / 60);

    expect(vizStore.panels[PANEL_ID]).toBeDefined();
    expect(vizStore.panels[PANEL_ID].title).toBe('Mesh');
    expect(vizStore.panels[PANEL_ID].position).toBe('top-left');
    expect(vizStore.panels[PANEL_ID].visible).toBe(true);
  });

  it('adopts a debugger component that already exists at initialize time', () => {
    // Create the Mesh + debugger entities BEFORE initialize so the System's
    // onInitialize scan over this.entities finds the component.
    addMeshEntity();
    const dbg = world.createEntity();
    dbg.add(new MeshDebuggerComponent({ visible: true }));

    world.addSystem(new MeshSystem(eventBus));
    world.addSystem(new MeshDebuggerSystem(eventBus));
    world.initialize();

    // One frame lets MeshSystem build the instance; the debugger's onUpdate
    // retry then registers the (already-adopted) component's panel.
    world.update(1 / 60);

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

  it('does not register a panel while no Mesh has a live instance', () => {
    world.addSystem(new MeshDebuggerSystem(eventBus));
    world.initialize();

    const dbg = world.createEntity();
    dbg.add(new MeshDebuggerComponent({ visible: true }));
    world.update(1 / 60);

    // No MeshComponent with an instance anywhere → nothing registered.
    expect(vizStore.panels[PANEL_ID]).toBeUndefined();
  });

  it('registers the panel hidden when the component starts not visible', () => {
    world.addSystem(new MeshSystem(eventBus));
    world.addSystem(new MeshDebuggerSystem(eventBus));
    world.initialize();

    addMeshEntity();
    const dbg = world.createEntity();
    dbg.add(new MeshDebuggerComponent()); // visible defaults to false
    world.update(1 / 60);

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

  it('targets the entity named by targetEntityId when present', () => {
    world.addSystem(new MeshSystem(eventBus));
    world.addSystem(new MeshDebuggerSystem(eventBus));
    world.initialize();

    addMeshEntity('Hero');
    addMeshEntity('Decoy');
    const dbg = world.createEntity();
    dbg.add(
      new MeshDebuggerComponent({ visible: true, targetEntityId: 'Hero' })
    );
    world.update(1 / 60);

    expect(vizStore.panels[PANEL_ID]).toBeDefined();

    // The panel's Reload callback emits a LOAD for the targeted entity.
    const seen: Array<{ entityId: string; src: string }> = [];
    eventBus.on(MeshInputEvents.LOAD, (e) =>
      seen.push(e as { entityId: string; src: string })
    );
    const { getByText } = render(() => vizStore.panels[PANEL_ID].content());
    fireEvent.click(getByText(/reload/i));
    expect(seen).toHaveLength(1);
    expect(seen[0].entityId).toBe('Hero');
    expect(seen[0].src).toBe('/hero.glb');
  });

  it('falls back to scanning for any Mesh when targetEntityId is unknown', () => {
    world.addSystem(new MeshSystem(eventBus));
    world.addSystem(new MeshDebuggerSystem(eventBus));
    world.initialize();

    addMeshEntity('Hero');
    const dbg = world.createEntity();
    dbg.add(
      new MeshDebuggerComponent({
        visible: true,
        targetEntityId: 'DoesNotExist',
      })
    );
    world.update(1 / 60);

    // Scan path still finds Hero and registers the panel.
    expect(vizStore.panels[PANEL_ID]).toBeDefined();
  });

  it('adopts a debugger component added after initialize', () => {
    world.addSystem(new MeshSystem(eventBus));
    world.addSystem(new MeshDebuggerSystem(eventBus));
    world.initialize();

    addMeshEntity();
    world.update(1 / 60); // build the Mesh instance first

    // Now add the debugger entity — onEntityAdded should adopt + register.
    const dbg = world.createEntity();
    dbg.add(new MeshDebuggerComponent({ visible: true }));

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

  it('registers on a later frame once a Mesh instance appears', () => {
    world.addSystem(new MeshSystem(eventBus));
    world.addSystem(new MeshDebuggerSystem(eventBus));
    world.initialize();

    // Debugger present first, no Mesh yet.
    const dbg = world.createEntity();
    dbg.add(new MeshDebuggerComponent({ visible: true }));
    world.update(1 / 60);
    expect(vizStore.panels[PANEL_ID]).toBeUndefined();

    // Mesh shows up; the onUpdate retry path registers it.
    addMeshEntity();
    world.update(1 / 60);
    expect(vizStore.panels[PANEL_ID]).toBeDefined();
  });

  it('renders the live MeshPanel content into the registered panel', () => {
    world.addSystem(new MeshSystem(eventBus));
    world.addSystem(new MeshDebuggerSystem(eventBus));
    world.initialize();

    addMeshEntity();
    const dbg = world.createEntity();
    dbg.add(new MeshDebuggerComponent({ visible: true }));
    world.update(1 / 60);

    const { container } = render(() => vizStore.panels[PANEL_ID].content());
    expect(container.textContent).toContain('Status');
    expect(container.textContent).toContain('Source');
  });

  it('unregisters the panel on shutdown', () => {
    world.addSystem(new MeshSystem(eventBus));
    world.addSystem(new MeshDebuggerSystem(eventBus));
    world.initialize();

    addMeshEntity();
    const dbg = world.createEntity();
    dbg.add(new MeshDebuggerComponent({ visible: true }));
    world.update(1 / 60);
    expect(vizStore.panels[PANEL_ID]).toBeDefined();

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