Drift Spots (driftSpots/)

This page describes level-local drift spot folders.

Drift spots define freeroam drift challenges. They combine UI metadata, scoring objectives, spatial setup, route data, boundary data, and scene marker objects.

File location

Drift spots are stored under the level root:

levels/<levelName>/driftSpots/<spotName>/

Common files:

info.json
spot.driftSpot.json
race.race.json
bounds.sites.json
preview.jpg

The drift system discovers spots by scanning for spot.driftSpot.json.

Discovery behavior

When a level is loaded, the drift spot system scans:

levels/<levelName>/driftSpots/

Each folder containing spot.driftSpot.json is treated as one drift spot. The folder name becomes part of the drift spot id, so keep it stable after releasing or after career/progress data references it.

File roles

info.json

The drift spot info.json is not the same as level info.json. It is local to one drift spot and usually contains UI and progression data:

Score thresholds should be tuned with real driving. If they are too low, progression feels accidental; if they are too high, the spot may appear broken to players.

Minimal info.json:

{
  "name": "levels.example.driftSpots.harbor.name",
  "objectives": [
    {
      "id": "bronze",
      "score": 5000,
      "rewards": {
        "money": 500,
        "beamXP": 25
      }
    },
    {
      "id": "silver",
      "score": 10000,
      "rewards": {
        "money": 1000,
        "beamXP": 50
      }
    },
    {
      "id": "gold",
      "score": 15000,
      "rewards": {
        "money": 1500,
        "beamXP": 75
      }
    }
  ],
  "unlock": {}
}

Use stable objective ids. Progress systems may store completion by objective id.

spot.driftSpot.json

This file stores spatial setup for the spot. Common concepts include:

The exact line layout can vary by spot. Keep the file authored by the Drift Data Editor when possible.

Minimal spot.driftSpot.json shape:

{
  "spatialInfo": {
    "bigMapTp": {
      "pos": [0, 0, 0],
      "rot": [0, 0, 0, 1],
      "scl": [1, 1, 1]
    },
    "lines": {
      "lineOne": {
        "markerObjects": [
          "harbor_line_1_a",
          "harbor_line_1_b",
          "harbor_drift_sign"
        ],
        "pos": [0, 0, 0],
        "rot": [0, 0, 0, 1],
        "scl": [6, 2, 2],
        "startDir": [1, 0, 0]
      }
    }
  }
}

spot.driftSpot.json fields

rot is stored as a quaternion array. scl controls the line volume size.

race.race.json and bounds.sites.json

The drift spot loader expects these files next to spot.driftSpot.json:

race.race.json
bounds.sites.json

race.race.json describes the path used by drift gameplay. bounds.sites.json contains the playable/scoring area. These formats are shared with other gameplay systems, so prefer creating them with the existing path and sites tools instead of writing large files manually.

Folder identity

The spot id is derived from the current level and the folder name:

<levelName>/<spotName>

Keep folder names stable once progress, career data, leagues, or UI references exist.

Scene object references

spot.driftSpot.json can reference scene marker objects for drift lines and signs. These objects are usually hidden or managed by the drift system at runtime.

When moving or renaming drift marker objects, update the drift spot file at the same time.

Marker objects should be grouped clearly in the scene so the drift spot can be maintained without searching the entire level tree.

Relationship with missions and POIs

Drift spots can appear as big map POIs and can share patterns with mission path data. The race.race.json and bounds.sites.json files should be treated as part of the spot, even though similar file names are also used by missions.

The drift system can also save player progress separately from the level files. Changing folder names, objective ids, or spot ids after release can disconnect existing scores or completion data.

Authoring workflow

1. Create or choose the road/area to use.
2. Create marker objects and line placement in the level scene.
3. Author spot.driftSpot.json with the Drift Data Editor where possible.
4. Add or update race.race.json for the intended route.
5. Add bounds.sites.json for the scoring/play area.
6. Tune info.json objectives from real test runs.
7. Check the big map marker and teleport target.

Creating a drift spot with editor tools

Use the Drift Data Editor when available. It helps keep the spatial data and marker references consistent.

Recommended editor-first workflow:

1. Open the level in World Editor.
2. Create a dedicated scene group for the drift spot markers.
3. Place visible marker meshes or signs for the drift start/scoring lines.
4. Use the Drift Data Editor to define the drift lines and spatial data.
5. Save the spot under levels/<levelName>/driftSpots/<spotName>/.
6. Create or update race.race.json for the intended drift path.
7. Create or update bounds.sites.json for the scoring area.
8. Add info.json with name, unlock data, and objectives.
9. Reload the level or drift data and test from the big map.

Keep marker object names short but descriptive. For example:

garage_line_1_a
garage_line_1_b
garage_drift_sign

Writing files manually

Manual authoring is possible, but it is easier to break marker references or transforms. If editing by hand, work in this order:

1. Create the folder first.
2. Write info.json with a name and a small set of objectives.
3. Create bounds.sites.json in the Sites Editor.
4. Create or copy a race.race.json path, then adjust it for the spot.
5. Write spot.driftSpot.json last, after marker object names and transforms are stable.

The minimum useful drift spot folder normally needs:

info.json
spot.driftSpot.json
race.race.json
bounds.sites.json

Do not tune objective scores until the line placement, route, and boundary are final.

Updating an existing drift spot

When editing an existing spot:

• Preserve the folder name if player progress or career data may exist.
• Preserve objective ids such as bronze, silver, and gold unless intentionally resetting progress.
• If marker objects are renamed, update every markerObjects entry.
• If the route changes significantly, retune score thresholds.
• If the big map teleport changes, test the spawn with several vehicles.

Troubleshooting

Spot does not appear

Check:

• The folder is under levels/<levelName>/driftSpots/.
• spot.driftSpot.json exists.
• info.json exists or the fallback display data is acceptable.
• The feature is enabled in the current gameplay mode.

Markers are missing or stuck visible

Check:

• Every marker name in spot.driftSpot.json exists in the level scene.
• Marker objects are not renamed by prefab unpacking or scene cleanup.
• The spot was reloaded after editing marker names.

Scores or objectives feel wrong

Check:

• race.race.json follows the intended route.
• bounds.sites.json covers the intended scoring area.
• info.json objective score thresholds were tuned with the intended vehicle class.
• The player is entering the line in the expected direction.

Validation checklist

• The folder contains spot.driftSpot.json and info.json.
• The spot folder name is stable and unique within the level.
• race.race.json exists and matches the intended route.
• bounds.sites.json exists and covers the intended area.
• Marker object names referenced by spot.driftSpot.json exist in the level scene.
• The big map teleport transform is safe and points to the intended start area.
• Objective thresholds in info.json are reachable in normal gameplay.
• Folder names and objective ids are stable once progress data depends on them.

Related pages

• Sites (.sites.json)
• Gameplay Areas and Points of Interest
• Level Gameplay Data