World Physics & Collision Mesh
Relevant source files
The following files were used as context for generating this wiki page:
The World Physics & Collision Mesh system manages terrain support, polygon contacts, and spatial registries for static and live models. It consumes serialized records to build a runtime environment for body contacts, segment queries, and ground support selection. The system prioritizes faithfulness to the original game's physics rules, including specific ranking scales for terrain versus model contacts.
Sources: crates/cyrus-collision/README.md:14-18
Core Collision Architecture
The collision system distinguishes between authored static geometry and mutable live actor states. It prepares initial live static-model geometry independently and retains original candidate orders for mixed ground queries.
Component Relationships
The following diagram illustrates the relationship between asset definitions and the runtime collision structures.
Collision Mesh and Geometry
The CollisionMesh structure prepares authored polygons for queries. It stores validated geometry once during scene loading to support efficient segment and sphere contacts.
Geometry Preparation
Preparation involves validating authored polygons and normals. The system discards version-4 subobjects during runtime preparation to match the original engine's behavior. Version-5 models require extent factors for subobject admission.
Sources: crates/cyrus-collision/src/collision_mesh.rs:101-115, crates/cyrus-collision/README.md:46-48
Key Data Structures
| Structure | Purpose |
|---|---|
CollisionGeometry | Authored model-local polygons, vertices, and subobjects. |
CollisionSubobject | Authored subgroup order with center, radius, and extent factors. |
ModelPose | Stored model-instance transform using original map units and rotation matrices. |
WorldSegmentContact | A contact result with points and normals transformed into world map axes. |
Sources: crates/cyrus-assets/src/collision.rs:102-113, crates/cyrus-collision/src/collision_mesh.rs:25-30, crates/cyrus-collision/src/collision_mesh.rs:40-45
Collision Queries
The system supports various query types, including segments (raycasting), sphere contacts (body volumes), and ground support.
Segment Queries
Segment queries accept map-unit endpoints and preserve static/live face order. The system uses a nearest-even integer adapter for world normals, which rounds points without normalizing the vectors.
Body and Sphere Contacts
Body queries test actor-local spheres against model faces. The system suppresses successful faces across multiple spheres to avoid redundant reporting. It retains the first 32 successful faces; filling this buffer constitutes a successful query.
Sources: crates/cyrus-collision/src/collision_mesh.rs:134-159, crates/cyrus-collision/README.md:73-77
Actor Model Collision
The ActorModelCollision registry manages initial model bindings for actors. It distinguishes between model-less actors and those with prepared geometry.
Features
- Initial Bounds: Derives static-actor extents from original model vertices using nearest-even conversion.
- Collision Flags: Retrieves authored metadata for actors, which is used to determine eligibility for different collision types.
- Surface Materials: Resolves textured contacts to surface codes using
SURFACE.INIassignments. Version-4 and version-5 solid-color contacts resolve to surface zero.
Sources: crates/cyrus-collision/src/actor_models.rs:23-45, crates/cyrus-collision/src/actor_models.rs:91-100, crates/cyrus-collision/README.md:40-45
Ground and Terrain Support
Ground support queries differentiate between terrain and model rankings. If primary support is absent, the system uses a "selected-player fallback" based on support history and the actor's runtime Y-coordinate at the first accepted non-side contact.
Support Selection Logic
- Primary Support: Attempts to select ordinary actor support.
- Fallback: If primary fails, uses the caller's support history state.
- History Updates: Explicit queries commit shared support history, even on misses, to reset fallback timers.
Sources: crates/cyrus-collision/README.md:55-66
Summary
The World Physics & Collision Mesh system provides a faithful implementation of the original game's spatial rules. By using a 32-entry contact buffer, specific ranking for terrain versus models, and nearest-even rounding for world transformations, it ensures deterministic and accurate collision behavior. The system maintains a strict separation between authored assets and mutable runtime states like actor poses and support history.