#+TITLE: Forts Data Directory Map (index of the shipped game files)
#+AUTHOR: LibreForts Project
#+DATE: 2026-07-02
#+OPTIONS: toc:3 num:t

* What this is

An INDEX of how the shipped Forts game data is organised, so we know where to
look when we need a reference value or want to understand a mechanic. It maps a
local install at:

: SteamLibrary/steamapps/common/Forts/data/

This is a structural map only (directory layout, file inventory, purpose). The
game's actual content is EarthWork Games' copyright and lives ONLY on your own
machine; none of it is copied into this repo. We read it at runtime (materials
etc. via `forts:` paths) and distil numbers into
=research/forts-data-reference.org=.

The whole game logic ships as *plain, unpacked Lua* (nothing compiled or packed),
which is why the design is fully readable.

* Totals

- ~6,700 files total, ~2,650 of them =.lua=.
- Art: ~2,380 =.dds=, ~674 =.tga=, ~248 =.png=. Audio: streamed elsewhere.
- What you CANNOT get from here: the compiled C++ engine (solver, renderer,
  netcode) and the binary assets themselves — the Lua only references those.

* Top-level directories

| Dir           | Files | Lua  | What it is                                             |
|---------------+-------+------+--------------------------------------------------------|
| =db/=         |    23 |   18 | Global constants, rules, mod system, sprite atlas defs |
| =materials/=  |   119 |    2 | Building materials data + their textures               |
| =weapons/=    |   270 |   16 | Weapon + projectile definitions + art                  |
| =devices/=    |   288 |   20 | Device definitions (reactor, generators, tech) + art   |
| =scripts/=    |    45 |   44 | Mission condition/action scripts + engine helpers      |
| =ai/=         |    42 |   21 | Skirmish AI logic + prebuilt fort templates            |
| =effects/=    |   498 |  181 | Particle/impact/fire effect defs + their textures      |
| =environment/=|   268 |   53 | Terrain/backdrop themes (alpine, canyon, desert, ...)  |
| =maps/=       |   888 |  328 | Playable maps (~100+), each Lua + preview + heightdata |
| =mods/=       |  2880 | 1867 | ~100 built-in mods (commanders, DLC, disables, cheats) |
| =ui/=         |  1248 |   87 | HUD layout, menus, fonts, icons                        |
| =objects/=    |    15 |    0 | Misc props (art only)                                  |
| =packs/=      |    63 |    0 | Texture atlas packs                                    |
| =shaders/=    |     7 |    0 | GPU shaders                                            |

* The important directories for us (gameplay data)

** db/ — global tuning + framework
- =constants.lua= — THE tuning file: gravity, solver oversampling, spring
  stiffness/damping ranges, stress + angle break thresholds, fire rates,
  extrusion rules, terrain bounce, network/sync. (Distilled in our data-reference.)
- =rules.lua= — game rules / win conditions / resource rules.
- =mods.lua=, =modtools.lua= — the mod loading + priority system and its API.
- =sprites.lua= — sprite/atlas definitions. =version.lua= — build version.
- =*_user.lua= — user-overridable copies. =skins_menu_*.lua= — cosmetic skins.

** materials/ — building materials
- =building_materials.lua= — every material (bracing, background bracing, camo,
  armour, door, energy shield, solar, rope, fuse) with HP, stiffness, mass,
  compression/expansion + angle break limits, min/max/segment lengths, costs,
  flammability + burn/spread rates, and per-projectile/beam collision flags.
- =brace_plates.lua= — cladding plate defs. Rest of the dir is =.tga= textures
  (bracing, armour, cable, damage states).

** weapons/ — weapons + projectiles
- =weapon_list.lua= — the roster + tech prerequisites + costs.
- =projectile_list.lua= — projectile physics/damage/splash for all weapons.
- Per-weapon files: =cannon.lua=, =beamlaser.lua= (plasma laser/firebeam),
  =mortar.lua=, =mortar-incendiary.lua=, =machinegun.lua=, =minigun.lua=,
  =sniper-ap.lua=, =snipertower.lua=, =missilelauncher*.lua=, =missileswarm*.lua=
  (+ inverted variants). Each has fire arc, reload, muzzle speed, damage, sprites.
- Subfolders hold each weapon's art/animation frames.

** devices/ — devices
- =device_list.lua= — the catalog + prerequisites + costs.
- Per-device: =reactor.lua=, =minireactor.lua=, =mine.lua= / =mine2.lua=,
  =windturbine.lua= / =windturbine2.lua=, =battery.lua=, =metal_store.lua=,
  =derrick.lua=, =sandbags.lua=, =explosivebarrel.lua=, =target.lua=, and the
  tech buildings =workshop.lua=, =factory.lua=, =upgradecentre.lua=.
- =ammo_list.lua=, =device.lua=, =device_util.lua= — shared plumbing.

** scripts/ — mission scripting
- ~28 =condition-*.lua= (e.g. connect/disconnect to ground, destroy device
  first, limit shots, efficiency reached, group fired/created) and matching
  action scripts — the building blocks for campaign/tutorial objectives.
- Engine helpers: =campaign.lua=, =mission.lua=, =schedule_call.lua=,
  =interpolate.lua=, =shapes.lua=, =lights.lua=, =music.lua=, =blastdoors.lua=.

** ai/ — skirmish AI
- =ai.lua= — the AI behaviour. =tips.lua= — loading tips.
- =forts/= — a large tree of prebuilt fort TEMPLATES the AI places, categorised
  by terrain (cliff / tall / hanging / ledge / step / vanilla) and range
  (mid/long) and tier (t1/t2). Useful reference for fort-building patterns.

* mods/ — the built-in mod library (~100)

All follow the same layered-override structure (a =mod.lua= manifest with
Priority/Category, plus files mirroring the base tree that mutate the globals).
Categories observed:

- =commander-*= (12): the commanders — each bundles =commander.lua= (ability),
  tweaks to =weapons/=, =materials/=, =db/rules.lua=, portraits, and effects.
- =disable_weapon_*= (29), =disable_tech_*= (5): toggle content off.
- DLC packs (=dlc2=, =dlc3=, moonshot/high-seas content), =weapon_pack=.
- Sandbox/cheat mods: =unlimited-metal/energy(-cap)=, =zerogravity=, =windy=,
  =unlock-all-weapons=, =truce*=, =target-self=, =smooth-recording=,
  =repair_station=.

These are the best worked examples of the modding API in practice (add a
weapon/material/device, tweak balance, override rules).

* effects/ + environment/ + ui/ (support systems)

- =effects/= — ~180 Lua effect defs (impacts, ricochets, explosions, fire,
  smoke, destruction) each pointing at particle textures; how the game wires
  visual feedback to events.
- =environment/= — themed terrain/backdrop sets (alpine, canyon, desert, fields,
  midwest, polluted, training ground, common shared bits).
- =ui/= — HUD/menu layout, fonts, and the large icon set.

* How we use this

1. Need a real value (HP, stiffness, damage, arc, fire rate)? -> the matching
   file above, then record it in =research/forts-data-reference.org=.
2. Studying a mechanic? -> read the relevant =*_list.lua= + per-item file.
3. Building a mod system feature? -> =db/mods.lua= + any =mods/*= as examples.
4. Reference art at runtime? -> =forts:<relative path>= (see CLAUDE.md §5),
   e.g. =forts:devices/windturbine/base.tga=. Nothing gets copied into the repo.