167 lines
3.9 KiB
Markdown
167 lines
3.9 KiB
Markdown
# Copilot Rules — Spacetris (SDL3 / C++20)
|
||
|
||
These rules define **non-negotiable constraints** for all AI-assisted changes.
|
||
They exist to preserve determinism, performance, and architecture.
|
||
|
||
If these rules conflict with `.github/copilot-instructions.md`,
|
||
**follow `.github/copilot-instructions.md`.**
|
||
|
||
---
|
||
|
||
## Project Constraints (Non-Negotiable)
|
||
|
||
- Language: **C++20**
|
||
- Runtime: **SDL3** + **SDL3_ttf**
|
||
- Build system: **CMake**
|
||
- Dependencies via **vcpkg**
|
||
- Assets must use **relative paths only**
|
||
- Deterministic gameplay logic is mandatory
|
||
|
||
Do not rewrite or refactor working systems unless explicitly requested.
|
||
|
||
---
|
||
|
||
## Repo Layout & Responsibilities
|
||
|
||
- Core gameplay loop/state: `src/Game.*`
|
||
- Entry point: `src/main.cpp`
|
||
- Text/TTF: `src/Font.*`
|
||
- Audio: `src/Audio.*`, `src/SoundEffect.*`
|
||
- Effects: `src/LineEffect.*`, `src/Starfield*.cpp`
|
||
- High scores: `src/Scores.*`
|
||
- Packaging: `build-production.ps1`
|
||
|
||
When adding a module:
|
||
- Place it under `src/` (or an established subfolder)
|
||
- Register it in `CMakeLists.txt`
|
||
- Avoid circular includes
|
||
- Keep headers minimal
|
||
|
||
---
|
||
|
||
## Build & Verification
|
||
|
||
Prefer existing scripts:
|
||
|
||
- Debug: `cmake --build build-msvc --config Debug`
|
||
- Release:
|
||
- Configure: `cmake -S . -B build-release -DCMAKE_BUILD_TYPE=Release`
|
||
- Build: `cmake --build build-release --config Release`
|
||
- Packaging (Windows): `./build-production.ps1`
|
||
|
||
Before finalizing changes:
|
||
- Debug build must succeed
|
||
- Packaging must succeed if assets or DLLs are touched
|
||
|
||
Do not introduce new build steps unless required.
|
||
|
||
---
|
||
|
||
## Coding & Architecture Rules
|
||
|
||
- Match local file style (naming, braces, spacing)
|
||
- Avoid large refactors
|
||
- Prefer small, testable helpers
|
||
- Avoid floating-point math in core gameplay state
|
||
- Game logic must be deterministic
|
||
- Rendering code must not mutate game state
|
||
|
||
---
|
||
|
||
## Rendering & Performance Rules
|
||
|
||
- Do not allocate memory per frame
|
||
- Do not load assets during rendering
|
||
- No blocking calls in render loop
|
||
- Visual effects must be time-based (`deltaTime`)
|
||
- Rendering must not contain gameplay logic
|
||
|
||
---
|
||
|
||
## Threading Rules
|
||
|
||
- SDL main thread:
|
||
- Rendering
|
||
- Input
|
||
- Game simulation
|
||
- Networking must run in a **separate thread**
|
||
- SDL main loop must **never block** on networking
|
||
- Cross-thread communication via queues or buffers only
|
||
|
||
---
|
||
|
||
## Assets, Fonts, and Paths
|
||
|
||
- Runtime expects adjacent `assets/` directory
|
||
- `FreeSans.ttf` must remain at repo root
|
||
- New assets:
|
||
- Go under `assets/`
|
||
- Must be included in `build-production.ps1`
|
||
|
||
Never hardcode machine-specific paths.
|
||
|
||
---
|
||
|
||
## AI Partner (COOPERATE Mode)
|
||
|
||
- AI is **supportive**, not competitive
|
||
- AI must respect sync timing and shared grid logic
|
||
- AI must not “cheat” or see hidden future pieces
|
||
- AI behavior must be deterministic per seed/difficulty
|
||
|
||
---
|
||
|
||
## Networking (COOPERATE Network Mode)
|
||
|
||
Follow `network_cooperate_multiplayer.md`.
|
||
|
||
Mandatory model:
|
||
- **Input lockstep**
|
||
- Transmit inputs only (no board state replication)
|
||
|
||
Determinism requirements:
|
||
- Fixed tick (e.g. 60 Hz)
|
||
- Shared RNG seed
|
||
- Deterministic gravity, rotation, locking, scoring
|
||
|
||
Technology:
|
||
- Use **ENet**
|
||
- Do NOT use SDL_net or TCP-only networking
|
||
|
||
Architecture:
|
||
- Networking must be isolated (e.g. `src/network/NetSession.*`)
|
||
- Game logic must not care if partner is local, AI, or network
|
||
|
||
Robustness:
|
||
- Input delay buffer (4–6 ticks)
|
||
- Periodic desync hashing
|
||
- Graceful disconnect handling
|
||
|
||
Do NOT implement:
|
||
- Rollback
|
||
- Full state sync
|
||
- Server-authoritative sim
|
||
- Matchmaking SDKs
|
||
- Versus mechanics
|
||
|
||
---
|
||
|
||
## Agent Behavior Rules (IMPORTANT)
|
||
|
||
- Always read relevant markdown specs **before coding**
|
||
- Treat markdown specs as authoritative
|
||
- Do not invent APIs
|
||
- Do not assume external libraries exist
|
||
- Generate code **file by file**, not everything at once
|
||
- Ask before changing architecture or ownership boundaries
|
||
|
||
---
|
||
|
||
## When to Ask Before Proceeding
|
||
|
||
Ask the maintainer if unclear:
|
||
- UX or menu flow decisions
|
||
- Adding dependencies
|
||
- Refactors vs local patches
|
||
- Platform-specific behavior
|