BattleForge/docs/superpowers/specs/2026-07-04-curated-tactical-sandbox-design.md

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.