Crawls (crawls/)

This page describes level-local crawl data.

Crawl data defines off-road trail gameplay through companion files for trails, paths, boundaries, and starting positions. Some crawl missions can also carry mission-local crawl files under gameplay/missions/.

File location

Level crawl data is stored under:

levels/<levelName>/crawls/

Common file names:

<crawlName>.trail.json
<crawlName>.path.json
<crawlName>.boundary.json
<crawlName>.startingPosition.json
presets.json

The crawl save/load system recognizes files by suffix. Keep the suffixes exact:

.trail.json
.path.json
.boundary.json
.startingPosition.json

Creating crawl files with editor tools

Use the Crawl Data Editor for new crawl content when possible. It writes the companion files in the format expected by the crawl system.

Recommended workflow:

1. Open the level in World Editor.
2. Open the Crawl Data Editor.
3. Create or edit the path by placing route nodes along the intended trail.
4. Add recovery checkpoint flags where the player should be able to recover.
5. Create a boundary that contains the intended route.
6. Create a starting position and verify its icon position.
7. Save the path, boundary, starting position, and trail files to levels/<levelName>/crawls/.
8. Test the crawl from a fresh start and recovery point.

If you are converting older race/path data, use the conversion tools first, then manually review the generated files.

Writing crawl files manually

Manual authoring works best when you create the companion files in this order:

1. *.path.json
2. *.boundary.json
3. *.startingPosition.json
4. *.trail.json

The trail file should be last because it references the other files.

Minimal folder layout:

levels/<levelName>/crawls/example.path.json
levels/<levelName>/crawls/example.boundary.json
levels/<levelName>/crawls/example.startingPosition.json
levels/<levelName>/crawls/example.trail.json

Use matching base names where possible. Matching names are not strictly required, but they make authoring and debugging much easier.

File roles

Trail references

A trail file links the companion files together with fields such as:

{
  "pathId": "/levels/example/crawls/example.path.json",
  "boundaryId": "/levels/example/crawls/example.boundary.json",
  "startingPositionId": "/levels/example/crawls/example.startingPosition.json"
}

Use level-rooted paths and keep referenced files in sync when renaming a crawl.

Trail files are the highest-level crawl files. They do not usually contain the full path or boundary inline; they point at the companion files. This makes it possible to reuse or swap path, boundary, or starting position data, but it also means broken references can make an otherwise valid crawl invisible or unusable.

When writing a trail manually, start with only the required references and add optional metadata later:

{
  "name": "trail.example.title",
  "pathId": "/levels/example/crawls/example.path.json",
  "boundaryId": "/levels/example/crawls/example.boundary.json",
  "startingPositionId": "/levels/example/crawls/example.startingPosition.json",
  "pathReversed": false
}

Add preview, thumbnail, rules, and prefabs after the trail loads successfully.

*.trail.json fields

Path files

Path files store ordered route nodes. Nodes can include:

• A display/debug name.
• Position.
• Rotation.
• Radius.
• Flags such as recovery checkpoint data or side padding.

The path should follow the intended driving direction. If a trail supports reverse driving, prefer using explicit reverse settings rather than duplicating nearly identical paths unless the reverse route needs different checkpoints.

For hand-written paths:

• Keep nodes ordered from start to finish.
• Use readable node names.
• Use larger radii for difficult off-road sections.
• Add recovery checkpoint flags where failing would be frustrating.
• Test with the slowest and largest vehicles expected for the crawl.

Minimal *.path.json:

{
  "name": "example_path",
  "description": "Example crawl path",
  "nodes": [
    {
      "name": "Start",
      "position": [0, 0, 0],
      "rotation": [0, 0, 0, 1],
      "radius": 4,
      "flags": {}
    },
    {
      "name": "Checkpoint 1",
      "position": [20, 0, 2],
      "rotation": [0, 0, 0, 1],
      "radius": 5,
      "flags": {
        "isRecoveryCheckpoint": true,
        "recovery": 1
      }
    }
  ]
}

*.path.json fields

Boundary files

Boundary files define the playable area for the crawl. Keep the boundary generous enough for normal driving mistakes, but not so large that players can bypass the intended challenge.

If the boundary clips the route, players may fail or reset unexpectedly. If it is too loose, the crawl may lose its challenge definition.

Create boundaries in the editor where possible. Manual boundary editing is error-prone because vertex order and placement matter.

Minimal *.boundary.json shape:

{
  "name": "example_boundary",
  "vertices": [
    [0, -10, 0],
    [100, -10, 0],
    [100, 10, 0],
    [0, 10, 0]
  ],
  "bot": {
    "active": false,
    "normal": [0, 0, -1],
    "pos": [0, 0, -10]
  },
  "top": {
    "active": false,
    "normal": [0, 0, 1],
    "pos": [0, 0, 10]
  },
  "customFields": {
    "names": {},
    "tags": {},
    "types": {},
    "values": {}
  }
}

The boundary format is shared with site zone serialization. If possible, create it through the Sites or Crawl tools.

Starting position files

Starting position files define where the player starts or recovers. They commonly include:

• A transform position.
• A transform rotation.
• A radius.
• An icon position for UI or map display.

Place starts on stable, flat-enough ground and test them with the vehicle classes expected for the crawl.

When writing manually, remember that iconPosition is for UI/map display and is not necessarily the same as the actual spawn transform.

Minimal *.startingPosition.json:

{
  "name": "Example Start",
  "description": "Start for the example crawl",
  "transform": {
    "position": [0, 0, 1],
    "rotation": [0, 0, 0, 1],
    "radius": 5
  },
  "iconPosition": [0, 0, 3],
  "metadata": {
    "created": "2026-06-08",
    "modified": "2026-06-08"
  }
}

*.startingPosition.json fields

Mission-local crawl data

Some crawl gameplay lives under modern mission folders:

gameplay/missions/<levelName>/crawl/<missionName>/

Mission-local crawl data can use the same concepts as level-local crawl data. Check the mission folder before assuming all crawl files are in levels/<levelName>/crawls/.

Conversion notes

Some crawl files are converted from older race.race.json data. Converted files often keep descriptions such as “Converted from race.race.json”. After conversion, treat the generated path, boundary, trail, and starting-position files as the active crawl data.

When converting, review the result manually. Converted path node names, recovery checkpoints, side padding, and boundaries may be technically valid but still need gameplay tuning.

Presets

presets.json is editor/tooling data. It can store reusable crawl authoring presets and should be kept with the level only when those presets are useful for future editing.

Do not rely on presets as gameplay data. The active crawl should be represented by the trail, path, boundary, and starting-position files.

Troubleshooting

Trail does not appear

Check:

• The file suffix is .trail.json.
• The trail references existing pathId, boundaryId, and startingPositionId files.
• The referenced paths are level-rooted and use the correct level name.
• The feature or mission that should expose the trail is enabled.

Player spawns badly

Check:

• The starting position transform is on the intended ground surface.
• The rotation faces the first section of the route.
• The radius is appropriate for the vehicle size.
• The icon position is not confused with the actual spawn transform.

Crawl fails unexpectedly

Check:

• The boundary contains the intended driving line.
• Recovery checkpoint flags are placed where needed.
• Path node radii are large enough for the route.
• Mission-local files are not overriding or replacing level-local data.

Validation checklist

• *.trail.json references valid path, boundary, and starting-position files.
• *.path.json has ordered nodes with reasonable radii and rotations.
• *.boundary.json covers the intended route and does not clip normal driving.
• *.startingPosition.json points to a safe spawn/recovery position.
• Preview and thumbnail paths exist when used.
• Mission-local crawl files are kept with the mission that owns them.
• Converted files are reviewed and tuned after conversion.

Related pages

• Sites (.sites.json)
• Level Gameplay Data