OPERATOR Map Modding Manual

A technical manual for people who build, package, load, and validate custom OPERATOR maps. It uses the current standalone Modded Operations method. It assumes a Windows PC, a legal local OPERATOR installation, Unity, AssetRipper, and exactly one supported IL2CPP loader: BepInEx or MelonLoader.

Worked public implementations:

• OPERATOR: Modded Operations framework
• Ukrainian Forest reference map
• LOT 12 reference map

The framework in this manual is OPERATOR: Modded Operations — Standalone Map Framework. Read the OPERATOR Standalone Map Modding BIBLE before you make a release package.

Current source checkpoint: Modded Operations 0.3.31 with bundled-only Operator Mod API 0.2.0-alpha.7. Shared source builds isolated BepInEx and MelonLoader products; install exactly one variant. Protocol v6 adds fail-closed PVP and PVE content/scene agreement, a host-authoritative PVE enemy-count identity, and restart epochs. These contracts and their automated tests are PROVEN-STATIC, not supported online gameplay. A real host and remote client must still pass the full mode-specific launch, movement, combat, restart, failure, return, and teardown matrix.

Build a map in this order

1. Read the language and evidence rules.
2. Install the tools in docs/00-toolchain.md.
3. Create the workspace in docs/01-workspace-setup.md.
4. Inspect a shipped reference map with docs/02-recon-first.md.
5. Export reference assets, create a clean Unity project, and build a Windows bundle using docs/03a-assetripper-to-bundle.md.
6. Author terrain, full prefabs, foliage, cover, and LOD using docs/03-authoring-native-quality.md.
7. Wire the exact mission row, briefing, preview, infiltration marker, time, bundle, and scene data with docs/03b-modded-operations-presentation.md.
8. Wire PVE or the shipped PvpGameode owner, PVP marker capacity, and exact peer-readiness contract with docs/03c-native-mode-ownership-and-pvp.md.
9. Build the standalone package.
10. Implement the standalone runtime flow.
11. Implement and test first spawn, respawn, collision, and bounds using docs/05-spawn-and-gameplay.md.
12. Build and test AI navigation and routes.
13. Wire native interactive objects with the DoorV2 reference method.
14. Match HDRP, sunlight, volumes, fog, and player-camera fidelity using docs/06-hdrp-and-fidelity.md.
15. Complete the gates in docs/07-validation-and-release.md.
16. Use the exact implementation reference to locate current code, bundles, assets, object names, and verification commands.
17. Trace every authored value through launch, terrain, player, AI, failure, restart, and teardown with the end-to-end package lifecycle.
18. For PVE, implement and prove the native completion, extraction, and ATAK contract.

Runtime paths

For a map selected from the mission laptop and loaded without a retail donor map, use the standalone architecture. Use a strict data-only package, OPERATOR: Modded Operations, and an optional exact-scene map companion for native material repair, navigation, grounding, or other map-specific runtime work. The generic framework reconstructs manifest-declared TerrainData and binds shared render/collision state. Map equations and exact asset repairs do not belong in the generic framework.

The scene/package owns marker coordinates, combat walls, tree families, and PVE minEnemies/maxEnemies. The global hard cap is 100, but every map must publish its smaller evidence-backed certified maximum. The exact-scene companion builds navigation from the authoritative gameplay physics/bullet volume and rejects outside markers before graph lookup. Inactive utility markers remain eligible only when they are navigation-valid and at least 2 m apart in X/Z after snapping. OPERATOR: Modded Operations consumes the declared population range and stays free of map coordinates. Tree-family acceptance also requires close/mid/far player-camera crown silhouettes; structural asset closure alone does not prove foliage quality.

The MapBridge retail-scene overlay method is RETIRED for mission parity. It remains available for explicit local diagnostics. See the archived overlay method.

Public distribution keeps executable runtime files and map data separate. The transactional suite installer selects one loader and installs the exact API, framework, and companion/product set recorded by its manifest, receipt, and sidecar. It does not install, update, remove, or rewrite data-only map packages under OPERATOR/OperatorMods. Map downloads must not duplicate the framework or API. A test transfer is not a release or an online-support claim.

Documentation map

• Technical BIBLE: normative ownership, package, asset, runtime, AI, interactive-object, lifecycle, multiplayer, and release contracts.
• Writing standard: ASD-STE100 language and evidence-status rules.
• 00 Toolchain: required downloads and working order.
• 01 Workspace setup: folder layout and baseline Unity project setup.
• 02 Recon first: inspect the target scene and game systems before changing anything.
• 03 Asset authoring: complete assets, terrain, materials, foliage, grounding, props, and LOD.
• 03a AssetRipper to bundle: reference export, asset closure, map prefab, and StandaloneWindows64 bundle build.
• 03b Modded Operations presentation: exact mission row, briefing, preview-image, infiltration-marker, time-code, bundle-content, hashing, and in-game presentation workflow.
• 03c Native mode ownership: exact PVE/PVP owner boundary, one-based team markers, shipped PvpGameode defaults and references, exact PVP peer agreement, scene generation epochs, lifecycle, teardown, and test gates.
• 04 Runtime integration: standalone ownership, exact load order, readiness, mode owner, restart, and teardown.
• 05 Spawn and gameplay: handoff timing, network player order, and test matrix.
• 06 HDRP and fidelity: sun/Volume ownership, terrain, foliage, and player-camera comparison.
• 15 Native PVE completion: exact extraction marker, native raid/exfil ownership, all-AI-dead unlock, ATAK visual, success screen, restart cleanup, and runtime evidence.
• 07 Validation and release: static, runtime, and in-game gates.
• 08 Troubleshooting: symptom-to-layer guide.
• 09 Interactive prefabs and DoorV2: lost AssetRipper fields, exact object wiring, lifecycle, networking, navigation links, and test matrix.
• 10 Standalone packages: manifest fields, file closure, identity, markers, terrain payloads, and load validation.
• Package JSON Schema: closed machine-readable schema-v1 manifest contract.
• Package JSON Schema v2: schema-v1 fields plus scene variants, the closed PVE-only fixed AI profile, runtime terrain, and the optional closed runtime-companion identity/readiness contract.
• Package manifest template: complete PVE/PVP schema shape with explicit placeholder hashes; read the template instructions before use.
• DoorV2 prefab validator: exact developer-source GUID, component, serialized-reference, reciprocal-handle, pivot, sound-array, and destroyed-door graph checks.
• 11 AI navigation and behavior: playable-only A* graph, marker grounding, fixed PVE profiles, native wander, foliage sight blocking, routes, cover, combat, and restart.
• 12 Asset data contracts: model, pivot, texture, material, foliage, tree-family, terrain, and runtime-audit requirements.
• 13 Exact implementation reference: path tokens, source members, assembly names, bundle names, Ukrainian Forest asset addresses, scene objects, and exact load order.
• 14 End-to-end package lifecycle: complete data-to-runtime flow, exact code members, Forest material and lighting example, failure decisions, restart, teardown, and release proof.
• Archived methods: methods that MUST NOT be used as current standalone release proof.
• Codex skill: reusable instructions for human-supervised AI work on OPERATOR mods.

Install the Codex skill

Copy the complete skills/operator-unity-modding directory to the Codex skills directory. On Windows, the default destination is:

<USER_PROFILE>\.codex\skills\operator-unity-modding\

<USER_PROFILE> means the operating-system user profile directory. Keep this token in public documentation. Do not publish an actual account name.

Keep SKILL.md, agents/openai.yaml, and the references directory together. Start a new Codex task after installation. Invoke the skill as $operator-unity-modding.

Status vocabulary

• Authoring candidate: opens in Unity; not runtime tested.
• Static candidate: bundle and structural checks pass; gameplay not proven.
• Runtime candidate: loads in a normal session; visual/gameplay QA remains.
• Release candidate: normal player-camera, first-spawn, respawn, collision, material, lighting, pre-nav marker containment, playable-only navigation/all-marker grounding, package PVE range, reciprocal combat, close/mid/far foliage silhouettes, restart, teardown, and bounds checks pass. Death/KIA restart remains a separate gate. It MUST use the generic framework's native-compatible mode owner and the shipped failure UI. The map bundle MUST NOT own this UI.

Online PVP and PVE co-op are separate release gates. Each requires two distinct OPERATOR processes to start together with exact suite-receipt and complete package-content agreement. Both peers must leave loading, remain grounded, complete the mode-specific combat flow, Restart, and return cleanly; late join or membership change must be rejected within its bound. PVE additionally must prove the host-selected enemy count, replicated AI, completion, extraction, and the claimed capacity/performance/teardown ceiling. Static agreement tests, a solo or host-only session, and join-in-progress success do not close either gate.

Do not call a map ready because it looks correct in the Unity editor or in a forced-camera capture.