Ymir/docs/soa-world.md
Meta Vens be21de1959 SoA impulse tests reach the overflow solver and a swung arm; docs: the lane is a sum of magnitudes
A big sphere with 60 small ones converging has more contacts than graph colours, so Box3D's
scalar overflow path runs: the big lane equals the sum of the small lanes, each its own
momentum change, at restitution 0 and 0.5. A swung arm (ApplyImpulse launches) into a
frictionless slab is exact. The docs say the lane sums magnitudes and is the weight at
rest only on average.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
2026-11-20 03:22:09 +01:00

140 lines
14 KiB
Markdown

# Headless SoA world
A headless 3D Box3D world with a structure-of-arrays state view, for Lodur and Bad Day Simulator.
Box3D decides every physical outcome; Ymir creates bodies, steps the world and exposes state.
## Why it is not the retained session
`ymir_box3d_session_*` (`ymir_box3d.c`) is the planar Aetheria session: gravity is zero, Y is locked,
only yaw rotates (`motionLocks.linearY/angularX/angularZ`), and state leaves by `copy_bodies` into an
array of structs. A body cannot fall or tumble there, and every read is a copy. The SoA world is a
separate native object (`ymir_box3d_soa.c`, ABI 7) so the Aetheria session's contract is untouched.
## Contract
- Native (ABI 7): `ymir_box3d_soa_create(capacity, joint_capacity, gravity, fact_capacity, hit_threshold) /
add_body / add_joint / step / get_view / get_facts / set_anchor_target / destroy_joint / free_joint_slots / apply_impulse / cast_ray_closest / destroy`. `add_body` takes one descriptor (sphere, capsule, box, static box, anchor; position,
rotation, velocity, size, density, friction, restitution, rolling resistance, material id, parent, limb). Capacities are fixed at creation,
so lane pointers never move.
- Body lanes (`ymir_box3d_soa_view`): `stable_id`, `kind`, `parent` and `limb` (set at creation, not read by
Box3D: the limb tree for the consumer), `size_0`, `size_1`, `size_2` (read-only shape size set at creation,
never changed by `step`: sphere {radius}, capsule {radius, half_length} along local Y, box and static box
{half_x, half_y, half_z}; unused components 0; shapes are centred on the body origin, so a renderer draws
every body from kind and size), position xyz, rotation quaternion xyzw, linear and angular
velocity xyz. One contiguous array per component, indexed by body.
- Write lanes: per-body world `force` (at the centre of mass) and `torque`, xyz, mutable through the view.
`step` applies them to the dynamic bodies and clears them, so a lane holds one step's intent. A
non-finite value refuses the whole step before any body is touched.
- Joints: `add_joint` takes two body indices (B is the child), a world anchor and axis, and a kind
(revolute, spherical, weld). The joint frame has its z axis on the axis (the hinge axis); the creation
pose is the joint's zero. Optional limits: revolute angle, spherical swing cone and twist. Joint lanes:
`joint_kind`, `joint_body_a/b`, `joint_angle` (Box3D's revolute angle or spherical twist), `joint_frame`
(world orientation of frame A, quaternion), `joint_rotation` (frame B relative to frame A, quaternion,
w >= 0) and `joint_angular_velocity` (B minus A, in frame A). A consumer can compute a joint torque from
these and write it as equal and opposite torques on the two body lanes.
- Contact lanes (read-only, rewritten by every `step`): `contact_impulse` (N s: the normal impulse the
body's touching contacts delivered to it over the whole step, the sum of Box3D's `stepNormalImpulse` over
its manifold points; 0 for a body touching nothing; exact, so a jointed limb's reading is what the contacts
really delivered, not a mass formula's guess. It is a sum of magnitudes over all the body's contacts, not the
net: a ball under a ball reads support plus load, 3 m g dt, not m g dt. At rest it equals the weight only on
average: heavy balls in a pile alternate between about 1.5 and 0.5 m g dt from step to step, so a consumer
must not threshold a single step; average over steps or use `contact_impulse / dt` as a load estimate over a
window), `contact_count`
(touching contacts) and `material_id` (the body's `material_id`, also set as the shape's Box3D user
material). `stepNormalImpulse` is the GameCult Box3D fork's observed field (see `box3d-parity.md`); it is
the normal channel only, since Box3D exposes no tangent impulse. Sleep is off in SoA worlds, so manifolds
hold no stale values; if sleep is ever enabled, zero the lanes of sleeping bodies. The hit fact's `impulse`
(N s) is the same sum over the manifold of the hit's two shapes, read after the step.
- Contact facts: every shape is created with contact and hit events on (Box3D's default is off). After each
`step`, `ymir_box3d_soa_get_facts` returns pointers and counts into buffers fixed at create (`fact_capacity`
per kind, no allocation in the step): Begin and End `{lane_a, lane_b, stable_id_a, stable_id_b}` and Hit
those plus `point` xyz, `normal` xyz (A to B), `approach_speed` (a touch faster than `hit_threshold` m/s)
and `material_a`, `material_b`. Facts are in Box3D's event order and last one step: the next `step`
rewrites them. `*_dropped` counts the facts a step could not keep past `fact_capacity`. The lane in a fact
is the body's user data (lane + 1) and the stable id is the shape's user data. The facts report; they
decide nothing.
- Grab and poke input (immediate commands; Ymir decides nothing about grabbing, so a player grab, a scripted
hook and a cursor tool are all the same three calls):
- Anchor (body kind 4): a kinematic body with no shape. It never collides or is hit, its size lanes are 0 and
size, density, friction and material are ignored. `set_anchor_target(lane, position, rotation, time_step)`
gives it the velocity that reaches the pose after `time_step`, so passing the step's dt lands it on the pose
at the end of the next step, where `step` stops it: after every step an anchor's velocity is zeroed, so with no
new target it holds still at the last pose (a skipped frame flings nothing) and its velocity lanes read 0. It is
refused for a lane that is not an anchor, for non-finite or non-unit input and for a time step <= 0. The force and torque lanes never move an anchor. Its pose reads from the state lanes.
- Motor joint (kind 3): `add_joint` with the descriptor's `linear_hertz`, `linear_damping`, `max_force`,
`angular_hertz`, `angular_damping`, `max_torque` (finite, >= 0, ignored by the other kinds; zero hertz turns that
spring off; no velocity target). The frame is built from the world anchor and axis like every joint, so the
linear spring pulls body B's anchor point onto A's (A an anchor, B the body to grab). `max_force` and
`max_torque` bound the pull: with a max force below the weight the body hangs below the target. `joint_angle`
reads 0.
- Release: the cursor's anchor is long-lived (a client creates one per cursor and keeps it; bodies are never
removed here). `destroy_joint(joint, generation)` releases a grab by destroying the motor joint only; the anchor and the
grabbed body stay. Only motor joints can be destroyed (general joint and body removal belongs to
`ymir-break-and-remove`); anything else is refused. The joint's lane becomes a tombstone: `joint_kind` 4
(Removed), `joint_body_a/b` -1 and every joint lane 0. `joint_count` counts slots ever used, tombstones included.
`add_joint` reuses the lowest tombstone only after a step has completed since the destroy, so lanes read within a
step stay valid; until then the slot is not free. `free_joint_slots` (managed `FreeJointSlots`) is what
`add_joint` could create right now: check it, and `FreeBodySlots`, before adding an anchor for a grab, so a full
world leaves no orphan anchor. Repeated grab and release on one slot do not grow the world.
A joint's handle is its lane and the slot's generation (`joint_generation` lane, counts destroys of the slot;
managed `Box3DSoaJointHandle`, returned by `AddJoint` and `AddMotorJoint`, converts to the lane). `destroy_joint`
refuses a generation that is not the slot's, so a second release click with an old handle never destroys a later
grab that reused the slot. Anchor creation must be followed by a joint that validates (its spring fields are
checked there), or the anchor is left behind: with one long-lived anchor per cursor that is accepted, and an atomic
`AddGrab` is a follow-up only if cursors become dynamic.
- `apply_impulse(lane, impulse, point)`: a one-shot world impulse (N s) at a world point; off the centre of mass it
also spins the body. Dynamic bodies only (a static body or anchor is refused), non-finite input refused.
- `cast_ray_closest(origin, translation)` fills a `ymir_box3d_soa_ray_hit` {hit, lane, stable_id, point, normal,
fraction}: Box3D's closest hit along origin + t * translation, t in [0, 1], default filter; a miss is success with
`hit` 0 and every field 0; a non-finite or zero translation is refused. Anchors are never hit. A ray that starts
inside a shape skips that shape (Box3D's behaviour, it ignores initial overlap) and reports what lies beyond.
- Managed: `AddAnchor`, `SetAnchorTarget`, `AddMotorJoint`, `DestroyJoint`, `FreeJointSlots`, `FreeBodySlots`, `ApplyImpulse`, `CastRayClosest` (returns
`Box3DSoaRayHit`) on `Box3DSoaWorld`; refusals throw `InvalidOperationException`.
- State lanes change only inside `step`. Between steps a caller may read any state lane in place.
- Managed (`src/Ymir.Box3D/Box3DSoaWorld.cs`, public: `Box3DSoaWorld`, `Box3DSoaView`, `Box3DSoaFacts`, `Box3DSoaKind`, `Box3DSoaJointKind`; the native structs and the view constructor stay internal): `Box3DSoaView` exposes each lane as a span over
native memory (`ReadOnlySpan` for state, `Span` for write lanes). Spans are invalid after `Dispose`.
`Count` and `JointCount` are as of when the view was taken, so take it after the last add.
`Box3DSoaWorld.Facts` is a `ref struct` of `ReadOnlySpan`s (`Begin`, `End`, `Hit`) with the same dispose
guard; the constructor takes `factCapacity` (default 4 x capacity, 0 refused) and `hitThreshold` (default 1);
the `Add*` methods take an optional `materialId`.
- Determinism: one Box3D worker, bodies stepped in insertion order, same inputs give identical lane
bytes on the same build. It is not claimed across platforms or CPUs.
- Concurrency: see Threading below; world creation and destruction are serialized by Ymir's native lock.
## Tests
`tests/Ymir.Box3D.Soa.Tests`, run serially: gravity and rest read through one held view, address stability
across steps, two runs byte-equal at six checkpoints (25 spheres colliding on a slab), a one-ulp input
difference diverging, argument refusal, dispose; and for joints: hinge angle and the relative-rotation
lanes agreeing, an off-axis hinge, a limit and a weld, a spherical joint leaving the swing plane, force and
torque lanes (exact acceleration, cleared after the step, static bodies ignoring them, NaN refusing the
step), capsule and box rest heights with parent and limb lanes, refusals, and bit-identical repeat runs of
a torque-driven jointed body. `Box3DSoaGrabTests`: a strong grab reaching a target 1 m away within 1 s, a weak grab falling at least `g - F/m`, an anchor that does not collide and is not hit by a ray, force lanes not moving an anchor, an off-centre impulse (linear `J/m` and the spin's sign and size), the ray's nearest body with lane, stable id, point and fraction, refusals changing nothing, and bit-identical repeat runs with a moving anchor and an impulse. `Box3DSoaContactTests`: a drop gives one begin and one hit (speed within 5%
of sqrt(2gh), point and normal), lifting gives one end, dropped counters resetting each step, materials on
hits, facts lasting one step, overflow counted, per-step byte determinism of facts and contact lanes, and
no allocation across 100 steps with fact reads. `Box3DSoaImpulseTests`: `contact_impulse` and the hit `impulse` equal the momentum change of the bodies the contact acted on, plus their weight, within 1e-4 of the peak at every step: a 5 kg ball and a 0.3 g BB at 100 m/s onto a jointed forearm (the BB reads 0.030 N s, the ball over 400 times more), the arm falling forearm-first onto a slab, a sphere dropped 1.4 m at 60 and 240 Hz, 1 and 4 sub-steps, restitution 0 and 0.5, two free bodies at restitution 0 and 0.5; a swung arm into a slab, a big sphere with 60 small ones converging (more contacts than graph colours, so the scalar overflow solver runs: the big lane is the sum of the small lanes, each equal to its own momentum change), and at rest `contact_impulse / dt` is the weight (0.1%, a lone sphere) while a body touching nothing reads 0.
## Not done
Body removal with a stable ordering rule, compound bodies
and per-shape material, and motor joints with a velocity target or per-joint force readback (the motor joint here is a position spring only; Lodur drives limbs from torque lanes).
`Ymir.Core` has no session-level surface over the SoA world yet; consumers use `Ymir.Box3D` directly.
Unity consumption is unrun; cross-platform bit-identity is unclaimed.
## Build and lifetime notes
- Native library name: `ymir_box3d.dll` on Windows (MinGW needs `PREFIX ""`, set under `if(MINGW)`; MSVC emits it
natively), `libymir_box3d.so` on Linux, `libymir_box3d.dylib` on macOS. `Ymir.Box3D.csproj` copies from
`bin\$(Configuration)\` on every platform: `CMakeLists.txt` writes `bin/$<CONFIG>/` and the csproj passes `-DCMAKE_BUILD_TYPE=$(Configuration)`, so single- and multi-config generators land in the same place.
- Windows run: MinGW gcc with `CMAKE_GENERATOR="Ninja Multi-Config" CC=gcc`; `Ymir.Box3D.Soa.Tests` passes.
Linux run (Yggdrasil, default generator, gcc): the same tests pass and emit `bin/Debug/libymir_box3d.so`. macOS is unrun.
- Threading: creating and destroying worlds is safe from any number of threads at once (a process-wide lock in the native
layer serializes `b3CreateWorld`/`b3DestroyWorld`, which otherwise scan and rewrite Box3D's global world pool unsynchronized;
the retained session and pair-step paths take the same lock). Stepping distinct worlds concurrently is not known to race: Box3D's own docs promise no thread safety, and this rests on a reading of the pinned source and one light test. A single world
is still not thread-safe. `Box3DSoaConcurrentCreateTests` creates, steps and disposes worlds from eight threads.
- At most 128 live worlds per process (Box3D's `B3_MAX_WORLDS`); creating more trips a Box3D assert, not a managed error.
- `Box3DSoaWorld` is not thread-safe: `Dispose` must not race `Step` or a lane read. A `Box3DSoaView` refuses
to hand out a lane (ObjectDisposedException) once its world is disposed, and a `default` view refuses with
InvalidOperationException. The check guards obtaining a span, not a span already held: a span taken from a
view must not be used after the world is disposed. Known limit: an undisposed world leaks its
native memory; there is no finalizer or SafeHandle.