AI Assistant Developer Guide

AI Assistant Developer Guide

This page is written for Codex, Claude and future coding agents.

Always Start Here

For the canonical boot order (AGENTS.md → CLAUDE.md → collaboration protocol/json/events → git status/branch/remote) use LLM agent entry pack. Two rules gate every edit on this page: treat Missions/[55-2hc]warfarev2_073v48co.chernarus as the mission source for gameplay edits, and use Arma 2 OA external reference guide / Arma 2 OA compatibility audit and Bohemia Interactive Arma 2 OA scripting docs, never Arma 3.

Safe Edit Rules

• Edit source mission files under Chernarus, then run dotnet run -c RELEASE in Tools/LoadoutManager to propagate to all three maintained terrains (CH → TK + ZG). Omitting -c RELEASE defaults to DEBUG.
• After LoadoutManager runs, restore any version.sqf.template drift to merge-base before staging.
• Verify TK and ZG generated output: TK=61 players (no naval), ZG=61 players (STARTING_DISTANCE 5000). ZG-specific constants live in a worldName == "Zargabad" guard block (lines 85–97) inside Common/Init/Init_CommonConstants.sqf; no separate Init_Zargabad.sqf or Zargabad_EdgeGuard.sqf files exist. Key identifiers from that block: WFBE_C_AICOM_HQSTRIKE_MIN_TOWNS, WFBE_C_AICOM_ENGAGE_MIN_TOWNS, WFBE_C_BASE_EGRESS_MAP_BOUNDS.
• Do not edit generated Takistan/Zargabad/modded mission folders as the primary source of truth.
• SQF edits on Windows: use targeted Python scripts (read/replace/write preserving CRLF). The Edit/Write tools trigger a formatter that reflows entire files — this produces diff churn across every line and makes review impossible.
• Do not change live-server modes, extension/database behavior, or anti-stack behavior without explicit confirmation.
• Keep diffs small in server init, PVF registration, economy and purchase/spawn paths.
• Preserve WF_Debug-gated logging style for debug detail and use small always-on INFORMATION/WARNING logs only for tester-visible state transitions.

Common Pitfalls

• Arma 2 OA SQF differs from Arma 3; avoid using newer commands unless verified for OA 1.64. Full list: Agent Guide trap taxonomy.
• remoteExec, CfgFunctions-era assumptions and Arma 3-only command variants are not valid drop-ins for this mission's OA-era PV/PVEH model.
• inline private _x = is A3-only and silently kills the enclosing script in OA. Use private ["_x"].
• NSSETVAR3 trap: missionNamespace setVariable [name, value, true] (third argument) causes A2/OA runtime error. Check with check_sqf.py --select NSSETVAR3.
• getVariable [name, default] on a GROUP receiver does not return the default in OA; use WFBE_CO_FNC_GroupGetBool or 1-arg + isNil. See Group-Bool-GetVariable-A2OA-Trap-Reference.
• If a doc mentions Arma 3 terms, classify the hit with Arma 2 OA compatibility audit before treating it as implementation advice.
• HC RPT vs server RPT: AICOM team events log to the HC RPT (ArmA2OA.RPT), not arma2oaserver.RPT. Scope reads to the current MISSINIT boundary.
• Hosted server paths often need local handler calls as well as public-variable dispatch.
• Client-side UI/marker loops are performance-sensitive.
• publicVariable payloads can become a network performance issue.
• addEventHandler stacks handlers; reusable vehicles/units need guards or stored handler IDs before adding another handler.
• setVariable [..., true] publishes object/group state, but it does not make client-written authority data trustworthy.
• LoadoutManager has very deep paths; Windows clones may require Git core.longpaths=true.
• 7za missing does not block copy-only generation, but does block packaging. Use A2WASP_SKIP_ZIP=1 for propagation-only runs.

Feature Work Checklist

• Locate the authoritative function registration in Init_Common.sqf, Init_Client.sqf, Init_Server.sqf or Init_PublicVariables.sqf.
• For Auth/PV, economy, victory, supply or BattlEye-sensitive patches, read Hardening implementation roadmap and Server authority migration map before editing. For attack-wave work, also read Attack-wave authority playbook; it records the direct-PV DR-41 failure and the current all-side-supply spend model.
• For any gameplay patch, record the validation level using Testing workflow and agent-test-plan.schema.json. Mark source-only review separately from in-game smoke tests.
• Identify whether state is client-owned, server-owned, common config or generated tool data.
• Add or reuse constants in Init_CommonConstants.sqf only when the value is truly shared.
• For networked features, prefer Common_SendToServer, Common_SendToClient or Common_SendToClients.
• Cross-check engine behavior in Arma 2 OA external reference guide when touching public variables, PVEHs, object vars, event handlers, object scans, JIP waits, UI marker loops or performance instrumentation.
• Run/read targeted searches for duplicate hardcoded arrays before adding new ones.
• Verify with source mission first, then propagate generated mission folders.

High-Value Search Patterns

rg -n "WFBE_C_MY_FEATURE|MyFeature|publicVariable|addPublicVariableEventHandler" Missions/[55-2hc]warfarev2_073v48co.chernarus
rg -n "Compile preprocessFile|execVM|execFSM" Missions/[55-2hc]warfarev2_073v48co.chernarus
rg -n "TODO|FIXME|DoNotUse|GAME_CRASH|disabled|commented" Missions/[55-2hc]warfarev2_073v48co.chernarus Tools

Recommended Verification

• For documentation-only changes: link check and diff review.
• For mission code changes: run dotnet run -c RELEASE in Tools/LoadoutManager; tolerate missing 7za only for packaging. Run check_sqf.py --select A3CMD,A3MARKER,A3REVEAL,A3SELECT,A3SORT,A3STRING,GROUPGETVAR,BRACKET,NSSETVAR3 --no-classname-index before every PR.
• For performance changes: collect RPT with Performance Audit and run Tools/PerformanceAuditAnalyzer. AICOM team events go to the HC RPT (ArmA2OA.RPT), not arma2oaserver.RPT; scope reads to the current MISSINIT boundary.
• For network changes: test dedicated-server and hosted/local branches if the code has isServer, isDedicated, isHostedServer or local player conditions.

For the complete HARD rule set, trap taxonomy, and claim protocol, see Agent Guide.

Continue Reading

Previous: Arma 2 OA compatibility audit | Next: Agent context

Main map: Home | Fast path: Quickstart | Agent file: agent-context.json