Skip to content

3D engine that AI agents drive

Document hingedDoorSwing, add its change note and size note (#983)

Nguyen Xuan An0e1e9012f431
diff --git a/changes/983-doors.md b/changes/983-doors.md
new file mode 100644
index 00000000..6e034944
--- /dev/null
+++ b/changes/983-doors.md
@@ -0,0 +1 @@
+- `hingedDoorSwing` in `crucible/addons/vehicle` swings a damaged door open on its hinge: a torque-driven, damped swing that stops at `maxAngle` with a small bounce and rests (#983)
diff --git a/changes/983-doors.size.md b/changes/983-doors.size.md
new file mode 100644
index 00000000..2c22a854
--- /dev/null
+++ b/changes/983-doors.size.md
@@ -0,0 +1 @@
+- entry:vehicle: 976 bytes gzip for `hingedDoorSwing`, the torque-driven hinge swing of a damaged door (damping, a stop at maxAngle with a bounce, a rest, and the door transform about the hinge line), which the addon did not have (#983). It is opt-in and only ships in the vehicle addon entry.
diff --git a/docs/vehicle.md b/docs/vehicle.md
index 2e11b5b8..9a5f15b5 100644
--- a/docs/vehicle.md
+++ b/docs/vehicle.md
@@ -224,7 +224,9 @@ A part that comes off in a physics crash is a body joined to the car body by a `
For a drive, where nothing simulates the loose part, `detachedPartFlight(part, hit, { seed, gravity, groundY, restitution })` gives it a flight. `part` is `{ id, threshold, mass, position, size }`, with `size` the box of the part as three extents in metres (optional) and `hit` is `{ impulse, direction, point }` from `findDriveImpact` (`point` is optional and defaults to the part's centre); the part never crosses the plane through `point` with normal `direction`, which is the wall: with a `size`, no corner of its box (Euler angles in XYZ order) crosses it; without one, only the centre is held, so a long part can swing over the wall. It returns null when the impulse stays below `threshold`, so the part stays on. Otherwise `flight.sample(seconds)` (0 to 30 s) returns `{ position, rotation, velocity, settled }`: the part leaves mostly sideways at `(impulse - threshold) / (mass * 100)` m/s (at most 30) (a seeded sign, across `direction`, with a small rebound along `direction` and an up kick) and tumbles, falls, bounces on the plane `groundY` and comes to rest. The same inputs and `seed` give the same numbers. Set the node's transform from the sample each frame.
-Not covered yet: hinged doors, hood and trunk that pop open, swapping broken glass for shards, and dents driven by the live vehicle controller. A drive is kinematic, so `findDriveImpact` only reports the moment of the hit; the car does not stop or bounce.
+A door does not tear off: `hingedDoorSwing(part, hit, { hinge, maxAngle, damping, seed })` swings it open on its hinge. `part` and `hit` are as above, and `hinge` is `{ point, axis }`: a point on the hinge line (the line passes at least 1 mm from the door's centre) and its direction (any length but zero). It returns null when the impulse stays below `threshold`. Otherwise `swing.sample(seconds)` (0 to 30 s) returns `{ angle, angularVelocity, position, rotation, quaternion, settled }`: the door turns about the hinge line from the torque of the hit (`(impulse - threshold) / 100` along `direction`, at the lever from `hit.point` to the hinge, over the door's inertia, at most 15 rad/s), slows by `damping` (0 to 20, default 3) and dry friction, stops at `maxAngle` degrees (0 to 170, default 70) with a small bounce, and comes to rest. `angle` is in radians and its sign follows the hit; the frame stops the door from swinging back past shut. `position` is the door's centre and `rotation` (Euler XYZ, radians) or `quaternion` is its turn, so the hinge line stays where it is; set the node's transform from them each frame. A hit along the hinge line gives no torque, so the door stays shut. The same inputs and `seed` give the same numbers.
+
+Not covered yet: hood and trunk that pop open, swapping broken glass for shards, and dents driven by the live vehicle controller. A drive is kinematic, so `findDriveImpact` only reports the moment of the hit; the car does not stop or bounce.
## Limits