Spin.core.ts

Spin.core.ts — a random tumble axis.

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

Spin.core.ts

/** A stable pseudo-random value in [0, 1) from a string and a counter. */
export function hashUnit(id: string, n: number): number {
  let h = 2166136261 ^ n;
  for (let i = 0; i < id.length; i++) {
    h ^= id.charCodeAt(i);
    h = Math.imul(h, 16777619);
  }
  h ^= h >>> 13;
  h = Math.imul(h, 0x5bd1e995);
  h ^= h >>> 15;
  return (h >>> 0) / 4294967296;
}

Per-axis rates for a tumble of speed rad/s about a direction picked from (id, n) — uniform over the sphere, so no axis is favoured.

Spin.core.ts

export function tumbleRate(id: string, n: number, speed: number): [number, number, number] {
  const u = hashUnit(id, n * 2 + 1);
  const v = hashUnit(id, n * 2 + 2);
  const z = 2 * u - 1;
  const s = Math.sqrt(Math.max(0, 1 - z * z));
  const phi = 2 * Math.PI * v;
  return [s * Math.cos(phi) * speed, s * Math.sin(phi) * speed, z * speed];
}

Spin.defs.ts

Spin — definitions.

Holds the SpinComponent class. No System lives here. Import from here, not from Spin.ts.

Spin.defs.ts

import { Component } from '@babylonjsmarket/ecs';

export interface SpinInput {
  /** Radians per second about x, y and z. */
  rate?: [number, number, number];
  /**
   * When above 0, ignore `rate` and tumble at this many radians per second
   * about an axis picked afresh every time the entity enters play — so a stream
   * of pooled rocks never tumbles in lockstep.
   */
  tumble?: number;
}

export const DEFAULT_SPIN: Required<SpinInput> = {
  rate: [0, 0.5, 0],
  tumble: 0,
};

export class SpinComponent extends Component {
  rate: [number, number, number];
  tumble: number;

  constructor(data: SpinInput = {}) {
    super();
    const r = data.rate ?? DEFAULT_SPIN.rate;
    this.rate = [r[0], r[1], r[2]];
    this.tumble = data.tumble ?? DEFAULT_SPIN.tumble;
  }

  serialize(): Required<SpinInput> {
    return { rate: [this.rate[0], this.rate[1], this.rate[2]], tumble: this.tumble };
  }
}

Spin.ts

Spin.ts — turns a MeshPrimitive at a steady rate (SpinSystem).

A fixed rate for a ring that turns about one axis; tumble for a rock that should turn about SOME axis, picked afresh each time the entity enters play. The angle lives in MeshPrimitive.rotation, so a pooled entity parked mid-turn is restored where it was.

On the frame a pooled entity is (re)acquired, MeshPrimitiveSystem's queued restore writes its rotation; Spin advances the component but leaves that one mesh write to the restore, so the two never touch the handle in one frame.

Renderer-agnostic: zero @babylonjs / three imports. Constructor takes (eventBus) only.

Spin.ts

import { System } from '@babylonjsmarket/ecs';
import type { Entity, EventBus } from '@babylonjsmarket/ecs';
import { PoolComponent } from '@babylonjsmarket/arcade';
import { MeshPrimitiveComponent } from '../MeshPrimitive/MeshPrimitive.defs';
import { SpinComponent } from './Spin.defs';
import { tumbleRate } from './Spin.core';

interface SpinRuntime {
  rate: [number, number, number];
  /** Times this component has entered play — reseeds the tumble axis. */
  entries: number;
}

export class SpinSystem extends System {
  protected query = {
    required: [SpinComponent, MeshPrimitiveComponent],
    excluded: [PoolComponent],
  };

  private runtime = new WeakMap<SpinComponent, SpinRuntime>();
  private newborns = new Set<string>();

  constructor(eventBus: EventBus) {
    super(eventBus);
    this.priority = 15;
  }

  protected onEntityAdded(entity: Entity): void {
    this.newborns.add(entity.id);
    const cfg = entity.get(SpinComponent)!;
    const rt = this.getRuntime(cfg);
    rt.entries++;
    rt.rate = cfg.tumble > 0 ? tumbleRate(entity.id, rt.entries, cfg.tumble) : [...cfg.rate];
  }

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

  protected onUpdate(dt: number): void {
    const r = this.world?.renderer;
    for (const entity of this.entities) {
      const cfg = entity.get(SpinComponent)!;
      const mesh = entity.get(MeshPrimitiveComponent)!;
      const rt = this.getRuntime(cfg);
      if (cfg.tumble <= 0) rt.rate = cfg.rate; // a live edit to `rate` takes effect
      const rot = mesh.rotation;
      rot[0] = (rot[0] + rt.rate[0] * dt) % (Math.PI * 2);
      rot[1] = (rot[1] + rt.rate[1] * dt) % (Math.PI * 2);
      rot[2] = (rot[2] + rt.rate[2] * dt) % (Math.PI * 2);
      if (r && mesh.handle && !this.newborns.has(entity.id)) {
        r.setMeshRotation(mesh.handle, rot[0], rot[1], rot[2]);
      }
    }
    this.newborns.clear();
  }

  private getRuntime(cfg: SpinComponent): SpinRuntime {
    let rt = this.runtime.get(cfg);
    if (!rt) {
      rt = { rate: [...cfg.rate], entries: 0 };
      this.runtime.set(cfg, rt);
    }
    return rt;
  }
}

export { SpinComponent, DEFAULT_SPIN, type SpinInput } from './Spin.defs';
export { tumbleRate, hashUnit } from './Spin.core';

Spin.contract.test.ts

11 ✓

ArcadeECS contract: Spin

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

Last run 2026-10-03

Spin.contract.test.ts

import { runMechanicContract } from '@babylonjsmarket/ecs/testing';
import { SpinComponent, SpinSystem } from './Spin';
import { MeshPrimitiveComponent } from '../MeshPrimitive/MeshPrimitive.defs';

runMechanicContract({
  name: 'Spin',
  componentClass: SpinComponent,
  systemClass: SpinSystem,
  sampleInput: { rate: [0.55, 0.35, 0], tumble: 0 },
  // It turns the MeshPrimitive on its own entity. It emits and hears nothing.
  companions: [MeshPrimitiveComponent],
});

Spin.core.test.ts

8 ✓

hashUnit

is stable: the same id and counter always give the same value
stays in [0, 1)
changes with the id and with the counter
spreads near-identical ids evenly across the range

tumbleRate

turns at exactly `speed` rad/s, whatever the axis
picks the axis from (id, entry): same pair, same axis; a new entry, a new axis
favours no axis — across rocks, and across one rock’s re-entries
a speed of 0 is no spin at all

Last run 2026-10-03

Spin.core.test.ts

import { describe, it, expect } from 'vitest';
import { hashUnit, tumbleRate } from './Spin.core';

const length = (v: number[]) => Math.hypot(v[0], v[1], v[2]);

describe('hashUnit', () => {
  it('is stable: the same id and counter always give the same value', () => {
    expect(hashUnit('rock-3', 7)).toBe(hashUnit('rock-3', 7));
  });

  it('stays in [0, 1)', () => {
    for (let i = 0; i < 500; i++) {
      const u = hashUnit(`rock-${i}`, i % 7);
      expect(u).toBeGreaterThanOrEqual(0);
      expect(u).toBeLessThan(1);
    }
    expect(hashUnit('', 0)).toBeGreaterThanOrEqual(0);
  });

  it('changes with the id and with the counter', () => {
    expect(hashUnit('rock-0', 1)).not.toBe(hashUnit('rock-1', 1));
    expect(hashUnit('rock-0', 1)).not.toBe(hashUnit('rock-0', 2));
  });

  // A stream of pooled rocks named rock-0, rock-1, … must not clump: ids that
  // differ in one character have to land all over the range.
  it('spreads near-identical ids evenly across the range', () => {
    const buckets = new Array(10).fill(0);
    for (let i = 0; i < 2000; i++) buckets[Math.floor(hashUnit(`rock-${i}`, 1) * 10)]++;
    for (const b of buckets) {
      expect(b).toBeGreaterThan(150);
      expect(b).toBeLessThan(250);
    }
  });
});

describe('tumbleRate', () => {
  it('turns at exactly `speed` rad/s, whatever the axis', () => {
    for (let i = 0; i < 50; i++) expect(length(tumbleRate(`rock-${i}`, i, 2.4))).toBeCloseTo(2.4, 12);
  });

  it('picks the axis from (id, entry): same pair, same axis; a new entry, a new axis', () => {
    expect(tumbleRate('rock-0', 1, 2)).toEqual(tumbleRate('rock-0', 1, 2));
    expect(tumbleRate('rock-0', 2, 2)).not.toEqual(tumbleRate('rock-0', 1, 2));
    expect(tumbleRate('rock-1', 1, 2)).not.toEqual(tumbleRate('rock-0', 1, 2));
  });

  // Uniform over the sphere means no favoured axis: every component averages
  // zero, and each carries a third of the squared length.
  it('favours no axis — across rocks, and across one rock’s re-entries', () => {
    const N = 2000;
    for (const pick of [(i: number) => tumbleRate(`rock-${i}`, 1, 1), (i: number) => tumbleRate('rock-3', i + 1, 1)]) {
      const mean = [0, 0, 0];
      const square = [0, 0, 0];
      for (let i = 0; i < N; i++) {
        const r = pick(i);
        for (let k = 0; k < 3; k++) {
          mean[k] += r[k] / N;
          square[k] += (r[k] * r[k]) / N;
        }
      }
      for (let k = 0; k < 3; k++) {
        expect(Math.abs(mean[k])).toBeLessThan(0.05);
        expect(Math.abs(square[k] - 1 / 3)).toBeLessThan(0.03);
      }
    }
  });

  it('a speed of 0 is no spin at all', () => {
    expect(tumbleRate('rock-0', 1, 0).every((c) => c === 0)).toBe(true);
  });
});

Spin.test.ts

13 ✓

SpinComponent

defaults to half a radian a second about Y, no tumble
serialize() round-trips every field
copies its rate in and out
the entry file re-exports the tumble arithmetic

SpinSystem

runs late in the frame
turns the mesh at its rate, writing the rotation every frame after the first
keeps the angle within one turn
a live edit to rate takes effect on the next frame
ignores a Pool blueprint

SpinSystem › tumble

ignores rate and turns at `tumble` rad/s about an axis of its own
two rocks never tumble in lockstep
a pooled rock picks a fresh axis every time it is handed out, at the same speed

SpinSystem › the spawn frame

a pooled rock is posed by MeshPrimitive’s restore on the frame it is acquired — no race

Last run 2026-10-03

Spin.test.ts

/**
 * Spin.test.ts — the System against a real World and the mock renderer. The
 * tumble-axis arithmetic is covered in Spin.core.test.ts; this file covers the
 * rotation it drives, live edits, pooled re-entries, and who writes a newborn's
 * mesh.
 */

import { afterEach, beforeEach, describe, expect, it } from 'vitest';
import { EventBus, World, MockRendererAdapter } from '@babylonjsmarket/ecs';
import type { Entity } from '@babylonjsmarket/ecs';
import { PoolComponent } from '@babylonjsmarket/arcade';
import { MeshPrimitiveComponent } from '../MeshPrimitive/MeshPrimitive.defs';
import { MeshPrimitiveSystem } from '../MeshPrimitive/MeshPrimitive';
import * as core from './Spin.core';
import { SpinSystem, SpinComponent, DEFAULT_SPIN, hashUnit, tumbleRate, type SpinInput } from './Spin';

type Vec3 = [number, number, number];

describe('SpinComponent', () => {
  it('defaults to half a radian a second about Y, no tumble', () => {
    expect(new SpinComponent().serialize()).toEqual({ rate: [0, 0.5, 0], tumble: 0 });
    expect(new SpinComponent().serialize()).toEqual(DEFAULT_SPIN);
  });

  it('serialize() round-trips every field', () => {
    const authored: Required<SpinInput> = { rate: [0.55, 0.35, 0], tumble: 2.4 };
    expect(new SpinComponent(new SpinComponent(authored).serialize()).serialize()).toEqual(authored);
  });

  it('copies its rate in and out', () => {
    const shared: Vec3 = [1, 2, 3];
    const a = new SpinComponent({ rate: shared });
    a.rate[0] = 9;
    expect(shared[0]).toBe(1);
    a.serialize().rate![1] = 9;
    expect(a.rate[1]).toBe(2);
    new SpinComponent().rate[1] = 9;
    expect(DEFAULT_SPIN.rate).toEqual([0, 0.5, 0]);
  });

  it('the entry file re-exports the tumble arithmetic', () => {
    expect(hashUnit).toBe(core.hashUnit);
    expect(tumbleRate).toBe(core.tumbleRate);
  });
});

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

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

  afterEach(() => world.destroy());

  function spinner(id: string, data: SpinInput = {}): Entity {
    const e = world.createEntity(id);
    e.add(new MeshPrimitiveComponent({ primitive: 'torus' }));
    e.add(new SpinComponent(data));
    return e;
  }

  function rockPool(tumble: number): void {
    world.registerPool('rock', {
      size: 1,
      build: (e) => {
        e.add(new MeshPrimitiveComponent({ primitive: 'sphere' }));
        e.add(new SpinComponent({ tumble }));
      },
    });
  }

  const rot = (e: Entity) => e.get(MeshPrimitiveComponent)!.rotation;
  const writes = (e: Entity) =>
    renderer.calls.filter((c) => c.method === 'setMeshRotation' && c.args[0] === e.get(MeshPrimitiveComponent)!.handle);
  const unit = (v: number[]) => {
    const l = Math.hypot(v[0], v[1], v[2]);
    return [v[0] / l, v[1] / l, v[2] / l];
  };

  it('runs late in the frame', () => {
    expect(system.priority).toBe(15);
  });

  it('turns the mesh at its rate, writing the rotation every frame after the first', () => {
    const ring = spinner('ring', { rate: [1, 2, 0] });
    renderer.calls.length = 0;
    world.update(0.25);
    // The angle advanced; the mesh write waits a frame (see the newborn rule).
    expect(rot(ring)).toEqual([0.25, 0.5, 0]);
    expect(writes(ring)).toHaveLength(0);

    world.update(0.25);
    expect(rot(ring)).toEqual([0.5, 1, 0]);
    expect(writes(ring).map((c) => c.args.slice(1))).toEqual([[0.5, 1, 0]]);
  });

  it('keeps the angle within one turn', () => {
    const ring = spinner('ring', { rate: [0, 4, -4] });
    world.update(2);
    expect(rot(ring)[1]).toBeCloseTo(8 - 2 * Math.PI, 12);
    expect(rot(ring)[2]).toBeCloseTo(-(8 - 2 * Math.PI), 12);
  });

  it('a live edit to rate takes effect on the next frame', () => {
    const ring = spinner('ring', { rate: [0, 1, 0] });
    world.update(0.25);
    ring.get(SpinComponent)!.rate = [2, 0, 0];
    world.update(0.25);
    expect(rot(ring)).toEqual([0.5, 0.25, 0]);
  });

  describe('tumble', () => {
    it('ignores rate and turns at `tumble` rad/s about an axis of its own', () => {
      const rock = spinner('rock', { rate: [5, 5, 5], tumble: 2 });
      world.update(0.1);
      const turned = rot(rock);
      expect(Math.hypot(turned[0], turned[1], turned[2])).toBeCloseTo(0.2, 12);
      expect(turned).toEqual(tumbleRate('rock', 1, 2).map((r) => r * 0.1));
    });

    it('two rocks never tumble in lockstep', () => {
      const a = spinner('rock-a', { tumble: 2 });
      const b = spinner('rock-b', { tumble: 2 });
      world.update(0.1);
      expect(unit(rot(a))).not.toEqual(unit(rot(b)));
    });

    it('a pooled rock picks a fresh axis every time it is handed out, at the same speed', () => {
      rockPool(2);
      const rock = world.acquire('rock')!;
      world.update(0.1);
      const before = [...rot(rock)];
      world.update(0.1);
      const firstAxis = unit(rot(rock).map((r, k) => r - before[k]));

      world.removeEntity(rock);
      world.acquire('rock');
      const parkedAt = [...rot(rock)]; // the angle survives parking
      world.update(0.1);
      const step = rot(rock).map((r, k) => r - parkedAt[k]);
      expect(Math.hypot(step[0], step[1], step[2])).toBeCloseTo(0.2, 9);
      expect(unit(step)).not.toEqual(firstAxis);
    });
  });

  describe('the spawn frame', () => {
    it('a pooled rock is posed by MeshPrimitive’s restore on the frame it is acquired — no race', () => {
      rockPool(2);
      const rock = world.acquire('rock')!;
      renderer.calls.length = 0;
      world.update(1 / 60);
      // One write, the restore's, carrying the angle Spin has already advanced.
      const first = writes(rock);
      expect(first).toHaveLength(1);
      expect(first[0].args.slice(1)).toEqual([...rot(rock)]);
      expect(world.raceDetector!.warnings).toHaveLength(0);

      renderer.calls.length = 0;
      world.update(1 / 60);
      expect(writes(rock)).toHaveLength(1);
      expect(writes(rock)[0].args.slice(1)).toEqual([...rot(rock)]);
      expect(world.raceDetector!.warnings).toHaveLength(0);
    });
  });

  it('ignores a Pool blueprint', () => {
    const blueprint = world.createEntity('Rocks');
    blueprint.add(new PoolComponent({ name: 'rock' }));
    blueprint.add(new MeshPrimitiveComponent({ primitive: 'sphere' }));
    blueprint.add(new SpinComponent({ rate: [1, 1, 1] }));
    world.update(0.25);
    expect(system.getEntities()).not.toContain(blueprint);
    expect(rot(blueprint)).toEqual([0, 0, 0]);
  });
});