2D physics test harness

Read as Markdown

import { createPhysicsTestHarness2D } from "@pibbl/core/physics/2d/testing";
import type {
  PibblPhysicsTestHarness2D,
  PibblPhysicsTestHarness2DOptions,
} from "@pibbl/core/physics/2d/testing";

createPhysicsTestHarness2D mounts a public Pibbl root with a deterministic manual host-frame driver. It lets tests and coding agents observe public handles and state without importing private world storage.

function createPhysicsTestHarness2D<Observation>(
  options: PibblPhysicsTestHarness2DOptions<Observation>,
): PibblPhysicsTestHarness2D<Observation>;

`PibblPhysicsTestHarness2DOptions`

interface PibblPhysicsTestHarness2DOptions<Observation> {
  readonly canvas: HTMLCanvasElement;
  readonly root: () => PibblNode;
  readonly observe: () => Observation;
}

The caller owns the canvas; disposal never removes it. root() creates the initial and reset composition. observe() should read public application state. External fixtures are not reset automatically.

`PibblPhysicsTestHarness2D`

interface PibblPhysicsTestHarness2D<Observation> {
  readonly pendingFrames: number;
  flush(): boolean;
  advanceFrames(count: number, milliseconds?: number): number;
  act<Result>(callback: () => Result): Result;
  observe(): Observation;
  reset(): void;
  dispose(): void;
}

flush() delivers one requested host frame at current host time. advanceFrames uses 1000 / 60 milliseconds by default and returns the host callbacks it ran; it does not promise an equal number of physics ticks because fixed-step worlds may take zero, one, or several ticks per host frame. act() runs a state action then flushes one frame without moving host time. reset() remounts while time remains monotonic; dispose() is idempotent and restores the previous driver.

The harness requires an isolated Pibbl realm and rejects creation while another Pibbl root is mounted, because Pibbl has one realm scheduler. See the 2D physics guide for the public world and handle API under test.

API details from source

Creates an isolated manual-clock test mount for one Pibbl 2D physics composition.

It refuses a realm with an existing root because a Pibbl realm deliberately has one scheduler. Use ordinary browser tests when a test needs multiple roots.

createPhysicsTestHarness2D: <Observation>(options: PibblPhysicsTestHarness2DOptions<Observation>) => PibblPhysicsTestHarness2D<Observation>

Parameters

options — Caller-owned canvas, root factory, and semantic state observer. See PibblPhysicsTestHarness2DOptions .

Returns

A harness owning the test mount and scheduler lifetime; dispose it after use. See PibblPhysicsTestHarness2D .

Implementation guidance for agents

Read the Physics and geometry companion for ownership, adaptation, failure modes, and verification. Agent start provides the version-selection workflow.

Complete minimal examples

Deterministic physics test: Advance a public physics scene through controlled host frames. Plain source

Documentation version

Documentation built with @pibbl/core 0.0.2, revision 272a94a. ALPHA — NOT FOR PRODUCTION USE.