GravityMass.core.ts

GravityMass.core.ts — the gravitational field of a set of point masses.

Everything here is arithmetic over plain numbers. The integrator (GravityBody) and the predictor (TrajectoryPreview) both call fieldAt, so a rock and the dotted line drawn ahead of it are pushed by the SAME function — which is what lets the preview be trusted.

Units are chosen so G = 1. The field of one mass is

a = m · d / (|d|² + ε²)^1.5

where d points from the body to the mass and ε is that mass's softening. Far away that is the familiar m / r². Near the centre the softening keeps it finite, so a body that grazes a point mass gets a hard shove, not infinity.

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

GravityMass.core.ts

export type Vec3 = [number, number, number];

One mass, flattened to numbers so the hot loop never touches an ECS object. id lets a body skip its own mass — rocks pull on each other, not on themselves.

GravityMass.core.ts

export interface MassPoint {
  id: string;
  x: number;
  y: number;
  z: number;
  mass: number;
  softening: number;
  radius: number;
  absorbs: boolean;
}

/** A fresh, zeroed MassPoint — the systems keep a pool of these and refill them. */
export function makeMassPoint(): MassPoint {
  return { id: '', x: 0, y: 0, z: 0, mass: 0, softening: 0, radius: 0, absorbs: false };
}

Acceleration at (px, py, pz) from every mass in masses[0..count) except the one whose id is skipId. Written into out, which is returned.

GravityMass.core.ts

export function fieldAt(
  px: number,
  py: number,
  pz: number,
  masses: ReadonlyArray<MassPoint>,
  count: number,
  skipId: string,
  out: Vec3,
): Vec3 {
  let ax = 0;
  let ay = 0;
  let az = 0;
  for (let i = 0; i < count; i++) {
    const m = masses[i];
    if (m.id === skipId || m.mass === 0) continue;
    const dx = m.x - px;
    const dy = m.y - py;
    const dz = m.z - pz;
    const r2 = dx * dx + dy * dy + dz * dz + m.softening * m.softening;
    // Coincident with an unsoftened mass: there is no direction to pull in.
    if (r2 === 0) continue;
    const inv = 1 / Math.sqrt(r2);
    const f = m.mass * inv * inv * inv;
    ax += dx * f;
    ay += dy * f;
    az += dz * f;
  }
  out[0] = ax;
  out[1] = ay;
  out[2] = az;
  return out;
}

The first mass in masses[0..count) whose surface a sphere of bodyRadius at (px, py, pz) touches, or null. Point masses (radius 0) are never hit.

GravityMass.core.ts

export function contactAt(
  px: number,
  py: number,
  pz: number,
  bodyRadius: number,
  masses: ReadonlyArray<MassPoint>,
  count: number,
  skipId: string,
): MassPoint | null {
  for (let i = 0; i < count; i++) {
    const m = masses[i];
    if (m.id === skipId || m.radius <= 0) continue;
    const dx = m.x - px;
    const dy = m.y - py;
    const dz = m.z - pz;
    const reach = m.radius + bodyRadius;
    if (dx * dx + dy * dy + dz * dz <= reach * reach) return m;
  }
  return null;
}

Speed of a circular orbit of radius r around mass (G = 1). A body launched past a black hole at much more than this sails by with a bend; at much less it falls in. Level design reads it to pick masses that make a slingshot possible without making it free.

GravityMass.core.ts

export function circularSpeed(mass: number, r: number): number {
  if (r <= 0 || mass <= 0) return 0;
  return Math.sqrt(mass / r);
}

GravityMass.defs.ts

GravityMass — definitions.

Holds the GravityMassComponent class and the shapes its data travels in. No System lives here, which is the point: another component can name GravityMass in a query without pulling the integrator into its own bundle. Import from here, not from GravityMass.ts.

GravityMass.defs.ts

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

export interface GravityMassInput {
  /**
   * How hard this entity pulls. Units are chosen so the gravitational constant
   * is 1: a body `r` units away accelerates at `mass / r²` units/s². A black
   * hole of 600 bends a rock passing 8 units away by about 9 units/s².
   */
  mass?: number;
  /**
   * The solid (or event-horizon) radius, in world units. A GravityBody that
   * touches it has hit it. 0 is a point mass that pulls but can never be hit.
   */
  radius?: number;
  /**
   * Softening length. The pull is `mass · r / (r² + softening²)^1.5`, which is
   * plain inverse-square far away and stays finite at the centre — a body
   * skimming a point mass would otherwise pick up an unbounded kick in one step.
   */
  softening?: number;
  /**
   * True for an event horizon: a body that reaches `radius` is swallowed rather
   * than crashing. Gameplay listens for the difference.
   */
  absorbs?: boolean;
  /**
   * Whether a GravityLens sky bends light around this mass. Defaults to
   * `absorbs` — black holes lens, rocks don't.
   */
  lenses?: boolean;
}

export const DEFAULT_GRAVITY_MASS: Required<GravityMassInput> = {
  mass: 1,
  radius: 0,
  softening: 0.25,
  absorbs: false,
  // Not used for a GravityMass built without one: it copies `absorbs` instead.
  lenses: false,
};

export class GravityMassComponent extends Component {
  mass: number;
  radius: number;
  softening: number;
  absorbs: boolean;
  lenses: boolean;

  constructor(data: GravityMassInput = {}) {
    super();
    this.mass = data.mass ?? DEFAULT_GRAVITY_MASS.mass;
    this.radius = data.radius ?? DEFAULT_GRAVITY_MASS.radius;
    this.softening = data.softening ?? DEFAULT_GRAVITY_MASS.softening;
    this.absorbs = data.absorbs ?? DEFAULT_GRAVITY_MASS.absorbs;
    this.lenses = data.lenses ?? this.absorbs;
  }

  serialize(): Required<GravityMassInput> {
    return {
      mass: this.mass,
      radius: this.radius,
      softening: this.softening,
      absorbs: this.absorbs,
      lenses: this.lenses,
    };
  }
}

GravityMass.ts

GravityMass.ts — System-tier entry point for the GravityMass component.

GravityMass is PURE DATA: how hard an entity pulls, and how big it is. It owns no System of its own. The integrator that reads it lives next door as GravityBodySystem — it gathers every GravityMass each frame and moves every GravityBody through their combined field — and TrajectoryPreview reads the same masses to draw the path ahead. This file re-exports the definitions and the field math so the registry can resolve GravityMassComponent by name.

GravityMass.ts

export {
  GravityMassComponent,
  DEFAULT_GRAVITY_MASS,
  type GravityMassInput,
} from './GravityMass.defs';
export {
  fieldAt,
  contactAt,
  circularSpeed,
  makeMassPoint,
  type MassPoint,
} from './GravityMass.core';

GravityMass.contract.test.ts

11 ✓

ArcadeECS contract: GravityMass

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

GravityMass.contract.test.ts

import { runMechanicContract } from '@babylonjsmarket/ecs/testing';
import { GravityMassComponent } from './GravityMass';
import { GravityBodySystem } from '../GravityBody/GravityBody';
import { MeshPrimitiveComponent } from '../MeshPrimitive/MeshPrimitive.defs';

runMechanicContract({
  name: 'GravityMass',
  componentClass: GravityMassComponent,
  // GravityMass is pure data — how hard an entity pulls and how big it is. It
  // owns no System; the integrator that reads it is GravityBodySystem, whose
  // query takes any MeshPrimitive that is a mass OR a body. It emits nothing of
  // its own: the contact event belongs to the body that hits it.
  systemClass: GravityBodySystem,
  sampleInput: { mass: 600, radius: 1.2, absorbs: true },
  companions: [MeshPrimitiveComponent],
});

GravityMass.core.test.ts

20 ✓

makeMassPoint

is a zeroed point that pulls on nothing and cannot be hit
hands out a fresh object every call

fieldAt

is plain inverse-square without softening, pointing at the mass
points from the body toward the mass in all three axes
is measured from the body, wherever the body is
softening weakens the pull near the centre and keeps it finite at the centre
matches the documented example: a 600 black hole pulls about 9 units/s² at 8 units
adds up every mass — equal pulls from opposite sides cancel
skips the mass whose id is skipId
ignores a massless point and a coincident unsoftened one instead of dividing by zero
reads only the first `count` masses

contactAt

reports a body whose sphere touches the surface — touching counts
misses a body just outside its reach
never hits a point mass, even dead centre
skips the body’s own mass
returns the first mass touched, in array order
reads only the first `count` masses

circularSpeed

is sqrt(mass / r) with G = 1
is 0 for a non-positive radius or mass
is the speed whose centripetal acceleration the field supplies

Last run 2026-10-03

GravityMass.core.test.ts

import { describe, it, expect } from 'vitest';
import { circularSpeed, contactAt, fieldAt, makeMassPoint, type MassPoint, type Vec3 } from './GravityMass.core';

/** A MassPoint with only the fields a case cares about; the rest stay zeroed. */
function point(over: Partial<MassPoint>): MassPoint {
  return { ...makeMassPoint(), ...over };
}

describe('makeMassPoint', () => {
  it('is a zeroed point that pulls on nothing and cannot be hit', () => {
    expect(makeMassPoint()).toEqual({
      id: '', x: 0, y: 0, z: 0, mass: 0, softening: 0, radius: 0, absorbs: false,
    });
  });

  // The systems keep a pool of these and refill them every frame, so two calls
  // handing back one shared object would have every slot alias the same mass.
  it('hands out a fresh object every call', () => {
    expect(makeMassPoint()).not.toBe(makeMassPoint());
  });
});

describe('fieldAt', () => {
  it('is plain inverse-square without softening, pointing at the mass', () => {
    // m / r² = 4 / 2² = 1, along +X from the body to the mass.
    const out: Vec3 = [9, 9, 9];
    const a = fieldAt(0, 0, 0, [point({ id: 'm', x: 2, mass: 4 })], 1, '', out);
    expect(a).toBe(out); // written in place — the hot loop allocates nothing
    expect(a).toEqual([1, 0, 0]);
  });

  it('points from the body toward the mass in all three axes', () => {
    // A 3-4-5 offset: |a| = 25 / 5² = 1, along (0, 0.6, 0.8).
    const a = fieldAt(0, 0, 0, [point({ id: 'm', y: 3, z: 4, mass: 25 })], 1, '', [0, 0, 0]);
    expect(a[0]).toBe(0);
    expect(a[1]).toBeCloseTo(0.6, 12);
    expect(a[2]).toBeCloseTo(0.8, 12);
  });

  it('is measured from the body, wherever the body is', () => {
    // Same geometry as above, both ends shifted by (10, -5, 7).
    const a = fieldAt(10, -5, 7, [point({ id: 'm', x: 10, y: -2, z: 11, mass: 25 })], 1, '', [0, 0, 0]);
    expect(a[0]).toBe(0);
    expect(a[1]).toBeCloseTo(0.6, 12);
    expect(a[2]).toBeCloseTo(0.8, 12);
  });

  // Softening is what stops a rock that skims a point mass from picking up an
  // unbounded kick in one step.
  it('softening weakens the pull near the centre and keeps it finite at the centre', () => {
    const soft = point({ id: 'm', mass: 1, softening: 1 });
    // m·d / (d² + ε²)^1.5 = 1 / 2^1.5 at one unit — a third of the bare 1 / 1².
    expect(fieldAt(1, 0, 0, [soft], 1, '', [0, 0, 0])[0]).toBeCloseTo(-1 / Math.pow(2, 1.5), 12);
    // Dead centre: no direction to pull in, and certainly not infinity.
    expect(fieldAt(0, 0, 0, [soft], 1, '', [0, 0, 0])).toEqual([0, 0, 0]);
  });

  it('matches the documented example: a 600 black hole pulls about 9 units/s² at 8 units', () => {
    const hole = point({ id: 'hole', mass: 600, softening: 0.25 });
    const a = fieldAt(8, 0, 0, [hole], 1, '', [0, 0, 0]);
    expect(-a[0]).toBeCloseTo(9.3613, 4);
    // Just under the bare 600 / 8² — softening barely matters out here.
    expect(-a[0]).toBeLessThan(600 / 64);
  });

  it('adds up every mass — equal pulls from opposite sides cancel', () => {
    const left = point({ id: 'l', x: -2, mass: 4 });
    const right = point({ id: 'r', x: 2, mass: 4 });
    expect(fieldAt(0, 0, 0, [left, right], 2, '', [0, 0, 0])).toEqual([0, 0, 0]);
    const twin = point({ id: 't', x: 2, mass: 4 });
    expect(fieldAt(0, 0, 0, [right, twin], 2, '', [0, 0, 0])).toEqual([2, 0, 0]);
  });

  // A rock is both a body and a mass; its own point must not pull on it.
  it('skips the mass whose id is skipId', () => {
    const self = point({ id: 'rock', x: 1, mass: 100 });
    const other = point({ id: 'hole', x: 2, mass: 4 });
    expect(fieldAt(0, 0, 0, [self, other], 2, 'rock', [0, 0, 0])).toEqual([1, 0, 0]);
  });

  it('ignores a massless point and a coincident unsoftened one instead of dividing by zero', () => {
    const massless = point({ id: 'ghost', mass: 0 });
    const coincident = point({ id: 'here', mass: 5, softening: 0 });
    const a = fieldAt(0, 0, 0, [massless, coincident], 2, '', [0, 0, 0]);
    expect(a).toEqual([0, 0, 0]);
    expect(a.every(Number.isFinite)).toBe(true);
  });

  // The systems refill a pooled array and pass a count: whatever is left past
  // `count` is last frame's stale data and must not pull.
  it('reads only the first `count` masses', () => {
    const live = point({ id: 'live', x: 2, mass: 4 });
    const stale = point({ id: 'stale', x: -1, mass: 1000 });
    expect(fieldAt(0, 0, 0, [live, stale], 1, '', [0, 0, 0])).toEqual([1, 0, 0]);
    expect(fieldAt(0, 0, 0, [live, stale], 0, '', [0, 0, 0])).toEqual([0, 0, 0]);
  });
});

describe('contactAt', () => {
  const rock = point({ id: 'rock', x: 2, radius: 1 });

  it('reports a body whose sphere touches the surface — touching counts', () => {
    // Reach is radius + bodyRadius = 1.5, and the body is exactly 1.5 away.
    expect(contactAt(0.5, 0, 0, 0.5, [rock], 1, '')).toBe(rock);
    expect(contactAt(2, 0.2, 0, 0.5, [rock], 1, '')).toBe(rock); // deep inside
  });

  it('misses a body just outside its reach', () => {
    expect(contactAt(0.49, 0, 0, 0.5, [rock], 1, '')).toBeNull();
  });

  it('never hits a point mass, even dead centre', () => {
    const pointMass = point({ id: 'p', mass: 50, radius: 0 });
    expect(contactAt(0, 0, 0, 0.5, [pointMass], 1, '')).toBeNull();
  });

  it('skips the body’s own mass', () => {
    expect(contactAt(2, 0, 0, 0.5, [rock], 1, 'rock')).toBeNull();
  });

  it('returns the first mass touched, in array order', () => {
    const second = point({ id: 'second', x: 2, radius: 3 });
    expect(contactAt(2, 0, 0, 0.1, [rock, second], 2, '')).toBe(rock);
    expect(contactAt(2, 0, 0, 0.1, [second, rock], 2, '')).toBe(second);
  });

  it('reads only the first `count` masses', () => {
    expect(contactAt(2, 0, 0, 0.1, [rock], 0, '')).toBeNull();
  });
});

describe('circularSpeed', () => {
  it('is sqrt(mass / r) with G = 1', () => {
    expect(circularSpeed(4, 1)).toBe(2);
    expect(circularSpeed(600, 8)).toBeCloseTo(8.660254, 6);
  });

  it('is 0 for a non-positive radius or mass', () => {
    expect(circularSpeed(600, 0)).toBe(0);
    expect(circularSpeed(600, -3)).toBe(0);
    expect(circularSpeed(0, 8)).toBe(0);
    expect(circularSpeed(-5, 8)).toBe(0);
  });

  // The level-design reading only holds if it agrees with the field the rocks
  // actually feel: at that speed, the pull is exactly the centripetal v² / r.
  it('is the speed whose centripetal acceleration the field supplies', () => {
    const m = 16;
    const r = 4;
    const v = circularSpeed(m, r);
    const a = fieldAt(r, 0, 0, [point({ id: 'm', mass: m })], 1, '', [0, 0, 0]);
    expect(-a[0]).toBeCloseTo((v * v) / r, 12);
  });
});

GravityMass.test.ts

8 ✓

GravityMassComponent

defaults to a unit point mass that cannot be hit and does not lens
lenses whenever it absorbs, unless the scene says otherwise
serialize() round-trips every field

GravityMass entry file

re-exports the definitions and the field math, so the registry resolves it by name

a GravityMass in a world (read by GravityBodySystem)

pulls a body toward it
is read where it is NOW — move the mass and the pull follows
stays where it is: a mass that is not a body is never moved or written
a mass parked by its pool stops pulling

Last run 2026-10-03

GravityMass.test.ts

import { afterEach, beforeEach, describe, expect, it } from 'vitest';
import { EventBus, World, MockRendererAdapter } from '@babylonjsmarket/ecs';
import type { Entity } from '@babylonjsmarket/ecs';
import * as entry from './GravityMass';
import * as core from './GravityMass.core';
import { GravityMassComponent, DEFAULT_GRAVITY_MASS, type GravityMassInput } from './GravityMass.defs';
import { GravityBodySystem } from '../GravityBody/GravityBody';
import { GravityBodyComponent } from '../GravityBody/GravityBody.defs';
import { MeshPrimitiveComponent } from '../MeshPrimitive/MeshPrimitive.defs';

type Vec3 = [number, number, number];

describe('GravityMassComponent', () => {
  it('defaults to a unit point mass that cannot be hit and does not lens', () => {
    const c = new GravityMassComponent();
    expect(c.mass).toBe(1);
    expect(c.radius).toBe(0);
    expect(c.softening).toBe(0.25);
    expect(c.absorbs).toBe(false);
    expect(c.lenses).toBe(false);
    expect(c.serialize()).toEqual(DEFAULT_GRAVITY_MASS);
  });

  // Black holes lens and rocks don't, so a scene that marks a mass absorbing
  // gets the lensing without having to say so twice.
  it('lenses whenever it absorbs, unless the scene says otherwise', () => {
    expect(new GravityMassComponent({ absorbs: true }).lenses).toBe(true);
    expect(new GravityMassComponent({ absorbs: true, lenses: false }).lenses).toBe(false);
    expect(new GravityMassComponent({ lenses: true }).lenses).toBe(true);
  });

  it('serialize() round-trips every field', () => {
    const authored: Required<GravityMassInput> = {
      mass: 450, radius: 1.2, softening: 0.3, absorbs: true, lenses: false,
    };
    const copy = new GravityMassComponent(new GravityMassComponent(authored).serialize());
    expect(copy.serialize()).toEqual(authored);
  });
});

describe('GravityMass entry file', () => {
  it('re-exports the definitions and the field math, so the registry resolves it by name', () => {
    expect(entry.GravityMassComponent).toBe(GravityMassComponent);
    expect(entry.DEFAULT_GRAVITY_MASS).toBe(DEFAULT_GRAVITY_MASS);
    expect(entry.fieldAt).toBe(core.fieldAt);
    expect(entry.contactAt).toBe(core.contactAt);
    expect(entry.circularSpeed).toBe(core.circularSpeed);
    expect(entry.makeMassPoint).toBe(core.makeMassPoint);
  });
});

describe('a GravityMass in a world (read by GravityBodySystem)', () => {
  let eventBus: EventBus;
  let renderer: MockRendererAdapter;
  let world: World;

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

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

  function massAt(id: string, at: Vec3, data: GravityMassInput = {}): Entity {
    const e = world.createEntity(id);
    const mesh = new MeshPrimitiveComponent({ primitive: 'sphere', position: at });
    mesh.handle = renderer.createMesh(id, { kind: 'sphere' });
    e.add(mesh);
    e.add(new GravityMassComponent(data));
    return e;
  }

  /** A body at rest that never collides, so only the pull is under test. */
  function probeAt(at: Vec3): Entity {
    const e = world.createEntity('probe');
    e.add(new MeshPrimitiveComponent({ primitive: 'sphere', position: at }));
    e.add(new GravityBodyComponent({ collides: false, maxSpeed: 0 }));
    return e;
  }

  const velocityOf = (e: Entity) => e.get(GravityBodyComponent)!.velocity;

  it('pulls a body toward it', () => {
    // m / r² = 4 / 2² = 1 unit/s². One frame of exactly one step (1/120 s):
    // v = a·dt, then p = v·dt from the NEW velocity.
    massAt('hole', [2, 0, 0], { mass: 4, softening: 0 });
    const probe = probeAt([0, 0, 0]);
    world.update(1 / 120);
    expect(velocityOf(probe)).toEqual([1 / 120, 0, 0]);
    expect(probe.get(MeshPrimitiveComponent)!.position[0]).toBeCloseTo(1 / 14400, 15);
  });

  // Masses are gathered afresh every frame, so a black hole the player drags
  // bends the next frame's pull with it.
  it('is read where it is NOW — move the mass and the pull follows', () => {
    const hole = massAt('hole', [2, 0, 0], { mass: 4, softening: 0 });
    const probe = probeAt([0, 0, 0]);
    world.update(1 / 120);
    expect(velocityOf(probe)[0]).toBeGreaterThan(0);

    hole.get(MeshPrimitiveComponent)!.position[0] = -2;
    velocityOf(probe).fill(0);
    world.update(1 / 120);
    expect(velocityOf(probe)[0]).toBeLessThan(0);
  });

  it('stays where it is: a mass that is not a body is never moved or written', () => {
    const hole = massAt('hole', [5, 0, 0], { mass: 400 });
    probeAt([0, 0, 0]);
    renderer.calls.length = 0;
    for (let i = 0; i < 30; i++) world.update(1 / 60);
    expect(hole.get(MeshPrimitiveComponent)!.position).toEqual([5, 0, 0]);
    const handle = hole.get(MeshPrimitiveComponent)!.handle;
    expect(renderer.calls.filter((c) => c.args[0] === handle)).toHaveLength(0);
  });

  // Parking is how a level clears its black holes; a parked one must stop
  // pulling, or the next level's rocks bend round something that is not there.
  it('a mass parked by its pool stops pulling', () => {
    world.registerPool('hole', {
      size: 1,
      build: (e) => {
        e.add(new MeshPrimitiveComponent({ primitive: 'sphere', position: [2, 0, 0] }));
        e.add(new GravityMassComponent({ mass: 4, softening: 0 }));
      },
    });
    const hole = world.acquire('hole')!;
    const probe = probeAt([0, 0, 0]);
    world.update(1 / 120);
    expect(velocityOf(probe)[0]).toBeGreaterThan(0);

    world.removeEntity(hole); // parks it
    velocityOf(probe).fill(0);
    world.update(1 / 120);
    expect(velocityOf(probe)).toEqual([0, 0, 0]);
  });
});