diff --git a/docs/soa-world.md b/docs/soa-world.md index f06fcaf..875d88a 100644 --- a/docs/soa-world.md +++ b/docs/soa-world.md @@ -34,8 +34,12 @@ separate native object (`ymir_box3d_soa.c`, ABI 7) so the Aetheria session's con 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; a resting load is `contact_impulse / dt`; exact, so a - jointed limb's reading is what the contacts really delivered, not a mass formula's guess), `contact_count` + 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 @@ -108,7 +112,7 @@ step), capsule and box rest heights with parent and limb lanes, refusals, and bi 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; and at rest `contact_impulse / dt` is the weight (0.1%) while a body touching nothing reads 0. +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 diff --git a/tests/Ymir.Box3D.Soa.Tests/Box3DSoaImpulseTests.cs b/tests/Ymir.Box3D.Soa.Tests/Box3DSoaImpulseTests.cs index 2487d29..f76f3eb 100644 --- a/tests/Ymir.Box3D.Soa.Tests/Box3DSoaImpulseTests.cs +++ b/tests/Ymir.Box3D.Soa.Tests/Box3DSoaImpulseTests.cs @@ -130,6 +130,106 @@ public sealed class Box3DSoaImpulseTests } } + [Fact] + public void A_swung_arm_into_a_wall_delivers_the_whole_arms_momentum_change() + { + // The swing the probe measured: impulses launch the upper arm and the forearm off-centre (spin included) at 6 m/s, + // no gravity, and the forearm meets a slab. The wall's impulse is the three bodies' momentum change. + var (world, arm) = Arm(0f); + using var _w = world; + world.AddStaticBox(9, (1.0f, 0.2f - 0.04f - 0.5f - 0.1f, 0f), (0.3f, 0.1f, 0.5f), friction: 0f); // under the forearm only; frictionless, as the lane is the normal channel only + const int fore = 2; + world.ApplyImpulse(1, (0f, -arm[1].Mass * 6f, 0f), (0.55f, 0.2f, 0f)); + world.ApplyImpulse(fore, (0f, -arm[2].Mass * 6f, 0f), (0.95f, 0.2f, 0f)); + // The swung forearm meets the slab at a tilt, so the impulse is along the contact normal, not Y: the truth is the + // length of the momentum change vector (every contact point of the one contact shares its normal). + var before = (X: 0.0, Y: -(double)(arm[1].Mass + arm[2].Mass) * 6f, Z: 0.0); + var dt = 1f / 60f; + var truths = new List(); + var lanes = new List(); + for (var i = 0; i < 8; i++) // the impact is step 3; after it the forearm swings into its own torso, an internal contact whose impulses cancel in the sum + { + world.Step(dt, 4); + var v = world.View; + var after = (X: 0.0, Y: 0.0, Z: 0.0); + foreach (var (lane, mass) in arm) after = (after.X + (double)mass * v.VelocityX[lane], after.Y + (double)mass * v.VelocityY[lane], after.Z + (double)mass * v.VelocityZ[lane]); + var dx = after.X - before.X; var dy = after.Y - before.Y; var dz = after.Z - before.Z; + truths.Add(Math.Sqrt(dx * dx + dy * dy + dz * dz)); + before = after; + lanes.Add(v.ContactImpulse[fore]); + } + var peak = truths.Max(Math.Abs); + Assert.True(peak > 5.0, $"the arm hit the slab (peak {peak} N s)"); + for (var i = 0; i < truths.Count; i++) + { + Assert.True(Math.Abs(lanes[i] - truths[i]) <= 1e-4 * peak, $"step {i}: {lanes[i]} vs {truths[i]}"); + } + } + + [Theory] + [InlineData(0f)] + [InlineData(0.5f)] + public void A_body_with_more_contacts_than_graph_colours_still_reads_every_one(float restitution) + { + // One big sphere with 60 small ones converging on it: more contacts on the big body than Box3D has graph colours, + // so some are solved by its overflow path. Each small ball has one contact, so its lane is its own momentum + // change; the big ball's lane is the sum of theirs. + const int count = 60; + const float bigRadius = 0.5f, smallRadius = 0.05f, speed = 4f; + using var world = new Box3DSoaWorld(capacity: count + 2, gravityY: 0f); + var big = world.AddSphere(1, (0f, 0f, 0f), bigRadius, 500f, restitution: restitution); + var smallMass = SphereMass(smallRadius, 500f); + var smalls = new int[count]; + var dirs = new (float X, float Y, float Z)[count]; + for (var i = 0; i < count; i++) + { + var y = 1f - 2f * (i + 0.5f) / count; + var r = MathF.Sqrt(1f - y * y); + var a = i * MathF.PI * (3f - MathF.Sqrt(5f)); + dirs[i] = (r * MathF.Cos(a), y, r * MathF.Sin(a)); + var d = bigRadius + smallRadius - 0.001f; + smalls[i] = world.AddSphere((ulong)(10 + i), (dirs[i].X * d, dirs[i].Y * d, dirs[i].Z * d), smallRadius, 500f, restitution: restitution); + } + var dt = 1f / 60f; + world.Step(dt); + world.Step(dt); + Assert.True(world.View.ContactCount[big] > 24, $"the big ball has {world.View.ContactCount[big]} contacts, more than Box3D has graph colours"); + for (var i = 0; i < count; i++) + { + world.ApplyImpulse(smalls[i], (-dirs[i].X * smallMass * speed, -dirs[i].Y * smallMass * speed, -dirs[i].Z * smallMass * speed), + (dirs[i].X * bigRadius, dirs[i].Y * bigRadius, dirs[i].Z * bigRadius)); + } + var launched = new (double X, double Y, double Z)[count]; + for (var i = 0; i < count; i++) launched[i] = (-dirs[i].X * smallMass * speed, -dirs[i].Y * smallMass * speed, -dirs[i].Z * smallMass * speed); + var peak = 0.0; + var steps = 12; + var sumOfSmalls = new double[steps]; + var bigLane = new float[steps]; + var worst = new double[steps]; + for (var s = 0; s < steps; s++) + { + world.Step(dt); + var v = world.View; + for (var i = 0; i < count; i++) + { + var l = smalls[i]; + var now = (X: (double)smallMass * v.VelocityX[l], Y: (double)smallMass * v.VelocityY[l], Z: (double)smallMass * v.VelocityZ[l]); + var dp = Math.Sqrt((now.X - launched[i].X) * (now.X - launched[i].X) + (now.Y - launched[i].Y) * (now.Y - launched[i].Y) + (now.Z - launched[i].Z) * (now.Z - launched[i].Z)); + launched[i] = now; + sumOfSmalls[s] += v.ContactImpulse[l]; + worst[s] = Math.Max(worst[s], Math.Abs(v.ContactImpulse[l] - dp)); + peak = Math.Max(peak, dp); + } + bigLane[s] = v.ContactImpulse[big]; + } + Assert.True(peak > 0.5, $"the small balls hit (peak {peak} N s)"); + for (var s = 0; s < steps; s++) + { + Assert.True(Math.Abs(bigLane[s] - sumOfSmalls[s]) <= 1e-4 * sumOfSmalls.Max(), $"step {s}: big {bigLane[s]} vs the smalls' sum {sumOfSmalls[s]}"); + Assert.True(worst[s] <= 1e-3 * peak, $"step {s}: a small ball's lane is off its momentum change by {worst[s]}"); + } + } + [Theory] [InlineData(60, 1, 0f)] [InlineData(60, 4, 0f)]