Rapier cluster physics: contact events + per-entity collider shapes

[martinjms]

Quick Summary

• 🟡 Status: planned, ready to start. Depends on #117 — Rapier cluster physics: minimum integration.
• Add a sibling trait RapierClusterSimulation (in arcane-infra::rapier_cluster) that takes an extended context with contact events, plus a per-entity collider shape declaration.
• Without these two, Rapier integration is "all entities are uniform spheres with invisible collisions" — fine for tech demo, useless for real games.
• Single PR; tests for each new capability.

Why This Matters

• Contact events make Rapier physics observable to game code — collision damage, item pickup, area triggers, hit detection.
• Per-entity collider shapes make Rapier physics real — capsules for humans, boxes for crates, rather than uniform 0.5-radius spheres.
• Together these are the minimum surface to make Rapier-backed nodes usable for typical action games. Either alone is half-built: contact events without varied shapes give artificial sphere-on-sphere contacts; varied shapes without events leave the game blind to what physics produced.

Scope

• In:
  • New trait RapierClusterSimulation (sibling to ClusterSimulation) with extended context.
  • RapierClusterTickContext<'a> — ClusterTickContext fields plus contact_events: &[ContactEvent].
  • Enum RapierColliderShape — Ball(f32) | Capsule { half_height, radius } | Cuboid([f32; 3]).
  • Method RapierClusterSimulation::collider_for(&self, entry: &EntityStateEntry) -> RapierColliderShape with default impl returning Ball(config.default_body_radius).
  • Constructor RapierClusterSim::with_rapier_sim(...) accepting the new trait.
  • Rapier ChannelEventCollector wired into step_with_accumulator; contacts mapped from ColliderHandle pairs back to entity_id pairs via the existing handle map.
• Out (each its own follow-up issue):
  • Physics commands (impulses, forces, teleports).
  • Raycasts.
  • Joints.
  • Kinematic neighbor proxies (cross-cluster physics visibility).
  • World-bounds policy / boundary colliders.

Action Items

• Define RapierClusterSimulation trait + RapierClusterTickContext in arcane-infra::rapier_cluster.
• Add RapierColliderShape enum + private conversion to ColliderBuilder.
• Add collider_for trait method with default impl.
• Add RapierClusterSim::with_rapier_sim constructor; preserve V1 new constructor.
• Wire contact event collector; map handle pairs back to (Uuid, Uuid) per tick.
• Tests:
  • Two spheres collide → contact event surfaces with both ids and started: true.
  • Two non-overlapping capsules don't generate contacts.
  • Box-on-box stack settles under gravity (sanity check for non-sphere shapes).
  • collider_for is honored at first-sight spawn.
  • Shape change after first-sight is ignored (matches first-sight-only contract from V1; documented).
  • Contact events drained correctly across ticks — no duplicates, no losses, paired started/stopped.
• Update module docs with new trait and shape examples.
• Clippy clean both with and without feature.

Design notes

Why a sibling trait, not extending ClusterSimulation

ClusterSimulation and ClusterTickContext live in arcane-core, which can't depend on Rapier. Extending the existing trait would either pull Rapier into core (no) or make new fields conditional with feature gymnastics that leak into core (no). Sibling trait in arcane-infra::rapier_cluster is clean — the wrapper accepts either trait via separate constructors; users opt in by implementing the richer trait.

Why collider shape is a method, not user_data schema

A method gives full programmatic control (per-entity, per-class, per-state) with zero schema overhead. A schema-driven version remains possible later but isn't needed for this surface.

Why first-sight-only for shape

Same reason as V1's first-sight-only spawn position: changing collider shape mid-life requires destroying and re-creating the body in Rapier. Users who need that go through despawn/respawn — same escape hatch as V1's teleport story.

Industry terms

• Physics tick lifecycle hooks — Unreal PrePhysicsTick / PostPhysicsTick, Bevy PhysicsSet::*.
• Contact event listener / observer — Box2D b2ContactListener, PhysX PxSimulationEventCallback. Standard names; we use them.

Reference

• Parent EPIC: #8 — Cluster physics backends — Unreal (Chaos) first, multi-engine path
• Strategic context: #33 — Engine-specific node types — heterogeneous physics tiers
• Depends on: #117 — Rapier cluster physics: minimum integration
• Architecture doc: docs/architecture/physics-backends-and-unreal.md — §6 entity/body mapping, §9 testing expectations

[martinjms]

🟢 Implemented locally

Commit 664671c on local branch chore/disable-claude-code-ci (sits on top of #117's commit 131b439). Not yet pushed; PR pending the same branch decision as #117.

What landed

• RapierClusterSimulation trait + RapierClusterTickContext — sibling of ClusterSimulation/ClusterTickContext, lives in arcane-infra::rapier_cluster. Public.
• ContactEvent { entity_a, entity_b, started } — collisions mapped from Rapier ColliderHandle pairs back to entity Uuids via a new reverse map. Surfaced in ctx.contact_events: &[ContactEvent].
• RapierColliderShape::{Ball | Capsule | Cuboid} — declared per entity via RapierClusterSimulation::collider_for(&entry, &config). Default impl returns Ball(config.default_body_radius).
• RapierClusterSim::with_rapier_sim(rapier_sim, config) — V2 constructor. V1 new and with_default_config preserved unchanged.
• Internal: private Backend { None, Cluster, Rapier } enum dispatches on_tick. Custom EventHandler (CollisionRecorder) drains CollisionEvents into ContactEvents post-step.
• ActiveEvents::COLLISION_EVENTS set on every spawned collider so contacts surface by default.

Action items — status

• RapierClusterSimulation trait + RapierClusterTickContext defined
• RapierColliderShape enum + private build_collider conversion
• collider_for trait method with default impl
• with_rapier_sim constructor; V1 path preserved
• CollisionRecorder EventHandler installed in step_with_accumulator
• Handle pairs mapped to (Uuid, Uuid) via collider_to_entity reverse map
• All 6 V2 tests pass
• Module docs updated with V2 surfaces, contract, and one-tick-delay note
• Clippy clean both with and without feature
• Push branch and open PR (gated on the same branch decision as #117)
• Review and merge

Tests added

Test	What it verifies
contact_event_surfaces_for_overlapping_spheres	Two overlapping balls → Started event with both ids in next tick's ctx.contact_events
distant_capsules_produce_no_contacts	Capsules 100 units apart → no events across 5 ticks
collider_for_is_honored_at_first_sight	Cuboid([0.7, 0.3, 0.5]) → spawned collider's shape().as_cuboid() has matching half-extents
shape_change_after_first_sight_is_ignored	collider_for returning a different shape on later calls is ignored; assertion: it's called exactly once per entity
contact_events_one_tick_delay_to_user	Tick 1 sees &[], tick 2 sees the contact from tick 1's step
no_duplicate_started_event_for_persistent_overlap	20 ticks of persistent overlap → exactly 1 Started event (edge-triggered)

Verification

Build	Tests	Rapier in dep tree
Vanilla cargo test -p arcane-infra	65 pass (unchanged from #117)	0
--features rapier-cluster	54 lib (24 in rapier_cluster::tests) + 35 integration + 1 doctest	rapier3d v0.32.0
cargo build --bin arcane-cluster (vanilla)	builds	n/a
cargo build --bin arcane-rapier-cluster --features rapier-cluster	builds	n/a
cargo clippy both modes	silent	n/a

Design notes that landed

• Sibling trait, not extension. ClusterSimulation lives in arcane-core which can't depend on Rapier. Adding Rapier types to the existing trait/context would either pull Rapier into core (no) or require feature gymnastics that leak into core (no). Sibling trait in arcane-infra::rapier_cluster is the clean answer — wrapper accepts either via separate constructors.
• Composition all the way down. RapierClusterSim IS-A ClusterSimulation that HAS-A Backend (None | ClusterSimulation | RapierClusterSimulation). Same outer type for run_cluster_loop; backend selection is internal.
• One-tick delay for contact events is intentional, not a workaround. User logic runs first to set intent (V1 contract); physics produces output for next tick. Same-tick post-physics reactivity = future follow-up (split user hook into pre_physics/post_physics).
• First-sight-only shape matches the V1 first-sight-only spawn position. Mid-life shape change requires destroying and re-creating the body in Rapier — users go through despawn/respawn for that, same escape hatch as V1's teleport story.
• Industry terms used: physics tick lifecycle hooks (Unreal PrePhysicsTick/PostPhysicsTick, Bevy PhysicsSet::*), contact event listener / observer pattern (Box2D b2ContactListener, PhysX PxSimulationEventCallback).

Real correctness improvement uncovered by the test suite

The shape_change_after_first_sight_is_ignored test caught a documentation gap: the spec says shape is fixed at first-sight, but the implementation needed an explicit "called exactly once per entity" assertion to prove it. The test now asserts both the contract and the call-count invariant.

Reference

• Parent EPIC: #8 — Cluster physics backends — Unreal (Chaos) first, multi-engine path
• Strategic context: #33 — Engine-specific node types — heterogeneous physics tiers
• Depends on: #117 — Rapier cluster physics: minimum integration (also implemented locally)
• Commit: 664671c (local, on top of 131b439; not yet pushed)
• Architecture doc: docs/architecture/physics-backends-and-unreal.md §6 entity/body mapping