| name | player-controller |
| description | Documents PlayerControllerPlugin and InputPlugin, detailing how movement interacts with the procedural terrain. |
Player Controller Architecture
The movement system is decoupled into two plugins: InputPlugin.ts for raw hardware event gathering, and PlayerControllerPlugin.ts for physics and terrain clamping.
1. InputPlugin.ts
A lightweight singleton manager that listens to keydown, keyup, and mouse events.
- Maintains a
keys dictionary representing the current active state of movement keys (W, A, S, D, Shift, Space).
- Normalizes mouse deltas for camera rotation.
2. PlayerControllerPlugin.ts
The logic engine that translates input into physical movement.
Kinematics
- Velocity & Acceleration: Uses a physics-based approach with acceleration, friction, and max velocity vectors to ensure smooth acceleration and deceleration, rather than rigid snapping.
- Camera Coupling: The Three.js
camera is attached to a dummy object. Mouse input rotates the dummy object (yaw) and the camera's pitch, creating a standard First-Person/Third-Person view matrix.
Terrain Interaction
Because the terrain is procedural and completely displaced on the GPU, the CPU does not naturally know where the ground is.
- Height Polling: The plugin queries
TerrainSystem.getTerrainHeightAt(x, z).
getTerrainHeightAt Implementation: The TerrainSystem looks up the specific pixel in the CPU-side Float32Array generated by the GraphGenerator, calculates the exact triangular barycentric interpolation for smooth slopes, and returns the height.- Clamping: The player's
y position is constantly clamped to max(terrainHeight, waterLevel) + playerHeight. This prevents the player from clipping through mountains or sinking below the ocean floor.
Key Interactions
- Heavily reliant on
TerrainSystem for collision data. If the graph rebuilds, the player must immediately snap to the new height.
