spacetris/.github/copilot-instructions.md

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.