packages/core/src/features/physics/2d-geometry.ts

Read as Markdown

This is the source snapshot used to build these API details. View this revision on GitHub.

Back to reference

1 import type { boundsOfShape2D, massProperties2D, transformShape2D } from './lib/2d/shapes.js';
2 import type { findAabbMatch2D, raycastClosest2D } from './2d.js';
3 import type { raycastShape2D, shapeCastAgainstShape2D } from './lib/2d/collision/casts.js';
4 import type { PibblPhysicsCollisionEvent2D, PibblPhysicsQueryHit2D } from './lib/2d/types.js';
5 import type { PibblPhysicsContactInspection2D } from './lib/2d/inspection-types.js';
6 /**
7  * An x/y pair in the 2D physics coordinate system.
8  *
9  * @see {@link PibblPhysicsPose2D}
10  * @see {@link PibblPhysicsAabb2D}
11  * @see {@link PibblPhysicsRay2D}
12  */
13 export type PibblPhysicsVector2 = readonly [x: number, y: number];
14 
15 /**
16  * Position and rotation in degrees for a 2D shape or body.
17  *
18  * @see {@link PibblPhysicsVector2}
19  * @see {@link PibblPhysicsTransform2D}
20  * @see {@link containsPoint2D}
21  */
22 export interface PibblPhysicsPose2D {
23   /** Position of the geometry, source, or selected resize handle. See {@link PibblPhysicsVector2}. */
24   readonly position: PibblPhysicsVector2;
25   /** Rotation in degrees. See {@link PibblPhysicsPose2D}. */
26   readonly rotationDegrees: number;
27 }
28 
29 /**
30  * A rigid 2D transform expressed as position and rotation in degrees.
31  *
32  * @see {@link PibblPhysicsPose2D}
33  * @see {@link transformShape2D}
34  */
35 export type PibblPhysicsTransform2D = PibblPhysicsPose2D;
36 
37 /**
38  * Axis-aligned bounds expressed as minimum and maximum coordinates.
39  *
40  * @see {@link PibblPhysicsVector2}
41  * @see {@link boundsOfShape2D}
42  * @see {@link findAabbMatch2D}
43  */
44 export interface PibblPhysicsAabb2D {
45   /** Lower bound of the coordinate or sampling interval. See {@link PibblPhysicsVector2}. */
46   readonly min: PibblPhysicsVector2;
47   /** Upper bound of the coordinate or sampling interval. See {@link PibblPhysicsVector2}. */
48   readonly max: PibblPhysicsVector2;
49 }
50 
51 /**
52  * Origin, direction, and maximum travel distance of a 2D query ray.
53  *
54  * @see {@link PibblPhysicsVector2}
55  * @see {@link raycastShape2D}
56  * @see {@link raycastClosest2D}
57  */
58 export interface PibblPhysicsRay2D {
59   /** Origin of the transform or geometric query. See {@link PibblPhysicsVector2}. */
60   readonly origin: PibblPhysicsVector2;
61   /** Direction in which this operation proceeds. See {@link PibblPhysicsVector2}. */
62   readonly direction: PibblPhysicsVector2;
63   /** Maximum distance accepted by the query. See {@link PibblPhysicsRay2D}. */
64   readonly maxDistance: number;
65 }
66 
67 declare const physicsShape2DBrand: unique symbol;
68 /**
69  * An immutable branded shape created by the public 2D geometry constructors.
70  *
71  * @see {@link containsPoint2D}
72  * @see {@link distanceBetweenShapes2D}
73  * @see {@link overlapShapes2D}
74  */
75 export interface PibblPhysicsShape2D {
76   readonly [physicsShape2DBrand]: true;
77 }
78 
79 /**
80  * Area, centroid, mass, and rotational inertia derived from a shape and density.
81  *
82  * @see {@link PibblPhysicsVector2}
83  * @see {@link massProperties2D}
84  */
85 export interface PibblPhysicsMassProperties2D {
86   /** Area enclosed by the shape. See {@link PibblPhysicsMassProperties2D}. */
87   readonly area: number;
88   /** Area-weighted center of the shape. See {@link PibblPhysicsVector2}. */
89   readonly centroid: PibblPhysicsVector2;
90   /** Mass used by the spring or physics calculation. See {@link PibblPhysicsMassProperties2D}. */
91   readonly mass: number;
92   /** Moment of inertia about the shape's center of mass. See {@link PibblPhysicsMassProperties2D}. */
93   readonly rotationalInertia: number;
94 }
95 
96 /**
97  * Signed separation, witness points, and normal between two posed shapes.
98  *
99  * @see {@link PibblPhysicsVector2}
100  * @see {@link distanceBetweenShapes2D}
101  */
102 export interface PibblPhysicsDistance2D {
103   /** Signed distance between the witness points. See {@link PibblPhysicsDistance2D}. */
104   readonly separation: number;
105   /** Witness point on the first shape. See {@link PibblPhysicsVector2}. */
106   readonly pointOnFirst: PibblPhysicsVector2;
107   /** Witness point on the second shape. See {@link PibblPhysicsVector2}. */
108   readonly pointOnSecond: PibblPhysicsVector2;
109   /** Direction from the second shape toward the first. */
110   readonly normal: PibblPhysicsVector2;
111 }
112 
113 /**
114  * A pair of contact witness points and their signed separation.
115  *
116  * @see {@link PibblPhysicsVector2}
117  * @see {@link PibblPhysicsShapeContact2D}
118  * @see {@link PibblPhysicsCollisionEvent2D}
119  * @see {@link PibblPhysicsContactInspection2D}
120  */
121 export interface PibblPhysicsContactPoint2D {
122   /** Witness point on the first shape. See {@link PibblPhysicsVector2}. */
123   readonly pointOnFirst: PibblPhysicsVector2;
124   /** Witness point on the second shape. See {@link PibblPhysicsVector2}. */
125   readonly pointOnSecond: PibblPhysicsVector2;
126   /** Signed distance between the witness points. See {@link PibblPhysicsContactPoint2D}. */
127   readonly separation: number;
128 }
129 
130 /**
131  * Contact normal and witness-point pairs for two overlapping or touching shapes.
132  *
133  * @see {@link PibblPhysicsVector2}
134  * @see {@link PibblPhysicsContactPoint2D}
135  * @see {@link contactBetweenShapes2D}
136  */
137 export interface PibblPhysicsShapeContact2D {
138   /** Direction from the second shape toward the first. */
139   readonly normal: PibblPhysicsVector2;
140   /**
141    * Points defining the geometry or reported by the contact query. See
142    * {@link PibblPhysicsContactPoint2D}.
143    */
144   readonly points: readonly PibblPhysicsContactPoint2D[];
145 }
146 
147 /**
148  * Point, normal, distance, and time of impact returned by a geometry cast.
149  *
150  * @see {@link PibblPhysicsVector2}
151  * @see {@link raycastShape2D}
152  * @see {@link shapeCastAgainstShape2D}
153  * @see {@link PibblPhysicsQueryHit2D}
154  */
155 export interface PibblPhysicsShapeHit2D {
156   /** A point in the operation's coordinate system. See {@link PibblPhysicsVector2}. */
157   readonly point: PibblPhysicsVector2;
158   /** Contact or surface normal returned by this query. See {@link PibblPhysicsVector2}. */
159   readonly normal: PibblPhysicsVector2;
160   /**
161    * Distance measured in this query or guide's coordinate system. See {@link PibblPhysicsShapeHit2D}
162    * .
163    */
164   readonly distance: number;
165   /** Position along the cast at which contact first occurs. See {@link PibblPhysicsShapeHit2D}. */
166   readonly timeOfImpact: number;
167 }
168 
169 export {
170   arcShape2D,
171   boundsOfShape2D,
172   boxShape2D,
173   capsuleShape2D,
174   chainShape2D,
175   circleShape2D,
176   ellipseShape2D,
177   massProperties2D,
178   polygonShape2D,
179   roundedBoxShape2D,
180   segmentShape2D,
181   transformShape2D,
182   wedgeShape2D,
183 } from './lib/2d/shapes.js';
184 
185 import {
186   contactBetweenPreparedShapes2D,
187   containsPointInShape2D,
188   distanceBetweenPreparedShapes2D,
189   overlapPreparedShapes2D,
190 } from './lib/2d/collision/pairs.js';
191 export {
192   raycastShape2D,
193   shapeCastAgainstShape2D,
194 } from './lib/2d/collision/casts.js';
195 
196 /**
197  * Tests whether a point lies within a posed shape without creating a physics world.
198  *
199  * @param shape - Shape to test. See {@link PibblPhysicsShape2D}.
200  * @param pose - Shape pose. See {@link PibblPhysicsPose2D}.
201  * @param point - Point in the same coordinate space as the posed shape. See
202  * {@link PibblPhysicsVector2} .
203  * @returns Whether the posed shape contains the point.
204  *
205  * @see {@link PibblPhysicsShape2D}
206  * @see {@link PibblPhysicsPose2D}
207  * @see {@link PibblPhysicsVector2}
208  */
209 export function containsPoint2D(
210   shape: PibblPhysicsShape2D,
211   pose: PibblPhysicsPose2D,
212   point: PibblPhysicsVector2,
213 ): boolean {
214   return containsPointInShape2D(shape, pose, point);
215 }
216 
217 /**
218  * Computes signed separation and witness geometry between two posed shapes.
219  *
220  * @param first - First shape. See {@link PibblPhysicsShape2D}.
221  * @param firstPose - Pose of the first shape. See {@link PibblPhysicsPose2D}.
222  * @param second - Second shape. See {@link PibblPhysicsShape2D}.
223  * @param secondPose - Pose of the second shape. See {@link PibblPhysicsPose2D}.
224  * @returns Distance and closest-point information for the two posed shapes. See
225  * {@link PibblPhysicsDistance2D} .
226  *
227  * @see {@link PibblPhysicsShape2D}
228  * @see {@link PibblPhysicsPose2D}
229  * @see {@link PibblPhysicsDistance2D}
230  */
231 export function distanceBetweenShapes2D(
232   first: PibblPhysicsShape2D,
233   firstPose: PibblPhysicsPose2D,
234   second: PibblPhysicsShape2D,
235   secondPose: PibblPhysicsPose2D,
236 ): PibblPhysicsDistance2D {
237   return distanceBetweenPreparedShapes2D(first, firstPose, second, secondPose);
238 }
239 
240 /**
241  * Tests whether two posed shapes overlap without creating a physics world.
242  *
243  * @param first - First shape. See {@link PibblPhysicsShape2D}.
244  * @param firstPose - Pose of the first shape. See {@link PibblPhysicsPose2D}.
245  * @param second - Second shape. See {@link PibblPhysicsShape2D}.
246  * @param secondPose - Pose of the second shape. See {@link PibblPhysicsPose2D}.
247  * @returns Whether the two posed shapes overlap.
248  *
249  * @see {@link PibblPhysicsShape2D}
250  * @see {@link PibblPhysicsPose2D}
251  */
252 export function overlapShapes2D(
253   first: PibblPhysicsShape2D,
254   firstPose: PibblPhysicsPose2D,
255   second: PibblPhysicsShape2D,
256   secondPose: PibblPhysicsPose2D,
257 ): boolean {
258   return overlapPreparedShapes2D(first, firstPose, second, secondPose);
259 }
260 
261 /**
262  * Computes contact geometry for two posed shapes, or null when they do not contact.
263  *
264  * @param first - First shape. See {@link PibblPhysicsShape2D}.
265  * @param firstPose - Pose of the first shape. See {@link PibblPhysicsPose2D}.
266  * @param second - Second shape. See {@link PibblPhysicsShape2D}.
267  * @param secondPose - Pose of the second shape. See {@link PibblPhysicsPose2D}.
268  * @returns Contact information, or null when the shapes do not contact. See
269  * {@link PibblPhysicsShapeContact2D} .
270  *
271  * @see {@link PibblPhysicsShape2D}
272  * @see {@link PibblPhysicsPose2D}
273  * @see {@link PibblPhysicsShapeContact2D}
274  */
275 export function contactBetweenShapes2D(
276   first: PibblPhysicsShape2D,
277   firstPose: PibblPhysicsPose2D,
278   second: PibblPhysicsShape2D,
279   secondPose: PibblPhysicsPose2D,
280 ): PibblPhysicsShapeContact2D | null {
281   return contactBetweenPreparedShapes2D(first, firstPose, second, secondPose);
282 }
283 

Documentation version

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