2D physics functions and components

Read as Markdown

import {
  Capsule2D,
  Chain2D,
  PhysicsDebug2D,
  PhysicsShape2D,
  PhysicsWorld2D,
  Segment2D,
  circleShape2D,
  collider2D,
  pibblPhysicsBody2D,
  pibblPhysicsWorld2D,
  dynamicBody2D,
} from "@pibbl/core/physics/2d";

@pibbl/core/physics/2d is a component-scoped, Pibbl-scheduled Rapier 2D world. It does not start a second animation loop. For recipes and interaction examples, read the 2D physics guide. Pure construction and geometry operations are also exported by @pibbl/core/physics/2d/geometry. The central contracts are PibblPhysicsWorld2DProps, PibblPhysicsBodyHandle2D, and PibblPhysicsShape2D.

World and Canvas primitives

`PhysicsWorld2D`

const world = (
  <PhysicsWorld2D gravity={[0, 600]} fixedStepMilliseconds={1000 / 60} />
);

Creates one world for descendants. It owns fixed-step simulation, collision delivery, presentation interpolation, and teardown. Default space="root" uses root-logical coordinates; creation-only space="local" follows the world’s viewport transform. See PibblPhysicsWorld2DProps.

`pibblPhysicsWorld2D`

function pibblPhysicsWorld2D(): PibblPhysicsWorldHandle2D;

Returns the nearest world while a descendant evaluates. Use it for world queries, coordinate conversion, and inspection.

`PhysicsShape2D`, `Capsule2D`, `Segment2D`, and `Chain2D`

Canvas primitives that paint exact supported shapes and accept physics:

const primitiveShapes = (
  <>
    <PhysicsShape2D style={{ shape: circleShape2D({ radius: 8 }) }} />
    <Capsule2D style={{ start: [0, 0], end: [36, 0], radius: 5 }} />
    <Segment2D style={{ start: [0, 0], end: [60, 0] }} />
    <Chain2D
      style={{
        points: [
          [0, 0],
          [40, 0],
          [40, 24],
        ],
        radius: 2,
      }}
    />
  </>
);

Their props and styles are covered by the 2D physics types.

`PhysicsDebug2D`

const debug = (
  <PhysicsDebug2D world={pibblPhysicsWorld2D()} color="rgba(0, 160, 255, .8)" />
);

Renders a read-only diagnostic overlay of committed collider bounds, centers of mass, contact points, and contact normals. It creates no pointer targets, does not advance the world, and is appropriate for tests and development-only scenes.

`withPhysicsShape2D`

function withPhysicsShape2D<P, I, ResolvedStyle>(
  component: PibblPrimitiveComponent<P, I>,
  options: { resolveShape(style: Readonly<ResolvedStyle>): PibblPhysicsShape2D },
): PibblPrimitiveComponent<
  P & PibblPhysicsPrimitiveProps2D,
  I & { physics?: PibblPhysicsAttachment2D }
>;

Derives a primitive that resolves an immutable shape synchronously from its resolved style. This is the custom-primitive extension point; it does not mount a world or alter paint order.

Descriptor and handle factories

function dynamicBody2D(
  options?: PibblPhysicsDynamicBody2DOptions,
): PibblPhysicsBodyAttachment2D;
function staticBody2D(
  options?: PibblPhysicsStaticBody2DOptions,
): PibblPhysicsBodyAttachment2D;
function kinematicBody2D(
  options?: PibblPhysicsKinematicBody2DOptions,
): PibblPhysicsBodyAttachment2D;
function collider2D(
  options?: PibblPhysicsColliderConfiguration2D,
): PibblPhysicsColliderAttachment2D;
function pibblPhysicsBody2D(): PibblPhysicsBodyHandle2D;

Attach a body descriptor to a primitive and child collider2D() descriptors to its geometry. Dynamic bodies receive forces and contacts; static bodies remain fixed; kinematic bodies follow declared signals and affect other bodies. The body primitive’s authored transform supplies its initial pose. pibblPhysicsBody2D is a stable hook handle that can bind to one live body at a time.

Commands

Commands enter Pibbl’s Begin phase and take effect on the next admitted physics frame; none mutate a world during render.

function applyForce2D(
  body: PibblPhysicsBodyHandle2D,
  force: PibblPhysicsVector2,
  options?: { at?: PibblPhysicsVector2; wake?: boolean },
): void;
function applyImpulse2D(
  body: PibblPhysicsBodyHandle2D,
  impulse: PibblPhysicsVector2,
  options?: { at?: PibblPhysicsVector2; wake?: boolean },
): void;
function applyTorque2D(body: PibblPhysicsBodyHandle2D, torque: number): void;
function setLinearVelocity2D(
  body: PibblPhysicsBodyHandle2D,
  velocity: PibblPhysicsVector2,
): void;
function setAngularVelocity2D(
  body: PibblPhysicsBodyHandle2D,
  degreesPerSecond: number,
): void;
function teleportBody2D(
  body: PibblPhysicsBodyHandle2D,
  pose: PibblPhysicsPose2D,
): void;
function wakeBody2D(body: PibblPhysicsBodyHandle2D): void;
function sleepBody2D(body: PibblPhysicsBodyHandle2D): void;
function disableBody2D(body: PibblPhysicsBodyHandle2D): void;
function enableBody2D(
  body: PibblPhysicsBodyHandle2D,
  options?: { velocity?: "zero" | "preserve" },
): void;

at is a world-space application point. Teleportation sets a pose without a sweep. Re-enabling uses zero velocity unless preserve is selected.

Mounted-world queries and observation

function raycastAny2D(
  world: PibblPhysicsWorldHandle2D,
  ray: PibblPhysicsRay2D,
  options?: PibblPhysicsQueryOptions2D,
): boolean;
function raycastClosest2D(
  world: PibblPhysicsWorldHandle2D,
  ray: PibblPhysicsRay2D,
  options?: PibblPhysicsQueryOptions2D,
): PibblPhysicsQueryHit2D | null;
function raycastAll2D(
  world: PibblPhysicsWorldHandle2D,
  ray: PibblPhysicsRay2D,
  options?: PibblPhysicsQueryOptions2D,
): readonly PibblPhysicsQueryHit2D[];
function shapeCastAny2D(
  world: PibblPhysicsWorldHandle2D,
  shape: PibblPhysicsShape2D,
  from: PibblPhysicsPose2D,
  translation: PibblPhysicsVector2,
  options?: PibblPhysicsQueryOptions2D,
): boolean;
function shapeCastClosest2D(
  world: PibblPhysicsWorldHandle2D,
  shape: PibblPhysicsShape2D,
  from: PibblPhysicsPose2D,
  translation: PibblPhysicsVector2,
  options?: PibblPhysicsQueryOptions2D,
): PibblPhysicsQueryHit2D | null;
function shapeCastAll2D(
  world: PibblPhysicsWorldHandle2D,
  shape: PibblPhysicsShape2D,
  from: PibblPhysicsPose2D,
  translation: PibblPhysicsVector2,
  options?: PibblPhysicsQueryOptions2D,
): readonly PibblPhysicsQueryHit2D[];
function hasShapeOverlap2D(
  world: PibblPhysicsWorldHandle2D,
  shape: PibblPhysicsShape2D,
  pose: PibblPhysicsPose2D,
  options?: PibblPhysicsQueryOptions2D,
): boolean;
function findShapeOverlap2D(
  world: PibblPhysicsWorldHandle2D,
  shape: PibblPhysicsShape2D,
  pose: PibblPhysicsPose2D,
  options?: PibblPhysicsQueryOptions2D,
): PibblPhysicsQueryMatch2D | null;
function findAllShapeOverlaps2D(
  world: PibblPhysicsWorldHandle2D,
  shape: PibblPhysicsShape2D,
  pose: PibblPhysicsPose2D,
  options?: PibblPhysicsQueryOptions2D,
): readonly PibblPhysicsQueryMatch2D[];
function hasAabbMatch2D(
  world: PibblPhysicsWorldHandle2D,
  bounds: PibblPhysicsAabb2D,
  options?: PibblPhysicsQueryOptions2D,
): boolean;
function findAabbMatch2D(
  world: PibblPhysicsWorldHandle2D,
  bounds: PibblPhysicsAabb2D,
  options?: PibblPhysicsQueryOptions2D,
): PibblPhysicsQueryMatch2D | null;
function findAllAabbMatches2D(
  world: PibblPhysicsWorldHandle2D,
  bounds: PibblPhysicsAabb2D,
  options?: PibblPhysicsQueryOptions2D,
): readonly PibblPhysicsQueryMatch2D[];
function hasPointMatch2D(
  world: PibblPhysicsWorldHandle2D,
  point: PibblPhysicsVector2,
  options?: PibblPhysicsQueryOptions2D,
): boolean;
function findPointMatch2D(
  world: PibblPhysicsWorldHandle2D,
  point: PibblPhysicsVector2,
  options?: PibblPhysicsQueryOptions2D,
): PibblPhysicsQueryMatch2D | null;
function findAllPointMatches2D(
  world: PibblPhysicsWorldHandle2D,
  point: PibblPhysicsVector2,
  options?: PibblPhysicsQueryOptions2D,
): readonly PibblPhysicsQueryMatch2D[];
function toPhysicsPoint2D(
  world: PibblPhysicsWorldHandle2D,
  point: PibblPhysicsVector2,
): PibblPhysicsVector2;
function fromPhysicsPoint2D(
  world: PibblPhysicsWorldHandle2D,
  point: PibblPhysicsVector2,
): PibblPhysicsVector2;
function inspectPhysics2D(
  world: PibblPhysicsWorldHandle2D,
): PibblPhysicsInspection2D;
function inspectPhysics2D(
  body: PibblPhysicsBodyHandle2D,
): PibblPhysicsBodyInspection2D | undefined;

Queries read the committed world and accept filtering options. Each named operation returns a fixed boolean, nullable record, or readonly array contract. The point helpers cross between root-logical and simulation coordinates. inspectPhysics2D(world) returns an immutable JSON-safe world observation without advancing, restoring, or scheduling. inspectPhysics2D(body) returns only that body’s observation; an unbound or stale handle returns undefined.

Pure shapes and geometry

circleShape2D, ellipseShape2D, boxShape2D, roundedBoxShape2D, capsuleShape2D, arcShape2D, wedgeShape2D, segmentShape2D, chainShape2D, and polygonShape2D each create an immutable PibblPhysicsShape2D from their corresponding option object.

function boundsOfShape2D(shape: PibblPhysicsShape2D): PibblPhysicsAabb2D;
function massProperties2D(
  shape: PibblPhysicsShape2D,
  density?: number,
): PibblPhysicsMassProperties2D;
function transformShape2D(
  shape: PibblPhysicsShape2D,
  transform: PibblPhysicsTransform2D,
): PibblPhysicsShape2D;
function containsPoint2D(
  shape: PibblPhysicsShape2D,
  pose: PibblPhysicsPose2D,
  point: PibblPhysicsVector2,
): boolean;
function distanceBetweenShapes2D(
  first: PibblPhysicsShape2D,
  firstPose: PibblPhysicsPose2D,
  second: PibblPhysicsShape2D,
  secondPose: PibblPhysicsPose2D,
): PibblPhysicsDistance2D;
function overlapShapes2D(
  first: PibblPhysicsShape2D,
  firstPose: PibblPhysicsPose2D,
  second: PibblPhysicsShape2D,
  secondPose: PibblPhysicsPose2D,
): boolean;
function contactBetweenShapes2D(
  first: PibblPhysicsShape2D,
  firstPose: PibblPhysicsPose2D,
  second: PibblPhysicsShape2D,
  secondPose: PibblPhysicsPose2D,
): PibblPhysicsShapeContact2D | null;
function raycastShape2D(
  shape: PibblPhysicsShape2D,
  pose: PibblPhysicsPose2D,
  ray: PibblPhysicsRay2D,
  options?: { includeInitialOverlap?: boolean },
): PibblPhysicsShapeHit2D | null;
function shapeCastAgainstShape2D(
  moving: PibblPhysicsShape2D,
  from: PibblPhysicsPose2D,
  translation: PibblPhysicsVector2,
  target: PibblPhysicsShape2D,
  targetPose: PibblPhysicsPose2D,
  options?: { includeInitialOverlap?: boolean },
): PibblPhysicsShapeHit2D | null;

These deterministic functions need neither a mounted world nor Pibbl core. transformShape2D returns a new descriptor. Contact normals point from the second shape toward the first.

Fixed query return contracts

Query	Boolean	One result or `null`	Readonly result array
raycast	`raycastAny2D`	`raycastClosest2D`	`raycastAll2D`
shapeCast	`shapeCastAny2D`	`shapeCastClosest2D`	`shapeCastAll2D`
overlapShape	`hasShapeOverlap2D`	`findShapeOverlap2D`	`findAllShapeOverlaps2D`
queryAabb	`hasAabbMatch2D`	`findAabbMatch2D`	`findAllAabbMatches2D`
queryPoint	`hasPointMatch2D`	`findPointMatch2D`	`findAllPointMatches2D`

All functions accept PibblPhysicsQueryOptions2D for sensor policy, collision filtering, and exclusions. There is no mode option. Boolean queries stop at the first match. Cast results sort by time of impact, distance, then collider index and generation. Overlap, bounds, and point results sort by collider index and generation; find… returns the first in that order, not a nearest match. Returned result arrays are frozen; no matches produce false, null, or an empty array according to the named operation.

API details from source

arcShape2D

Creates an immutable arc collision shape without initializing a physics world.

arcShape2D: (input: Readonly<{ center?: PibblPhysicsVector2; radius: number; startAngleRadians: number; endAngleRadians: number; counterclockwise?: boolean; thickness: number; }>) => PibblPhysicsShape2D

Parameters

input — Arc center, radius, angular endpoints in radians, sweep direction, and thickness. See PibblPhysicsVector2 .

Returns

An immutable thick-arc collision shape. See PibblPhysicsShape2D.

boundsOfShape2D

Computes axis-aligned bounds for an immutable shape at an optional pose.

boundsOfShape2D: (shape: PibblPhysicsShape2D, pose?: PibblPhysicsPose2D) => PibblPhysicsAabb2D

Parameters

shape — Shape whose bounds are needed. See PibblPhysicsShape2D.
pose — Optional pose at which to evaluate the shape. See PibblPhysicsPose2D.

Returns

Axis-aligned bounds of the posed shape. See PibblPhysicsAabb2D.

boxShape2D

Creates an immutable box collision shape without initializing a physics world.

boxShape2D: (input: Readonly<{ width: number; height: number; center?: PibblPhysicsVector2; }>) => PibblPhysicsShape2D

Parameters

input — Box width, height, and optional center. See PibblPhysicsVector2.

Returns

An immutable box collision shape. See PibblPhysicsShape2D.

capsuleShape2D

Creates an immutable capsule collision shape without initializing a physics world.

capsuleShape2D: (input: Readonly<{ start: PibblPhysicsVector2; end: PibblPhysicsVector2; radius: number; }>) => PibblPhysicsShape2D

Parameters

input — Capsule centerline endpoints and radius. See PibblPhysicsVector2.

Returns

An immutable capsule collision shape. See PibblPhysicsShape2D.

chainShape2D

Creates an immutable chain collision shape without initializing a physics world.

chainShape2D: (input: Readonly<{ points: readonly PibblPhysicsVector2[]; closed?: boolean; radius?: number; }>) => PibblPhysicsShape2D

Parameters

input — Ordered chain points, closure policy, and optional radius. See PibblPhysicsVector2 .

Returns

An immutable chain collision shape. See PibblPhysicsShape2D.

circleShape2D

Creates an immutable circle collision shape without initializing a physics world.

circleShape2D: (input: Readonly<{ radius: number; center?: PibblPhysicsVector2; }>) => PibblPhysicsShape2D

Parameters

input — Circle radius and optional center. See PibblPhysicsVector2.

Returns

An immutable circle collision shape. See PibblPhysicsShape2D.

ellipseShape2D

Creates an immutable ellipse collision shape without initializing a physics world.

ellipseShape2D: (input: Readonly<{ radiusX: number; radiusY: number; center?: PibblPhysicsVector2; rotationDegrees?: number; }>) => PibblPhysicsShape2D

Parameters

input — Ellipse radii, optional center, and rotation in degrees. See PibblPhysicsVector2 .

Returns

An immutable ellipse collision shape. See PibblPhysicsShape2D.

massProperties2D

Computes shape area, centroid, mass, and rotational inertia at the requested density.

massProperties2D: (shape: PibblPhysicsShape2D, options?: Readonly<{ density?: number; }>) => PibblPhysicsMassProperties2D

Parameters

shape — Shape whose mass properties are needed. See PibblPhysicsShape2D.
options — Optional material density.

Returns

Mass, center of mass, and inertia for the shape. See PibblPhysicsMassProperties2D.

polygonShape2D

Creates an immutable polygon collision shape without initializing a physics world.

polygonShape2D: (input: Readonly<{ points: readonly PibblPhysicsVector2[]; }>) => PibblPhysicsShape2D

Parameters

input — Ordered polygon vertices. See PibblPhysicsVector2.

Returns

An immutable polygon collision shape. See PibblPhysicsShape2D.

roundedBoxShape2D

Creates an immutable rounded box collision shape without initializing a physics world.

roundedBoxShape2D: (input: Readonly<{ width: number; height: number; radius: number | readonly [topLeft: number, topRight: number, bottomRight: number, bottomLeft: number]; center?: PibblPhysicsVector2; }>) => PibblPhysicsShape2D

Parameters

input — Box dimensions, center, and uniform or per-corner radii. See PibblPhysicsVector2 .

Returns

An immutable rounded-box collision shape. See PibblPhysicsShape2D.

segmentShape2D

Creates an immutable segment collision shape without initializing a physics world.

segmentShape2D: (input: Readonly<{ start: PibblPhysicsVector2; end: PibblPhysicsVector2; }>) => PibblPhysicsShape2D

Parameters

input — Segment endpoints. See PibblPhysicsVector2.

Returns

An immutable line-segment collision shape. See PibblPhysicsShape2D.

transformShape2D

Returns independent shape geometry transformed by a rigid 2D pose.

transformShape2D: (shape: PibblPhysicsShape2D, transform: PibblPhysicsTransform2D) => PibblPhysicsShape2D

Parameters

shape — Source shape; it is not modified. See PibblPhysicsShape2D.
transform — Transform to apply to the shape. See PibblPhysicsTransform2D.

Returns

A shape containing the transformed geometry. See PibblPhysicsShape2D.

wedgeShape2D

Creates an immutable wedge collision shape without initializing a physics world.

wedgeShape2D: (input: Readonly<{ center?: PibblPhysicsVector2; radius: number; startAngleRadians: number; endAngleRadians: number; counterclockwise?: boolean; }>) => PibblPhysicsShape2D

Parameters

input — Wedge center, radius, angular endpoints in radians, and sweep direction. See PibblPhysicsVector2 .

Returns

An immutable wedge collision shape. See PibblPhysicsShape2D.

containsPoint2D

Tests whether a point lies within a posed shape without creating a physics world.

containsPoint2D: (shape: PibblPhysicsShape2D, pose: PibblPhysicsPose2D, point: PibblPhysicsVector2) => boolean

Parameters

shape — Shape to test. See PibblPhysicsShape2D.
pose — Shape pose. See PibblPhysicsPose2D.
point — Point in the same coordinate space as the posed shape. See PibblPhysicsVector2 .

Returns

Whether the posed shape contains the point.

distanceBetweenShapes2D

Computes signed separation and witness geometry between two posed shapes.

distanceBetweenShapes2D: (first: PibblPhysicsShape2D, firstPose: PibblPhysicsPose2D, second: PibblPhysicsShape2D, secondPose: PibblPhysicsPose2D) => PibblPhysicsDistance2D

Parameters

first — First shape. See PibblPhysicsShape2D.
firstPose — Pose of the first shape. See PibblPhysicsPose2D.
second — Second shape. See PibblPhysicsShape2D.
secondPose — Pose of the second shape. See PibblPhysicsPose2D.

Returns

Distance and closest-point information for the two posed shapes. See PibblPhysicsDistance2D .

overlapShapes2D

Tests whether two posed shapes overlap without creating a physics world.

overlapShapes2D: (first: PibblPhysicsShape2D, firstPose: PibblPhysicsPose2D, second: PibblPhysicsShape2D, secondPose: PibblPhysicsPose2D) => boolean

Parameters

first — First shape. See PibblPhysicsShape2D.
firstPose — Pose of the first shape. See PibblPhysicsPose2D.
second — Second shape. See PibblPhysicsShape2D.
secondPose — Pose of the second shape. See PibblPhysicsPose2D.

Returns

Whether the two posed shapes overlap.

contactBetweenShapes2D

Computes contact geometry for two posed shapes, or null when they do not contact.

contactBetweenShapes2D: (first: PibblPhysicsShape2D, firstPose: PibblPhysicsPose2D, second: PibblPhysicsShape2D, secondPose: PibblPhysicsPose2D) => PibblPhysicsShapeContact2D | null

Parameters

first — First shape. See PibblPhysicsShape2D.
firstPose — Pose of the first shape. See PibblPhysicsPose2D.
second — Second shape. See PibblPhysicsShape2D.
secondPose — Pose of the second shape. See PibblPhysicsPose2D.

Returns

Contact information, or null when the shapes do not contact. See PibblPhysicsShapeContact2D .

raycastShape2D

Casts a ray against one posed shape and returns its first hit or null.

raycastShape2D: (shape: PibblPhysicsShape2D, publicPose: PibblPhysicsPose2D, ray: PibblPhysicsRay2D, options?: Readonly<{ includeInitialOverlap?: boolean; }>) => PibblPhysicsShapeHit2D | null

Parameters

shape — Shape to intersect. See PibblPhysicsShape2D.
publicPose — Target shape pose. See PibblPhysicsPose2D.
ray — Ray origin, direction, and travel limit. See PibblPhysicsRay2D.
options — Whether initial overlap counts as a hit.

Returns

The first shape hit, or null when there is no hit. See PibblPhysicsShapeHit2D.

shapeCastAgainstShape2D

Sweeps a posed shape along a translation against another posed shape and returns a hit or null.

shapeCastAgainstShape2D: (moving: PibblPhysicsShape2D, publicFrom: PibblPhysicsPose2D, publicTranslation: PibblPhysicsVector2, target: PibblPhysicsShape2D, publicTargetPose: PibblPhysicsPose2D, options?: Readonly<{ includeInitialOverlap?: boolean; }>) => PibblPhysicsShapeHit2D | null

Parameters

moving — Shape to sweep. See PibblPhysicsShape2D.
publicFrom — Initial pose of the moving shape. See PibblPhysicsPose2D.
publicTranslation — Translation vector for the sweep. See PibblPhysicsVector2.
target — Stationary shape to test against. See PibblPhysicsShape2D.
publicTargetPose — Pose of the stationary shape. See PibblPhysicsPose2D.
options — Whether initial overlap counts as a hit.

Returns

The first sweep hit, or null when there is no hit. See PibblPhysicsShapeHit2D.

PhysicsWorld2D

Owns one transparent, component-scoped 2D physics world.

PhysicsWorld2D: PibblComponent<PibblPhysicsWorld2DProps>

PhysicsShape2D

Draws an immutable physics shape as a Canvas primitive with optional body or collider attachment.

PhysicsShape2D: PibblPrimitiveComponent<PhysicsShape2DProps, PrimitiveInput<PhysicsShape2DProps, PhysicsShape2DStyle>>

Parameters

props — Authored component inputs, supplied through JSX or createElement. See the linked props and style types.

Throws

When called directly; Pibbl mounts this component through JSX or createElement.

Capsule2D

Draws a capsule between two endpoints with optional physics attachment.

Capsule2D: PibblPrimitiveComponent<Capsule2DProps, PrimitiveInput<Capsule2DProps, Capsule2DStyle>>

Parameters

props — Authored component inputs, supplied through JSX or createElement. See the linked props and style types.

Throws

When called directly; Pibbl mounts this component through JSX or createElement.

Segment2D

Draws a line segment with optional physics attachment.

Segment2D: PibblPrimitiveComponent<Segment2DProps, PrimitiveInput<Segment2DProps, Segment2DStyle>>

Parameters

props — Authored component inputs, supplied through JSX or createElement. See the linked props and style types.

Throws

When called directly; Pibbl mounts this component through JSX or createElement.

Chain2D

Draws an open or closed point chain with optional physics attachment.

Chain2D: PibblPrimitiveComponent<Chain2DProps, PrimitiveInput<Chain2DProps, Chain2DStyle>>

Parameters

props — Authored component inputs, supplied through JSX or createElement. See the linked props and style types.

Throws

When called directly; Pibbl mounts this component through JSX or createElement.

collider2D

Creates a declarative collider attachment for a primitive within a physics body.

collider2D: (options?: PibblPhysicsColliderConfiguration2D) => PibblPhysicsColliderAttachment2D

Parameters

options — Collider shape, material, filtering, and sensor configuration. See PibblPhysicsColliderConfiguration2D .

Returns

A collider attachment for a supported primitive’s physics prop. See PibblPhysicsColliderAttachment2D .

dynamicBody2D

Creates a declarative body attachment whose motion is advanced by the physics solver.

dynamicBody2D: (options?: PibblPhysicsDynamicBody2DOptions) => PibblPhysicsBodyAttachment2D

Parameters

options — Dynamic body, collider, and initial motion configuration. See PibblPhysicsDynamicBody2DOptions .

Returns

A dynamic-body attachment for a supported primitive’s physics prop. See PibblPhysicsBodyAttachment2D .

kinematicBody2D

Creates a declarative body attachment driven by application-supplied target signals.

kinematicBody2D: (options?: PibblPhysicsKinematicBody2DOptions) => PibblPhysicsBodyAttachment2D

Parameters

options — Kinematic body, collider, and motion configuration. See PibblPhysicsKinematicBody2DOptions .

Returns

A kinematic-body attachment for a supported primitive’s physics prop. See PibblPhysicsBodyAttachment2D .

staticBody2D

Creates a declarative body attachment that remains fixed in the simulation.

staticBody2D: (options?: PibblPhysicsStaticBody2DOptions) => PibblPhysicsBodyAttachment2D

Parameters

options — Static body and collider configuration. See PibblPhysicsStaticBody2DOptions .

Returns

A static-body attachment for a supported primitive’s physics prop. See PibblPhysicsBodyAttachment2D .

withPhysicsShape2D

Adds physics-attachment support to a custom primitive using its resolved-style shape callback.

withPhysicsShape2D: <P, I, ResolvedStyle>(component: PibblPrimitiveComponent<P, I>, options: Readonly<{ resolveShape(style: Readonly<ResolvedStyle>): PibblPhysicsShape2D; }>) => PibblPrimitiveComponent<P & PibblPhysicsPrimitiveProps2D, I & { readonly physics?: PibblPhysicsAttachment2D; }>

Parameters

component — Primitive whose rendered style determines its collision shape. See PibblPrimitiveComponent .
options — Pure resolver deriving collision geometry from resolved style. See PibblPhysicsShape2D .

Returns

A derived primitive accepting the public physics attachment prop. See PibblPrimitiveComponent , PibblPhysicsPrimitiveProps2D , PibblPhysicsAttachment2D .

pibblPhysicsBody2D

Returns one stable, component-owned 2D body endpoint for this hook slot.

pibblPhysicsBody2D: () => PibblPhysicsBodyHandle2D

Returns

A stable body handle that can be attached to a physics body. See PibblPhysicsBodyHandle2D .

pibblPhysicsWorld2D

Returns the nearest 2D physics world while a descendant is evaluating.

pibblPhysicsWorld2D: () => PibblPhysicsWorldHandle2D

Returns

A stable world handle that can be attached to a physics world. See PibblPhysicsWorldHandle2D .

applyForce2D

Queues a force on a body, optionally at a world point and with wake-up control.

applyForce2D: (body: PibblPhysicsBodyHandle2D, force: PibblPhysicsVector2, options?: Readonly<{ at?: PibblPhysicsVector2; wake?: boolean; }>) => void

Parameters

body — Body receiving the force. See PibblPhysicsBodyHandle2D.
force — Force vector in the world’s public coordinate system. See PibblPhysicsVector2 .
options — Optional application point and wake policy. See PibblPhysicsVector2.

applyImpulse2D

Queues an instantaneous momentum change, optionally at a world point and with wake-up control.

applyImpulse2D: (body: PibblPhysicsBodyHandle2D, impulse: PibblPhysicsVector2, options?: Readonly<{ at?: PibblPhysicsVector2; wake?: boolean; }>) => void

Parameters

body — Body receiving the impulse. See PibblPhysicsBodyHandle2D.
impulse — Impulse vector in the world’s public coordinate system. See PibblPhysicsVector2 .
options — Optional application point and wake policy. See PibblPhysicsVector2.

applyTorque2D

Queues torque on a dynamic body through the shared scheduler.

applyTorque2D: (body: PibblPhysicsBodyHandle2D, torque: number) => void

Related API: applyTorque2D, PibblPhysicsBodyHandle2D.

Parameters

body — Body receiving the torque. See PibblPhysicsBodyHandle2D.
torque — Torque to apply in the world’s public units.

disableBody2D

Queues removal of a body’s active participation in the simulation.

disableBody2D: (body: PibblPhysicsBodyHandle2D) => void

Related API: disableBody2D, PibblPhysicsBodyHandle2D.

Parameters

body — Body to disable. See PibblPhysicsBodyHandle2D.

enableBody2D

Queues re-enabling a body with the requested velocity-preservation policy.

enableBody2D: (body: PibblPhysicsBodyHandle2D, options?: Readonly<{ velocity?: "zero" | "preserve"; }>) => void

Related API: enableBody2D, PibblPhysicsBodyHandle2D.

Parameters

body — Body to re-enable. See PibblPhysicsBodyHandle2D.
options — Whether to zero or preserve velocity when enabling.

setAngularVelocity2D

Queues a body’s angular velocity in degrees per second.

setAngularVelocity2D: (body: PibblPhysicsBodyHandle2D, degreesPerSecond: number) => void

Parameters

body — Body whose angular velocity changes. See PibblPhysicsBodyHandle2D.
degreesPerSecond — Angular speed in degrees per second.

setLinearVelocity2D

Queues a body’s linear velocity in physics units per second.

setLinearVelocity2D: (body: PibblPhysicsBodyHandle2D, velocity: PibblPhysicsVector2) => void

Parameters

body — Body whose linear velocity changes. See PibblPhysicsBodyHandle2D.
velocity — Velocity vector in public distance units per second. See PibblPhysicsVector2 .

sleepBody2D

Queues a request to put a body to sleep.

sleepBody2D: (body: PibblPhysicsBodyHandle2D) => void

Related API: sleepBody2D, PibblPhysicsBodyHandle2D.

Parameters

body — Body to put to sleep. See PibblPhysicsBodyHandle2D.

teleportBody2D

Queues an immediate pose change for a body at the next admitted simulation command phase.

teleportBody2D: (body: PibblPhysicsBodyHandle2D, pose: PibblPhysicsPose2D) => void

Parameters

body — Body to reposition. See PibblPhysicsBodyHandle2D.
pose — Destination position and rotation in public coordinates. See PibblPhysicsPose2D .

wakeBody2D

Queues a request to wake a sleeping body.

wakeBody2D: (body: PibblPhysicsBodyHandle2D) => void

Related API: wakeBody2D, PibblPhysicsBodyHandle2D.

Parameters

body — Body to wake. See PibblPhysicsBodyHandle2D.

raycastAny2D

Tests whether the committed world has any ray match, stopping at the first match.

raycastAny2D: (world: PibblPhysicsWorldHandle2D, ray: PibblPhysicsRay2D, options?: PibblPhysicsQueryOptions2D) => boolean

Parameters

world — World to query. See PibblPhysicsWorldHandle2D.
ray — Ray origin, direction, and travel limit. See PibblPhysicsRay2D.
options — Sensor policy and collider filtering. See PibblPhysicsQueryOptions2D.

Returns

Whether a matching collider exists.

View source — packages/core/src/features/physics/2d.ts:88

raycastClosest2D

Returns the first ray result ordered by time of impact, distance, then collider identity, or null.

raycastClosest2D: (world: PibblPhysicsWorldHandle2D, ray: PibblPhysicsRay2D, options?: PibblPhysicsQueryOptions2D) => PibblPhysicsQueryHit2D | null

Parameters

world — World to query. See PibblPhysicsWorldHandle2D.
ray — Ray origin, direction, and travel limit. See PibblPhysicsRay2D.
options — Sensor policy and collider filtering. See PibblPhysicsQueryOptions2D.

Returns

One result or null. See PibblPhysicsQueryHit2D.

View source — packages/core/src/features/physics/2d.ts:104

raycastAll2D

Returns all ray results ordered by time of impact, distance, then collider identity as a frozen array.

raycastAll2D: (world: PibblPhysicsWorldHandle2D, ray: PibblPhysicsRay2D, options?: PibblPhysicsQueryOptions2D) => readonly PibblPhysicsQueryHit2D[]

Parameters

world — World to query. See PibblPhysicsWorldHandle2D.
ray — Ray origin, direction, and travel limit. See PibblPhysicsRay2D.
options — Sensor policy and collider filtering. See PibblPhysicsQueryOptions2D.

Returns

Frozen results, empty when no collider matches. See PibblPhysicsQueryHit2D.

View source — packages/core/src/features/physics/2d.ts:120

shapeCastAny2D

Tests whether the committed world has any shape sweep match, stopping at the first match.

shapeCastAny2D: (world: PibblPhysicsWorldHandle2D, shape: PibblPhysicsShape2D, from: PibblPhysicsPose2D, translation: PibblPhysicsVector2, options?: PibblPhysicsQueryOptions2D) => boolean

Parameters

world — World to query. See PibblPhysicsWorldHandle2D.
shape — Shape to sweep. See PibblPhysicsShape2D.
from — Initial shape pose. See PibblPhysicsPose2D.
translation — Translation vector for the sweep. See PibblPhysicsVector2.
options — Sensor policy and collider filtering. See PibblPhysicsQueryOptions2D.

Returns

Whether a matching collider exists.

View source — packages/core/src/features/physics/2d.ts:138

shapeCastClosest2D

Returns the first shape sweep result ordered by time of impact, distance, then collider identity, or null.

shapeCastClosest2D: (world: PibblPhysicsWorldHandle2D, shape: PibblPhysicsShape2D, from: PibblPhysicsPose2D, translation: PibblPhysicsVector2, options?: PibblPhysicsQueryOptions2D) => PibblPhysicsQueryHit2D | null

Parameters

world — World to query. See PibblPhysicsWorldHandle2D.
shape — Shape to sweep. See PibblPhysicsShape2D.
from — Initial shape pose. See PibblPhysicsPose2D.
translation — Translation vector for the sweep. See PibblPhysicsVector2.
options — Sensor policy and collider filtering. See PibblPhysicsQueryOptions2D.

Returns

One result or null. See PibblPhysicsQueryHit2D.

View source — packages/core/src/features/physics/2d.ts:158

shapeCastAll2D

Returns all shape sweep results ordered by time of impact, distance, then collider identity as a frozen array.

shapeCastAll2D: (world: PibblPhysicsWorldHandle2D, shape: PibblPhysicsShape2D, from: PibblPhysicsPose2D, translation: PibblPhysicsVector2, options?: PibblPhysicsQueryOptions2D) => readonly PibblPhysicsQueryHit2D[]

Parameters

world — World to query. See PibblPhysicsWorldHandle2D.
shape — Shape to sweep. See PibblPhysicsShape2D.
from — Initial shape pose. See PibblPhysicsPose2D.
translation — Translation vector for the sweep. See PibblPhysicsVector2.
options — Sensor policy and collider filtering. See PibblPhysicsQueryOptions2D.

Returns

Frozen results, empty when no collider matches. See PibblPhysicsQueryHit2D.

View source — packages/core/src/features/physics/2d.ts:178

hasShapeOverlap2D

Tests whether the committed world has any shape overlap match, stopping at the first match.

hasShapeOverlap2D: (world: PibblPhysicsWorldHandle2D, shape: PibblPhysicsShape2D, pose: PibblPhysicsPose2D, options?: PibblPhysicsQueryOptions2D) => boolean

Parameters

world — World to query. See PibblPhysicsWorldHandle2D.
shape — Shape to test. See PibblPhysicsShape2D.
pose — Shape pose. See PibblPhysicsPose2D.
options — Sensor policy and collider filtering. See PibblPhysicsQueryOptions2D.

Returns

Whether a matching collider exists.

View source — packages/core/src/features/physics/2d.ts:197

findShapeOverlap2D

Returns the first shape overlap result ordered by collider index, then generation, or null.

findShapeOverlap2D: (world: PibblPhysicsWorldHandle2D, shape: PibblPhysicsShape2D, pose: PibblPhysicsPose2D, options?: PibblPhysicsQueryOptions2D) => PibblPhysicsQueryMatch2D | null

Parameters

world — World to query. See PibblPhysicsWorldHandle2D.
shape — Shape to test. See PibblPhysicsShape2D.
pose — Shape pose. See PibblPhysicsPose2D.
options — Sensor policy and collider filtering. See PibblPhysicsQueryOptions2D.

Returns

One result or null. See PibblPhysicsQueryMatch2D.

View source — packages/core/src/features/physics/2d.ts:215

findAllShapeOverlaps2D

Returns all shape overlap results ordered by collider index, then generation as a frozen array.

findAllShapeOverlaps2D: (world: PibblPhysicsWorldHandle2D, shape: PibblPhysicsShape2D, pose: PibblPhysicsPose2D, options?: PibblPhysicsQueryOptions2D) => readonly PibblPhysicsQueryMatch2D[]

Parameters

world — World to query. See PibblPhysicsWorldHandle2D.
shape — Shape to test. See PibblPhysicsShape2D.
pose — Shape pose. See PibblPhysicsPose2D.
options — Sensor policy and collider filtering. See PibblPhysicsQueryOptions2D.

Returns

Frozen results, empty when no collider matches. See PibblPhysicsQueryMatch2D.

View source — packages/core/src/features/physics/2d.ts:233

hasAabbMatch2D

Tests whether the committed world has any bounds intersection match, stopping at the first match.

hasAabbMatch2D: (world: PibblPhysicsWorldHandle2D, bounds: PibblPhysicsAabb2D, options?: PibblPhysicsQueryOptions2D) => boolean

Parameters

world — World to query. See PibblPhysicsWorldHandle2D.
bounds — Axis-aligned query bounds. See PibblPhysicsAabb2D.
options — Sensor policy and collider filtering. See PibblPhysicsQueryOptions2D.

Returns

Whether a matching collider exists.

View source — packages/core/src/features/physics/2d.ts:250

findAabbMatch2D

Returns the first bounds intersection result ordered by collider index, then generation, or null.

findAabbMatch2D: (world: PibblPhysicsWorldHandle2D, bounds: PibblPhysicsAabb2D, options?: PibblPhysicsQueryOptions2D) => PibblPhysicsQueryMatch2D | null

Parameters

world — World to query. See PibblPhysicsWorldHandle2D.
bounds — Axis-aligned query bounds. See PibblPhysicsAabb2D.
options — Sensor policy and collider filtering. See PibblPhysicsQueryOptions2D.

Returns

One result or null. See PibblPhysicsQueryMatch2D.

View source — packages/core/src/features/physics/2d.ts:266

findAllAabbMatches2D

Returns all bounds intersection results ordered by collider index, then generation as a frozen array.

findAllAabbMatches2D: (world: PibblPhysicsWorldHandle2D, bounds: PibblPhysicsAabb2D, options?: PibblPhysicsQueryOptions2D) => readonly PibblPhysicsQueryMatch2D[]

Parameters

world — World to query. See PibblPhysicsWorldHandle2D.
bounds — Axis-aligned query bounds. See PibblPhysicsAabb2D.
options — Sensor policy and collider filtering. See PibblPhysicsQueryOptions2D.

Returns

Frozen results, empty when no collider matches. See PibblPhysicsQueryMatch2D.

View source — packages/core/src/features/physics/2d.ts:282

hasPointMatch2D

Tests whether the committed world has any point containment match, stopping at the first match.

hasPointMatch2D: (world: PibblPhysicsWorldHandle2D, point: PibblPhysicsVector2, options?: PibblPhysicsQueryOptions2D) => boolean

Parameters

world — World to query. See PibblPhysicsWorldHandle2D.
point — Point in simulation coordinates. See PibblPhysicsVector2.
options — Sensor policy and collider filtering. See PibblPhysicsQueryOptions2D.

Returns

Whether a matching collider exists.

View source — packages/core/src/features/physics/2d.ts:298

findPointMatch2D

Returns the first point containment result ordered by collider index, then generation, or null.

findPointMatch2D: (world: PibblPhysicsWorldHandle2D, point: PibblPhysicsVector2, options?: PibblPhysicsQueryOptions2D) => PibblPhysicsQueryMatch2D | null

Parameters

world — World to query. See PibblPhysicsWorldHandle2D.
point — Point in simulation coordinates. See PibblPhysicsVector2.
options — Sensor policy and collider filtering. See PibblPhysicsQueryOptions2D.

Returns

One result or null. See PibblPhysicsQueryMatch2D.

View source — packages/core/src/features/physics/2d.ts:314

findAllPointMatches2D

Returns all point containment results ordered by collider index, then generation as a frozen array.

findAllPointMatches2D: (world: PibblPhysicsWorldHandle2D, point: PibblPhysicsVector2, options?: PibblPhysicsQueryOptions2D) => readonly PibblPhysicsQueryMatch2D[]

Parameters

world — World to query. See PibblPhysicsWorldHandle2D.
point — Point in simulation coordinates. See PibblPhysicsVector2.
options — Sensor policy and collider filtering. See PibblPhysicsQueryOptions2D.

Returns

Frozen results, empty when no collider matches. See PibblPhysicsQueryMatch2D.

View source — packages/core/src/features/physics/2d.ts:330

toPhysicsPoint2D

Converts root-logical pointer coordinates to this world’s simulation space.

toPhysicsPoint2D: (world: PibblPhysicsWorldHandle2D, point: PibblPhysicsVector2) => PibblPhysicsVector2

Parameters

world — World providing unit and coordinate conversion. See PibblPhysicsWorldHandle2D .
point — Point in public Canvas coordinates. See PibblPhysicsVector2.

Returns

The equivalent point in this world’s local simulation space. See PibblPhysicsVector2 .

fromPhysicsPoint2D

Converts a simulation-space point to root-logical Canvas coordinates.

fromPhysicsPoint2D: (world: PibblPhysicsWorldHandle2D, point: PibblPhysicsVector2) => PibblPhysicsVector2

Parameters

world — World providing unit and coordinate conversion. See PibblPhysicsWorldHandle2D .
point — Point in this world’s local simulation space. See PibblPhysicsVector2.

Returns

The equivalent point in public Canvas coordinates. See PibblPhysicsVector2.

inspectPhysics2D

Returns immutable JSON-safe observations without advancing the simulation. See PibblPhysicsWorldHandle2D. Returns the immutable observation for this currently bound body, if any. See PibblPhysicsBodyHandle2D. Returns a diagnostic snapshot of a live world or body, or undefined when unavailable.

inspectPhysics2D: { (world: PibblPhysicsWorldHandle2D): PibblPhysicsInspection2D; (body: PibblPhysicsBodyHandle2D): PibblPhysicsBodyInspection2D | undefined; }

Parameters

world — World to inspect. See PibblPhysicsWorldHandle2D.
body — Body to inspect. See PibblPhysicsBodyHandle2D.
target — World or body handle to inspect. See PibblPhysicsWorldHandle2D , PibblPhysicsBodyHandle2D .

Returns

Current world simulation and ownership diagnostics.

Current body diagnostics, or undefined when the handle has no live body.

The corresponding diagnostics, or undefined for an unmounted body.

PhysicsDebug2D

Read-only authoritative bounds, mass centers and contact normals; no hit targets.

PhysicsDebug2D: PibblPrimitiveComponent<PibblPhysicsDebug2DProps, PrimitiveInput<PibblPhysicsDebug2DProps, SystemStyle>>

Parameters

props — Authored component inputs, supplied through JSX or createElement. See the linked props and style types.

Throws

When called directly; Pibbl mounts this component through JSX or createElement.

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

Physics drawing components: Draw four physics shapes and move a custom kinematic collider. Plain source
Live physics world: Mount a falling ball, inspect it, and control its body with buttons. Plain source
Path-like shapes: Create curved, stroked, and polygonal shapes and transform them. Plain source
Shape measurements: Compare bounds, area, and mass for four common 2D shapes. Plain source
Geometry queries: Check point containment, separation, overlap, contact, and casts. Plain source
World queries: Query a static collider by ray, moving shape, overlap, point, and bounds. Plain source

Interactive examples

Documentation version

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

2D physics functions and components

World and Canvas primitives

PhysicsWorld2D

pibblPhysicsWorld2D

PhysicsShape2D, Capsule2D, Segment2D, and Chain2D

PhysicsDebug2D

withPhysicsShape2D

Descriptor and handle factories

Commands

Mounted-world queries and observation

Pure shapes and geometry

Fixed query return contracts

API details from source

arcShape2D

Parameters

Returns

See also

boundsOfShape2D

Parameters

Returns

See also

boxShape2D

Parameters

Returns

See also

capsuleShape2D

Parameters

Returns

See also

chainShape2D

Parameters

Returns

See also

circleShape2D

Parameters

Returns

See also

ellipseShape2D

Parameters

Returns

See also

massProperties2D

Parameters

Returns

See also

polygonShape2D

Parameters

Returns

See also

roundedBoxShape2D

Parameters

Returns

See also

segmentShape2D

Parameters

Returns

See also

transformShape2D

Parameters

Returns

See also

wedgeShape2D

Parameters

Returns

See also

containsPoint2D

Parameters

Returns

See also

distanceBetweenShapes2D

Parameters

Returns

See also

overlapShapes2D

Parameters

Returns

See also

contactBetweenShapes2D

Parameters

Returns

`PhysicsWorld2D`

`pibblPhysicsWorld2D`

`PhysicsShape2D`, `Capsule2D`, `Segment2D`, and `Chain2D`

`PhysicsDebug2D`

`withPhysicsShape2D`