darktide-AutoMark/AGENTS.md

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 <file> 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: when omni_mark is on, candidates come from enumerating smart_tag_system._unit_extension_data (alive, _target_type == "breed", in range) instead of the forward raycast — do NOT use PhysicsWorld.linear_sphere_sweep for this: it returns only a capped table (no count), floods slots with world-geometry actors, and starves real enemies. LOS gates still apply unless omni_mark_ignore_los (settings: omni_mark, omni_mark_ignore_los). With debug_mode on, logs OMNI-DIAG lines: candidate breeds per sweep + per-pass reject reasons.

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 <gamedir>/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).