45 lines
2.9 KiB
Markdown
45 lines
2.9 KiB
Markdown
# Copilot Instructions — Tetris (C++ SDL3)
|
||
|
||
Purpose: Speed up development on this native SDL3 Tetris. Follow these conventions to keep builds reproducible and packages shippable.
|
||
|
||
## Project shape
|
||
- C++20 app using SDL3 + SDL3_ttf via vcpkg.
|
||
- Build system: CMake; Windows-focused, but portable with proper toolchain.
|
||
- Sources: `src/` (Game.cpp, Scores.cpp, Starfield*.cpp, Audio.cpp, LineEffect.cpp, Font.cpp, SoundEffect.cpp, main.cpp).
|
||
- Assets: `assets/` (images/music/fonts), plus `FreeSans.ttf` at repo root.
|
||
|
||
## Build and run
|
||
- Configure and build Release:
|
||
- CMake picks up vcpkg toolchain if found (`VCPKG_ROOT`, local `vcpkg/`, or user path). Required packages: `sdl3`, `sdl3-ttf` (see `vcpkg.json`).
|
||
- Typical sequence (PowerShell): `cmake -S . -B build-release -DCMAKE_BUILD_TYPE=Release` then `cmake --build build-release --config Release`.
|
||
- Packaging: `.\build-production.ps1` creates `dist/TetrisGame/` with exe, DLLs, assets, README, and ZIP; it can clean via `-Clean` and package-only via `-PackageOnly`.
|
||
- MSVC generator builds are under `build-msvc/` when using Visual Studio.
|
||
|
||
## Runtime dependencies
|
||
- Links: `SDL3::SDL3`, `SDL3_ttf::SDL3_ttf`; on Windows also `mfplat`, `mfreadwrite`, `mfuuid` for media.
|
||
- The package step copies `SDL3.dll` and `SDL3_ttf.dll` from `vcpkg_installed/x64-windows/bin/` if present. If changing triplet or layout, update paths in `build-production.ps1`.
|
||
|
||
## Key modules and responsibilities
|
||
- Game loop and state: `Game.cpp/h` (core), `main.cpp` (entry), `Scores.cpp/h` (high-scores/local), `LineEffect.cpp` (row clear visuals), `Starfield.cpp` and `Starfield3D.cpp` (background effects), `Audio.cpp` + `SoundEffect.cpp` (music/SFX), `Font.cpp` (TTF text rendering).
|
||
- Keep drawing and update timing consistent; prefer updating effects modules rather than inlining in `Game.cpp`.
|
||
|
||
## Assets and fonts
|
||
- Expect `assets/` folder adjacent to the executable; `FreeSans.ttf` is copied next to the exe by packaging scripts.
|
||
- When adding assets, ensure packaging script includes new folders/files; use BMP/PNG consistently with existing loaders.
|
||
|
||
## Conventions
|
||
- C++20, no exceptions policy not enforced; match current code style in each file.
|
||
- Use SDL_ttf for text; don’t vendor fonts in code—load from filesystem as done in `Font.cpp`.
|
||
- Avoid hardcoding absolute paths; rely on relative paths within the package layout.
|
||
|
||
## Useful files
|
||
- `CMakeLists.txt` — targets, toolchain detection, link libs.
|
||
- `vcpkg.json` and `vcpkg-configuration.json` — dependencies and registry.
|
||
- `build-production.ps1` — authoritative packaging steps and expected layout.
|
||
- `cmake/ProductionBuild.cmake` — extra flags if needed (included by `CMakeLists.txt`).
|
||
|
||
## When extending
|
||
- Add new modules under `src/` and register them in `CMakeLists.txt` target sources.
|
||
- If new DLLs are required, extend the copy list in `build-production.ps1` and document them in the generated README.
|
||
- Validate with a Release build before packaging to catch optimizer-related issues.
|