Expand Box2Dxt to the full Box2D v3.1.0 live-object API (ABI 3)

[SethMorrowSoftware]

What & why

Two related pieces of work that make the binding feature-complete, both on this branch:

1. Kit completeness pass (commit edb0ffe) — the Kit (b2k…) now covers the full existing core b2… surface (position/centre-of-mass/damping/gravity-scale getters, one-shot angular impulse, per-shape hit-test, contact polling, version check).
2. Full Box2D v3.1.0 live-object API (commit 300768f) — a review found large, useful swaths of the engine unreachable from any layer. This adds essentially the whole live-object surface: ~240 new shim functions, each with a b2… extension wrapper and, where it helps, a b2k… Kit helper. ABI bumped 2 → 3.

All changes are additive — every existing handler keeps its signature.

New capabilities (layer 2)

Area	Core b2…	Friendly Kit b2k…
Sensors	shape-def builder (b2ShapeDefSensor/Filter/Enable*Events), b2SensorsUpdate + accessors	b2kAddSensor, on b2kSensorEnter/Exit
Collision filtering	b2SetShapeFilter + category/mask/group getters (32 layers)	b2kDefineLayer, b2kSetCategory/Mask/CollisionGroup, b2kNoCollide
Chains (terrain)	b2CreateChain + builder, materials, segments	b2kChain, b2kSmoothGround
More joints	motor + filter joints, generic surface, full per-joint get/set (all 6 types)	b2kMotorTo, b2kNoCollide
Queries	overlap (AABB/point/circle/shape), ray-cast-all (sorted), shape-cast	b2kOverlap, b2kOverlapCircle, b2kRayHitAll
Events	contact hit, sensor, bulk body-move events	(dispatched as messages / pollers)
World	tuning, b2WorldExplode, gravity getter, profile/counters	passthroughs, b2kProfile, native b2kExplode (old → b2kExplodeLegacy)
Body	transforms, velocity/force/impulse-at-point, mass data, enumeration	—
Shape	geometry get/set, material/filter/event-flag get/set, ray cast, sensor overlaps	—

Design (all mechanical, five reusable shim patterns)

• A shape-def "pending overrides" struct gives every existing shape creator sensors/filters/event-flags/material with no new variants (one-shot, like the polygon builder).
• A chains handle table (DEFINE_TABLE) + point builder.
• Box2D's callback-based queries are run with a small C collector that pushes hits into one shared result buffer → count + indexed getters (same idea as the existing ray/contact stashes).
• Sensor / hit / body-move events reuse the growable contact-snapshot pattern.
• register_joint stamps joint handles into Box2D userData so the generic/enumeration joint features round-trip.

Only CInt/CDouble/nothing cross the FFI — no new foreign types.

Verification

The C-shim side is fully tested here: tests/smoke_test.c gains a per-area block (sensors begin/end, filtered pair does not collide, chain ground catches a box, motor joint reaches its offset, ray-cast-all returns N sorted hits, native explosion scatters bodies, body-move events report a fallen box, mass-data get/set round-trip). A clean cmake … -DBOX2DXT_BUILD_TESTS=ON && ctest is green (44/44), warning-clean. Cross-layer checks confirm all 368 binds to symbols resolve to shim exports and every Kit b2… call resolves to a public handler.

The LCB/Kit side can't be run here (needs OpenXTalk / LiveCode); it was written to match the existing file's idioms exactly and verified structurally (binding resolution, handler balance). Recommend a quick IDE smoke per CONTRIBUTING (put b2Version() → 3; a sensor zone firing on b2kSensorEnter; a chain ground; b2kOverlap).

Intentionally out of scope (documented)

• Pre-solve / custom-filter / friction-restitution callbacks — no safe way to call back into xTalk mid-step over the LCB FFI.
• Standalone math / geometry / TOI / manifold helpers — operate on raw structs, not world objects; xTalk has its own math.
• User-data setters — the shim stores each object's handle in Box2D userData; exposing setters would corrupt the round-trip.

Notes for the reviewer

• ABI 2 → 3: b2Version() now returns 3; updated across code/docs/examples. The committed prebuilt/* libraries are now stale until CI rebuilds them on a release tag.
• Collision filter bits are 32-bit (32 layers), not Box2D's full 64 — xTalk doubles carry 32 unsigned bits cleanly. Widening later won't break the signatures (they already cross as double).
• The big diff is highly repetitive; both box2d_lc.c and box2dxt.lcb are organised under matching section banners for section-by-section review.

https://claude.ai/code/session_01NbsPt8oTFhzZJBry4GxjSR