docs: define curated tactical sandbox scope

2026-07-04 13:41:13 -05:00
commit f43fa541c0
1 changed files with 201 additions and 0 deletions
@@ -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.