# Copilot Instructions — Spacetris (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
  - 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/SpacetrisGame/` with exe, DLLs, assets, README, and ZIP; it can clean via `-Clean` and package-only via `-PackageOnly`.

## 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.