game-engine-guidelines

Game Engine Guidelines

AI/Cursor MUST follow these rules when writing game engine, renderer, or gameplay systems code. These rules harden correctness, performance, and determinism.

1. Performance & Frame Budget

• Rule: Profile before optimizing; never guess. Every hot path must include measurable metrics (TimeMeasure, GPU timers, counters).
• Rule: Allocators in the render/hot loop are forbidden. Use pool, stack, or arena allocators per frame; reserve at startup.
• Rule: Draw calls are precious. Batch by material/pipeline; cap state changes (SetPipeline/SetShader); prefer instancing and indirect draw.
• Rule: No new/malloc during simulation or render ticks. If code allocates in a tick, it is a review-blocker.
• Rule: Vectors of unique_ptr to polymorphic entities are rejected. Keep component data in contiguous arrays (SoA) and entity IDs index them.

2. Data-Oriented & Cache Design

• Rule: Model CPU cache: elements in hot systems are contiguous, 32-64 byte stride structs; split hot/cold component data into separate arrays.
• Rule: Prefer std::vector<T> + index handles over object pointers in entity systems.
• Rule: Object-oriented hierarchies (Actor base class with virtual Tick()) are allowed only for gameplay-throttled, low-frequency logic; never per-entity per-frame.
• Rule: SIMD is required where a uniform operation runs over many elements (transforms, particle sim). Write scalar reference first, then vectorize.

3. Threading & Determinism

• Rule: The simulation step MUST be deterministic given the same inputs (same seed, same binary, same settings). Never allow wall-clock time, map iteration order, or std::rand() into the simulation.
• Rule: Render jobs, physics, and sim run on a job graph; no thread may block on another for more than a bounded slice.
• Rule: All shared mutable state is owned by exactly one system (ownership), or accessed via atomic/lock-free structures that are benchmarked. Unlocked cross-thread writes = review-blocker.
• Rule: Tick data is never mutated while being read by another thread; use per-frame double buffering or generation counters.
• Rule: Never block the render thread on asset I/O, shader compile, network, or GC.