Capture mode config
中文 | English
Run this command at the repository root to replay the examples through the local Unity MCP.
python Docs/Manual/manual/tools/tutorials.py run capture-mode-config
A capture zone mode config describes the zones, capture points, per-zone spawns and zone connectivity used by a capture-zone battle. It is a CaptureZoneModeConfig JSON stored under the config root and packed into binary config data at build time.
1. Prepare the map scene
- Complete Set the Steam game folder so the Editor can read the game's
LuaProjectassets. - For a DIY map, follow Import a DIY map into the Unity project and load the YAML into the base playground. For an official or other non-DIY map, just open the desired scene in the Editor.
- Keep the scene open while editing. Point placement and the Refresh Position (NavMesh) button sample the NavMesh of the open scene, so the map must already have its NavMesh in place.
2. Create the config
- Open Framework - 框架 → 2. Config - 配置文件.
- In the creation form, choose Config Path. The dropdown lists the config paths stored in the framework settings; the value also decides which folder tree the config appears in.
- Choose the serialized config type CaptureZoneModeConfig.
- Enter a File Name and click Create Config. An empty file name only shows an error dialog, so fill it first. The file name does not need an extension.
- The tool writes
<config root>/CaptureZone/<name>.jsonand assigns a fresh GUID internally. Do not copy GUIDs from another file.
The created object has these fields, and they serve different purposes:
| Field | Purpose |
|---|---|
captureZoneName |
Internal identifier. Use a distinct, unique ID; do not reuse one across configs. |
displayName |
User-facing localized name shown to players. |
mapGuid |
Runtime map identifier. Use the MapData GUID for regular maps and the Defined Name for DIY maps. |
backgroundCameraTransformInfo |
Optional camera position and rotation for the map background view. |
The Editor menu tree lists the file as <config path folder>/CaptureZone/<file name>, and selecting it opens the capture zone editor for that file.
3. Set the map GUID and background camera
- In the zone editor, the Map Guid row shows the current value (empty shows
—). Click Use Current Scene to fill it from the map data that is discoverable for the active scene. - For a regular map, check the saved value against the GUID in MapData. For a DIY map, enter the exact Defined Name (
definedName) from the imported YAML, including spaces and punctuation. The game registers the DIY map under that name. - The background camera is optional. Click Set Bg Camera while the Scene view is framed the way you want, and it stores that camera position and rotation. Leave it at zero if the mode does not need a background camera.
4. Add capture zones
- Click + New Zone in the editor panel or the scene overlay. The zone is added at the current scene view point with a placeholder
pointName(Zone_<n>) and a default radius of 30. - Click the zone label to select it, then fill in:
pointName— must be unique. Zone chains resolve zones by this string, so renaming a zone means updating the chains too.- Position and Radius — the capture point and capture circle.
- Default Owner — initial team owner, or
nonefor neutral.
- Build the perimeter with +Pt / -Pt on the selected zone.
zonePointsis the perimeter polygon that defines the zone area; it is separate from the capture point position and radius. Place perimeter points on walkable ground and use Refresh Position (NavMesh) and Merge Nearby Points to snap and tidy them. - Repeat for every zone. A small map usually needs 2-3 zones; do not invent extra zones just to fill the array.
5. Add per-zone spawns
- Select the zone and click Show Spawn (older builds labelled it Edit), then + to add a spawn marker.
- A numbered marker appears. Click it to select that spawn and move or rotate it with the scene handles. The values are saved in the zone's
spawnTransformInfosand can also be edited in the serialized fields. - Choose clear drivable poses: on or next to the ground, facing the intended direction, and not inside walls, props or other vehicles. Refresh Position (NavMesh) snaps spawn positions to the navmesh and zeroes pitch and roll, which helps but still needs a visual check.
- Click Hide Spawn when done to declutter the scene view.
6. Add zone chains
- Add entries to
zoneChains, using A and B with the samepointNamestrings that exist on the zones. - Connect only the neighbours that the map design intends to be connected. The runtime
CaptureZoneGameMode.Setup.csreadsfromZoneas a prerequisite neighbour fortoZone, so each entry is directional. Add both directions only when the map design really allows travel both ways. - Check every link: names must resolve to existing zones. Unresolved names are silently skipped at runtime and are not drawn by the editor, so a typo simply removes the connection.
7. Save, pack and test
- Save the config.
- Add the saved capture-zone JSON to Config file in the map mod's build pipeline. Select the target platform and build the mod package. The pipeline converts the JSON into configuration data and includes it in the
.modpack. Use the map build workflow for the scene itself. - For a local export of the configuration data, click Pack All Configs. This rebuilds
Build/Configand writes the capture-zone data toBuild/Config/capturezone/<config GUID>.bytes. - Install the built mod and start a capture battle on the target map. Check the zones, their spawn points, and the order in which the teams can advance.
The example checks the configuration for Tutorial Town with two regions, Depot and Ridge. The chain in the example permits progression from Depot to Ridge. It writes and verifies a local .bytes file.
Click to expand MCP actionsClick to collapse MCP actions
[
{
"tool": "invoke",
"arguments": {
"path": "static:ShanghaiWindy.Core.AssetBundleManager/LuaEnv/DoString",
"args": [
"return assert(loadfile(\"../../Docs/Manual/tutorials/capture-mode-config/example.lua\"))()",
"docs-capture",
"null"
]
},
"expect": {
"contains": "Capture mode JSON and .bytes export verified"
}
}
]