player-controller

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.