packages/core/src/features/physics/2d.ts
This is the source snapshot used to build these API details. View this revision on GitHub.
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
Section titled “Documentation version”Documentation built with @pibbl/core 0.0.2, revision 272a94a. ALPHA — NOT FOR PRODUCTION USE.