Drag Strips (dragstrips/)

This page describes level-local drag strip data.

Drag strips define staged drag race gameplay. A drag strip setup usually combines settings, strip geometry, lane waypoints, timing definitions, optional prefabs, and facility/POI integration.

File location

Drag strip data is stored under:

levels/<levelName>/dragstrips/

Common files:

<stripName>.dragSettings.json
<stripName>_main.strip.json
dragStripData.dragData.json
<stripName>.facility.json

Modern gameplay discovers level drag strips by scanning for *.dragSettings.json.

Discovery behavior

The drag racing system scans the current level’s dragstrips/ folder for:

*.dragSettings.json

Each settings file is treated as an entry point. Other files, such as *.strip.json or facility files, are only useful when referenced by a settings file, mission, facility entry, or compatibility workflow.

Creating drag strip files with editor tools

Use the Drag Race Editor for new drag strip data when possible. It can create and save strips, lane data, drag settings, zones, and feature-specific facility files.

Recommended workflow:

1. Open the level in World Editor.
2. Open the Drag Race Editor.
3. Create the strip layout first.
4. Define lanes, boundaries, spawn waypoints, stage waypoints, and end-line waypoints.
5. Save the strip as *.strip.json.
6. Create drag settings that reference the saved strip.
7. Configure timers, race phases, context, and optional prefabs.
8. Save the settings as *.dragSettings.json.
9. Add or connect facility/POI data if the strip should appear in freeroam or career UI.
10. Test staging, countdown, race completion, reset, and big map entry.

Create the strip before the settings file. The settings file is the entry point, but it needs a valid strip layout to be useful.

Writing drag strip files manually

Manual authoring is possible, but the lane transforms and waypoints are easier to place in the editor. If writing manually, work in this order:

1. Create the dragstrips/ folder.
2. Write the *.strip.json layout with lane boundaries and waypoints.
3. Write the *.dragSettings.json file that references the strip.
4. Add optional *.facility.json or facility integration.
5. Add optional prefabs only after the race works.

Minimum modern setup:

levels/<levelName>/dragstrips/example_main.strip.json
levels/<levelName>/dragstrips/example.dragSettings.json

The settings file must point to the strip file:

{
  "id": "example",
  "stripId": "/levels/example/dragstrips/example_main.strip.json"
}

Use absolute game paths beginning with /levels/ for references that may be loaded from missions or other systems.

*.dragSettings.json structure

Minimal settings file:

{
  "id": "exampleStrip",
  "context": "freeroam",
  "dragType": "headsUpRace",
  "stripId": "/levels/example/dragstrips/exampleStrip_main.strip.json",
  "canBeReseted": true,
  "canBeTeleported": true,
  "timers": [
    {
      "id": "time_1_4",
      "label": "1/4 mile",
      "shortLabel": "1/4",
      "type": "distanceTimer",
      "distance": 402.336,
      "important": true
    }
  ],
  "phases": [
    { "name": "stage", "dependency": true, "startedOffset": 0 },
    { "name": "countdown", "dependency": true, "startedOffset": 0 },
    { "name": "race", "dependency": false, "startedOffset": 0 },
    { "name": "stop", "dependency": false, "startedOffset": 0 }
  ],
  "prefabs": {
    "christmasTree": { "isUsed": false },
    "displaySign": { "isUsed": false },
    "paths": { "isUsed": false },
    "decorations": { "isUsed": false }
  }
}

Settings fields

Timer entries support distanceTimer and velocity types. Distances are meters.

*.strip.json structure

Minimal strip file:

{
  "id": "exampleStrip_main",
  "name": "Example Strip",
  "description": "Two-lane example drag strip",
  "lanes": [
    {
      "id": "exampleStrip_lane1",
      "shortName": "Right",
      "longName": "Right Lane",
      "laneOrder": 1,
      "color": "green",
      "boundary": {
        "name": "Right Lane Boundary",
        "vertices": [
          [0, -2, 0],
          [100, -2, 0],
          [100, 2, 0],
          [0, 2, 0]
        ]
      },
      "waypoints": [
        {
          "id": "exampleStrip_lane1_spawn",
          "type": "spawn",
          "name": "exampleStrip_wp_spawn_1",
          "transform": {
            "position": { "x": 0, "y": 0, "z": 0 },
            "rotation": { "x": 0, "y": 0, "z": 0, "w": 1 },
            "scale": { "x": 1, "y": 1, "z": 1 }
          },
          "waypoint": {
            "mode": "limit",
            "speed": 20
          }
        },
        {
          "id": "exampleStrip_lane1_stage",
          "type": "stage",
          "name": "exampleStrip_wp_stage_1",
          "transform": {
            "position": { "x": 10, "y": 0, "z": 0 },
            "rotation": { "x": 0, "y": 0, "z": 0, "w": 1 },
            "scale": { "x": 1, "y": 1, "z": 1 }
          },
          "waypoint": {
            "mode": "limit",
            "speed": 1
          }
        },
        {
          "id": "exampleStrip_lane1_endLine",
          "type": "endLine",
          "name": "exampleStrip_wp_endLine_1",
          "transform": {
            "position": { "x": 402.336, "y": 0, "z": 0 },
            "rotation": { "x": 0, "y": 0, "z": 0, "w": 1 },
            "scale": { "x": 1, "y": 1, "z": 1 }
          },
          "waypoint": {
            "mode": "set",
            "speed": 800
          }
        }
      ]
    }
  ]
}

Strip fields

Transforms in newer strip files use object-style vectors/quaternions:

{
  "position": { "x": 0, "y": 0, "z": 0 },
  "rotation": { "x": 0, "y": 0, "z": 0, "w": 1 },
  "scale": { "x": 1, "y": 1, "z": 1 }
}

Some older content may use compact pos, rot, and scl names. Prefer the newer object-style fields for new authored strip files.

File roles

Settings and strip relationship

A drag settings file should reference the strip layout file:

{
  "id": "exampleStrip",
  "stripId": "/levels/example/dragstrips/exampleStrip_main.strip.json"
}

Keep the settings id, strip id, and file names stable once missions, POIs, or career/freeroam data reference the strip.

The settings file describes how the activity behaves. The strip file describes where the lanes, boundaries, and waypoints are. Keep those responsibilities separate when editing:

• Change timers, phases, context, or race type in the settings file.
• Change lane geometry, lane order, and waypoint transforms in the strip file.
• Change big map/career/freeroam integration in facility or POI data.

When creating settings from scratch, start simple:

1. One strip reference.
2. One drag type.
3. Basic phases.
4. One or two important timers.
5. No optional prefabs.

After the race starts and finishes correctly, add more timers, displays, and presentation.

Lane and waypoint data

The strip file describes each lane. Lanes usually contain:

• A boundary volume.
• Lane order and display names.
• Waypoints such as spawn, stage, and end line.
• Optional zone data.

These waypoints are gameplay positions, not regular road navgraph nodes. Keep them aligned with the visible strip and any supporting prefabs.

Important waypoint types usually include:

Lane order should match what the player sees. Incorrect lane ordering can make UI labels, staging, or opponent placement confusing even if the race technically starts.

For two-lane strips, test both lanes independently. A common authoring mistake is fixing the player lane while leaving the opponent lane spawn, stage, or end-line waypoint misaligned.

Timers and phases

Drag settings can define timers and race phases such as staging, countdown, race, and stop. Timer names and phase names are consumed by drag race gameplay and UI, so prefer editing them through the Drag Race Editor when possible.

Common timer data includes elapsed-time checkpoints and trap-speed measurements. Keep labels concise because they can appear in race result UI.

Prefabs and presentation

Drag settings can enable supporting prefabs such as:

• Christmas tree lights.
• Display signs.
• Path helpers.
• Decorations.

Only enable prefabs that exist and are aligned with the strip. Missing or misplaced presentation prefabs can make a valid race look broken.

Prefab placement should be treated as presentation, not as core race logic. If a new strip fails, disable optional prefabs while debugging the settings and lane data.

Relationship with facilities and missions

Drag strips can appear as freeroam/career facilities and can also be used by drag mission types. A mission may reference a drag settings file, while freeroam/career UI may use related facility or POI data.

For general facility behavior, see Facilities .

Drag mission types may point directly at a settings file. If a drag strip works in freeroam but not in a mission, check the mission reference first, then the settings file and strip file.

Legacy and compatibility data

Some shipped content includes dragStripData.dragData.json. This can contain older or shared drag strip data and may overlap with newer settings/strip files. For new or actively maintained content, prefer the *.dragSettings.json entry point plus referenced *.strip.json layout.

Do not delete compatibility files from shipped content unless you have verified every consumer that might still read them.

Troubleshooting

Strip does not appear

Check:

• The settings file ends with .dragSettings.json.
• The file is under levels/<levelName>/dragstrips/.
• The drag feature is enabled in the current mode.
• The settings file can be parsed.

Race starts in the wrong place

Check:

• stripId points to the intended *.strip.json file.
• Lane spawn and stage waypoints are placed correctly.
• Lane order matches the visible strip.
• The player and opponent have enough room to spawn.

Timing or results look wrong

Check:

• End-line waypoints are placed at the intended finish.
• Timer distances match the intended race length.
• Race phases match the selected drag type.
• Display labels match the timer purpose.

Freeroam marker is missing

Check:

• Facility or POI data references the drag strip correctly.
• The facility id and drag settings id are stable.
• The big map or freeroam mode has drag racing enabled.

Validation checklist

• *.dragSettings.json loads and references an existing strip file.
• Strip ids and file names are stable.
• Lane boundaries cover the intended lanes.
• Spawn, stage, and end-line waypoints are placed and oriented correctly.
• Timers and phases match the intended race type.
• Prefabs referenced by the settings exist when enabled.
• Facility or POI data resolves if the strip should appear in freeroam/career UI.
• Drag missions that reference the strip can start and reset correctly.
• Compatibility files are preserved when old consumers may still need them.

Related pages

• Facilities
• Level Gameplay Data
• Gameplay Areas and Points of Interest