From c7d22de35288bca4fea85815cd57d315760c91ee Mon Sep 17 00:00:00 2001 From: michael Date: Sat, 3 Oct 2026 06:19:00 -0400 Subject: [PATCH] docs: AGENTS.md with post-update maintenance procedure --- AGENTS.md | 50 ++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 50 insertions(+) create mode 100644 AGENTS.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..f979d03 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,50 @@ +# AutoMark (fork) — maintainer notes + +Fork of AutoMark v2.5.3 (upstream: Shui Yu, Nexus mod #736). Local git only, no remote. + +## Layout + +- `AutoMark/` — the mod tree. All edits happen here. +- `install.sh` — rsyncs `AutoMark/` into the game's `mods/` folder (game dir overridable via `GAMEDIR=`). Takes effect on next game start. +- `breed_dump-YYYY-MM-DD.txt` — snapshots of the live game breed table (see below). + +Game: `/mnt/AetherVault/games/SteamLibrary/steamapps/common/Warhammer 40,000 DARKTIDE` (Proton prefix: `steamapps/compatdata/1361210`, logs at `pfx/drive_c/users/steamuser/AppData/Roaming/Fatshark/Darktide/console_logs/`). + +## Engine/sandbox gotchas + +- The mod sandbox has **no standard `io` library** (`io` is nil). Use `Mods.lua.io` (DMF engine backup). A load-time error here bricks boot with a DMF error screen — guard dev utilities with `pcall`. +- The game bundle (`bundle/`) is chunk-encrypted: **no offline extraction of unit/breed names**. Anything internal must be captured at runtime. +- `luac -p ` is enough syntax checking; game Lua is 5.1-ish with `goto` support. +- Files are CRLF; keep it that way. + +## Targeting architecture (the 5 % you need) + +Breed enumeration is **runtime-driven** from the game's `scripts/settings/breed/breeds` — new enemies/bosses automatically appear in menus and targeting if they pass the filter: `is_minion and unit_template_name == "minion" and smart_tag_target_type == "breed" and faction_name ~= "imperium"` (AutoMark.lua, AutoMark_data.lua). + +Only the exception tables need manual updates. All in `scripts/mods/AutoMark/targeting/custom_targeting.lua`: + +- `ENEMY_EXTENTS` — melee-aim half-extents for big units (fallback = breed's own values, then 0.3) +- `IGNORE_EXECUTION_ORDER_FORCE_MARK_BREED_NAMES` / `IGNORE_EXECUTION_ORDER_PRIORITY_BREED_NAMES` / `IGNORE_THREAT_PRIORITY_BREED_NAMES` — special-mechanic exceptions (netgunner, ritualists, grenadiers, bomber) +- Hard-coded name/behaviour checks: `renegade_netgunner` (sticky targeting), `cultist_ritualist` / `chaos_mutator_ritualist` (ignore-unaggroed exemption), `chaos_poxwalker_bomber` (priority-0 default), dormant-daemonhost logic keyed off the `witch` breed tag +- `360° marking` lives in `find_auto_mark_target_unit`: a full-sphere `linear_sphere_sweep` replaces the forward raycast when `omni_mark` is on (settings: `omni_mark`, `omni_mark_ignore_los`). + +## Procedure after a game update + +1. Launch the game once. `mods/AutoMark/breed_dump.txt` is (re)written silently on every mod load by `mod:dump_breeds()` in `utils/utils.lua`. +2. Snapshot it: `cp /mods/AutoMark/breed_dump.txt breed_dump-YYYY-MM-DD.txt` in the repo (rsync --delete wipes the installed copy on reinstall, so save it!). +3. Diff against the previous snapshot: + - new/removed/renamed breeds (renames = stale hard-coded names to fix) + - `filter=false` taggable-looking units (filter needs extending) + - boss-tier changes, new `tags=`, `pounce=` changes + - new `witch`-tagged bosses get `_passive` priority automatically; new special-mechanic units (think netgunner/ritualist/bomber analogues) need the `IGNORE_*` lists +4. Check for crashes/`[MOD][AutoMark][ERROR]` lines in the newest console log. +5. `luac -p` every touched file, commit, `./install.sh`. + +## Known open questions + +- `renegade_wizard` (new lord boss, no `witch` tag): if it can't be pinged while unaggroed, give it the dormant-daemonhost treatment in `is_dormant_daemonhost`. +- Karnak Twins (`renegade_twin_captain` / `_two`): auto-handled as bosses so far; revisit if the link-mechanic breaks marking. + +## History + +- 2026-10-03: forked; added 360° omni marking + silent breed dumper; verified all hard-coded breed names against live dump (`breed_dump-2026-10-03.txt`). \ No newline at end of file