# packages/core/src/features/physics/2d.ts This is the source snapshot used to build these API details. [View this revision on GitHub](https://github.com/benlesh/pibbl/blob/272a94aaf62e0bd6ad8726a4c607a76a9ec44ca1/packages/core/src/features/physics/2d.ts#L88). [Back to reference](/reference/functions/physics-2d/)
1 import type { PibblPhysicsInspection2D, PibblPhysicsBodyInspection2D } from "./lib/2d/inspection-types.js";
2 import type {
3   PibblPhysicsAabb2D,
4   PibblPhysicsPose2D,
5   PibblPhysicsRay2D,
6   PibblPhysicsShape2D,
7   PibblPhysicsVector2,
8 } from "./2d-geometry.js";
9 import type {
10   PibblPhysicsQueryHit2D,
11   PibblPhysicsQueryMatch2D,
12   PibblPhysicsQueryOptions2D,
13   PibblPhysicsBodyHandle2D,
14   PibblPhysicsWorldHandle2D,
15 } from "./lib/2d/types.js";
16 import {
17   collider2D,
18   dynamicBody2D,
19   kinematicBody2D,
20   staticBody2D,
21 } from "./lib/2d/runtime/descriptors.js";
22 import {
23   PhysicsWorld2D,
24   pibblPhysicsWorld2D,
25 } from "./lib/2d/runtime/world-component.js";
26 import {
27   Capsule2D,
28   Chain2D,
29   PhysicsShape2D,
30   Segment2D,
31 } from "./lib/2d/canvas/components.js";
32 import { withPhysicsShape2D } from "./lib/2d/canvas/custom.js";
33 import {
34   applyForce2D,
35   applyImpulse2D,
36   applyTorque2D,
37   pibblPhysicsBody2D,
38   disableBody2D,
39   enableBody2D,
40   isPhysicsBodyHandle2D,
41   physicsBodyHandleBinding2D,
42   setAngularVelocity2D,
43   setLinearVelocity2D,
44   sleepBody2D,
45   teleportBody2D,
46   wakeBody2D,
47 } from "./lib/2d/runtime/body-handle.js";
48 import { requirePhysicsWorld2DController } from "./lib/2d/runtime/controller.js";
49 
50 export * from "./2d-geometry.js";
51 export {
52   raycastShape2D,
53   shapeCastAgainstShape2D,
54 } from "./lib/2d/collision/casts.js";
55 export * from "./lib/2d/types.js";
56 
57 export { PhysicsWorld2D };
58 export { PhysicsShape2D, Capsule2D, Segment2D, Chain2D };
59 
60 export { collider2D, dynamicBody2D, kinematicBody2D, staticBody2D };
61 export { withPhysicsShape2D };
62 
63 export { pibblPhysicsBody2D };
64 
65 export { pibblPhysicsWorld2D };
66 
67 export {
68   applyForce2D,
69   applyImpulse2D,
70   applyTorque2D,
71   disableBody2D,
72   enableBody2D,
73   setAngularVelocity2D,
74   setLinearVelocity2D,
75   sleepBody2D,
76   teleportBody2D,
77   wakeBody2D,
78 };
79 
80 /**
81  * Tests whether the committed world has any ray match, stopping at the first match.
82  *
83  * @param world - World to query. See {@link PibblPhysicsWorldHandle2D}.
84  * @param ray - Ray origin, direction, and travel limit. See {@link PibblPhysicsRay2D}.
85  * @param options - Sensor policy and collider filtering. See {@link PibblPhysicsQueryOptions2D}.
86  * @returns Whether a matching collider exists.
87  */
88 export function raycastAny2D(
89   world: PibblPhysicsWorldHandle2D,
90   ray: PibblPhysicsRay2D,
91   options?: PibblPhysicsQueryOptions2D,
92 ): boolean {
93   return requirePhysicsWorld2DController(world).raycast(ray, { ...options, mode: "any" });
94 }
95 
96 /**
97  * Returns the first ray result ordered by time of impact, distance, then collider identity, or null.
98  *
99  * @param world - World to query. See {@link PibblPhysicsWorldHandle2D}.
100  * @param ray - Ray origin, direction, and travel limit. See {@link PibblPhysicsRay2D}.
101  * @param options - Sensor policy and collider filtering. See {@link PibblPhysicsQueryOptions2D}.
102  * @returns One result or null. See {@link PibblPhysicsQueryHit2D}.
103  */
104 export function raycastClosest2D(
105   world: PibblPhysicsWorldHandle2D,
106   ray: PibblPhysicsRay2D,
107   options?: PibblPhysicsQueryOptions2D,
108 ): PibblPhysicsQueryHit2D | null {
109   return requirePhysicsWorld2DController(world).raycast(ray, { ...options, mode: "closest" });
110 }
111 
112 /**
113  * Returns all ray results ordered by time of impact, distance, then collider identity as a frozen array.
114  *
115  * @param world - World to query. See {@link PibblPhysicsWorldHandle2D}.
116  * @param ray - Ray origin, direction, and travel limit. See {@link PibblPhysicsRay2D}.
117  * @param options - Sensor policy and collider filtering. See {@link PibblPhysicsQueryOptions2D}.
118  * @returns Frozen results, empty when no collider matches. See {@link PibblPhysicsQueryHit2D}.
119  */
120 export function raycastAll2D(
121   world: PibblPhysicsWorldHandle2D,
122   ray: PibblPhysicsRay2D,
123   options?: PibblPhysicsQueryOptions2D,
124 ): readonly PibblPhysicsQueryHit2D[] {
125   return requirePhysicsWorld2DController(world).raycast(ray, { ...options, mode: "all" });
126 }
127 
128 /**
129  * Tests whether the committed world has any shape sweep match, stopping at the first match.
130  *
131  * @param world - World to query. See {@link PibblPhysicsWorldHandle2D}.
132  * @param shape - Shape to sweep. See {@link PibblPhysicsShape2D}.
133  * @param from - Initial shape pose. See {@link PibblPhysicsPose2D}.
134  * @param translation - Translation vector for the sweep. See {@link PibblPhysicsVector2}.
135  * @param options - Sensor policy and collider filtering. See {@link PibblPhysicsQueryOptions2D}.
136  * @returns Whether a matching collider exists.
137  */
138 export function shapeCastAny2D(
139   world: PibblPhysicsWorldHandle2D,
140   shape: PibblPhysicsShape2D,
141   from: PibblPhysicsPose2D,
142   translation: PibblPhysicsVector2,
143   options?: PibblPhysicsQueryOptions2D,
144 ): boolean {
145   return requirePhysicsWorld2DController(world).shapeCast(shape, from, translation, { ...options, mode: "any" });
146 }
147 
148 /**
149  * Returns the first shape sweep result ordered by time of impact, distance, then collider identity, or null.
150  *
151  * @param world - World to query. See {@link PibblPhysicsWorldHandle2D}.
152  * @param shape - Shape to sweep. See {@link PibblPhysicsShape2D}.
153  * @param from - Initial shape pose. See {@link PibblPhysicsPose2D}.
154  * @param translation - Translation vector for the sweep. See {@link PibblPhysicsVector2}.
155  * @param options - Sensor policy and collider filtering. See {@link PibblPhysicsQueryOptions2D}.
156  * @returns One result or null. See {@link PibblPhysicsQueryHit2D}.
157  */
158 export function shapeCastClosest2D(
159   world: PibblPhysicsWorldHandle2D,
160   shape: PibblPhysicsShape2D,
161   from: PibblPhysicsPose2D,
162   translation: PibblPhysicsVector2,
163   options?: PibblPhysicsQueryOptions2D,
164 ): PibblPhysicsQueryHit2D | null {
165   return requirePhysicsWorld2DController(world).shapeCast(shape, from, translation, { ...options, mode: "closest" });
166 }
167 
168 /**
169  * Returns all shape sweep results ordered by time of impact, distance, then collider identity as a frozen array.
170  *
171  * @param world - World to query. See {@link PibblPhysicsWorldHandle2D}.
172  * @param shape - Shape to sweep. See {@link PibblPhysicsShape2D}.
173  * @param from - Initial shape pose. See {@link PibblPhysicsPose2D}.
174  * @param translation - Translation vector for the sweep. See {@link PibblPhysicsVector2}.
175  * @param options - Sensor policy and collider filtering. See {@link PibblPhysicsQueryOptions2D}.
176  * @returns Frozen results, empty when no collider matches. See {@link PibblPhysicsQueryHit2D}.
177  */
178 export function shapeCastAll2D(
179   world: PibblPhysicsWorldHandle2D,
180   shape: PibblPhysicsShape2D,
181   from: PibblPhysicsPose2D,
182   translation: PibblPhysicsVector2,
183   options?: PibblPhysicsQueryOptions2D,
184 ): readonly PibblPhysicsQueryHit2D[] {
185   return requirePhysicsWorld2DController(world).shapeCast(shape, from, translation, { ...options, mode: "all" });
186 }
187 
188 /**
189  * Tests whether the committed world has any shape overlap match, stopping at the first match.
190  *
191  * @param world - World to query. See {@link PibblPhysicsWorldHandle2D}.
192  * @param shape - Shape to test. See {@link PibblPhysicsShape2D}.
193  * @param pose - Shape pose. See {@link PibblPhysicsPose2D}.
194  * @param options - Sensor policy and collider filtering. See {@link PibblPhysicsQueryOptions2D}.
195  * @returns Whether a matching collider exists.
196  */
197 export function hasShapeOverlap2D(
198   world: PibblPhysicsWorldHandle2D,
199   shape: PibblPhysicsShape2D,
200   pose: PibblPhysicsPose2D,
201   options?: PibblPhysicsQueryOptions2D,
202 ): boolean {
203   return requirePhysicsWorld2DController(world).overlapShape(shape, pose, { ...options, mode: "any" });
204 }
205 
206 /**
207  * Returns the first shape overlap result ordered by collider index, then generation, or null.
208  *
209  * @param world - World to query. See {@link PibblPhysicsWorldHandle2D}.
210  * @param shape - Shape to test. See {@link PibblPhysicsShape2D}.
211  * @param pose - Shape pose. See {@link PibblPhysicsPose2D}.
212  * @param options - Sensor policy and collider filtering. See {@link PibblPhysicsQueryOptions2D}.
213  * @returns One result or null. See {@link PibblPhysicsQueryMatch2D}.
214  */
215 export function findShapeOverlap2D(
216   world: PibblPhysicsWorldHandle2D,
217   shape: PibblPhysicsShape2D,
218   pose: PibblPhysicsPose2D,
219   options?: PibblPhysicsQueryOptions2D,
220 ): PibblPhysicsQueryMatch2D | null {
221   return requirePhysicsWorld2DController(world).overlapShape(shape, pose, { ...options, mode: "closest" });
222 }
223 
224 /**
225  * Returns all shape overlap results ordered by collider index, then generation as a frozen array.
226  *
227  * @param world - World to query. See {@link PibblPhysicsWorldHandle2D}.
228  * @param shape - Shape to test. See {@link PibblPhysicsShape2D}.
229  * @param pose - Shape pose. See {@link PibblPhysicsPose2D}.
230  * @param options - Sensor policy and collider filtering. See {@link PibblPhysicsQueryOptions2D}.
231  * @returns Frozen results, empty when no collider matches. See {@link PibblPhysicsQueryMatch2D}.
232  */
233 export function findAllShapeOverlaps2D(
234   world: PibblPhysicsWorldHandle2D,
235   shape: PibblPhysicsShape2D,
236   pose: PibblPhysicsPose2D,
237   options?: PibblPhysicsQueryOptions2D,
238 ): readonly PibblPhysicsQueryMatch2D[] {
239   return requirePhysicsWorld2DController(world).overlapShape(shape, pose, { ...options, mode: "all" });
240 }
241 
242 /**
243  * Tests whether the committed world has any bounds intersection match, stopping at the first match.
244  *
245  * @param world - World to query. See {@link PibblPhysicsWorldHandle2D}.
246  * @param bounds - Axis-aligned query bounds. See {@link PibblPhysicsAabb2D}.
247  * @param options - Sensor policy and collider filtering. See {@link PibblPhysicsQueryOptions2D}.
248  * @returns Whether a matching collider exists.
249  */
250 export function hasAabbMatch2D(
251   world: PibblPhysicsWorldHandle2D,
252   bounds: PibblPhysicsAabb2D,
253   options?: PibblPhysicsQueryOptions2D,
254 ): boolean {
255   return requirePhysicsWorld2DController(world).queryAabb(bounds, { ...options, mode: "any" });
256 }
257 
258 /**
259  * Returns the first bounds intersection result ordered by collider index, then generation, or null.
260  *
261  * @param world - World to query. See {@link PibblPhysicsWorldHandle2D}.
262  * @param bounds - Axis-aligned query bounds. See {@link PibblPhysicsAabb2D}.
263  * @param options - Sensor policy and collider filtering. See {@link PibblPhysicsQueryOptions2D}.
264  * @returns One result or null. See {@link PibblPhysicsQueryMatch2D}.
265  */
266 export function findAabbMatch2D(
267   world: PibblPhysicsWorldHandle2D,
268   bounds: PibblPhysicsAabb2D,
269   options?: PibblPhysicsQueryOptions2D,
270 ): PibblPhysicsQueryMatch2D | null {
271   return requirePhysicsWorld2DController(world).queryAabb(bounds, { ...options, mode: "closest" });
272 }
273 
274 /**
275  * Returns all bounds intersection results ordered by collider index, then generation as a frozen array.
276  *
277  * @param world - World to query. See {@link PibblPhysicsWorldHandle2D}.
278  * @param bounds - Axis-aligned query bounds. See {@link PibblPhysicsAabb2D}.
279  * @param options - Sensor policy and collider filtering. See {@link PibblPhysicsQueryOptions2D}.
280  * @returns Frozen results, empty when no collider matches. See {@link PibblPhysicsQueryMatch2D}.
281  */
282 export function findAllAabbMatches2D(
283   world: PibblPhysicsWorldHandle2D,
284   bounds: PibblPhysicsAabb2D,
285   options?: PibblPhysicsQueryOptions2D,
286 ): readonly PibblPhysicsQueryMatch2D[] {
287   return requirePhysicsWorld2DController(world).queryAabb(bounds, { ...options, mode: "all" });
288 }
289 
290 /**
291  * Tests whether the committed world has any point containment match, stopping at the first match.
292  *
293  * @param world - World to query. See {@link PibblPhysicsWorldHandle2D}.
294  * @param point - Point in simulation coordinates. See {@link PibblPhysicsVector2}.
295  * @param options - Sensor policy and collider filtering. See {@link PibblPhysicsQueryOptions2D}.
296  * @returns Whether a matching collider exists.
297  */
298 export function hasPointMatch2D(
299   world: PibblPhysicsWorldHandle2D,
300   point: PibblPhysicsVector2,
301   options?: PibblPhysicsQueryOptions2D,
302 ): boolean {
303   return requirePhysicsWorld2DController(world).queryPoint(point, { ...options, mode: "any" });
304 }
305 
306 /**
307  * Returns the first point containment result ordered by collider index, then generation, or null.
308  *
309  * @param world - World to query. See {@link PibblPhysicsWorldHandle2D}.
310  * @param point - Point in simulation coordinates. See {@link PibblPhysicsVector2}.
311  * @param options - Sensor policy and collider filtering. See {@link PibblPhysicsQueryOptions2D}.
312  * @returns One result or null. See {@link PibblPhysicsQueryMatch2D}.
313  */
314 export function findPointMatch2D(
315   world: PibblPhysicsWorldHandle2D,
316   point: PibblPhysicsVector2,
317   options?: PibblPhysicsQueryOptions2D,
318 ): PibblPhysicsQueryMatch2D | null {
319   return requirePhysicsWorld2DController(world).queryPoint(point, { ...options, mode: "closest" });
320 }
321 
322 /**
323  * Returns all point containment results ordered by collider index, then generation as a frozen array.
324  *
325  * @param world - World to query. See {@link PibblPhysicsWorldHandle2D}.
326  * @param point - Point in simulation coordinates. See {@link PibblPhysicsVector2}.
327  * @param options - Sensor policy and collider filtering. See {@link PibblPhysicsQueryOptions2D}.
328  * @returns Frozen results, empty when no collider matches. See {@link PibblPhysicsQueryMatch2D}.
329  */
330 export function findAllPointMatches2D(
331   world: PibblPhysicsWorldHandle2D,
332   point: PibblPhysicsVector2,
333   options?: PibblPhysicsQueryOptions2D,
334 ): readonly PibblPhysicsQueryMatch2D[] {
335   return requirePhysicsWorld2DController(world).queryPoint(point, { ...options, mode: "all" });
336 }
337 
338 /**
339  * Converts root-logical pointer coordinates to this world's simulation space.
340  *
341  * @param world - World providing unit and coordinate conversion. See
342  * {@link PibblPhysicsWorldHandle2D} .
343  * @param point - Point in public Canvas coordinates. See {@link PibblPhysicsVector2}.
344  * @returns The equivalent point in this world's local simulation space. See
345  * {@link PibblPhysicsVector2} .
346  *
347  * @see {@link PibblPhysicsWorldHandle2D}
348  * @see {@link PibblPhysicsVector2}
349  */
350 export function toPhysicsPoint2D(
351   world: PibblPhysicsWorldHandle2D,
352   point: PibblPhysicsVector2,
353 ): PibblPhysicsVector2 {
354   return requirePhysicsWorld2DController(world).convertPoint(point, false);
355 }
356 
357 /**
358  * Converts a simulation-space point to root-logical Canvas coordinates.
359  *
360  * @param world - World providing unit and coordinate conversion. See
361  * {@link PibblPhysicsWorldHandle2D} .
362  * @param point - Point in this world's local simulation space. See {@link PibblPhysicsVector2}.
363  * @returns The equivalent point in public Canvas coordinates. See {@link PibblPhysicsVector2}.
364  *
365  * @see {@link PibblPhysicsWorldHandle2D}
366  * @see {@link PibblPhysicsVector2}
367  */
368 export function fromPhysicsPoint2D(
369   world: PibblPhysicsWorldHandle2D,
370   point: PibblPhysicsVector2,
371 ): PibblPhysicsVector2 {
372   return requirePhysicsWorld2DController(world).convertPoint(point, true);
373 }
374 
375 export type {
376   PibblPhysicsInspection2D,
377   PibblPhysicsBodyInspection2D,
378   PibblPhysicsColliderInspection2D,
379   PibblPhysicsContactInspection2D,
380 } from "./lib/2d/inspection-types.js";
381 
382 /**
383  * Returns immutable JSON-safe observations without advancing the simulation. See
384  * {@link PibblPhysicsWorldHandle2D}.
385  * @param world - World to inspect. See {@link PibblPhysicsWorldHandle2D}.
386  * @returns Current world simulation and ownership diagnostics.
387  */
388 export function inspectPhysics2D(
389   world: PibblPhysicsWorldHandle2D,
390 ): import("./lib/2d/inspection-types.js").PibblPhysicsInspection2D;
391 
392 /**
393  * Returns the immutable observation for this currently bound body, if any. See
394  * {@link PibblPhysicsBodyHandle2D}.
395  * @param body - Body to inspect. See {@link PibblPhysicsBodyHandle2D}.
396  * @returns Current body diagnostics, or undefined when the handle has no live body.
397  */
398 export function inspectPhysics2D(
399   body: PibblPhysicsBodyHandle2D,
400 ): import("./lib/2d/inspection-types.js").PibblPhysicsBodyInspection2D | undefined;
401 /**
402  * Returns a diagnostic snapshot of a live world or body, or undefined when unavailable.
403  *
404  * @param target - World or body handle to inspect. See {@link PibblPhysicsWorldHandle2D} ,
405  * {@link PibblPhysicsBodyHandle2D} .
406  * @returns The corresponding diagnostics, or undefined for an unmounted body.
407  *
408  * @see {@link PibblPhysicsWorldHandle2D}
409  * @see {@link PibblPhysicsBodyHandle2D}
410  * @see {@link PibblPhysicsInspection2D}
411  * @see {@link PibblPhysicsBodyInspection2D}
412  */
413 export function inspectPhysics2D(
414   target: PibblPhysicsWorldHandle2D | PibblPhysicsBodyHandle2D,
415 ):
416   | import("./lib/2d/inspection-types.js").PibblPhysicsInspection2D
417   | import("./lib/2d/inspection-types.js").PibblPhysicsBodyInspection2D
418   | undefined {
419   if (isPhysicsBodyHandle2D(target)) {
420     const binding = physicsBodyHandleBinding2D(target);
421     return binding?.controller.inspectBody(binding.bodyId);
422   }
423   return requirePhysicsWorld2DController(target).inspect();
424 }
425 
426 export {
427   PhysicsDebug2D,
428   type PibblPhysicsDebug2DProps,
429 } from "./lib/2d/canvas/debug.js";
430 
431 /**
432  * A borrowed committed solid batch, structurally compatible with a flow obstacle source.
433  *
434  * @param world - World supplying collider geometry. See {@link PibblPhysicsWorldHandle2D}.
435  * @returns An obstacle source whose read method returns the current revision and packed geometry.
436  *
437  * @see {@link PibblPhysicsWorldHandle2D}
438  */
439 export function physicsObstacles2D(world: PibblPhysicsWorldHandle2D): Readonly<{
440   read(): Readonly<{ revision: number; boxes: Float64Array; ellipses: Float64Array; polygons: Float64Array }>;
441 }> {
442   return requirePhysicsWorld2DController(world).getObstacleSource();
443 }
444
## Documentation version Documentation built with @pibbl/core 0.0.2, revision 272a94a. ALPHA — NOT FOR PRODUCTION USE.