Player Controller & Movement
Relevant source files
The following files were used as context for generating this wiki page:
The Player Controller and Movement system manages deterministic movement rules, input sampling, and logical actor transformations. It separates player logical transforms from camera transforms and integrates with collision, script, and audio systems to reproduce original game behavior.
The system uses a faithful-by-default policy, ensuring that movement logic, script timing, and animation synchronization match the original engine. It handles complex interactions such as grounded walking, slope sliding, and surface-dependent audio cues.
Sources: crates/cyrus-game/README.md, crates/cyrus-audio/examples/surface_audio.rs:18-35
Movement Architecture
The movement architecture relies on a structured flow where input sampling precedes simulation updates. The game engine processes animation states before resolving physical support and final positions.
Data Flow for Grounded Movement
This diagram shows the sequential update cycle for a grounded player. The system captures the actor's position and surface state before movement to ensure accurate sound emission.
Sources: crates/cyrus-audio/examples/surface_audio.rs:255-315, crates/cyrus-game/tests/player_walking.rs:408-445
Movement Configuration
The system uses MovementSettings to define the physical constraints of the player actor. These values are parsed from original configuration files like SYSTEM.INI, PLAYER.INI, and COMBAT.INI.
| Setting | Type | Description |
|---|---|---|
standing_height | i32 | The vertical offset of the player when standing. |
slide_speed | Option<i32> | Speed at which the player slides down steep slopes. |
turn_speed | u32 | Base rotation speed in engine units. |
turn_max_speed | u32 | Maximum angular velocity during rotation. |
poly_push_units | u32 | Distance the actor is pushed by geometry during collision. |
swim_depth | Option<i32> | The depth threshold for entering a swimming state. |
Sources: crates/cyrus-assets/src/player.rs:6-30, crates/cyrus-assets/src/player_export.rs:24-60
Grounded Movement Logic
Grounded movement is handled by the GroundedWalk and StaticGroundQuery structures. The system performs vertical probes to find support geometry and determines if the actor can stand on the target surface.
Ground Resolution Process
- Support Query: The
StaticGroundQuerysearches for faces and terrain heightmaps under the actor's footprint. - Surface Assignment: If support is found, the system assigns a
SoundSurfaceattribute based on the underlying material (e.g., sand, stone, water). - Veto Check: A "veto" occurs if the slope is too steep or if the collision attributes exclude the current position.
- Height Resolution: The controller updates the vertical component of the actor's
position_q8(Fixed-point Q8 coordinates) to match the supporting geometry.
Sources: crates/cyrus-audio/examples/surface_audio.rs:317-340, crates/cyrus-game/tests/player_walking.rs:205-245
Forward Walking & Animation
Forward movement is tied directly to animation frames. The WalkingStartup component calculates distance based on the active animation group's forward speed attributes.
Collision Handling
The system uses CollisionScene data to manage static interactions. It separates "body" collision (horizontal displacement from walls) from "ground" collision (vertical support).
- Residual Distance: The system calculates the distance required to separate a player from an overlapping wall.
- Classification: Grounded contacts are classified by their normals to determine if they constitute walkable floor or a vertical barrier.
- Quantization: Distance calculations are rounded before map unit shifts to maintain deterministic movement across frames.
Sources: crates/cyrus-game/tests/player_walking.rs:370-390, crates/cyrus-game/tests/player_walking.rs:480-520
Integration with Audio
Movement triggers audio events based on the current surface. The surface_audio example demonstrates how the system captures state for the audio mixer.
- Cue Emission: Sounds are emitted during specific animation stages (
ordinary_animation,forward_animation). - Surface Remapping: The system uses
SURFACE.INIto map collision materials to specific sound effect IDs. - Position Capture: Sound events capture the exact
position_q8of the actor at the moment of emission, which is used for spatial panning and volume attenuation.
Sources: crates/cyrus-audio/examples/surface_audio.rs:455-500, crates/cyrus-assets/src/player_export.rs:90-110
Summary
The Player Controller & Movement system provides a deterministic, fixed-point simulation of actor locomotion. By strictly ordering animation updates, ground queries, and collision responses, the system ensures that movement remains synchronized with visual frames and audio cues while maintaining fidelity to the original game's physical constraints.