Initial release: SDL Windows Tetris

.github/copilot-instructions.md

@@ -0,0 +1,44 @@
+# 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.