football/docs/specs/2026-05-08-physics-dynamics-design.md

Design: Physics & Puck Dynamics (M2)

Goal

Implement basic physical properties for the puck to make movement feel natural: gradual slowing down (friction) and energy loss upon hitting boundaries (restitution).

Architecture

The physics logic will be integrated into the World.Update loop. Constants for physical properties will be defined to allow easy tuning of the game feel.

Implementation Details

1. Physical Constants

The following constants will be introduced:

• PuckFriction: Multiplier applied to velocity every frame (e.g., 0.99).
• PuckRestitution: Multiplier applied to velocity upon boundary collision (e.g., 0.8).
• StopThreshold: Minimum velocity magnitude below which the puck is forced to a complete stop (e.g., 0.1).

2. Movement Logic (World.Update)

The update loop for the puck will follow these steps:

1. Apply Friction: velocity = velocity * PuckFriction.
2. Stop Check: If length(velocity) < StopThreshold, then velocity = (0, 0).
3. Position Update: position = position + velocity.
4. Boundary Collision:
   • If the puck hits a boundary (considering its radius):
     • Invert the velocity component perpendicular to the boundary.
     • Multiply the resulting velocity by PuckRestitution.
     • Correction: Snap the puck's position to be exactly on the boundary edge to prevent it from getting stuck inside the wall.

Success Criteria

• The puck gradually slows down and eventually stops.
• The puck loses speed after bouncing off the walls.
• The puck does not get stuck in the boundaries.