Initial import: LibreForts (M0-M5 in progress)

Open-source Forts clone: custom C++20 engine + data-driven (Lua) 2D physics
artillery RTS.

- Building: node/strut graph on a stiff mass-spring solver (canon Forts model),
  triangulation rigidity, axial + 30-degree angle-stress breaking, cascading
  collapse, fire (DoT + spread), ground destroys debris.
- Weapons (M4): cannon (ballistic) + laser (beam/ignite) with select-and-aim-in-
  arc UX; splash / beam damage; bg-brace passthrough.
- Devices + economy (M5): reactors + win/loss + restart, mines/turbines/battery,
  metal deposits, storage caps, per-shot energy cost.
- Data-driven via Lua/sol2 with a layered mod loader; enemy-fort scenario mod.
- Renderer: SDL3 + textures + ImGui dev UI. stb_image + ImGui vendored.
- Assets: CC0 placeholders only; real game art loaded at runtime from the user's
  own install via forts: paths (bring-your-own; nothing copyrighted committed).

See README.md / CLAUDE.md and research/ + requirements/ for detail.

1 files changed, 409 insertions, 0 deletions

diff --git a/research/forts-gameplay.org b/research/forts-gameplay.org
new file mode 100644
index 0000000..549c0d1
--- /dev/null
+++ b/research/forts-gameplay.org
@@ -0,0 +1,409 @@
+#+TITLE: Forts — Gameplay Mechanics Research
+#+AUTHOR: Forts Clone Project
+#+DATE: 2025-06-19
+#+OPTIONS: toc:3 num:t
+
+* Overview
+
+Forts is a 2D physics-based real-time strategy game developed by EarthWork Games
+(Australia), released April 19, 2017 on Steam. Over 1 million copies sold, 91-92%
+positive reviews (22,000+). Described as "Worms meets bridge-building meets RTS."
+
+Core tagline: ~Build, research, and blast your opponent's fort to rubble.~
+
+* Core Game Loop
+
+1. Build resource structures (mines on metal deposits, wind turbines for energy)
+2. Construct your fortress from physics-simulated materials
+3. Research the tech tree to unlock weapons and devices
+4. Fortify defenses and position weapons
+5. Fire weapons manually at the enemy's weak points
+6. Destroy the enemy's Reactor (core) to win
+
+The loop is real-time, not turn-based. All construction happens under fire — you
+build and fight simultaneously. The single-pointer multitasking model means
+you're constantly switching between building, repairing, aiming, and managing
+resources.
+
+* Win Conditions
+
+- Primary: Destroy the opponent's Reactor (core)
+- Methods to destroy the reactor:
+  - Direct damage (lasers, cannons, missiles that hit the reactor)
+  - Indirect damage (fire spread, splash damage that reaches the reactor)
+  - Structural collapse (destroying supports so the reactor falls — falling
+    damage destroys it)
+- Some DLC/custom missions add capture-point objectives
+
+* Resources & Economy
+
+**Resources**
+
+| Resource    | How to Obtain                                            | Used For                          |
+|-------------+----------------------------------------------------------+-----------------------------------|
+| Metal       | Mines placed on metal deposits scattered across the map  | Building blocks, weapons, devices |
+| Energy      | Wind turbines (higher placement = more energy)           | Powering weapons, shields, devices|
+| Oil         | Campaign narrative focus, not a direct gameplay resource | Story context                     |
+| Rare Metal   | Moonshot DLC resource for reactor upgrades              | Advanced tech                     |
+
+**Resource Mechanics**
+- Metal is a continuous trickle — more mines = more metal/sec
+- Energy scales with turbine height AND lack of obstruction (build tall, build
+  free of blockage for max efficiency)
+- Energy is stored in Battery devices
+- Metal is stored in Storage devices
+- All construction costs both metal and energy
+- Repairing damaged structures costs resources proportional to damage
+
+* Building & Construction
+
+**Core Building Philosophy**
+- Free-form, real-time construction — not grid-snapped, not pre-placed
+- Every plank, beam, rope, and panel is a separate physics body
+- Structures must be anchored to something stable or they collapse
+- You can build literally any shape and size
+- Construction is a skill — good builders create stable, defensible forts;
+  bad builders create structures that collapse under their own weight or from
+  a single well-placed shot
+
+**Known Building Materials**
+
+Categorized by function:
+
+| Category        | Materials                                    | Properties                         |
+|-----------------+----------------------------------------------+------------------------------------|
+| Structural      | Wooden beams, Metal beams, Planks             | Basic building blocks, have HP     |
+| Reinforcement   | Metal plates, Armor panels                    | Higher HP, resist damage types     |
+| Tension         | Ropes/Cables                                  | Connect points, provide stability  |
+| Defense         | Sandbags, Doors (openable/closable)           | Absorb/redirect damage             |
+| Resource        | Batteries, Metal Storage                      | Store energy/metal buffers         |
+| Functional      | Wind Turbines, Mines, Tech Buildings          | Generate/process resources         |
+
+**Rope/Cable Mechanics (from Chinese wiki)**
+- Cost: 5 metal + 25 energy per cell
+- HP: 50 per segment
+- Vulnerable to: fire, cutting weapons
+- Primary use: suspending cannons, reactors, and heavy structures
+- Provides tension stability — a rope under tension keeps structures upright
+- If a rope is destroyed, whatever it was supporting may collapse
+- Can catch fire and burn through
+
+**Structural Integrity**
+- Every piece has independent physics — not a unified "health bar" for the fort
+- Destroying key support pieces causes cascading collapse
+- A well-placed shot on a load-bearing beam can bring down an entire weapon
+  platform, reactor, or section of the fort
+- This is THE core strategic mechanic — you're not just depleting HP, you're
+  finding and exploiting structural weaknesses
+
+**Building Actions**
+- Build: Place a material piece, costs resources instantly
+- Repair: Fix damaged piece, cost proportional to damage amount
+- Recycle/Delete: Remove piece, recover partial resources
+
+**Physics Properties of Buildings**
+- Gravity applies to everything
+- Pieces have mass, friction, collision shapes
+- Weight distribution matters — top-heavy forts tip over
+- Pieces connected via joints (distance joints, revolute/weld equivalents)
+- Destruction of joints triggers cascading failure
+
+* Combat Systems
+
+**Weapons — 16+ base weapons across base game and DLCs**
+
+| Weapon            | Type        | Characteristics                                    |
+|-------------------+-------------+----------------------------------------------------|
+| Machine Gun       | Hitscan     | High fire rate, low building damage, can shoot down|
+|                   |             | incoming mortars/missiles (point-defense)          |
+| Sniper Rifle      | Hitscan     | Precision, high single-point damage, used to guide |
+|                   |             | Swarm Missiles to target                           |
+| Cannon            | Projectile  | Heavy damage, rips through armor layers            |
+| Mortar            | Projectile  | High building damage, slow projectile, arcing shot |
+| Swarm Missiles    | Guided      | Self-aiming cluster, accurate, tracks targets      |
+| Plasma Laser      | Beam        | Cuts through entire bases in a line, countered by  |
+|                   |             | energy shields                                     |
+| Flak              | Point-Def   | Anti-projectile, shoots down incoming shells       |
+| EMP Missile       | Special     | Disables devices/weapons temporarily               |
+| Minigun           | Hitscan     | Extreme fire rate, suppression                     |
+| Howitzer          | Projectile  | Moonshot DLC — heavy artillery                     |
+| Smoke Bombs       | Utility     | Moonshot DLC — obscures vision                     |
+| Magnabeam         | Beam        | Moonshot DLC — magnetic manipulation               |
+| Buzzsaw           | Melee/Phys  | Moonshot DLC — physical cutting                    |
+| Dome              | Shield      | High Seas DLC — protective energy dome             |
+| Orbital Laser     | Beam        | High Seas DLC — orbital strike                     |
+| Deckguns          | Projectile  | High Seas DLC — naval cannons                      |
+| Naval Missiles    | Projectile  | High Seas DLC — ship-launched missiles             |
+
+**Damage Types**
+- Kinetic (bullets, shells): splashes, penetration
+- Energy (lasers, plasma): cuts linearly, blocked by shields
+- Fire: spreads, burns ropes and wood, continuous damage over time
+- Explosive: area damage, knocks pieces loose, stress damage
+- EMP: disables without physical destruction
+- Physical/Falling: collision damage from collapsing structures
+
+**Aiming Model**
+- All weapons are manually aimed by the player
+- No auto-targeting (except Swarm Missiles and point-defense)
+- Aiming is skill-based — angle, power, and timing matter
+- The sniper uses a 2D scope view
+- Weapons have limited firing arcs based on mounting position
+
+**Defensive Systems**
+- Armor panels: absorb kinetic damage
+- Energy shields: block lasers and plasma
+- Flak: shoot down incoming projectiles
+- Sandbags: cheap damage absorption
+- Machine guns: can be set to point-defense mode
+- Structural redundancy: building with multiple load paths so one broken
+  connection doesn't collapse everything
+
+* Commanders & Factions
+
+**12+ Commanders (base game + DLCs)**
+
+Each commander has unique active abilities and passive traits:
+
+| Commander      | Theme / Playstyle              |
+|----------------+--------------------------------|
+| Warthog        | Aggressive firepower           |
+| Armourdillo    | Defensive resilience           |
+| Shockenaugh    | Cunning/tactical               |
+| Architect      | Building mastery               |
+| (8+ more)      | Various hybrid styles          |
+
+Commanders differentiate playstyles — they're like fighting game characters.
+One player's optimal fort design may be completely different from another's
+based on commander choice.
+
+**Campaign Factions (narrative only)**
+- Eagle Empire (fictional USA)
+- Dragon Army (fictional China)
+- Iron Bear Alliance (fictional Russia)
+- Black Penguin Oil Company (antagonist — private military)
+
+In multiplayer, factions are cosmetic/narrative — the mechanical differentiation
+comes from commander choice.
+
+* Tech Tree & Progression
+
+- Starts with basic weapons and materials
+- Research unlocks progressively more powerful weapons, devices, and materials
+- Two strategic paths:
+  1. Rush tech — invest resources in research, get powerful weapons fast but
+     with a weaker fort
+  2. Turtle — invest in fortification, outlast the enemy, tech up slowly
+- Tech buildings must be physically built on your fort and can be destroyed
+- Weapons Factory: unlocks weapon production
+- Upgrade Center: improves existing weapons (damage, fire rate, etc.)
+- Tech prerequisites create build-order strategy (like StarCraft tech tree)
+- Research costs both metal and energy
+
+* Game Modes
+
+| Mode             | Players      | Description                                   |
+|------------------+--------------+-----------------------------------------------|
+| Campaign         | 1            | 28 missions + tutorial, 3 factions, story     |
+| Skirmish         | 1 vs AI      | 3 AI difficulty levels                        |
+| Multiplayer TDM  | Up to 8 (2 teams) | Each player has own fort & resources      |
+| Multiplayer Co-op| Up to 8 (2 teams) | Team shares base and resources            |
+| Ranked 1v1       | 2            | Bi-monthly seasons, leaderboard, medals       |
+| Sandbox          | 1            | Free build, no enemies, experiment mode       |
+
+- ~70 official maps included
+- Hundreds of community-made maps via Steam Workshop
+- Official tournaments (XXII+ held as of 2022) with prize pools
+- Community tournaments including AI vs AI tournaments
+
+* Maps & Environment
+
+**Map Features**
+- 2D side-view maps
+- Terrain with metal deposit nodes scattered throughout
+- Destructible terrain in some maps
+- Background environments with dynamic elements (17+ dynamic backgrounds in
+  High Seas DLC)
+- Water/physics in High Seas DLC — floating naval forts with buoyancy
+
+**Starting Conditions**
+- Each player starts with a Reactor (core) at a fixed position
+- Initial small fort structure around the reactor
+- Nearby metal deposits for initial mining
+- Symmetric or asymmetric map layouts depending on map design
+
+* Physics & Simulation
+
+**Structural Physics (the game's signature feature)**
+- Every building piece is an independent rigid body
+- Pieces connected via joints (distance joints for ropes, weld joints for
+  attached planks, revolute joints for pivoting structures)
+- Joint breaking triggers cascading destruction — this is the core of
+  the gameplay
+- Stress and strain accumulate on connections
+- Weight distribution matters — unbalanced loading causes tilt and collapse
+- Counterweights can stabilize structures (hanging heavy objects off the
+  opposite side)
+
+**Projectile Physics**
+- Real ballistic trajectories (not hitscan except for machine gun/sniper)
+- Gravity affects all projectiles
+- Splash damage has radial falloff
+- Impact force can knock pieces loose from joints
+- Penetration mechanics — some projectiles punch through multiple layers
+
+**Environmental Physics**
+- Water buoyancy (High Seas DLC) — structures float, ships have hulls
+- Fire propagation — spreads along connected flammable materials
+- Wind affects turbine efficiency
+
+**Determinism**
+- The game uses a deterministic physics simulation for multiplayer
+- Lockstep netcode (inferred — common for physics-based RTS games of this era)
+- Same initial state + same inputs = identical simulation on all peers
+
+* Multiplayer & Netcode
+
+**Multiplayer Structure**
+- Up to 8 players per lobby
+- Two teams (any split: 1v1, 2v2, 3v3, 4v4, 4v2, etc.)
+- Team Deathmatch: separate forts
+- Team Co-op: shared base and resource pool
+- Ranked 1v1 with bi-monthly season resets
+- Leaderboard ranks and cosmetic medal rewards
+
+**Inferred Netcode Architecture**
+- Likely deterministic lockstep: all clients run full simulation, only inputs
+  are transmitted
+- This is standard for physics-heavy RTS games (Age of Empires, Spring RTS,
+  Supreme Commander all use this approach)
+- Bandwidth scales with player count and input rate, NOT entity count — can
+  support massive numbers of physics bodies with tiny packets
+- Downside: one slow connection freezes the game for everyone
+
+**Observed Multiplayer Issues**
+- Community reports mention desyncs and lag in some conditions
+- No ranked matchmaking — new players can match against veterans
+- Bugs and balance issues noted in multiplayer reviews
+
+* Modding System
+
+Forts has a deliberate, first-class modding architecture. This is one of the
+most important sections for designing a clone — Forts' moddability is a major
+reason for its longevity.
+
+**Modding Architecture**
+
+- Layered Lua loading system:
+  1. Base game Lua files load first
+  2. Each active mod's equivalent files load on top
+  3. Mods can override or extend variables and tables from earlier files
+
+- Priority system (1-10, default 5):
+  - Lower numbers load first
+  - Higher numbers load last, have "final say"
+  - Same priority: alphabetical order
+
+**Mod File Structure**
+#+begin_src text
+my_mod/
+├── mod.lua                  # Metadata (name, category, priority, selectable)
+├── db/
+│   └── constants.lua        # Physics constants (gravity, drag, max angles)
+├── devices/
+│   ├── device_list.lua      # Device definitions, costs, prerequisites
+│   └── my_device.lua        # Individual device config
+├── weapons/
+│   ├── weapons_list.lua     # Weapon definitions, fire rates, projectiles
+│   └── projectile_list.lua  # Projectile damage, splash, multipliers
+├── materials/
+│   └── building_materials.lua # Material properties, HP, costs, build times
+└── ui/textures/
+    └── HUD/                 # Custom HUD icons and sprites
+#+end_src
+
+**Key Lua API Functions**
+| Function                       | Purpose                                    |
+|--------------------------------+--------------------------------------------|
+| =table.insert()=                | Add new items to game tables               |
+| =IndexOfWeapon()/IndexOfDevice()=| Find existing item position for insertion  |
+| =FindProjectile()=              | Look up projectile to modify               |
+| =RegisterApplyMod()=            | Schedule function to run after all mods load |
+| =DeregisterApplyMod()=          | Remove previously registered ApplyMod      |
+| =ButtonSprite()/DetailSprite()= | Create HUD sprites from textures           |
+| =InterpolateTable()=            | Interpolate time-keyed data (beam weapons) |
+
+**What Can Be Modded**
+- ✅ New devices (weapons, buildings, tools)
+- ✅ New weapons with custom projectiles
+- ✅ New building materials with custom properties
+- ✅ New projectiles with custom damage/splash/physics
+- ✅ Beam weapons with custom thickness/damage functions
+- ✅ Game balance (costs, damage, build times, production rates)
+- ✅ Physics constants (gravity, drag, max angles)
+- ✅ Visuals (sprites, textures, HUD elements)
+- ✅ Game rules, prerequisites, tech tree requirements
+- ✅ Maps (hundreds of community maps)
+- ✅ AI behavior (AI tournaments exist)
+- ✅ Training missions
+
+**What's NOT Currently Moddable**
+- ❌ Commanders & Factions (special mod type, not Workshop-supported)
+- ❌ Custom campaigns (not yet available)
+- ❌ Environments/backgrounds
+- ❌ Localization/languages
+
+**Modding Tools**
+- Built-in Map Editor
+- VS Code extension: "Forts API extension" (autocomplete, intellisense, docs)
+- Community tools: sprite pivot tools, HUD icon generators, mod starter scripts,
+  structure duplication tools (GitHub: SamsterBirdies/forts-modding-tools)
+
+**Design Lesson for Our Clone**
+The layered Lua loading with priority system is elegant. It allows:
+- Mods to extend (add to tables) or override (replace values)
+- Multiple mods to coexist (priority + alphabetical ordering)
+- Modders to reference other mods' content (RegisterApplyMod runs after all
+  mods load, letting mods modify content added by later-loading mods)
+
+* DLC Content Summary
+
+| DLC              | Price   | Key Additions                                     |
+|------------------+---------+---------------------------------------------------|
+| Moonshot         | $7.99   | 4 weapons, 3 commanders, portals, new gamemode    |
+| High Seas        | $9.99   | Naval forts, buoyancy physics, 6 weapons, campaign|
+| Pro HUD          | $2.99   | UI reskins, new sounds                            |
+| Tons of Guns     | Free    | Large weapon pack                                 |
+| Repair Station   | Free    | Repair robot pet device                           |
+
+* Key Design Takeaways for Our Clone
+
+1. **Physics is THE feature.** The structural integrity system is what makes
+   Forts special. Building isn't cosmetic — it IS the gameplay. Every support
+   beam matters. Every rope under tension is a potential weakness.
+
+2. **Modding from day one.** Forts shipped with Lua modding and Steam Workshop
+   integration. Our clone should design modding into the core architecture,
+   not bolt it on later.
+
+3. **Manual aiming creates skill expression.** RTS + manual aim is unusual and
+   creates a unique skill ceiling. Players who can build well AND aim well
+   dominate.
+
+4. **Resource nodes drive map strategy.** Metal deposits on maps force players
+   to expand and defend territory — prevents turtling being the only strategy.
+
+5. **Commanders create matchup variety.** 12+ commanders with unique abilities
+   means 144+ matchup permutations in 1v1. This is enormous for replayability.
+
+6. **The single-pointer model is a double-edged sword.** Players must multitask
+   building, repairing, aiming, and resource management with one cursor. Our
+   UI needs to make this feel fluid, not frustrating.
+
+7. **Reactor-as-win-condition creates tense moments.** The reactor is fragile
+   and central. Every battle becomes a desperate defense of your own reactor
+   while trying to expose theirs.
+
+8. **2D side-view simplifies the problem space.** You only need to worry about
+   structural physics in 2 dimensions, which makes determinism and netcode
+   much more tractable than a 3D equivalent.