2D physics test harness types

Read as Markdown

Import these contracts with type from @pibbl/core/physics/2d/testing.

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() runs one requested host frame. advanceFrames() returns host frames run, rather than promising an equal number of fixed physics ticks. act() flushes a state action without moving host time. reset() remounts with monotonic time; dispose() is idempotent and restores the scheduler driver.

Use createPhysicsTestHarness2D from the test-harness function page and consult the 2D physics guide for public world and handle composition.

PibblPhysicsTestHarness2DOptions

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

The caller owns canvas; harness disposal never removes it. root() creates the initial and reset composition. observe() reads public application state. External fixtures stay under the test’s ownership and are not reset.

API details from source

PibblPhysicsTestHarness2DOptions

Caller-owned canvas, root factory, and observation callback for deterministic physics testing.

interface PibblPhysicsTestHarness2DOptions<Observation>

Related API: PibblPhysicsTestHarness2DOptions.

See also

PibblNode

createPhysicsTestHarness2D

View source — packages/core/src/features/physics/2d-testing.ts:21

Properties and methods

canvas

readonly canvas: HTMLCanvasElement

The caller owns this canvas; disposing the harness never removes it.

View source — packages/core/src/features/physics/2d-testing.ts:23

root

readonly root: () => PibblNode

Related API: PibblNode.

Creates a new public Pibbl root for the initial mount and each reset.

Returns

The Pibbl root tree mounted by the test harness. See PibblNode.

View source — packages/core/src/features/physics/2d-testing.ts:28

observe

readonly observe: () => Observation

Reads application state after a frame or action.

Returns

The semantic state to expose through the harness’s observe method.

View source — packages/core/src/features/physics/2d-testing.ts:33

PibblPhysicsTestHarness2D

A disposable test mount with explicit host-frame advancement and public-state observations.

interface PibblPhysicsTestHarness2D<Observation>

Related API: PibblPhysicsTestHarness2D.

See also

createPhysicsTestHarness2D

View source — packages/core/src/features/physics/2d-testing.ts:41

Properties and methods

pendingFrames

readonly pendingFrames: number

Number of host callbacks currently requested by Pibbl (zero or one).

View source — packages/core/src/features/physics/2d-testing.ts:43

flush

flush: () => boolean

Delivers one already-requested host frame at the current host time.

Returns

Whether a pending frame was flushed.

View source — packages/core/src/features/physics/2d-testing.ts:48

advanceFrames

advanceFrames: (count: number, milliseconds?: number) => number

Advances up to count requested host frames by milliseconds each. This advances the host clock, not a guaranteed count of physics fixed ticks.

Parameters

• count — Number of frames to advance.

• milliseconds — Duration of each frame in milliseconds.

Returns

The number of frames advanced.

View source — packages/core/src/features/physics/2d-testing.ts:56

act

act: <Result>(callback: () => Result) => Result

Runs an application action and delivers one resulting frame at the current time.

Parameters

• callback — Action to run within the harness’s deterministic scheduling context.

Returns

The action’s return value.

View source — packages/core/src/features/physics/2d-testing.ts:62

observe

observe: () => Observation

Reads the caller-provided public observation without scheduling work.

Returns

The current observation from the configured observer.

View source — packages/core/src/features/physics/2d-testing.ts:67

reset

reset: () => void

Disposes the mounted root and mounts a new one without moving host time backward.

View source — packages/core/src/features/physics/2d-testing.ts:69

dispose

dispose: () => void

Disposes the root and restores the previous realm scheduler driver.

View source — packages/core/src/features/physics/2d-testing.ts:71

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.