From f43fa541c0f0ab72b5308776381f46f62d111e91 Mon Sep 17 00:00:00 2001 From: Keith Solomon Date: Sat, 4 Jul 2026 13:41:13 -0500 Subject: [PATCH] docs: define curated tactical sandbox scope --- ...6-07-04-curated-tactical-sandbox-design.md | 201 ++++++++++++++++++ 1 file changed, 201 insertions(+) create mode 100644 docs/superpowers/specs/2026-07-04-curated-tactical-sandbox-design.md diff --git a/docs/superpowers/specs/2026-07-04-curated-tactical-sandbox-design.md b/docs/superpowers/specs/2026-07-04-curated-tactical-sandbox-design.md new file mode 100644 index 0000000..9798cdd --- /dev/null +++ b/docs/superpowers/specs/2026-07-04-curated-tactical-sandbox-design.md @@ -0,0 +1,201 @@ +# BattleForge Curated Tactical Sandbox + +## Purpose + +BattleForge's first release will validate its central promise: users can create a +small tactical scenario and play it as a complete game. The MVP balances simple +creation tools with tactically meaningful combat while avoiding the infrastructure +and complexity of a general-purpose game engine. + +The release is intended for early playtesting by people interested in creating +and playing lightweight tabletop-style skirmishes. + +## Success Criteria + +The MVP succeeds when a new user can, without developer assistance: + +1. Start from a bundled scenario and complete a local match. +2. Create two valid teams from provided unit templates. +3. Build and validate a battlefield. +4. Save the resulting scenario and start a match from it. +5. Complete a match with an unambiguous winner. + +The combat must offer meaningful choices through positioning, terrain, unit +roles, and action use. It does not need to support arbitrary user-authored rules. + +## Primary User Flow + +1. Choose a bundled scenario or create a new one. +2. Assemble two teams from curated unit archetypes. +3. Customize unit names, images, and bounded stats. +4. Paint terrain, place objectives, and define deployment zones on a square grid. +5. Select a supported victory condition and validate the scenario. +6. Begin a local hot-seat match. +7. Alternate team turns until the rules engine declares a winner. +8. View the result, then replay or return to an editable copy of the scenario. + +## In Scope + +### Curated Content + +- Four distinct unit archetypes: defender, striker, support, and scout. +- Three fixed special abilities: healing, area damage, and a temporary buff. +- Five terrain types: open ground, forest, rough ground, water, and blocking + terrain. Each type has fixed movement and defensive effects. +- A bundled top-down or pixel-art asset library for units, structures, and + terrain. +- Three ready-made scenarios that allow users to play without first using the + editors. + +### Team Editor + +- Build exactly two opposing teams of three to six units each. +- Add units from curated archetype templates. +- Customize unit names and display images. +- Adjust health, attack, defense, and speed within enforced limits. +- Assign only abilities allowed by the selected archetype. +- Validate team size, stat bounds, and required fields before play. + +### Battlefield Editor + +- Create a square-grid battlefield from 8 by 8 through 16 by 16 tiles. +- Paint predefined terrain tiles using a drag-and-drop or paint-style interface. +- Place one non-overlapping deployment zone for each team. +- Place objectives when required by the selected victory condition. +- Reject scenarios with invalid deployment zones, inaccessible required + objectives, or missing required elements. + +### Scenario Rules + +- Choose one of two victory conditions: + - eliminate every opposing unit; or + - control a designated objective for a configured number of complete rounds. +- Save, load, duplicate, edit, and delete scenarios associated with the current + anonymous browser installation. No sign-in or cross-device access is provided. +- Start each match from an immutable snapshot of its source scenario so later + scenario edits cannot alter an active match. + +### Turn-Based Combat + +- Local hot-seat play for two people sharing one device. +- Alternating team turns with a clear handoff screen between players. +- Two actions per unit on its team's turn. An action can be spent to move, make a + standard attack, or use one curated ability; a unit cannot attack or use an + ability more than once per turn. +- Grid-based movement and targeting with legal destinations and targets shown in + the interface. +- Terrain-based movement costs and defensive modifiers. +- Health, damage, defeat, temporary effects, round progression, objective + control, and victory detection. +- Match-scoped resources only. All action allowances and temporary resources + reset according to the match rules and never persist between matches. +- A result view identifying the winner and satisfied victory condition. + +### User Assets + +- Optional image upload for custom unit art. +- Strict server-side checks for allowed image types and maximum file size. +- A bundled placeholder is used when an uploaded image is absent or unavailable. + +## Explicitly Out of Scope + +- User accounts, cloud synchronization, or cross-device persistence. +- Online multiplayer, invitations, matchmaking, notifications, and spectators. +- Leaderboards, rankings, achievements, or social features. +- Computer-controlled opponents. +- Campaigns, narrative progression, persistent resources, purchases, or unit + upgrades between battles. +- Arbitrary formulas, scripting, programmable abilities, or a general rules + editor. +- Public scenario sharing, collaborative editing, an asset marketplace, or + moderation systems. +- Isometric rendering, animation-heavy presentation, or simultaneous support for + multiple visual perspectives. +- Dedicated native mobile applications or a mobile-first battle interface. + +These capabilities may be considered after playtesting demonstrates that the +creation-to-combat loop is valuable. + +## System Boundaries + +The MVP will be implemented as one web application with four clearly separated +modules: + +1. **Content library:** owns curated unit archetypes, abilities, terrain, and + bundled asset metadata. +2. **Scenario editor:** owns scenario authoring, validation feedback, and local + scenario management. +3. **Rules engine:** authoritatively validates actions and resolves movement, + targeting, combat, effects, turns, objectives, and victory. +4. **Battle interface:** renders match state and submits player intent without + independently deciding whether an action is legal. + +The rules engine must not depend on browser presentation code. This boundary +allows a future online service or AI player to use the same rule behavior without +rewriting combat. + +## Data and Action Flow + +1. The editor produces a validated scenario containing team definitions, grid + tiles, deployment zones, objectives, and victory settings. +2. Starting play creates an immutable match snapshot plus mutable match state. +3. The active player selects an action in the battle interface. +4. The rules engine validates the action against the authoritative match state. +5. A valid action is resolved and recorded in an ordered action log; an invalid + action leaves match state unchanged and returns a user-facing reason. +6. The rules engine advances unit, team, and round state as required and checks + the configured victory condition. +7. The interface renders the resulting state or the final match result. + +The action log is part of local match state for debugging and deterministic rule +verification. Replay visualization is not required in this MVP. + +## Validation and Failure Handling + +- Editors prevent play until all blocking validation errors are resolved. +- Invalid movement, attacks, abilities, and targets are disabled when practical; + rejected requests also return a concise explanation. +- A rejected action never partially changes match state or consumes resources. +- Failure to save a scenario or match is reported without discarding the user's + in-memory work. +- Missing user images fall back to a bundled placeholder and do not invalidate a + scenario. +- Corrupt or incompatible saved data is rejected safely and cannot start a + partially initialized match. + +## Security and Quality Requirements + +- Every state-changing form or request uses and verifies a nonce before mutation. +- All input is sanitized and validated at the application boundary. +- All rendered output is escaped for its output context. +- Uploaded images are validated by content as well as filename extension and are + stored so they cannot execute as application code. +- PHP follows the repository PHPCS rules and passes PHPStan at level 6 or higher. +- JavaScript passes ESLint using `airbnb/base` and Prettier checks. +- Composer configuration passes `composer validate`. + +## Verification Strategy + +- **Unit tests:** movement, range, line and area targeting where applicable, + damage and defense, ability effects, terrain modifiers, turn transitions, + objective control, and both victory conditions. +- **Integration tests:** scenario validation; save/load round trips; match snapshot + creation; action validation and state mutation; upload rejection and fallback + behavior; nonce verification. +- **End-to-end smoke test:** create teams, build a valid battlefield, save the + scenario, start a hot-seat match, perform legal actions, and reach a declared + winner. +- **Manual usability check:** a new tester completes both a bundled match and a + custom scenario without developer guidance. + +Lint, static analysis, unit and integration tests, the end-to-end smoke test, and +Composer validation are required CI checks. The MVP is releasable only when all +checks pass. + +## Release Boundary + +The MVP is complete when every in-scope capability and success criterion is met, +the verification suite is green, and no out-of-scope platform capability is +required to build or finish a local match. Feedback from this release will decide +whether the next investment should deepen combat, expand creation tools, add AI, +or introduce asynchronous online play.