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.