# packages/core/src/features/physics/lib/2d/runtime/body-handle.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/lib/2d/runtime/body-handle.ts#L77). [Back to reference](/reference/functions/physics-2d/)
1 import { signal, type WritableSignal } from "@pibbl/core";
2 import {
3   pibblInternalCurrentSimulationOwner,
4   pibblInternalQueueSimulationBegin,
5   useInternalHookSlot,
6   type PibblInternalSignalBatch,
7   type PibblInternalSimulationOwner,
8 } from "@pibbl/core/internal";
9 import type {
10   PibblPhysicsPose2D,
11   PibblPhysicsVector2,
12 } from "../../../2d-geometry.js";
13 import type { PibblPhysicsBodyHandle2D } from "../types.js";
14 import type { PhysicsBodyCommand2D } from "../world/world.js";
15 import {
16   copyFiniteVector2,
17   requireFiniteNumber,
18 } from "../../shared/validation.js";
19 import type { PhysicsWorld2DController } from "./controller.js";
20 
21 export type PhysicsBodyHandleField2D =
22   | "position"
23   | "rotationDegrees"
24   | "linearVelocity"
25   | "angularVelocityDegreesPerSecond"
26   | "sleeping"
27   | "enabled"
28   | "generation";
29 
30 export interface PhysicsBodyHandleBinding2D {
31   readonly controller: PhysicsWorld2DController;
32   readonly bodyId: number;
33   readonly bindingGeneration: number;
34 }
35 
36 interface PhysicsBodyHandleState2D {
37   readonly owner: PibblInternalSimulationOwner;
38   readonly signals: Partial<{
39     [Field in PhysicsBodyHandleField2D]: WritableSignal<
40       BodyFieldValue2D[Field]
41     >;
42   }>;
43   binding: PhysicsBodyHandleBinding2D | undefined;
44   nextBindingGeneration: number;
45   active: boolean;
46 }
47 
48 interface BodyFieldValue2D {
49   readonly position: PibblPhysicsVector2;
50   readonly rotationDegrees: number;
51   readonly linearVelocity: PibblPhysicsVector2;
52   readonly angularVelocityDegreesPerSecond: number;
53   readonly sleeping: boolean;
54   readonly enabled: boolean;
55   readonly generation: number;
56 }
57 
58 export interface PhysicsBodyHandleValues2D extends BodyFieldValue2D {}
59 
60 const states = new WeakMap<object, PhysicsBodyHandleState2D>();
61 const externalBindings = new WeakMap<
62   object,
63   {
64     binding: PhysicsBodyHandleBinding2D | undefined;
65     nextBindingGeneration: number;
66   }
67 >();
68 
69 /**
70  * Returns one stable, component-owned 2D body endpoint for this hook slot.
71  *
72  * @returns A stable body handle that can be attached to a physics body. See
73  * {@link PibblPhysicsBodyHandle2D} .
74  *
75  * @see {@link PibblPhysicsBodyHandle2D}
76  */
77 export function pibblPhysicsBody2D(): PibblPhysicsBodyHandle2D {
78   const owner = pibblInternalCurrentSimulationOwner();
79   const slot = useInternalHookSlot("physicsBody2DHandle", (teardowns) => {
80     const handle = createPhysicsBodyHandle2D(owner);
81     teardowns.add(() => disposePhysicsBodyHandle2D(handle));
82     return handle;
83   });
84   return slot.value;
85 }
86 
87 /**
88  * Queues a force on a body, optionally at a world point and with wake-up control.
89  *
90  * @param body - Body receiving the force. See {@link PibblPhysicsBodyHandle2D}.
91  * @param force - Force vector in the world's public coordinate system. See
92  * {@link PibblPhysicsVector2} .
93  * @param options - Optional application point and wake policy. See {@link PibblPhysicsVector2}.
94  *
95  * @see {@link PibblPhysicsBodyHandle2D}
96  * @see {@link PibblPhysicsVector2}
97  */
98 export function applyForce2D(
99   body: PibblPhysicsBodyHandle2D,
100   force: PibblPhysicsVector2,
101   options: Readonly<{ at?: PibblPhysicsVector2; wake?: boolean }> = {},
102 ): void {
103   const copied = copyFiniteVector2(force, "force");
104   const point =
105     options.at === undefined
106       ? undefined
107       : copyFiniteVector2(options.at, "options.at");
108   queueBodyCommand(body, {
109     kind: "apply-force",
110     bodyId: 0,
111     forceX: copied[0],
112     forceY: copied[1],
113     pointX: point?.[0],
114     pointY: point?.[1],
115     wake: requireBoolean(options.wake ?? true, "options.wake"),
116   });
117 }
118 
119 /**
120  * Queues an instantaneous momentum change, optionally at a world point and with wake-up control.
121  *
122  * @param body - Body receiving the impulse. See {@link PibblPhysicsBodyHandle2D}.
123  * @param impulse - Impulse vector in the world's public coordinate system. See
124  * {@link PibblPhysicsVector2} .
125  * @param options - Optional application point and wake policy. See {@link PibblPhysicsVector2}.
126  *
127  * @see {@link PibblPhysicsBodyHandle2D}
128  * @see {@link PibblPhysicsVector2}
129  */
130 export function applyImpulse2D(
131   body: PibblPhysicsBodyHandle2D,
132   impulse: PibblPhysicsVector2,
133   options: Readonly<{ at?: PibblPhysicsVector2; wake?: boolean }> = {},
134 ): void {
135   const copied = copyFiniteVector2(impulse, "impulse");
136   const point =
137     options.at === undefined
138       ? undefined
139       : copyFiniteVector2(options.at, "options.at");
140   queueBodyCommand(body, {
141     kind: "apply-impulse",
142     bodyId: 0,
143     impulseX: copied[0],
144     impulseY: copied[1],
145     pointX: point?.[0],
146     pointY: point?.[1],
147     wake: requireBoolean(options.wake ?? true, "options.wake"),
148   });
149 }
150 
151 /**
152  * Queues torque on a dynamic body through the shared scheduler.
153  *
154  * @param body - Body receiving the torque. See {@link PibblPhysicsBodyHandle2D}.
155  * @param torque - Torque to apply in the world's public units.
156  *
157  * @see {@link PibblPhysicsBodyHandle2D}
158  */
159 export function applyTorque2D(
160   body: PibblPhysicsBodyHandle2D,
161   torque: number,
162 ): void {
163   queueBodyCommand(body, {
164     kind: "apply-torque",
165     bodyId: 0,
166     torque: requireFiniteNumber(torque, "torque"),
167   });
168 }
169 
170 /**
171  * Queues a body's linear velocity in physics units per second.
172  *
173  * @param body - Body whose linear velocity changes. See {@link PibblPhysicsBodyHandle2D}.
174  * @param velocity - Velocity vector in public distance units per second. See
175  * {@link PibblPhysicsVector2} .
176  *
177  * @see {@link PibblPhysicsBodyHandle2D}
178  * @see {@link PibblPhysicsVector2}
179  */
180 export function setLinearVelocity2D(
181   body: PibblPhysicsBodyHandle2D,
182   velocity: PibblPhysicsVector2,
183 ): void {
184   const copied = copyFiniteVector2(velocity, "velocity");
185   queueBodyCommand(body, {
186     kind: "set-linear-velocity",
187     bodyId: 0,
188     linearVelocityX: copied[0],
189     linearVelocityY: copied[1],
190   });
191 }
192 
193 /**
194  * Queues a body's angular velocity in degrees per second.
195  *
196  * @param body - Body whose angular velocity changes. See {@link PibblPhysicsBodyHandle2D}.
197  * @param degreesPerSecond - Angular speed in degrees per second.
198  *
199  * @see {@link PibblPhysicsBodyHandle2D}
200  */
201 export function setAngularVelocity2D(
202   body: PibblPhysicsBodyHandle2D,
203   degreesPerSecond: number,
204 ): void {
205   queueBodyCommand(body, {
206     kind: "set-angular-velocity",
207     bodyId: 0,
208     angularVelocityDegrees: requireFiniteNumber(
209       degreesPerSecond,
210       "degreesPerSecond",
211     ),
212   });
213 }
214 
215 /**
216  * Queues an immediate pose change for a body at the next admitted simulation command phase.
217  *
218  * @param body - Body to reposition. See {@link PibblPhysicsBodyHandle2D}.
219  * @param pose - Destination position and rotation in public coordinates. See
220  * {@link PibblPhysicsPose2D} .
221  *
222  * @see {@link PibblPhysicsBodyHandle2D}
223  * @see {@link PibblPhysicsPose2D}
224  */
225 export function teleportBody2D(
226   body: PibblPhysicsBodyHandle2D,
227   pose: PibblPhysicsPose2D,
228 ): void {
229   queueBodyCommand(body, {
230     kind: "set-pose",
231     bodyId: 0,
232     pose: Object.freeze({
233       position: copyFiniteVector2(pose.position, "pose.position"),
234       rotationDegrees: requireFiniteNumber(
235         pose.rotationDegrees,
236         "pose.rotationDegrees",
237       ),
238     }),
239   });
240 }
241 
242 /**
243  * Queues a request to wake a sleeping body.
244  *
245  * @param body - Body to wake. See {@link PibblPhysicsBodyHandle2D}.
246  *
247  * @see {@link PibblPhysicsBodyHandle2D}
248  */
249 export function wakeBody2D(body: PibblPhysicsBodyHandle2D): void {
250   queueBodyCommand(body, { kind: "wake", bodyId: 0 });
251 }
252 
253 /**
254  * Queues a request to put a body to sleep.
255  *
256  * @param body - Body to put to sleep. See {@link PibblPhysicsBodyHandle2D}.
257  *
258  * @see {@link PibblPhysicsBodyHandle2D}
259  */
260 export function sleepBody2D(body: PibblPhysicsBodyHandle2D): void {
261   queueBodyCommand(body, { kind: "sleep", bodyId: 0 });
262 }
263 
264 /**
265  * Queues re-enabling a body with the requested velocity-preservation policy.
266  *
267  * @param body - Body to re-enable. See {@link PibblPhysicsBodyHandle2D}.
268  * @param options - Whether to zero or preserve velocity when enabling.
269  *
270  * @see {@link PibblPhysicsBodyHandle2D}
271  */
272 export function enableBody2D(
273   body: PibblPhysicsBodyHandle2D,
274   options: Readonly<{ velocity?: "zero" | "preserve" }> = {},
275 ): void {
276   const velocity = options.velocity ?? "zero";
277   if (velocity !== "zero" && velocity !== "preserve") {
278     throw new TypeError('options.velocity must be "zero" or "preserve".');
279   }
280   queueBodyCommand(body, { kind: "enable", bodyId: 0, velocity });
281 }
282 
283 /**
284  * Queues removal of a body's active participation in the simulation.
285  *
286  * @param body - Body to disable. See {@link PibblPhysicsBodyHandle2D}.
287  *
288  * @see {@link PibblPhysicsBodyHandle2D}
289  */
290 export function disableBody2D(body: PibblPhysicsBodyHandle2D): void {
291   queueBodyCommand(body, { kind: "disable", bodyId: 0 });
292 }
293 
294 export function createPhysicsBodyHandle2D(
295   owner: PibblInternalSimulationOwner,
296 ): PibblPhysicsBodyHandle2D {
297   const target = {} as Record<PropertyKey, unknown>;
298   const state: PhysicsBodyHandleState2D = {
299     owner,
300     signals: {},
301     binding: undefined,
302     nextBindingGeneration: 0,
303     active: true,
304   };
305   for (const field of BODY_FIELDS_2D) {
306     Object.defineProperty(target, field, {
307       enumerable: true,
308       get: () => materializeSignal(state, field).asReadonly(),
309     });
310   }
311   const handle = Object.freeze(target) as unknown as PibblPhysicsBodyHandle2D;
312   states.set(handle, state);
313   return handle;
314 }
315 
316 export function bindPhysicsBodyHandle2D(
317   handle: PibblPhysicsBodyHandle2D,
318   controller: PhysicsWorld2DController,
319   bodyId: number,
320 ): number {
321   const state = states.get(handle as object);
322   if (state === undefined) {
323     if (typeof handle !== "object" || handle === null) {
324       throw new TypeError("Expected a live Pibbl physics 2D body handle.");
325     }
326     let external = externalBindings.get(handle as object);
327     if (external?.binding !== undefined) {
328       if (
329         external.binding.controller === controller &&
330         external.binding.bodyId === bodyId
331       ) {
332         return external.binding.bindingGeneration;
333       }
334       throw new Error(
335         "A Pibbl physics 2D body handle may bind to at most one live body.",
336       );
337     }
338     external ??= { binding: undefined, nextBindingGeneration: 0 };
339     const bindingGeneration = ++external.nextBindingGeneration;
340     external.binding = Object.freeze({ controller, bodyId, bindingGeneration });
341     externalBindings.set(handle as object, external);
342     return bindingGeneration;
343   }
344   const current = state.binding;
345   if (current !== undefined) {
346     if (current.controller === controller && current.bodyId === bodyId) {
347       return current.bindingGeneration;
348     }
349     throw new Error(
350       "A Pibbl physics 2D body handle may bind to at most one live body.",
351     );
352   }
353   const bindingGeneration = ++state.nextBindingGeneration;
354   state.binding = Object.freeze({ controller, bodyId, bindingGeneration });
355   return bindingGeneration;
356 }
357 
358 export function unbindPhysicsBodyHandle2D(
359   handle: PibblPhysicsBodyHandle2D,
360   controller: PhysicsWorld2DController,
361   bodyId: number,
362   bindingGeneration: number,
363 ): void {
364   const state = states.get(handle as object);
365   if (state === undefined) {
366     const external = externalBindings.get(handle as object);
367     const binding = external?.binding;
368     if (
369       binding?.controller === controller &&
370       binding.bodyId === bodyId &&
371       binding.bindingGeneration === bindingGeneration
372     ) {
373       external!.binding = undefined;
374     }
375     return;
376   }
377   const binding = state?.binding;
378   if (
379     binding?.controller === controller &&
380     binding.bodyId === bodyId &&
381     binding.bindingGeneration === bindingGeneration
382   ) {
383     state!.binding = undefined;
384   }
385 }
386 
387 export function physicsBodyHandleBinding2D(
388   handle: PibblPhysicsBodyHandle2D,
389 ): PhysicsBodyHandleBinding2D | undefined {
390   return (
391     states.get(handle as object)?.binding ??
392     externalBindings.get(handle as object)?.binding
393   );
394 }
395 
396 export function isPhysicsBodyHandle2D(
397   value: unknown,
398 ): value is PibblPhysicsBodyHandle2D {
399   return (
400     typeof value === "object" &&
401     value !== null &&
402     (states.has(value) || externalBindings.has(value))
403   );
404 }
405 
406 export function physicsBodyHandleOwner2D(
407   handle: PibblPhysicsBodyHandle2D,
408 ): PibblInternalSimulationOwner {
409   return requireState(handle).owner;
410 }
411 
412 export function stagePhysicsBodyHandle2D(
413   batch: PibblInternalSignalBatch,
414   handle: PibblPhysicsBodyHandle2D,
415   values: PhysicsBodyHandleValues2D,
416   writer: object,
417 ): void {
418   const state = states.get(handle as object);
419   if (state === undefined) {
420     stageLegacyHandle(batch, handle, values, writer);
421     return;
422   }
423   for (const field of BODY_FIELDS_2D) {
424     const target = state.signals[field] as
425       WritableSignal<BodyFieldValue2D[typeof field]> | undefined;
426     if (target !== undefined) batch.stage(target, values[field], writer);
427   }
428 }
429 
430 export function snapshotPhysicsBodyHandle2DForTest(
431   handle: PibblPhysicsBodyHandle2D,
432 ): Readonly<{
433   readonly bound: boolean;
434   readonly bindingGeneration: number;
435   readonly materializedFields: readonly PhysicsBodyHandleField2D[];
436 }> {
437   const state = requireState(handle);
438   return Object.freeze({
439     bound: state.binding !== undefined,
440     bindingGeneration: state.binding?.bindingGeneration ?? 0,
441     materializedFields: Object.freeze(
442       BODY_FIELDS_2D.filter((field) => state.signals[field] !== undefined),
443     ),
444   });
445 }
446 
447 function disposePhysicsBodyHandle2D(handle: PibblPhysicsBodyHandle2D): void {
448   const state = states.get(handle as object);
449   if (state === undefined || !state.active) return;
450   state.active = false;
451   state.binding = undefined;
452 }
453 
454 function queueBodyCommand(
455   handle: PibblPhysicsBodyHandle2D,
456   command: PhysicsBodyCommand2D,
457 ): void {
458   const state = requireState(handle);
459   const captured = state.binding;
460   pibblInternalQueueSimulationBegin(state.owner, () => {
461     const current = state.binding;
462     if (
463       captured === undefined ||
464       current === undefined ||
465       current.bindingGeneration !== captured.bindingGeneration ||
466       current.controller !== captured.controller ||
467       current.bodyId !== captured.bodyId
468     ) {
469       traceStaleCommand(command.kind, captured?.bindingGeneration ?? 0);
470       return;
471     }
472     if (
473       !current.controller.acceptBodyHandleCommand(
474         handle,
475         current.bindingGeneration,
476         Object.freeze({
477           ...command,
478           bodyId: current.bodyId,
479         }) as PhysicsBodyCommand2D,
480       )
481     ) {
482       traceStaleCommand(command.kind, current.bindingGeneration);
483     }
484   });
485 }
486 
487 function traceStaleCommand(
488   kind: PhysicsBodyCommand2D["kind"],
489   generation: number,
490 ): void {
491   const runtime = globalThis as typeof globalThis & {
492     readonly process?: Readonly<{
493       readonly env?: Readonly<{ readonly NODE_ENV?: string }>;
494     }>;
495   };
496   if (runtime.process?.env?.NODE_ENV === "production") return;
497   console.warn(
498     `[Pibbl physics] Ignored stale ${kind} command for body handle generation ${String(generation)}.`,
499   );
500 }
501 
502 function requireBoolean(value: boolean, path: string): boolean {
503   if (typeof value !== "boolean")
504     throw new TypeError(`${path} must be boolean.`);
505   return value;
506 }
507 
508 function requireState(
509   handle: PibblPhysicsBodyHandle2D,
510 ): PhysicsBodyHandleState2D {
511   const state =
512     typeof handle === "object" && handle !== null
513       ? states.get(handle as object)
514       : undefined;
515   if (state === undefined || !state.active) {
516     throw new TypeError("Expected a live Pibbl physics 2D body handle.");
517   }
518   return state;
519 }
520 
521 function materializeSignal<Field extends PhysicsBodyHandleField2D>(
522   state: PhysicsBodyHandleState2D,
523   field: Field,
524 ): WritableSignal<BodyFieldValue2D[Field]> {
525   let target = state.signals[field] as
526     WritableSignal<BodyFieldValue2D[Field]> | undefined;
527   if (target === undefined) {
528     const binding = state.binding;
529     const current =
530       binding === undefined
531         ? undefined
532         : binding.controller.bodyHandleValues(binding.bodyId);
533     target = signal(current?.[field] ?? INITIAL_VALUES_2D[field], {
534       debugName: `PhysicsBody2D.${field}`,
535     });
536     state.signals[field] = target as never;
537   }
538   return target;
539 }
540 
541 function stageLegacyHandle(
542   batch: PibblInternalSignalBatch,
543   handle: PibblPhysicsBodyHandle2D,
544   values: PhysicsBodyHandleValues2D,
545   writer: object,
546 ): void {
547   for (const field of BODY_FIELDS_2D) {
548     const target = handle[field] as WritableSignal<
549       BodyFieldValue2D[typeof field]
550     >;
551     batch.stage(target, values[field], writer);
552   }
553 }
554 
555 const ZERO_VECTOR_2D = Object.freeze([0, 0] as const);
556 
557 const INITIAL_VALUES_2D: BodyFieldValue2D = Object.freeze({
558   position: ZERO_VECTOR_2D,
559   rotationDegrees: 0,
560   linearVelocity: ZERO_VECTOR_2D,
561   angularVelocityDegreesPerSecond: 0,
562   sleeping: false,
563   enabled: false,
564   generation: 0,
565 });
566 
567 const BODY_FIELDS_2D = Object.freeze([
568   "position",
569   "rotationDegrees",
570   "linearVelocity",
571   "angularVelocityDegreesPerSecond",
572   "sleeping",
573   "enabled",
574   "generation",
575 ] as const);
576
## Documentation version Documentation built with @pibbl/core 0.0.2, revision 272a94a. ALPHA — NOT FOR PRODUCTION USE.