From 617beec1dc160605205dc6cb6a2000e55d912d43 Mon Sep 17 00:00:00 2001 From: Meta Vens Date: Fri, 20 Nov 2026 00:51:05 +0100 Subject: [PATCH] SoA world publishes each body's shape size as read-only lanes (ABI 3) Size0/1/2 sit beside Kind, written once in add_body, never touched by step, so a renderer draws every body from one source. Co-Authored-By: Claude Sonnet 5.5 --- docs/soa-world.md | 9 +++-- native/Ymir.Box3D/ymir_box3d_soa.c | 19 ++++++++- src/Ymir.Box3D/Box3DSoaWorld.cs | 11 ++++- .../Box3DSoaWorldTests.cs | 40 +++++++++++++++++++ 4 files changed, 73 insertions(+), 6 deletions(-) diff --git a/docs/soa-world.md b/docs/soa-world.md index e3868fc..43f0a85 100644 --- a/docs/soa-world.md +++ b/docs/soa-world.md @@ -8,16 +8,19 @@ Box3D decides every physical outcome; Ymir creates bodies, steps the world and e `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 1) so the Aetheria session's contract is untouched. +separate native object (`ymir_box3d_soa.c`, ABI 3) so the Aetheria session's contract is untouched. ## Contract -- Native (ABI 2): `ymir_box3d_soa_create(capacity, joint_capacity, gravity) / add_body / add_joint / step / +- Native (ABI 3): `ymir_box3d_soa_create(capacity, joint_capacity, gravity) / add_body / add_joint / step / get_view / destroy`. `add_body` takes one descriptor (sphere, capsule, box, static box; position, rotation, velocity, size, density, friction, restitution, rolling resistance, 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), position xyz, rotation quaternion xyzw, linear and angular + 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 diff --git a/native/Ymir.Box3D/ymir_box3d_soa.c b/native/Ymir.Box3D/ymir_box3d_soa.c index 9420a81..6cfbba1 100644 --- a/native/Ymir.Box3D/ymir_box3d_soa.c +++ b/native/Ymir.Box3D/ymir_box3d_soa.c @@ -54,7 +54,7 @@ enum YMIR_SOA_JOINT_WELD = 2 }; -#define YMIR_SOA_ABI_VERSION 2u +#define YMIR_SOA_ABI_VERSION 3u // A body to create. `size` by kind: sphere {radius}, capsule {radius, half_length} (segment along // local Y), box and static box {half_x, half_y, half_z}. `parent` is the lane index of an earlier body @@ -110,6 +110,11 @@ typedef struct ymir_box3d_soa_view const uint32_t* kind; const int32_t* parent; const int32_t* limb; + // The body's shape size, read-only, same per-kind meaning as the body desc size: sphere {radius}, + // capsule {radius, half_length}, box and static box {half_x, half_y, half_z}; unused components are 0. + const float* size_0; + const float* size_1; + const float* size_2; const float* position_x; const float* position_y; const float* position_z; @@ -165,6 +170,7 @@ typedef struct ymir_box3d_soa_world uint32_t* kind; int32_t* parent; int32_t* limb; + float* size; // 3 arrays of `capacity` floats, lane-major; written once in add_body float* lanes; // YMIR_SOA_BODY_FLOAT_LANES arrays of `capacity` floats, lane-major b3JointId* joints; uint32_t* joint_kind; @@ -275,6 +281,7 @@ static void ymir_soa_free(ymir_box3d_soa_world* world) free(world->kind); free(world->parent); free(world->limb); + free(world->size); free(world->lanes); free(world->joints); free(world->joint_kind); @@ -315,6 +322,7 @@ YMIR_EXPORT int32_t YMIR_CALL ymir_box3d_soa_create( world->kind = (uint32_t*)calloc(n, sizeof(uint32_t)); world->parent = (int32_t*)calloc(n, sizeof(int32_t)); world->limb = (int32_t*)calloc(n, sizeof(int32_t)); + world->size = (float*)calloc(n * 3, sizeof(float)); world->lanes = (float*)calloc(n * YMIR_SOA_BODY_FLOAT_LANES, sizeof(float)); world->joints = (b3JointId*)calloc(m, sizeof(b3JointId)); world->joint_kind = (uint32_t*)calloc(m, sizeof(uint32_t)); @@ -324,7 +332,7 @@ YMIR_EXPORT int32_t YMIR_CALL ymir_box3d_soa_create( world->joint_local_b = (b3Quat*)calloc(m, sizeof(b3Quat)); world->joint_lanes = (float*)calloc(m * YMIR_SOA_JOINT_FLOAT_LANES, sizeof(float)); if (world->bodies == NULL || world->stable_id == NULL || world->kind == NULL || world->parent == NULL || - world->limb == NULL || world->lanes == NULL || world->joints == NULL || world->joint_kind == NULL || + world->limb == NULL || world->size == NULL || world->lanes == NULL || world->joints == NULL || world->joint_kind == NULL || world->joint_body_a == NULL || world->joint_body_b == NULL || world->joint_local_a == NULL || world->joint_local_b == NULL || world->joint_lanes == NULL) { @@ -488,6 +496,10 @@ YMIR_EXPORT int32_t YMIR_CALL ymir_box3d_soa_add_body( world->kind[i] = d->kind; world->parent[i] = d->parent; world->limb[i] = d->limb; + for (int k = 0; k < 3; k++) + { + world->size[(size_t)k * (size_t)world->capacity + (size_t)i] = d->size[k]; + } ymir_soa_refresh(world, i); if (index != NULL) { @@ -672,6 +684,9 @@ YMIR_EXPORT int32_t YMIR_CALL ymir_box3d_soa_get_view(const ymir_box3d_soa_world .kind = world->kind, .parent = world->parent, .limb = world->limb, + .size_0 = world->size + 0 * n, + .size_1 = world->size + 1 * n, + .size_2 = world->size + 2 * n, .position_x = base + 0 * n, .position_y = base + 1 * n, .position_z = base + 2 * n, diff --git a/src/Ymir.Box3D/Box3DSoaWorld.cs b/src/Ymir.Box3D/Box3DSoaWorld.cs index fcb6c05..7efdb3c 100644 --- a/src/Ymir.Box3D/Box3DSoaWorld.cs +++ b/src/Ymir.Box3D/Box3DSoaWorld.cs @@ -61,6 +61,9 @@ internal unsafe struct Box3DSoaViewNative public uint* Kind; public int* Parent; public int* Limb; + public float* Size0; + public float* Size1; + public float* Size2; public float* PositionX; public float* PositionY; public float* PositionZ; @@ -181,6 +184,12 @@ public readonly unsafe struct Box3DSoaView public ReadOnlySpan Parent => Lane(_v.Parent, Count); /// The caller's limb label for the body. Set at creation, not used by Box3D. public ReadOnlySpan Limb => Lane(_v.Limb, Count); + /// The body's shape size, read-only, set at creation and never changed by Step. Size0 is the sphere or + /// capsule radius, or the box half-extent x; Size1 is the capsule half-length (along local Y) or the box half-extent y; + /// Size2 is the box half-extent z. Unused components are 0. Shapes are centred on the body origin. + public ReadOnlySpan Size0 => Lane(_v.Size0, Count); + public ReadOnlySpan Size1 => Lane(_v.Size1, Count); + public ReadOnlySpan Size2 => Lane(_v.Size2, Count); public ReadOnlySpan PositionX => Lane(_v.PositionX, Count); public ReadOnlySpan PositionY => Lane(_v.PositionY, Count); public ReadOnlySpan PositionZ => Lane(_v.PositionZ, Count); @@ -241,7 +250,7 @@ public readonly unsafe struct Box3DSoaView /// public sealed class Box3DSoaWorld : IDisposable { - private const uint ExpectedAbi = 2; + private const uint ExpectedAbi = 3; private nint _handle; public Box3DSoaWorld(int capacity, float gravityX = 0f, float gravityY = -10f, float gravityZ = 0f, int jointCapacity = 0) diff --git a/tests/Ymir.Box3D.Soa.Tests/Box3DSoaWorldTests.cs b/tests/Ymir.Box3D.Soa.Tests/Box3DSoaWorldTests.cs index 89ee97d..b3534b2 100644 --- a/tests/Ymir.Box3D.Soa.Tests/Box3DSoaWorldTests.cs +++ b/tests/Ymir.Box3D.Soa.Tests/Box3DSoaWorldTests.cs @@ -122,6 +122,46 @@ public sealed unsafe class Box3DSoaWorldTests Assert.False(Lanes(a.View).AsSpan().SequenceEqual(Lanes(b.View))); } + [Fact] + public void Each_kind_reads_back_its_size_lanes_at_its_lane_index_and_step_never_changes_them() + { + // All four kinds interleaved, so a wrong lane-major offset would read one kind's size from another's slot. + using var world = new Box3DSoaWorld(capacity: 16); + var ground = world.AddStaticBox(1, (0f, -0.5f, 0f), (40f, 0.5f, 30f)); + var sphere = world.AddSphere(2, (0f, 4f, 0f), radius: 0.7f, density: 1f); + var capsule = world.AddCapsule(3, (3f, 4f, 0f), radius: 0.3f, halfLength: 0.9f, density: 1f); + var box = world.AddBox(4, (-3f, 4f, 0f), (0.4f, 0.6f, 0.8f), density: 1f); + var wall = world.AddStaticBox(5, (0f, 2f, 20f), (2f, 3f, 0.25f)); + var sphere2 = world.AddSphere(6, (6f, 4f, 0f), radius: 0.2f, density: 1f); + + (float, float, float)[] expected = new (float, float, float)[6]; + expected[ground] = (40f, 0.5f, 30f); + expected[sphere] = (0.7f, 0f, 0f); + expected[capsule] = (0.3f, 0.9f, 0f); + expected[box] = (0.4f, 0.6f, 0.8f); + expected[wall] = (2f, 3f, 0.25f); + expected[sphere2] = (0.2f, 0f, 0f); + + var view = world.View; + byte[] Sizes(Box3DSoaView v) => + MemoryMarshal.AsBytes(v.Size0).ToArray().Concat(MemoryMarshal.AsBytes(v.Size1).ToArray()) + .Concat(MemoryMarshal.AsBytes(v.Size2).ToArray()).ToArray(); + void AssertSizes(Box3DSoaView v) + { + Assert.Equal(6, v.Size0.Length); + for (var i = 0; i < expected.Length; i++) + { + Assert.Equal(expected[i], (v.Size0[i], v.Size1[i], v.Size2[i])); + } + } + + AssertSizes(view); + var before = Sizes(view); + Run(world, 120); + AssertSizes(world.View); + Assert.True(before.AsSpan().SequenceEqual(Sizes(world.View))); + } + [Fact] public void Refuses_bad_input_and_a_full_or_duplicate_world() {