Movement.core.ts

Movement — pure core.

Kinematic character movement with jumping and grounding. The core consumes an input intent (move vector [x,y,z] on the XZ plane + jump pressed) and a per-frame grounding cue (a groundY for the column directly beneath the character — the renderer supplies this via a raycast or a flat-floor assumption), and returns the next position and velocity.

The caller (System) is the bridge between the renderer and the core: it reads the mesh's current position, hands it to the core, and writes the result back to the renderer. All the bookkeeping — gravity integration, jump impulse, ground snapping, facing yaw — happens here, in pure TS.

No imports from @babylonjs, three, solid-js, or the DOM. Vec3 is a tuple. Same (params, inputs, dt) ⇒ same outputs.

Movement.core.ts

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

export interface MovementParams {
  /** Horizontal speed at full input, world units / second. */
  speed: number;
  /** Yaw rotation speed toward movement direction, radians / second. */
  rotationSpeed: number;
  /** Vertical velocity applied on jump press, world units / second. */
  jumpForce: number;
  /** Gravity pulling the character down, world units / second^2. */
  gravity: number;
  /** Half-height of the capsule — "feet" are `feetOffset` below the pivot. */
  feetOffset: number;
  /** Terminal fall speed cap. 0 = uncapped. */
  maxFallSpeed: number;
  /** When true, the mesh yaws to face its horizontal direction of motion. */
  faceMotion: boolean;
}

export const DEFAULT_MOVEMENT_PARAMS: MovementParams = {
  speed: 5,
  rotationSpeed: Math.PI * 2,
  jumpForce: 8,
  gravity: 20,
  feetOffset: 1,
  maxFallSpeed: 50,
  faceMotion: true,
};

export interface MovementInputs {
  /** Desired horizontal motion; magnitude clamped to 1 inside the core. */
  moveX: number;
  moveZ: number;
  /** True on the frame the user pressed jump (edge-triggered). */
  jumpPressed: boolean;
  /**
   * World Y of the ground in the character's current column, or `null` if no
   * ground was found below. Renderers that want flat-floor semantics can pass
   * `0` every frame; richer games pass a raycast hit Y.
   */
  groundY: number | null;
}

export interface MovementTick {
  /** New position (pivot at character center, so feet are at `posY - feetOffset`). */
  posX: number;
  posY: number;
  posZ: number;
  /** New velocity. Horizontal components mirror the input each frame (kinematic). */
  velX: number;
  velY: number;
  velZ: number;
  /** Yaw in radians the mesh should rotate to. Unchanged when not moving. */
  yaw: number;
  /** True after integration if the character's feet touched the ground this frame. */
  isGrounded: boolean;
  /** True if horizontal input had any magnitude this frame. */
  isMoving: boolean;
  /** Edge-triggered: true only on the frame the character left the ground via jump. */
  jumpedThisFrame: boolean;
  /** Edge-triggered: true only on the frame `isGrounded` flipped. */
  groundedChanged: boolean;
}

export interface MovementState {
  posX: number;
  posY: number;
  posZ: number;
  velX: number;
  velY: number;
  velZ: number;
  yaw: number;
  isGrounded: boolean;
  isMoving: boolean;
}

export interface MovementInstance {
  getState(): Readonly<MovementState>;
  setPosition(x: number, y: number, z: number): void;
  setVelocity(x: number, y: number, z: number): void;
  setYaw(yaw: number): void;
  update(inputs: MovementInputs, dt: number): MovementTick;
  getParams(): Readonly<MovementParams>;
  setParams(partial: Partial<MovementParams>): void;
  reset(): void;
}

Normalize a horizontal input vector into a [-1, 1] disc. Returns the input length so callers can distinguish "holding" from "holding hard".

Movement.core.ts

export function clampMoveInput(x: number, z: number): { x: number; z: number; len: number } {
  const len = Math.hypot(x, z);
  if (len <= 1e-6) return { x: 0, z: 0, len: 0 };
  if (len > 1) return { x: x / len, z: z / len, len: 1 };
  return { x, z, len };
}

Rotate current yaw toward target yaw by at most rotationSpeed * dt, taking the shorter of the two arcs. Handles PI wrap.

Movement.core.ts

export function stepYaw(current: number, target: number, rotationSpeed: number, dt: number): number {
  let delta = target - current;
  while (delta > Math.PI) delta -= Math.PI * 2;
  while (delta < -Math.PI) delta += Math.PI * 2;
  const maxStep = rotationSpeed * dt;
  if (Math.abs(delta) <= maxStep) return current + delta;
  return current + Math.sign(delta) * maxStep;
}

export function createMovement(params: Partial<MovementParams> = {}): MovementInstance {
  const active: MovementParams = { ...DEFAULT_MOVEMENT_PARAMS, ...params };
  const state: MovementState = {
    posX: 0,
    posY: 0,
    posZ: 0,
    velX: 0,
    velY: 0,
    velZ: 0,
    yaw: 0,
    isGrounded: true,
    isMoving: false,
  };

  return {
    getState() {
      return state;
    },

    setPosition(x, y, z) {
      state.posX = x;
      state.posY = y;
      state.posZ = z;
    },

    setVelocity(x, y, z) {
      state.velX = x;
      state.velY = y;
      state.velZ = z;
    },

    setYaw(yaw) {
      state.yaw = yaw;
    },

    update(inputs, dt) {
      const prevGrounded = state.isGrounded;
      const { x: ix, z: iz, len: inputLen } = clampMoveInput(inputs.moveX, inputs.moveZ);

      // Horizontal velocity is assigned from input each frame (kinematic, not
      // momentum-based). Matches the reference Movement's "move mesh by
      // desiredVelocity * speed * dt" semantics.
      state.velX = ix * active.speed;
      state.velZ = iz * active.speed;

      // Jump impulse: only honored when grounded; edge-triggered by the caller.
      let jumpedThisFrame = false;
      if (inputs.jumpPressed && state.isGrounded) {
        state.velY = active.jumpForce;
        state.isGrounded = false;
        jumpedThisFrame = true;
      }

      // Gravity integration. Clamp downward fall speed if configured.
      if (!state.isGrounded) {
        state.velY -= active.gravity * dt;
        if (active.maxFallSpeed > 0 && state.velY < -active.maxFallSpeed) {
          state.velY = -active.maxFallSpeed;
        }
      }

      // Integrate position.
      state.posX += state.velX * dt;
      state.posY += state.velY * dt;
      state.posZ += state.velZ * dt;

      // Ground resolution: snap feet to groundY when falling through it. The
      // character's pivot is at the capsule center, so feet = posY - feetOffset.
      if (inputs.groundY !== null) {
        const feetY = state.posY - active.feetOffset;
        if (state.velY <= 0 && feetY <= inputs.groundY) {
          state.posY = inputs.groundY + active.feetOffset;
          state.velY = 0;
          state.isGrounded = true;
        }
      }
      // No ground info means we stay in whatever state integration produced —
      // if the character was grounded and started falling this frame (no jump),
      // gravity will pull them off; the next frame the renderer needs to supply
      // a groundY or the character falls forever. That's the contract.
      if (inputs.groundY === null && !jumpedThisFrame && !inputs.jumpPressed) {
        // If we were grounded with no ground info, trust the previous state
        // rather than silently starting to fall.
        if (prevGrounded && state.velY === 0) {
          state.isGrounded = true;
        }
      }

      // Yaw toward horizontal direction of motion.
      if (active.faceMotion && inputLen > 1e-6) {
        const targetYaw = Math.atan2(ix, iz);
        state.yaw = stepYaw(state.yaw, targetYaw, active.rotationSpeed, dt);
      }

      state.isMoving = inputLen > 1e-6;

      return {
        posX: state.posX,
        posY: state.posY,
        posZ: state.posZ,
        velX: state.velX,
        velY: state.velY,
        velZ: state.velZ,
        yaw: state.yaw,
        isGrounded: state.isGrounded,
        isMoving: state.isMoving,
        jumpedThisFrame,
        groundedChanged: state.isGrounded !== prevGrounded,
      };
    },

    getParams() {
      return active;
    },

    setParams(partial) {
      Object.assign(active, partial);
    },

    reset() {
      state.posX = 0;
      state.posY = 0;
      state.posZ = 0;
      state.velX = 0;
      state.velY = 0;
      state.velZ = 0;
      state.yaw = 0;
      state.isGrounded = true;
      state.isMoving = false;
    },
  };
}

Exported for parity with other mechanics; unused but imported via tuple types in some adapters.

Movement.core.ts

export type MovementVec3 = Vec3;

Movement.defs.ts

Movement — definitions.

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

Movement.defs.ts

import { Component } from '@babylonjsmarket/ecs';
import type { Vec3 } from '@babylonjsmarket/ecs/renderer-types';
import { DEFAULT_MOVEMENT_PARAMS, type MovementInstance, type MovementParams } from './Movement.core';

Events

Movement.defs.ts

export const MovementEvents = {
  /** Emitted the frame the character leaves the ground via jump. */
  JUMP_STARTED: 'movement.jump.started',
  /** Emitted whenever the grounded state flips. Payload: { isGrounded }. */
  GROUNDED_CHANGED: 'movement.grounded.changed',
  /** Emitted the frame the character transitions from still to moving. */
  STARTED_MOVING: 'movement.started',
  /** Emitted the frame the character transitions from moving to still. */
  STOPPED_MOVING: 'movement.stopped',
} as const;

export const MovementInputEvents = {
  /** External move intent. Payload: `{ entityId, x, y?, z }`. XZ plane only. */
  SET_MOVEMENT_VECTOR: 'input.movement.vector',
  /** External jump request. Payload: `{ entityId }`. Edge-triggered. */
  JUMP_REQUESTED: 'input.jump.requested',
} as const;

export interface MovementSetVectorEvent {
  entityId: string;
  x: number;
  y?: number;
  z: number;
}

export interface MovementJumpEvent {
  entityId: string;
}

export interface MovementInput extends Partial<MovementParams> {
  /**
   * World Y value of the ground under the character (flat-floor assumption).
   * Pass `null` to disable grounding entirely — the character falls forever.
   */
  groundY?: number | null;
  /** Initial position of the character's pivot. Defaults to [0, feetOffset, 0]. */
  position?: Vec3;
}

Component

Movement.defs.ts

export class MovementComponent extends Component {
  params: MovementParams;
  /** Ground Y passed into the core each frame. null = no grounding. */
  groundY: number | null;
  initialPosition: Vec3;

  /** Live input intent — mutate directly or via input events. */
  moveX: number = 0;
  moveZ: number = 0;
  /** Edge-triggered: set true to request a jump; consumed on the next tick. */
  jumpPressed: boolean = false;

  /** Populated lazily by the System on first tick. */
  instance: MovementInstance | null = null;

  constructor(data: MovementInput = {}) {
    super();
    const { groundY, position, ...params } = data;
    this.params = { ...DEFAULT_MOVEMENT_PARAMS, ...params };
    this.groundY = groundY === undefined ? 0 : groundY;
    this.initialPosition = position
      ? [position[0], position[1], position[2]]
      : [0, this.params.feetOffset, 0];
  }

  serialize(): MovementInput {
    return {
      ...this.params,
      groundY: this.groundY,
      position: [...this.initialPosition] as Vec3,
    };
  }
}

Movement.panel.tsx

Movement — renderer-free Solid panel. Binds directly to the pure core and works over either the Babylon or the Three.js demo. No @babylonjs/three imports (including type-only).

Movement.panel.tsx

import { Component as SolidComponent, createSignal, onCleanup, onMount } from 'solid-js';
import { createStore } from 'solid-js/store';
import { Slider, ResetButton, Section } from '../_shared/ui';
import {
  DEFAULT_MOVEMENT_PARAMS,
  type MovementInstance,
  type MovementParams,
} from './Movement.core';

export interface MovementPanelProps {
  /** The live core instance. Panel reads/writes its params directly. */
  core: MovementInstance;
  /** Optional: called when the user hits the "Jump" button. */
  onJump?: () => void;
}

export const MovementPanel: SolidComponent<MovementPanelProps> = (props) => {
  const [params, setParams] = createStore<MovementParams>({ ...props.core.getParams() });
  const [isGrounded, setIsGrounded] = createSignal(props.core.getState().isGrounded);
  const [isMoving, setIsMoving] = createSignal(props.core.getState().isMoving);
  const [velY, setVelY] = createSignal(props.core.getState().velY);

  let pollId: ReturnType<typeof setInterval> | undefined;
  onMount(() => {
    pollId = setInterval(() => {
      const s = props.core.getState();
      setIsGrounded(s.isGrounded);
      setIsMoving(s.isMoving);
      setVelY(s.velY);
    }, 80);
  });
  onCleanup(() => {
    if (pollId) clearInterval(pollId);
  });

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

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

  return (
    <div style={{ 'font-family': 'system-ui, sans-serif', color: '#ddd', 'min-width': '240px' }}>
      <Section title="State">
        <button
          onClick={() => props.onJump?.()}
          style={{
            width: '100%',
            padding: '6px',
            background: '#222',
            color: '#7fe5a0',
            border: '1px solid #7fe5a0',
            cursor: 'pointer',
          }}
        >
          Trigger jump
        </button>
        <div style={{ 'margin-top': '6px', color: '#888', 'font-size': '10px' }}>
          {isGrounded() ? 'Grounded' : 'Airborne'} · {isMoving() ? 'moving' : 'still'} · velY {velY().toFixed(2)}
        </div>
      </Section>

      <Section title="Locomotion">
        <Slider
          label="speed (units / s)"
          value={params.speed}
          min={0}
          max={20}
          step={0.1}
          onChange={(v) => push('speed', v)}
        />
        <Slider
          label="rotationSpeed (rad / s)"
          value={params.rotationSpeed}
          min={0}
          max={Math.PI * 4}
          step={0.1}
          onChange={(v) => push('rotationSpeed', v)}
        />
        <label
          style={{
            display: 'flex', 'align-items': 'center', gap: '8px', 'font-size': '11px',
            'margin-top': '4px',
          }}
        >
          <input
            type="checkbox"
            checked={params.faceMotion}
            onChange={(e) => push('faceMotion', e.currentTarget.checked)}
          />
          <span>Face direction of motion</span>
        </label>
      </Section>

      <Section title="Jump & gravity">
        <Slider
          label="jumpForce"
          value={params.jumpForce}
          min={0}
          max={25}
          step={0.5}
          onChange={(v) => push('jumpForce', v)}
        />
        <Slider
          label="gravity"
          value={params.gravity}
          min={0}
          max={60}
          step={0.5}
          onChange={(v) => push('gravity', v)}
        />
        <Slider
          label="maxFallSpeed (0 = uncapped)"
          value={params.maxFallSpeed}
          min={0}
          max={100}
          step={1}
          onChange={(v) => push('maxFallSpeed', v)}
        />
      </Section>

      <Section title="Body">
        <Slider
          label="feetOffset (capsule half-height)"
          value={params.feetOffset}
          min={0}
          max={4}
          step={0.05}
          onChange={(v) => push('feetOffset', v)}
        />
      </Section>

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

Movement.ts

Movement.ts — renderer-agnostic System for character movement with jumping and grounding.

The pure core (Movement.core.ts) does the math. This System bridges it to the world: on each frame it reads the input intent (move vector + jump edge) out of the Component, reads the current mesh position from the active adapter, feeds both into the core with a groundY from the Component (flat-floor assumption by default), and writes the resulting position and yaw rotation back through the adapter.

Input intent is updated two ways: - Directly by setting component.moveX/moveZ/jumpPressed (script, AI). - Via event bus: MovementInputEvents.SET_MOVEMENT_VECTOR and MovementInputEvents.JUMP_REQUESTED.

Zero imports from @babylonjs or three. Identical under both adapters.

Movement.ts

import { PhysicsInputEvents } from '@babylonjsmarket/arcade';
import { System } from '@babylonjsmarket/ecs';
import type { EventBus } from '@babylonjsmarket/ecs';
import type { Entity } from '@babylonjsmarket/ecs';
import type { Vec3 } from '@babylonjsmarket/ecs/renderer-types';
import { MeshPrimitiveComponent } from '../MeshPrimitive/MeshPrimitive.defs';
import { PhysicsComponent, type PhysicsSetVelocityEvent } from '../Physics/Physics.defs';
import { createMovement } from './Movement.core';
import { MovementComponent, MovementEvents, MovementInputEvents, type MovementJumpEvent, type MovementSetVectorEvent } from './Movement.defs';

System

Movement.ts

export class MovementSystem extends System {
  private unsubscribes: Array<() => void> = [];
  /** Reusable tuple for get/set adapter calls — avoids per-frame allocation. */
  private _tmp: Vec3 = [0, 0, 0];
  /** Reused scratch for the separation neighbor scan + its result. */
  private _sep: Vec3 = [0, 0, 0];
  private _sepOut = { x: 0, z: 0 };

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

  /**
   * AI anti-clump separation. Physics bodies that all chase one ball pile into
   * a scrum; this adds a short-range, capped repulsion from nearby players so
   * `ai`-tagged agents keep their personal space and the play spreads out.
   * Only `ai` agents are pushed (the human's input stays crisp — they already
   * can't overlap thanks to the body), but they steer clear of EVERY player +
   * AI. Returns a velocity addend in `out`; zero when off or no one's close.
   */
  private separationVelocity(entity: Entity, px: number, pz: number, out: { x: number; z: number }): void {
    out.x = 0;
    out.z = 0;
    const r = this.world?.renderer;
    if (!r || !this.world || !entity.hasTag('ai')) return;
    const RADIUS = 2.2; // centers closer than this repel
    const STRENGTH = 4; // u/s per unit of crowding
    const MAX = 6; // cap so a tight cluster can't fling anyone
    let sx = 0;
    let sz = 0;
    for (const tag of ['ai', 'player']) {
      for (const other of this.world.getEntitiesByTag(tag)) {
        if (other.id === entity.id) continue;
        const om = other.get(MeshPrimitiveComponent);
        if (!om?.handle) continue;
        r.getMeshWorldPosition(om.handle, this._sep);
        const dx = px - this._sep[0];
        const dz = pz - this._sep[2];
        const d2 = dx * dx + dz * dz;
        if (d2 > 1e-6 && d2 < RADIUS * RADIUS) {
          const d = Math.sqrt(d2);
          const w = (1 - d / RADIUS) / d; // direction × linear falloff
          sx += dx * w;
          sz += dz * w;
        }
      }
    }
    let vx = sx * STRENGTH;
    let vz = sz * STRENGTH;
    const mag = Math.hypot(vx, vz);
    if (mag > MAX) {
      vx = (vx / mag) * MAX;
      vz = (vz / mag) * MAX;
    }
    out.x = vx;
    out.z = vz;
  }

  protected onInitialize(): void {
    this.unsubscribes.push(
      this.eventBus.on(MovementInputEvents.SET_MOVEMENT_VECTOR, (e: MovementSetVectorEvent) => {
        this.handleSetVector(e);
      }),
      this.eventBus.on(MovementInputEvents.JUMP_REQUESTED, (e: MovementJumpEvent) => {
        this.handleJump(e);
      }),
    );

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

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

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

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

    // Seed position: prefer mesh world position if available, else the
    // Component's initialPosition, else origin + feetOffset.
    const mesh = entity.get(MeshPrimitiveComponent);
    const r = this.world?.renderer;
    if (mesh?.handle && r) {
      r.getMeshWorldPosition(mesh.handle, this._tmp);
      comp.instance.setPosition(this._tmp[0], this._tmp[1], this._tmp[2]);
    } else {
      const p = comp.initialPosition;
      comp.instance.setPosition(p[0], p[1], p[2]);
    }
  }

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

  private handleSetVector(e: MovementSetVectorEvent): void {
    const entity = this.findEntityById(e.entityId);
    const comp = entity?.get(MovementComponent);
    if (!comp) return;
    comp.moveX = e.x;
    comp.moveZ = e.z;
  }

  private handleJump(e: MovementJumpEvent): void {
    const entity = this.findEntityById(e.entityId);
    const comp = entity?.get(MovementComponent);
    if (!comp) return;
    comp.jumpPressed = true;
  }

  protected onUpdate(dt: number): void {
    const r = this.world?.renderer;
    for (const entity of this.entities) {
      const comp = entity.get(MovementComponent);
      if (!comp?.instance) continue;

      // Pick up live panel edits to params.
      comp.instance.setParams(comp.params);

      // Sync the core's position with what the renderer actually shows —
      // external systems (Shadow, collisions) may have written to the mesh.
      const mesh = entity.get(MeshPrimitiveComponent);
      if (mesh?.handle && r) {
        r.getMeshWorldPosition(mesh.handle, this._tmp);
        comp.instance.setPosition(this._tmp[0], this._tmp[1], this._tmp[2]);
      }

      const wasMoving = comp.instance.getState().isMoving;
      const tick = comp.instance.update(
        {
          moveX: comp.moveX,
          moveZ: comp.moveZ,
          jumpPressed: comp.jumpPressed,
          groundY: comp.groundY,
        },
        dt,
      );

      // Jump is edge-triggered; reset after the update consumes it.
      comp.jumpPressed = false;

      const entityId = (entity as unknown as { id: string }).id;

      // Physics-velocity mode: when the entity ALSO carries a (non-static)
      // Physics body, the rigid body — not this System — owns the transform.
      // We translate the core's per-tick horizontal velocity into a
      // `physics.setVelocity` so the capsule COLLIDES with walls, the ball, and
      // other bodies instead of teleporting through them. Vertical velocity is
      // left to the engine (gravity), except on the jump frame where we inject
      // the jump impulse. We do NOT write the mesh transform here — Havok syncs
      // it from the body after each step (a setMeshPosition would be overwritten).
      const phys = entity.get(PhysicsComponent);
      const physicsMode = !!phys && phys.motionType !== 'static';

      if (physicsMode && r) {
        const state = r.physicsGetBodyState(entityId);
        if (state) {
          const vy = tick.jumpedThisFrame ? comp.params.jumpForce : state.linearVelocity[1];
          // Blend in AI separation so chasers don't clump on the ball.
          this.separationVelocity(entity, this._tmp[0], this._tmp[2], this._sepOut);
          this.eventBus.emit(PhysicsInputEvents.SET_VELOCITY, {
            entityId,
            vx: tick.velX + this._sepOut.x,
            vy,
            vz: tick.velZ + this._sepOut.z,
          } satisfies PhysicsSetVelocityEvent);
        }
      } else {
        if (mesh?.handle && r) {
          r.setMeshPosition(mesh.handle, tick.posX, tick.posY, tick.posZ);
          if (comp.params.faceMotion) {
            r.setMeshRotation(mesh.handle, 0, tick.yaw, 0);
          }
        }
        if (mesh) {
          mesh.position[0] = tick.posX;
          mesh.position[1] = tick.posY;
          mesh.position[2] = tick.posZ;
          if (comp.params.faceMotion) {
            mesh.rotation[1] = tick.yaw;
          }
        }
      }

      if (tick.jumpedThisFrame) {
        this.eventBus.emit(MovementEvents.JUMP_STARTED, { entityId });
      }
      if (tick.groundedChanged) {
        this.eventBus.emit(MovementEvents.GROUNDED_CHANGED, {
          entityId,
          isGrounded: tick.isGrounded,
        });
      }
      if (tick.isMoving !== wasMoving) {
        this.eventBus.emit(
          tick.isMoving ? MovementEvents.STARTED_MOVING : MovementEvents.STOPPED_MOVING,
          { entityId },
        );
      }
    }
  }
}

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

Movement.ts

export { MovementComponent, MovementEvents, type MovementInput, MovementInputEvents, type MovementJumpEvent, type MovementSetVectorEvent } from './Movement.defs';

Movement.viz.tsx

Movement.viz.tsx — ECS wrapper that registers the renderer-free MovementPanel with vizStore. The Panel itself lives in Movement.panel.tsx and binds to the pure core.

Movement.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 { MovementPanel } from './Movement.panel';
import {
  MovementComponent,
  MovementInputEvents,
} from './Movement';
import type { MovementInstance } from './Movement.core';

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

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

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

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

const PANEL_ID = 'movement-debugger';

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

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

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

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

  private findMovement(): { entityId: string; core: MovementInstance } | null {
    if (!this.world) return null;
    for (const entity of this.world.getEntities()) {
      const comp = entity.get(MovementComponent);
      if (comp?.instance) return { entityId: entity.id, core: comp.instance };
    }
    return null;
  }

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

    const found = this.findMovement();
    if (!found) return;

    const entityId = found.entityId;

    vizStore.registerPanel({
      id: PANEL_ID,
      title: 'Movement',
      position: this.component.position,
      titleColor: '#7fe5a0',
      content: () => (
        <MovementPanel
          core={found.core}
          onJump={() =>
            this.eventBus.emit(MovementInputEvents.JUMP_REQUESTED, { entityId })
          }
        />
      ),
    });

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

  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(MovementDebuggerComponent);
    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;
    }
  }
}

Movement.contract.test.ts

13 ✓

ArcadeECS contract: Movement

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

Movement.contract.test.ts

import { runMechanicContract } from '@babylonjsmarket/ecs/testing';
import type { MechanicContractContext } from '@babylonjsmarket/ecs/testing';
import {
  MovementComponent,
  MovementSystem,
  MovementEvents,
  MovementInputEvents,
} from './Movement';

/**
 * Movement routes its inputs by `entityId`. The contract battery mints a
 * fresh entity inside `buildWorld`; we latch onto `world.entity.created` so
 * `makeInputPayload` always references the most recent one.
 */
let latestEntityId = 'contract-test';

runMechanicContract({
  name: 'Movement',
  componentClass: MovementComponent,
  systemClass: MovementSystem,
  sampleInput: { speed: 12, jumpForce: 10 },
  events: {
    input: [
      MovementInputEvents.SET_MOVEMENT_VECTOR,
      MovementInputEvents.JUMP_REQUESTED,
    ],
    output: [
      MovementEvents.JUMP_STARTED,
      MovementEvents.GROUNDED_CHANGED,
      MovementEvents.STARTED_MOVING,
      MovementEvents.STOPPED_MOVING,
    ],
  },
  setup(ctx: MechanicContractContext) {
    ctx.eventBus.on('world.entity.created', (e: { entity: { id: string } }) => {
      latestEntityId = e.entity.id;
    });
  },
  makeInputPayload(event) {
    if (event === MovementInputEvents.SET_MOVEMENT_VECTOR) {
      return { entityId: latestEntityId, x: 1, z: 0 };
    }
    if (event === MovementInputEvents.JUMP_REQUESTED) {
      return { entityId: latestEntityId };
    }
    return {};
  },
});

Movement.core.test.ts

16 ✓

Movement core

starts grounded, still, with zero velocity
horizontal input translates the character at speed units per second
diagonal input is normalized so W+D does not exceed speed
jump sets upward velocity to jumpForce and lifts the character off the ground
jump is ignored while already airborne
gravity accumulates on velY while airborne
lands when feet touch groundY on the way down
groundedChanged fires on the frame the grounded state flips
faceMotion rotates yaw toward the direction of motion
setParams updates behavior on the next frame
reset returns the character to the origin, grounded, at rest
clampMoveInput normalizes magnitudes above 1 and preserves the direction
stepYaw takes the short arc across the PI wrap
caps downward velocity at maxFallSpeed during a long fall
does not clamp fall speed when maxFallSpeed is 0 (uncapped)
keeps a resting character grounded when ground info disappears (no jump)

Last run 2026-08-22

Movement.core.test.ts

import { describe, it, expect } from 'vitest';
import {
  createMovement,
  clampMoveInput,
  stepYaw,
  DEFAULT_MOVEMENT_PARAMS,
} from './Movement.core';

describe('Movement core', () => {
  it('starts grounded, still, with zero velocity', () => {
    const m = createMovement();
    const s = m.getState();
    expect(s.velX).toBe(0);
    expect(s.velY).toBe(0);
    expect(s.velZ).toBe(0);
    expect(s.isGrounded).toBe(true);
    expect(s.isMoving).toBe(false);
  });

  it('horizontal input translates the character at speed units per second', () => {
    const m = createMovement({ speed: 10, feetOffset: 1 });
    m.setPosition(0, 1, 0);
    const tick = m.update({ moveX: 1, moveZ: 0, jumpPressed: false, groundY: 0 }, 0.1);
    expect(tick.posX).toBeCloseTo(1, 5);
    expect(tick.isMoving).toBe(true);
  });

  it('diagonal input is normalized so W+D does not exceed speed', () => {
    const m = createMovement({ speed: 10, feetOffset: 1 });
    m.setPosition(0, 1, 0);
    const tick = m.update({ moveX: 1, moveZ: 1, jumpPressed: false, groundY: 0 }, 1);
    const dist = Math.hypot(tick.posX, tick.posZ);
    expect(dist).toBeCloseTo(10, 5);
  });

  it('jump sets upward velocity to jumpForce and lifts the character off the ground', () => {
    const m = createMovement({ jumpForce: 8, gravity: 20, feetOffset: 1 });
    m.setPosition(0, 1, 0);
    const tick = m.update({ moveX: 0, moveZ: 0, jumpPressed: true, groundY: 0 }, 0.1);
    // velY = 8 - 20*0.1 = 6 (gravity applied this same frame after jump).
    expect(tick.velY).toBeCloseTo(6, 5);
    expect(tick.jumpedThisFrame).toBe(true);
    expect(tick.isGrounded).toBe(false);
  });

  it('jump is ignored while already airborne', () => {
    const m = createMovement({ jumpForce: 8, gravity: 20, feetOffset: 1 });
    m.setPosition(0, 5, 0);
    // Kick off the ground first.
    m.update({ moveX: 0, moveZ: 0, jumpPressed: true, groundY: null }, 0.016);
    // Try to double-jump mid-air — should have no effect.
    const before = m.getState().velY;
    const tick = m.update({ moveX: 0, moveZ: 0, jumpPressed: true, groundY: null }, 0.016);
    expect(tick.jumpedThisFrame).toBe(false);
    // velY strictly decreases under gravity, never snaps back up to jumpForce.
    expect(tick.velY).toBeLessThan(before);
  });

  it('gravity accumulates on velY while airborne', () => {
    const m = createMovement({ gravity: 20, jumpForce: 8, feetOffset: 1 });
    m.setPosition(0, 5, 0);
    // Jump to kick off the ground — now airborne.
    m.update({ moveX: 0, moveZ: 0, jumpPressed: true, groundY: null }, 0.016);
    const t1 = m.update({ moveX: 0, moveZ: 0, jumpPressed: false, groundY: null }, 0.1);
    const t2 = m.update({ moveX: 0, moveZ: 0, jumpPressed: false, groundY: null }, 0.1);
    expect(t2.velY).toBeLessThan(t1.velY);
  });

  it('lands when feet touch groundY on the way down', () => {
    const m = createMovement({ gravity: 20, feetOffset: 1 });
    m.setPosition(0, 3, 0);
    m.setVelocity(0, -10, 0);
    // Manually clear grounded so the fall registers.
    m.update({ moveX: 0, moveZ: 0, jumpPressed: false, groundY: -100 }, 0.0001);
    // Now feed a real ground and step; feet should snap to groundY.
    const tick = m.update({ moveX: 0, moveZ: 0, jumpPressed: false, groundY: 0 }, 0.2);
    expect(tick.isGrounded).toBe(true);
    expect(tick.posY).toBeCloseTo(1, 5); // groundY(0) + feetOffset(1)
    expect(tick.velY).toBe(0);
  });

  it('groundedChanged fires on the frame the grounded state flips', () => {
    const m = createMovement({ jumpForce: 8, gravity: 20, feetOffset: 1 });
    m.setPosition(0, 1, 0);
    const leave = m.update({ moveX: 0, moveZ: 0, jumpPressed: true, groundY: 0 }, 0.016);
    expect(leave.groundedChanged).toBe(true);
    expect(leave.isGrounded).toBe(false);

    // Hanging mid-air: grounded state is stable, no change.
    const hang = m.update({ moveX: 0, moveZ: 0, jumpPressed: false, groundY: null }, 0.016);
    expect(hang.groundedChanged).toBe(false);
  });

  it('faceMotion rotates yaw toward the direction of motion', () => {
    const m = createMovement({ rotationSpeed: Math.PI, faceMotion: true, feetOffset: 1 });
    m.setPosition(0, 1, 0);
    const tick = m.update({ moveX: 1, moveZ: 0, jumpPressed: false, groundY: 0 }, 1);
    // Target is atan2(1, 0) = PI/2. With rotationSpeed=PI and dt=1 we step up
    // to PI, so we fully reach the target.
    expect(tick.yaw).toBeCloseTo(Math.PI / 2, 5);
  });

  it('setParams updates behavior on the next frame', () => {
    const m = createMovement({ speed: 5, feetOffset: 1 });
    m.setPosition(0, 1, 0);
    const a = m.update({ moveX: 1, moveZ: 0, jumpPressed: false, groundY: 0 }, 0.1);
    expect(a.posX).toBeCloseTo(0.5, 5);
    m.setParams({ speed: 20 });
    const b = m.update({ moveX: 1, moveZ: 0, jumpPressed: false, groundY: 0 }, 0.1);
    expect(b.posX - a.posX).toBeCloseTo(2, 5);
  });

  it('reset returns the character to the origin, grounded, at rest', () => {
    const m = createMovement();
    m.setPosition(5, 10, -3);
    m.setVelocity(1, 2, 3);
    m.setYaw(1.5);
    m.reset();
    const s = m.getState();
    expect(s.posX).toBe(0);
    expect(s.posY).toBe(0);
    expect(s.posZ).toBe(0);
    expect(s.velY).toBe(0);
    expect(s.yaw).toBe(0);
    expect(s.isGrounded).toBe(true);
    expect(m.getParams()).toEqual(DEFAULT_MOVEMENT_PARAMS);
  });

  it('clampMoveInput normalizes magnitudes above 1 and preserves the direction', () => {
    const r = clampMoveInput(3, 4);
    expect(r.len).toBe(1);
    expect(r.x).toBeCloseTo(0.6, 5);
    expect(r.z).toBeCloseTo(0.8, 5);
  });

  it('stepYaw takes the short arc across the PI wrap', () => {
    // From -3.1 (just past -PI) to 3.1 (just before +PI). The long way round
    // is 6.2 radians; the short way is 2*PI - 6.2 ≈ 0.083 radians through -PI.
    // With maxStep = 0.1, we cover the short arc in one step — the result
    // wraps around -PI and lands near -3.183 (same angle as 3.1, mod 2PI).
    const next = stepYaw(-3.1, 3.1, 10, 0.01);
    const shortArc = 2 * Math.PI - (3.1 - -3.1); // ≈ 0.0832
    expect(next).toBeCloseTo(-3.1 - shortArc, 5);
  });

  it('caps downward velocity at maxFallSpeed during a long fall', () => {
    // jumpForce 0 so the jump press only releases grounding without lifting,
    // then gravity runs unbounded except for the terminal cap.
    const m = createMovement({
      gravity: 100,
      maxFallSpeed: 12,
      jumpForce: 0,
      feetOffset: 1,
    });
    m.setPosition(0, 50, 0);
    // Leave the ground (jumpPressed flips isGrounded even with jumpForce 0).
    m.update({ moveX: 0, moveZ: 0, jumpPressed: true, groundY: null }, 0.016);
    // A big dt would drive velY to -100 without the clamp; expect the cap.
    const tick = m.update({ moveX: 0, moveZ: 0, jumpPressed: false, groundY: null }, 1);
    expect(tick.velY).toBe(-12);
  });

  it('does not clamp fall speed when maxFallSpeed is 0 (uncapped)', () => {
    const m = createMovement({
      gravity: 100,
      maxFallSpeed: 0,
      jumpForce: 0,
      feetOffset: 1,
    });
    m.setPosition(0, 50, 0);
    m.update({ moveX: 0, moveZ: 0, jumpPressed: true, groundY: null }, 0.016);
    const tick = m.update({ moveX: 0, moveZ: 0, jumpPressed: false, groundY: null }, 1);
    // velY = -100*0.016 (first frame) - 100*1 ≈ -101.6, well past any cap.
    expect(tick.velY).toBeLessThan(-100);
  });

  it('keeps a resting character grounded when ground info disappears (no jump)', () => {
    // Starts grounded at rest. A frame with no groundY and no jump must NOT
    // silently flip the character into a fall — it trusts the prior grounded
    // state because velY is still 0.
    const m = createMovement({ feetOffset: 1 });
    m.setPosition(0, 1, 0);
    const tick = m.update({ moveX: 0, moveZ: 0, jumpPressed: false, groundY: null }, 0.1);
    expect(tick.isGrounded).toBe(true);
    expect(tick.groundedChanged).toBe(false);
    expect(tick.velY).toBe(0);
  });
});

Movement.panel.test.tsx

7 ✓

MovementPanel

mounts without a renderer and shows the Locomotion section
moving a slider calls core.setParams with the new value
the Jump button fires onJump when supplied
the Reset button clears params back to defaults
every locomotion / jump / body slider pushes its param into the core
the faceMotion checkbox pushes its boolean into the core
polls the core each interval and reflects live state into the readout

Last run 2026-08-22

Movement.panel.test.tsx

// @vitest-environment jsdom
import { describe, it, expect, vi, afterEach } from 'vitest';
import { render, fireEvent } from '@solidjs/testing-library';
import { MovementPanel } from './Movement.panel';
import { createMovement } from './Movement.core';

describe('MovementPanel', () => {
  afterEach(() => {
    vi.useRealTimers();
  });

  it('mounts without a renderer and shows the Locomotion section', () => {
    const core = createMovement();
    const { container } = render(() => <MovementPanel core={core} />);
    expect(container.textContent).toContain('Locomotion');
    expect(container.textContent).toContain('speed');
    expect(container.textContent).toContain('Jump & gravity');
  });

  it('moving a slider calls core.setParams with the new value', () => {
    const core = createMovement();
    const spy = vi.spyOn(core, 'setParams');
    const { getAllByRole } = render(() => <MovementPanel core={core} />);
    const firstSlider = (getAllByRole('slider') as HTMLInputElement[])[0];
    fireEvent.input(firstSlider, { target: { value: '12' } });
    expect(spy).toHaveBeenCalledWith(expect.objectContaining({ speed: 12 }));
  });

  it('the Jump button fires onJump when supplied', () => {
    const core = createMovement();
    const onJump = vi.fn();
    const { getByText } = render(() => <MovementPanel core={core} onJump={onJump} />);
    fireEvent.click(getByText(/Trigger jump/));
    expect(onJump).toHaveBeenCalled();
  });

  it('the Reset button clears params back to defaults', () => {
    const core = createMovement({ speed: 15 });
    const spy = vi.spyOn(core, 'setParams');
    const { getByText } = render(() => <MovementPanel core={core} />);
    fireEvent.click(getByText(/reset/i));
    expect(spy).toHaveBeenCalled();
  });

  it('every locomotion / jump / body slider pushes its param into the core', () => {
    const core = createMovement();
    const spy = vi.spyOn(core, 'setParams');
    const { getAllByRole } = render(() => <MovementPanel core={core} />);
    const sliders = getAllByRole('slider') as HTMLInputElement[];

    // Order matches the panel: speed, rotationSpeed, jumpForce, gravity,
    // maxFallSpeed, feetOffset.
    const cases: Array<[number, string, number]> = [
      [1, 'rotationSpeed', 3],
      [2, 'jumpForce', 11],
      [3, 'gravity', 30],
      [4, 'maxFallSpeed', 40],
      [5, 'feetOffset', 0.5],
    ];

    for (const [idx, key, value] of cases) {
      spy.mockClear();
      fireEvent.input(sliders[idx], { target: { value: String(value) } });
      expect(spy).toHaveBeenCalledWith(expect.objectContaining({ [key]: value }));
    }
  });

  it('the faceMotion checkbox pushes its boolean into the core', () => {
    const core = createMovement({ faceMotion: true });
    const spy = vi.spyOn(core, 'setParams');
    const { getByRole } = render(() => <MovementPanel core={core} />);
    const checkbox = getByRole('checkbox') as HTMLInputElement;
    fireEvent.click(checkbox);
    expect(spy).toHaveBeenCalledWith(expect.objectContaining({ faceMotion: false }));
  });

  it('polls the core each interval and reflects live state into the readout', () => {
    vi.useFakeTimers();
    const core = createMovement({ jumpForce: 8, gravity: 20, feetOffset: 1 });
    core.setPosition(0, 1, 0);
    const { container } = render(() => <MovementPanel core={core} />);
    // Initial readout: grounded, still, velY 0.00.
    expect(container.textContent).toContain('Grounded');
    expect(container.textContent).toContain('still');
    expect(container.textContent).toContain('velY 0.00');

    // Drive the core airborne and moving, then let the panel's poll fire.
    core.update({ moveX: 1, moveZ: 0, jumpPressed: true, groundY: 0 }, 0.1);
    vi.advanceTimersByTime(80);

    expect(container.textContent).toContain('Airborne');
    expect(container.textContent).toContain('moving');
    // velY after a jump-then-gravity frame is jumpForce - gravity*dt = 6.00.
    expect(container.textContent).toContain('velY 6.00');
  });
});

Movement.test.ts

13 ✓

MovementComponent

applies defaults
merges params on top of defaults
serialize round-trips

MovementSystem

creates a core instance on entity add
seeds core position from renderer.getMeshWorldPosition
SET_MOVEMENT_VECTOR updates input intent and moves the mesh next frame
JUMP_REQUESTED emits JUMP_STARTED and GROUNDED_CHANGED
STARTED_MOVING / STOPPED_MOVING fire on move-intent edges
faceMotion rotates the mesh toward movement direction
skips cleanly when no entities are present
ignores a SET_MOVEMENT_VECTOR for an unknown entityId
ignores a JUMP_REQUESTED for an unknown entityId
seeds the core from initialPosition when the entity has no mesh handle

Last run 2026-08-22

Movement.test.ts

import { describe, it, expect, beforeEach, vi } from 'vitest';
import {
  MovementComponent,
  MovementSystem,
  MovementEvents,
  MovementInputEvents,
} from './Movement';
import { MeshPrimitiveComponent } from '../MeshPrimitive/MeshPrimitive.defs';
import { EventBus, World } from '@babylonjsmarket/ecs';
import { MockRendererAdapter } from '@babylonjsmarket/ecs';

describe('MovementComponent', () => {
  it('applies defaults', () => {
    const c = new MovementComponent();
    expect(c.params.speed).toBe(5);
    expect(c.params.jumpForce).toBe(8);
    expect(c.params.gravity).toBe(20);
    expect(c.params.feetOffset).toBe(1);
    expect(c.params.faceMotion).toBe(true);
    expect(c.groundY).toBe(0);
    expect(c.instance).toBeNull();
  });

  it('merges params on top of defaults', () => {
    const c = new MovementComponent({ speed: 12, jumpForce: 15, groundY: null });
    expect(c.params.speed).toBe(12);
    expect(c.params.jumpForce).toBe(15);
    expect(c.params.gravity).toBe(20); // untouched
    expect(c.groundY).toBeNull();
  });

  it('serialize round-trips', () => {
    const a = new MovementComponent({ speed: 8, gravity: 25, position: [3, 2, 1] });
    const b = new MovementComponent(a.serialize());
    expect(b.params).toEqual(a.params);
    expect(b.groundY).toBe(a.groundY);
    expect(b.initialPosition).toEqual([3, 2, 1]);
  });
});

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

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

  function makePlayer(pos: [number, number, number] = [0, 1, 0]) {
    const entity = world.createEntity();
    const mesh = new MeshPrimitiveComponent({ primitive: 'capsule', position: pos });
    mesh.handle = renderer.createMesh(entity.id, mesh.toPrimitiveSpec());
    renderer.meshWorldPositions.set(mesh.handle, [...pos]);
    entity.add(mesh);
    entity.add(new MovementComponent({ speed: 10, jumpForce: 8, feetOffset: 1 }));
    return entity;
  }

  it('creates a core instance on entity add', () => {
    const entity = makePlayer();
    const comp = entity.get(MovementComponent);
    expect(comp?.instance).not.toBeNull();
  });

  it('seeds core position from renderer.getMeshWorldPosition', () => {
    const entity = makePlayer([3, 1, -2]);
    const comp = entity.get(MovementComponent)!;
    const s = comp.instance!.getState();
    expect(s.posX).toBe(3);
    expect(s.posY).toBe(1);
    expect(s.posZ).toBe(-2);
  });

  it('SET_MOVEMENT_VECTOR updates input intent and moves the mesh next frame', () => {
    const entity = makePlayer();
    eventBus.emit(MovementInputEvents.SET_MOVEMENT_VECTOR, {
      entityId: entity.id,
      x: 1,
      z: 0,
    });
    renderer.calls.length = 0;
    world.update(0.1);
    const moves = renderer.calls.filter((c) => c.method === 'setMeshPosition');
    expect(moves.length).toBeGreaterThan(0);
    // speed(10) * dt(0.1) = 1 world unit in +X
    expect(moves[0].args[1]).toBeCloseTo(1, 5);
  });

  it('JUMP_REQUESTED emits JUMP_STARTED and GROUNDED_CHANGED', () => {
    const entity = makePlayer();
    const jumpSpy = vi.fn();
    const groundedSpy = vi.fn();
    eventBus.on(MovementEvents.JUMP_STARTED, jumpSpy);
    eventBus.on(MovementEvents.GROUNDED_CHANGED, groundedSpy);

    eventBus.emit(MovementInputEvents.JUMP_REQUESTED, { entityId: entity.id });
    world.update(0.016);

    expect(jumpSpy).toHaveBeenCalledWith(expect.objectContaining({ entityId: entity.id }));
    expect(groundedSpy).toHaveBeenCalledWith(
      expect.objectContaining({ entityId: entity.id, isGrounded: false }),
    );
  });

  it('STARTED_MOVING / STOPPED_MOVING fire on move-intent edges', () => {
    const entity = makePlayer();
    const started = vi.fn();
    const stopped = vi.fn();
    eventBus.on(MovementEvents.STARTED_MOVING, started);
    eventBus.on(MovementEvents.STOPPED_MOVING, stopped);

    eventBus.emit(MovementInputEvents.SET_MOVEMENT_VECTOR, {
      entityId: entity.id, x: 1, z: 0,
    });
    world.update(0.016);
    expect(started).toHaveBeenCalledTimes(1);

    eventBus.emit(MovementInputEvents.SET_MOVEMENT_VECTOR, {
      entityId: entity.id, x: 0, z: 0,
    });
    world.update(0.016);
    expect(stopped).toHaveBeenCalledTimes(1);
  });

  it('faceMotion rotates the mesh toward movement direction', () => {
    const entity = makePlayer();
    eventBus.emit(MovementInputEvents.SET_MOVEMENT_VECTOR, {
      entityId: entity.id, x: 1, z: 0,
    });
    renderer.calls.length = 0;
    world.update(1); // long step — rotationSpeed of 2*PI is plenty
    const rot = renderer.calls.find((c) => c.method === 'setMeshRotation');
    expect(rot).toBeDefined();
    // atan2(1, 0) = PI/2
    expect(rot!.args[2]).toBeCloseTo(Math.PI / 2, 3);
  });

  it('skips cleanly when no entities are present', () => {
    expect(() => world.update(1 / 60)).not.toThrow();
  });

  it('ignores a SET_MOVEMENT_VECTOR for an unknown entityId', () => {
    const entity = makePlayer();
    const comp = entity.get(MovementComponent)!;
    eventBus.emit(MovementInputEvents.SET_MOVEMENT_VECTOR, {
      entityId: 'not-a-real-entity',
      x: 1,
      z: 1,
    });
    // The real player's intent must be untouched — the lookup found nothing.
    expect(comp.moveX).toBe(0);
    expect(comp.moveZ).toBe(0);
  });

  it('ignores a JUMP_REQUESTED for an unknown entityId', () => {
    const entity = makePlayer();
    const comp = entity.get(MovementComponent)!;
    eventBus.emit(MovementInputEvents.JUMP_REQUESTED, { entityId: 'ghost' });
    expect(comp.jumpPressed).toBe(false);
  });

  it('seeds the core from initialPosition when the entity has no mesh handle', () => {
    const entity = world.createEntity();
    entity.add(new MovementComponent({ position: [4, 2, 6], feetOffset: 1 }));
    const comp = entity.get(MovementComponent)!;
    const s = comp.instance!.getState();
    expect(s.posX).toBe(4);
    expect(s.posY).toBe(2);
    expect(s.posZ).toBe(6);
  });
});

Movement.viz.test.tsx

16 ✓

MovementPanel (renderer-free)

mounts without a renderer and shows the state + locomotion sections
moving the first slider calls core.setParams with the new speed

MovementDebuggerComponent

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

MovementDebuggerSystem

registers a panel once a Movement entity with a live instance exists
registers the panel hidden when the component starts not visible
adopts a debugger component that already exists at initialize time
does not register a panel while no Movement has a live instance
registers on a later frame once a Movement instance appears
adopts a debugger component added after initialize (onEntityAdded)
renders the live MovementPanel content, whose jump button emits JUMP_REQUESTED
toggles the panel via the activation key and tracks visibility back onto the component
ignores key presses that are not the activation key
ignores key presses before any debugger component is adopted
unregisters the panel and removes the key listener on shutdown

Last run 2026-08-22

Movement.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 { MovementPanel } from './Movement.panel';
import { createMovement } from './Movement.core';
import {
  MovementDebuggerComponent,
  MovementDebuggerSystem,
  type MovementDebuggerInput,
} from './Movement.viz.tsx';
import { MovementComponent, MovementSystem, MovementInputEvents } from './Movement';
import { vizStore } from '../_shared/viz';

const PANEL_ID = 'movement-debugger';

// ----------------------------------------------------------------------------
// Panel (renderer-free Solid component)
// ----------------------------------------------------------------------------

describe('MovementPanel (renderer-free)', () => {
  it('mounts without a renderer and shows the state + locomotion sections', () => {
    const core = createMovement();
    const { container } = render(() => <MovementPanel core={core} />);
    expect(container.textContent).toContain('State');
    expect(container.textContent).toContain('speed');
    expect(container.textContent).toContain('jumpForce');
  });

  it('moving the first slider calls core.setParams with the new speed', () => {
    const core = createMovement();
    const spy = vi.spyOn(core, 'setParams');
    const { getAllByRole } = render(() => <MovementPanel core={core} />);
    const firstSlider = (getAllByRole('slider') as HTMLInputElement[])[0];
    fireEvent.input(firstSlider, { target: { value: '9' } });
    expect(spy).toHaveBeenCalledWith(expect.objectContaining({ speed: 9 }));
  });
});

// ----------------------------------------------------------------------------
// Debugger Component
// ----------------------------------------------------------------------------

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

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

  it('round-trips through serialize()', () => {
    const c = new MovementDebuggerComponent({
      visible: true,
      activationKey: 'Digit3',
      position: 'top-left',
    });
    const s = c.serialize();
    expect(s).toEqual({
      visible: true,
      activationKey: 'Digit3',
      position: 'top-left',
    });
    const round = new MovementDebuggerComponent(s);
    expect(round.visible).toBe(c.visible);
    expect(round.activationKey).toBe(c.activationKey);
    expect(round.position).toBe(c.position);
  });
});

// ----------------------------------------------------------------------------
// Debugger System
// ----------------------------------------------------------------------------

describe('MovementDebuggerSystem', () => {
  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 Movement entity; the MovementSystem builds its `.instance`. */
  function addMover(id?: string) {
    const e = id ? world.createEntity(id) : world.createEntity();
    e.add(new MovementComponent({ speed: 10, position: [0, 1, 0] }));
    return e;
  }

  function addDebugger(data: MovementDebuggerInput = {}) {
    const e = world.createEntity();
    const c = new MovementDebuggerComponent(data);
    e.add(c);
    return { entity: e, component: c };
  }

  it('registers a panel once a Movement entity with a live instance exists', () => {
    world.addSystem(new MovementSystem(eventBus));
    world.addSystem(new MovementDebuggerSystem(eventBus));
    world.initialize();

    addMover();
    addDebugger({ visible: true, position: 'top-left' });
    world.update(1 / 60);

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

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

    addMover();
    addDebugger(); // visible defaults to false
    world.update(1 / 60);

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

  it('adopts a debugger component that already exists at initialize time', () => {
    addMover();
    addDebugger({ visible: true });

    world.addSystem(new MovementSystem(eventBus));
    world.addSystem(new MovementDebuggerSystem(eventBus));
    world.initialize();

    // The MovementSystem builds the instance during initialize, so the
    // debugger's tryRegisterPanel() in onInitialize already finds it.
    expect(vizStore.panels[PANEL_ID]).toBeDefined();
  });

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

    addDebugger({ visible: true });
    world.update(1 / 60);

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

  it('registers on a later frame once a Movement instance appears', () => {
    world.addSystem(new MovementSystem(eventBus));
    world.addSystem(new MovementDebuggerSystem(eventBus));
    world.initialize();

    addDebugger({ visible: true });
    world.update(1 / 60);
    expect(vizStore.panels[PANEL_ID]).toBeUndefined();

    addMover();
    world.update(1 / 60);
    expect(vizStore.panels[PANEL_ID]).toBeDefined();
  });

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

    addMover();
    world.update(1 / 60); // build the Movement instance first

    // Now add the debugger entity — onEntityAdded adopts + registers.
    addDebugger({ visible: true });
    expect(vizStore.panels[PANEL_ID]).toBeDefined();
  });

  it('renders the live MovementPanel content, whose jump button emits JUMP_REQUESTED', () => {
    world.addSystem(new MovementSystem(eventBus));
    world.addSystem(new MovementDebuggerSystem(eventBus));
    world.initialize();

    const mover = addMover('Hero');
    addDebugger({ visible: true });
    world.update(1 / 60);

    const jumps: Array<{ entityId: string }> = [];
    eventBus.on(MovementInputEvents.JUMP_REQUESTED, (e) =>
      jumps.push(e as { entityId: string }),
    );

    const { getByText, container } = render(() => vizStore.panels[PANEL_ID].content());
    expect(container.textContent).toContain('Locomotion');
    fireEvent.click(getByText(/Trigger jump/));
    expect(jumps).toHaveLength(1);
    expect(jumps[0].entityId).toBe(mover.id);
  });

  it('toggles the panel via the activation key and tracks visibility back onto the component', () => {
    world.addSystem(new MovementSystem(eventBus));
    world.addSystem(new MovementDebuggerSystem(eventBus));
    world.initialize();

    addMover();
    const { component } = addDebugger({ visible: false, activationKey: 'Digit1' });
    world.update(1 / 60);
    expect(vizStore.isVisible(PANEL_ID)).toBe(false);

    // First press → show.
    window.dispatchEvent(new KeyboardEvent('keydown', { code: 'Digit1' }));
    expect(vizStore.isVisible(PANEL_ID)).toBe(true);
    expect(component.visible).toBe(true);

    // Second press → hide.
    window.dispatchEvent(new KeyboardEvent('keydown', { code: 'Digit1' }));
    expect(vizStore.isVisible(PANEL_ID)).toBe(false);
    expect(component.visible).toBe(false);
  });

  it('ignores key presses that are not the activation key', () => {
    world.addSystem(new MovementSystem(eventBus));
    world.addSystem(new MovementDebuggerSystem(eventBus));
    world.initialize();

    addMover();
    addDebugger({ visible: false, activationKey: 'Digit1' });
    world.update(1 / 60);

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

  it('ignores key presses before any debugger component is adopted', () => {
    world.addSystem(new MovementDebuggerSystem(eventBus));
    world.initialize();

    // No debugger component yet → handler returns early on the null guard.
    expect(() =>
      window.dispatchEvent(new KeyboardEvent('keydown', { code: 'Digit1' })),
    ).not.toThrow();
    expect(vizStore.panels[PANEL_ID]).toBeUndefined();
  });

  it('unregisters the panel and removes the key listener on shutdown', () => {
    world.addSystem(new MovementSystem(eventBus));
    world.addSystem(new MovementDebuggerSystem(eventBus));
    world.initialize();

    addMover();
    addDebugger({ visible: true, activationKey: 'Digit1' });
    world.update(1 / 60);
    expect(vizStore.panels[PANEL_ID]).toBeDefined();

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

    // After shutdown a press must not re-register anything.
    window.dispatchEvent(new KeyboardEvent('keydown', { code: 'Digit1' }));
    expect(vizStore.panels[PANEL_ID]).toBeUndefined();
  });
});