diff options
| -rw-r--r-- | CLAUDE.md | 3 | ||||
| -rw-r--r-- | research/forts-data-map.org | 131 |
2 files changed, 134 insertions, 0 deletions
@@ -182,5 +182,8 @@ consult it before deciding what to build; don't guess from vibes. - `research/forts-gameplay.org` — gameplay research. - `research/forts-data-reference.org` — **exact numbers** extracted from the game data (physics constants, material/weapon/fire values, modding API). +- `research/forts-data-map.org` — index of the shipped Forts data directory + (layout, file inventory, what each area holds). Use it to find where a + reference value or mechanic lives before diving into the game's Lua. - `research/gameplay-gaps.org` — sourced list of missing systems, prioritized. - `research/tech-stack.org` — locked tech choices and rationale. diff --git a/research/forts-data-map.org b/research/forts-data-map.org new file mode 100644 index 0000000..ccd9335 --- /dev/null +++ b/research/forts-data-map.org @@ -0,0 +1,131 @@ +#+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. |