path: root/requirements/v0.1-core.org

#+TITLE: Forts Clone v0.1 — Core Requirements
#+AUTHOR: Forts Clone Project
#+DATE: 2025-06-19
#+OPTIONS: toc:3 num:t

* Purpose

v0.1 exists to prove the core loop: build a fort, place weapons, and destroy
an enemy reactor through physics-based structural damage. No multiplayer.
No AI. No commanders. Just the fundamental building↔physics↔destruction
feedback loop working end-to-end.

* Resources

Two resources only. No tech tree — everything is available from the start.

** Metal
- Gathered via Mines placed on metal deposits in the terrain
- Deposits are fixed nodes on the map — a mine on a deposit produces metal at
  a constant rate
- Metal is consumed when placing building pieces and weapons
- If you run out of metal, you cannot build

** Energy
- Generated by Wind Turbines placed on your fort
- Turbine output scales with:
  - Height above terrain (higher = more energy)
  - Lack of obstruction around the turbine (clear air = more energy)
- Energy is consumed when placing building pieces and weapons
- If you run out of energy, you cannot build

* Building Materials

** Wood (Normal Bracing)
- Primary structural building material
- Opaque: projectiles CANNOT pass through it
- Guns cannot shoot through wood bracing — it blocks line of fire for both
  the player and hypothetically for enemies
- Has HP — takes damage from cannon shells, lasers, and fire
- Flammable: can be set on fire by laser or cannon (chance-based)
- When HP reaches zero, the piece is destroyed
- When a load-bearing piece is destroyed, connected pieces may collapse
  (Box2D joint destruction → cascade)
- Costs: metal + energy (exact values TBD during implementation)
- Appears as a solid plank/beam visually

** Background Bracing
- Structural building material — provides support just like wood
- Translucent/façade: structures behind it are visually hidden from the
  opponent (in v0.1, this is mostly cosmetic since there is no opponent)
- Projectiles pass THROUGH background bracing — it does NOT block shots
- Guns CAN shoot through background bracing (it doesn't block line of fire)
- Has HP — takes damage from cannon shells and lasers
- Flammable: fire-spreading weapons (laser, cannon) set fire to it
- When HP reaches zero, the piece is destroyed
- When destroyed, any structures it was hiding become visible
- Costs: metal + energy (likely cheaper than wood since it doesn't block
  projectiles — TBD)
- Appears as a visually distinct, lighter/more transparent plank

** Ropes
- Tension element connecting two points
- Provides structural stability — keeps structures from tipping over
- Does NOT block projectiles (they pass through ropes)
- Has HP (low compared to wood)
- Vulnerable to: fire (can burn through), cannon splash damage
- If a rope is destroyed, the structure it was stabilizing may collapse
  (tension is released → connected bodies may fall)
- Implemented via Box2D =b2DistanceJoint=
- Costs: metal + energy (cheap per segment — ropes are primarily for
  structural engineering, not defense)
- Appears as a thin line/cable visually

** Material Property Summary

| Property              | Wood Bracing | Background Bracing | Ropes       |
|-----------------------+--------------+-------------------+-------------|
| Blocks projectiles    | ✅ Yes       | ❌ No             | ❌ No        |
| Blocks line of fire   | ✅ Yes       | ❌ No             | ❌ No        |
| Provides structure    | ✅ Yes       | ✅ Yes            | ✅ Tension   |
| Flammable             | ✅ Yes       | ✅ Yes            | ✅ Yes       |
| HP (relative)         | High         | Medium            | Low          |
| Hides structures      | ❌ No        | ✅ Yes            | ❌ No        |

* Weapons

** Cannon (Artillery)
- Type: arcing projectile (affected by gravity)
- Aiming: player sets angle and power, fires on click
- Projectile: cannon shell with ballistic trajectory
  - Travels in an arc (Box2D body under gravity)
  - On impact: deals damage in a small splash radius
  - Knockback: applies force to bodies near impact point
  - Structural damage: can break joints near impact
- Chance to set fire: ~20-30% chance on impact to ignite the struck piece
  (fire then spreads to connected flammable materials)
- Firing rate: slow (e.g., 1 round per 2-3 seconds)
- Good against: structures, wooden walls
- Counter: Flak gun can shoot down cannon shells in flight
- Costs: metal + energy to build the cannon device on your fort

** Flak Gun
- Type: point-defense, hitscan or very fast projectile
- Aiming: automatic or manual? (TBD — auto-targeting incoming projectiles in
  a cone/radius, or player aims at incoming shells)
- Purpose: shoots down incoming cannon shells before they impact
- Cannot damage buildings (or does very little building damage)
- Firing rate: moderate/high (needs to be able to intercept cannon shells)
- Placement matters: must have line of sight to incoming projectiles
  (cannot shoot through wood bracing, CAN shoot through background bracing
  and ropes)
- Costs: metal + energy to build

** Laser
- Type: Line-of-Sight beam weapon
- Aiming: player draws a line from the laser turret to target point
- The beam traces through:
  - Empty space: passes freely
  - Background bracing: passes through (doesn't block)
  - Ropes: passes through
  - Wood bracing: blocked — beam stops at first wood piece hit
- Damage: low continuous damage to whatever piece it hits (or low damage
  per tick while beam is active)
- Fire starter: 100% chance to set the struck piece on fire (if flammable)
  — this is the laser's primary purpose
- Beam duration: fires for a short burst (e.g., 0.5-1 second) then goes on
  cooldown
- Cannot penetrate normal wood — the beam stops at the first wood surface
- Good against: starting fires in enemy structures, burning through ropes
  and background bracing, igniting key support pieces
- Costs: metal + energy to build

** Weapon Summary

| Weapon   | Damage | Fire? | Blocks Projectiles? | Penetrates Bg. Bracing? |
|----------+--------+-------+---------------------+--------------------------|
| Cannon   | High   | ~25%  | Flak can intercept   | Yes (arcing shot)        |
| Flak Gun | Low    | No    | N/A (defensive)      | Yes (hitscan within arc) |
| Laser    | Low    | 100%  | N/A (stops at wood)  | Yes (beam passes through)|

* Reactor

- The win/loss condition for both the player and the dummy fort
- A large, relatively fragile device placed at the core of each fort
- Has HP — when HP reaches zero, that side loses
- Can be damaged by:
  - Direct cannon shell hits
  - Fire reaching the reactor (spread from burning connected pieces)
  - Falling/collision damage if the reactor's supports are destroyed and
    it falls
- Player's reactor starts at a fixed position on the left side of the map
- Dummy reactor starts at a fixed position on the right side of the map
- Visually distinct — glows, pulses, or is marked clearly
- Costs: free (starts pre-placed on the map)

* Fire System

- Fire starts when:
  - Laser hits a flammable piece (100% ignition chance)
  - Cannon shell impacts a flammable piece (~20-30% ignition chance)
- Once ignited, a piece burns:
  - Takes damage over time (HP decreases per tick)
  - Fire spreads to adjacent connected flammable pieces (via Box2D joint
    graph — check neighboring bodies)
  - Burning pieces produce visual fire particles and smoke
  - Ropes burn faster than wood (lower HP, fire kills them quickly)
- Fire does NOT spread through empty space — only along joint connections
  between flammable bodies
- A piece destroyed by fire releases its joints, potentially causing
  structural collapse
- Fire can reach and damage the reactor if connected through flammable
  structure
- Extinguish? Not in v0.1 — once something is burning, it burns until
  destroyed. (Future: repair tool extinguishes fire.)

* Physics

- Box2D v3 simulation at fixed timestep (60Hz)
- Every building piece (wood, background bracing) is a =b2Body= (dynamic)
- Terrain/map geometry is =b2Body= (static)
- Joints:
  - Weld joints connect adjacent building pieces (rigid attachment)
  - Distance joints represent ropes (maintain fixed distance between two
    anchor points)
- Gravity: standard downward gravity (~9.8 m/s² in world units)
- Projectiles: dynamic =b2Body= with initial velocity, affected by gravity
- Impact forces: cannon shells apply =b2Body::ApplyLinearImpulse= to nearby
  bodies on detonation
- Joint breaking: when a body is destroyed (HP reaches zero), its attached
  joints are destroyed → connected bodies may fall
- =b2DestructionListener= triggers game-side logic (spawn debris particles,
  mark connected bodies for stability check, fire spread check)
- Structural collapse emerges naturally from the physics — if enough
  supports are destroyed, structures fall

* Map

** Layout
- 2D side-view
- Fixed-size playfield (e.g., 200m wide × 100m tall in world units)
- Left side: player's starting area
  - Player reactor pre-placed at a fixed position
  - Small starter structure around the reactor (a few wood planks forming
    a basic shell)
  - 2-3 metal deposits near the player's side
- Right side: dummy enemy fort
  - Dummy reactor pre-placed at a fixed position
  - Pre-built fort structure around the reactor (wood bracing walls, some
    background bracing panels hiding the reactor, a few rope supports)
  - Intended as a target to shoot at — the dummy has enough structure to
    demonstrate the physics/destruction/fire systems
  - 2-3 metal deposits near the enemy side
- Terrain: simple ground plane with some unevenness/hills
- Metal deposits: visible ore nodes embedded in terrain

** Visual Style
- Simple, functional — colored rectangles/sprites for building pieces
- Distinct colors for: wood (brown), background bracing (lighter brown/
  beige, semi-transparent), ropes (dark line), metal deposits (gray/silver),
  reactor (glowing red/orange)
- Sky/gradient background (simple)
- This is v0.1 — programmer art is fine. Aesthetics can wait.

* Game Mode: Target Practice (v0.1)

** Setup
- Single player on the left side
- Dummy fort on the right side (pre-built, no AI, no player controlling it)
- The dummy does NOT: build, shoot back, repair, or take any action
- The dummy fort is a static structure — it just sits there

** Player Actions
- Build: place wood, background bracing, and ropes on your fort
  - Drag to place beams/planks (TBD: exact building UX)
  - Click points to connect ropes
- Place weapons: build cannon, flak gun, and laser on your fort
  - Weapons are placed like building pieces but have an aim direction
- Aim & Fire:
  - Cannon: click and drag to set angle/power, release to fire
  - Laser: click and drag to draw beam path, fires along line
  - Flak gun: active passively? Or player aims at incoming shells?
    (TBD — simplest v0.1 approach: flak automatically shoots at cannon
    shells within its arc/range)
- Manage resources: build mines on deposits, build wind turbines for energy
- Repair: damaged structures can be repaired for a resource cost
  (TBD: repair tool or automatic?)

** Win Condition
- Destroy the dummy reactor
  - Reduce its HP to zero via direct hits, fire, or structural collapse

** Lose Condition
- Your own reactor is destroyed
  - In v0.1 with no enemy AI, this can only happen if you damage your own
    reactor (unlikely) or your fort collapses onto it (possible if built
    poorly)

** No Win/Lose Condition (Stretch)
- The game simply continues — there's no victory screen yet. When a reactor
  dies, it explodes/dissolves visually. Press R to restart.

* Camera & Controls

** Camera
- 2D orthographic projection via bgfx
- Camera pans with mouse (drag middle-mouse or scroll to edge)
- Zoom with scroll wheel (zoom in/out to see details or full battlefield)
- Default view: centered on the map, showing both forts

** Controls (Mouse + Keyboard)
| Action            | Input                        |
|-------------------+------------------------------|
| Pan camera        | Middle-mouse drag or arrow keys |
| Zoom              | Scroll wheel                 |
| Select build mode | Number keys (1=wood, 2=bg.brace, 3=rope, 4=cannon, 5=flak, 6=laser) |
| Place piece       | Click (in build mode)        |
| Cancel build      | Right-click or Escape        |
| Aim weapon        | Click (in weapon mode)       |
| Fire weapon       | Release after aim, or click  |
| Repair            | Right-click on damaged piece |
| Recycle/delete    | Shift+click on piece         |
| Restart            | R key                        |

* What is Explicitly OUT of Scope for v0.1

- Multiplayer (no networking needed)
- AI opponents (dummy fort is entirely passive)
- Commanders
- Tech tree
- Damage types beyond fire + kinetic (no EMP, no shields)
- Particle effects beyond basic fire/smoke
- Sound (can be added but not required — focus on gameplay)
- UI beyond basic resource counters and build mode indicators
- Save/load
- Replays
- Mod loading (Lua infrastructure can be in engine but no mods to load yet)
- Menu system (just drop into the game on launch)
- Win/loss screens (reactor explodes, press R to restart)

* Development Priorities (Build Order)

1. Windowing + rendering (SDL3 + bgfx — get a triangle on screen)
2. 2D sprite batcher on bgfx (colored quads for building pieces)
3. Box2D world + basic bodies (static terrain, dynamic plank)
4. Build mode: click to place a plank (creates Box2D body + renders sprite)
5. Resource system (mines, turbines, metal/energy counters)
6. Multiple connected pieces (weld joints, structural integrity)
7. Ropes (distance joints, tension visualization)
8. Cannon + projectile physics (spawn shell, ballistic arc, impact)
9. Flak gun (shoot down cannon shells)
10. Laser (line trace, fire ignition)
11. Fire system (HP-over-time, spread along joints, visual feedback)
12. Reactor + win/loss check
13. Dummy fort (pre-built target structure on the right side)
14. Camera (pan, zoom)
15. Repair + recycle
16. Polish pass (visual clarity, controls feel, edge cases)

* Open Design Questions (Resolve During Implementation)

- [ ] Building UX: drag-to-place beams? Click start + end points? Grid snap
  or freeform?
- [ ] Cannon aiming: click on your cannon + click target point? Or angle/
  power slider?
- [ ] Flak gun behavior: fully automatic within an arc? Or player manually
  targets incoming shells?
- [ ] Laser duration: continuous beam while holding click? Or fixed-duration
  burst?
- [ ] Resource rates: how much metal per mine per second? How much energy per
  turbine? (Tune during playtesting)
- [ ] Piece HP values: how many cannon hits to destroy wood? Background
  bracing? Ropes?
- [ ] Building piece sizes: fixed sizes (1m, 2m, 4m beams)? Or freeform drag?
- [ ] Does fire spread upward preferentially? (Heat rises — fire climbing up
  a structure is more dangerous than fire going down)
- [ ] Can you build pieces that intersect? Or is placement blocked by existing
  bodies?
- [ ] Repair cost: proportional to missing HP? Flat cost?