spacetris/UPGRADES.md

Spacetris — Upgrade Roadmap

This document lists recommended code, architecture, tooling, and runtime upgrades for the native SDL3 Tetris project. Items are grouped, prioritized, and mapped to target files and effort estimates so you can plan incremental work.

Short plan

• Audit surface area and break tasks into small, testable PRs.
• Start with low-risk safety and build improvements, then refactors (Gravity/Scoring/Board), then tests/CI, then UX polish and optional features.

Checklist (high level)

• Make NES gravity table constant (constexpr) and move per-level multipliers out of a mutable global
  • Note: FRAMES_TABLE is now immutable inside GravityManager; per-level multipliers are instance-scoped in GravityManager.
• Extract GravityManager (SRP)
  • Note: src/core/GravityManager.{h,cpp} implemented and Game delegates gravity computation to it.
• Replace globals / extern texture usage with StateContext-passed resources
  • Note: popup/background and menu wrappers now accept textures via StateContext; the temporary file_blocksTex bridge was removed. Run grep -R "extern .*SDL_Texture" src/ to confirm no remaining externs.
• [~] Add runtime knobs (gravity multiplier +/-, HUD display) and clamp ranges
  • Note: HUD displays gravity ms/fps; global/level multipliers are exposed via API but runtime keys/persistence are still pending.
• Replace ad-hoc printf with SDL_Log or injected Logger service
  • Note: majority of printf/fprintf debug prints were replaced with SDL_Log* calls; a quick grep audit is recommended to find any remaining ad-hoc prints.
• Add unit tests (gravity conversion, level progression, line clear behavior)
  • Note: a small test runner (tests/GravityTests.cpp) and the tetris_tests CMake target were added and run locally; gravity tests pass (see build-msvc test run). Converting to broader Catch2 suites is optional.
• Add CI (build + tests) and code style checks
• Improve input hit-testing for level popup and scalable UI
• Add defensive guards (clamps, null checks) and const-correctness
• Improve resource management (RAII, smart pointers), and error handling for SDL API calls

---

Rationale & Goals

• Improve maintainability: split Game responsibilities into focused classes (SRP) so logic is testable.
• Improve safety: remove mutable shared state (globals/extern) and minimize hidden side-effects.
• Improve tuning: per-level and global gravity tuning must be instance-local and debug-friendly.
• Improve developer experience: add unit tests, CI, and runtime debug knobs for quick tuning.

---

Detailed tasks (prioritized)

1) Safety & small win (Low risk — 1–3 hours)

• Make the NES frames-per-cell table constexpr and immutable.
  • File: src/Game.cpp (reverse any mutable anonymous namespace table changes)
  • Why: avoids accidental global mutation; makes compute deterministic.
• Move per-level multiplier array from global static to Game instance:
  • Add std::array<double, 30> levelMultipliers inside Game (default 1.0).
  • Change setLevelGravityMultiplier to update instance array and recompute gravityMs.
• Clamp gravity values to a minimum (e.g., 1.0 ms) and clamp multipliers to sensible range (0.1..10.0).

Deliverable: small patch to Game.h/Game.cpp and a rebuild verification.

2) Replace ad-hoc logging (Low risk — 0.5–1 hour)

• Replace printf debug prints with SDL_Log or an injected Logger interface.
• Prefer a build-time #ifdef DEBUG or runtime verbosity flag so release builds are quiet.

Files: src/Game.cpp, any file using printf for debug.

3) Remove fragile globals / externs (Low risk — 1–2 hours)

• Ensure all textures, fonts and shared resources are passed via StateContext& ctx.
• Remove leftover extern SDL_Texture* backgroundTex or similar; make call-sites accept SDL_Texture* or read from ctx.

Files: src/main.cpp, src/states/MenuState.cpp, other states.

4) Extract GravityManager (Medium risk — 2–6 hours)

• Create src/core/GravityManager.h|cpp that encapsulates
  • the constexpr NES frames table (read-only)
  • per-instance multipliers
  • conversion helpers: frames->ms and ms->fps
• Game will hold GravityManager gravity; and call gravity.getMs(level).

Benefits: easier testing and isolated behavior change for future gravity models.

5) Extract Board/Scoring responsibilities (Medium — 4–8 hours)

• Split Game into smaller collaborators:
  • Board — raw grid, collision, line detection/clear operations
  • Scorer — scoring rules, combo handling, level progression thresholds
  • PieceController — piece spawn, rotation, kicks
• Keep Game as an orchestrator that composes these objects.

Files: src/Board.*, src/Scorer.*, src/PieceController.*, adjust Game to compose them.

6) Unit tests & test infrastructure (Medium — 3–6 hours)

• Add Catch2 or GoogleTest to vcpkg.json or as FetchContent in CMake.
• Add tests:
  • Gravity conversion tests (frames→ms, per-level multipliers, global multiplier)
  • Board behavior: place blocks, clear lines, gravity after clear
  • Level progression increment logic and resulting gravity changes
• Add a tests/ CMake target and basic CI integration (see next section).

7) CI / Build checks (Medium — 2–4 hours)

• Add GitHub Actions to build Debug/Release on Windows and run tests.
• Add static analysis: clang-tidy/clang-format or cpplint configured for the project style.
• Add a Pre-commit hook to run format checks.

Files: .github/workflows/build.yml, .clang-format, optional clang-tidy config.

8) UX and input correctness (Low–Medium — 1–3 hours)

• Update level popup hit-testing to use the same computed button rectangles used for drawing.
  • Expose a function that returns vector<SDL_FRect> of button bounds from the popup draw logic.
• Ensure popup background texture is stretched to the logical viewport and that overlay alpha is constant across window sizes.
• Add keyboard navigation for popup (arrow keys + Enter) and mouse hover effects.

Files: src/main.cpp, src/states/MenuState.cpp.

9) Runtime debug knobs (Low — 1 hour)

• Add keys to increase/decrease gravityGlobalMultiplier (e.g., [ and ]) and reset to 1.0.
• Show gravityGlobalMultiplier and per-level effective ms on HUD (already partly implemented).
• Persist tuning to a small JSON file settings/debug_tuning.json (optional).

Files: src/Game.h/cpp, src/main.cpp HUD code.

10) Defensive & correctness improvements (Low — 2–4 hours)

• Add null checks for SDL_CreateTextureFromSurface and related APIs; log and fallback gracefully.
• Convert raw SDL_Texture* ownership to std::unique_ptr with custom deleter where appropriate, or centralize lifetime in a ResourceManager.
• Add const qualifiers to getters where possible.
• Remove magic numbers; define named constexpr constants for UI sizes, softDrop multiplier, DAS/ARR etc.

Files: various (src/*.cpp, src/*.h).

11) Packaging & build improvements (Low — 1–2 hours)

• Verify build-production.ps1 copies all required DLLs for SDL3 and SDL3_ttf from vcpkg_installed paths.
• Add an automated packaging job to CI that creates a ZIP artifact on release tags.

Files: build-production.ps1, .github/workflows/release.yml.

---

Suggested incremental PR plan

1. Small safety PR: make frames table constexpr, move multipliers into Game instance, clamp values, and add SDL_Log usage. (1–3 hours)
2. Global cleanup PR: remove extern textures and ensure all resource access goes through StateContext. (1–2 hours)
3. Add debug knobs & HUD display improvements. (1 hour)
4. Add tests and CMake test target. (3–6 hours)
5. Extract GravityManager and write unit tests for it. (2–4 hours)
6. Extract Board and Scorer (bigger refactor, add tests). (4–8 hours)
7. CI + packaging + formatting. (2–4 hours)

---

Recommended quick wins (apply immediately)

• Convert NES frames table to constexpr and clamp gravity to >= 1ms.
• Replace printf with SDL_Log for debug output.
• Pass SDL_Texture* via StateContext instead of extern globals (you already did this; check for leftovers with grep for "extern .*backgroundTex").
• Add simple unit test that asserts gravityMs(level0) == FRAME_MS * 48 * multiplier.

---

Example: gravity computation (reference)

// gravity constants
constexpr double NES_FPS = 60.0988;
constexpr double FRAME_MS = 1000.0 / NES_FPS;
constexpr int FRAMES_TABLE[30] = {48,43,38,33,28,23,18,13,8,6,5,5,5,4,4,4,3,3,3,2,2,2,2,2,2,2,2,2,1};

// per-instance multipliers in Game
std::array<double,30> levelMultipliers; // default 1.0

double GravityManager::msForLevel(int level) const {
    int idx = std::clamp(level, 0, 29);
    double frames = FRAMES_TABLE[idx] * levelMultipliers[idx];
    return std::max(1.0, frames * FRAME_MS * globalMultiplier);
}

---

Estimated total effort

• Conservative: 16–36 hours depending on how far you split Game and add tests/CI.

Next steps I can take for you now

• Create a PR that converts the frames table to constexpr and moves multipliers into Game instance (small patch + build). (I can do this.)
• Add a unit-test harness using Catch2 and a small GravityManager test.

Tell me which of the next steps above you'd like me to implement now and I will start the code changes.