| name | game-math-and-simulation |
| description | Use when a game system needs explicit vector, matrix, quaternion, geometry, interpolation, collision, camera, steering, probability, or numerical-simulation rules; use gameplay-systems-architecture for ownership and the engine skill for API integration. |
| metadata | {"portable":true,"compatible_with":["claude-code","codex"]} |
Game Math and Simulation
Turn mathematical intent into named coordinate spaces, explicit units, stable numerical methods, deterministic oracles, and player-visible behaviour that survives variable frame time.
Prerequisites
Load the approved mechanic or rendering requirement, gameplay-systems-architecture, and the selected engine skill before choosing engine-specific types or APIs.
Use When
- Specifying movement, aiming, cameras, animation blending, steering, trajectories, collision, procedural placement, spatial queries, simulation, or shader mathematics.
- Debugging jitter, drift, tunnelling, gimbal-like rotation defects, unstable springs, frame-rate dependence, or incorrect coordinate conversions.
- Writing deterministic mathematical test oracles for gameplay, tools, or rendering.
Do Not Use When
- The task is system ownership, persistence, or event architecture without a mathematical defect; use
gameplay-systems-architecture.
- The task is render-pipeline, material, or GPU design; use
real-time-game-graphics and return here for the mathematical contract.
- A built-in engine primitive already satisfies the requirement and profiling/tests show no gap; do not replace it with bespoke mathematics.
Inputs
| Artefact | Produced by | Required? | Why |
|---|
| Mechanic or visual behaviour specification | game design/system owner | yes | Defines player-visible intent and limits |
| Coordinate, unit, time and precision context | engine/physics/rendering owner | yes | Prevents space, scale and timestep ambiguity |
| Failure cases and acceptance criteria | testing owner | yes | Makes the result testable |
| Target-device performance evidence | mobile-game-performance | conditional | Bounds numerical and query cost |
Workflow
- State the player-visible behaviour before selecting a formula.
- Name every coordinate space, handedness, axis convention, unit, time source, angle unit, range and precision assumption.
- Choose the smallest mathematical model that represents the behaviour; prefer engine-tested primitives when their contract fits.
- Separate simulation state from presentation smoothing. Use fixed-step simulation where rule consistency requires it and render interpolation where visual continuity requires it.
- Define boundary conditions, tolerances, degenerate inputs, clamping, normalisation, random seeds and recovery from non-finite values.
- Work representative examples by hand, then encode property, boundary, invariant and frame-rate-independence tests.
- Instrument the result with debug vectors, paths, bounds, state graphs or numeric traces; profile worst-case queries on target devices.
Quality Standards
- Treat local, world, view, clip, screen, UV and tangent spaces as different types even if the engine represents them with the same structure.
- Keep units explicit. Convert at boundaries; do not scatter scale factors through gameplay code.
- Use dot products for alignment/projection questions, cross products for perpendicular/orientation questions, and quaternions for composed 3D orientation without exposing raw components to designers.
- Compare floating-point results with requirement-derived tolerances, never blanket exact equality or an unexplained epsilon.
- Preserve determinism only where the product needs replay, save reconstruction, lockstep, seeded tests, or auditability; record platform limits.
Decision Rules
| Need | Preferred model | Gate |
|---|
| Constant-rate rule simulation | Fixed timestep plus bounded catch-up | Same input sequence gives equivalent state across tested render rates |
| Visual smoothing only | Interpolation or critically damped response | No rule state is authored from smoothed presentation |
| 3D orientation composition | Normalised quaternion through engine API | No Euler accumulation; shortest-path behaviour tested |
| Fast moving collision | Sweep/continuous query or smaller bounded step | Tunnelling case passes at maximum specified speed |
| Random but reproducible content | Explicit seeded stream per owning system | Save/replay and test sequence remain stable |
Capability Contract
Read and search access to the requirement and implementation are required. Execute tests and visual/debug captures when available. Editing follows the parent implementation scope; without execution, return the model and unverified test vectors rather than claiming correctness.
Degraded Mode
If the engine version, scale, timestep, or coordinate convention is unknown, stop formula-level implementation. Return the missing contract fields, provisional equations, and the exact experiments required to resolve them.
Anti-Patterns
- Mixing local and world vectors. Fix: name conversion boundaries and assert the expected space.
- Multiplying movement by both fixed and render delta time. Fix: assign one time domain to each state update.
- Euler-angle accumulation for arbitrary 3D orientation. Fix: compose rotations with engine quaternion operations and test wrap boundaries.
- Normalising a zero-length vector. Fix: define the zero-input behaviour before the operation.
- Magic epsilon everywhere. Fix: derive tolerances from game scale, solver precision and the observable acceptance condition.
- Random calls from shared global state. Fix: give each deterministic system an owned, serialisable random stream.
- Complex custom collision before profiling built-in queries. Fix: prove the engine primitive is insufficient first.
Outputs
| Artefact | Consumed by | Acceptance condition |
|---|
| Mathematical behaviour contract | gameplay/rendering implementation | Spaces, units, time, equations, limits and degeneracies are explicit |
| Worked test vectors and invariant suite | game-testing-polish | Normal, boundary, degenerate and frame-rate cases have deterministic oracles |
| Debug and profiling plan | engine/performance owners | The result can be inspected and its worst-case cost measured |
References
Read Next
Use real-time-game-graphics for shader/rendering integration, the selected engine skill for implementation, and game-testing-polish for balance and player-facing verification.
