Track level

A track game keeps each level as a JSON file in src/levels, named level-<number>.json. The file lists the points the centerline passes through, what stands along the course, what a rider hits, and the finish. The schema package reads the file, so a bad file fails at load with the field it gets wrong. Sled’s levels are the first of these files.

Everything on the course is in track coordinates: at is metres along the centerline, and side is metres across it, positive to the right of travel. TrackMover rides in the same coordinates.

The file

A level has the following fields:

name: the level’s name.
track.points: two or more points, each with x, y and z in metres, the lane’s width edge to edge, and an optional zone, the material tag the point stands in, such as ice. The width and the zone blend to the next point.
placements: lists of copies that stand along the course, by kind, each with at, side and an optional scale.
triggers: lists of spots a rider hits, by kind, each with at, side and an optional lift, the metres it floats higher, such as a coin over a rock that only a rider in the air takes.
finish.at: metres along the centerline where the run ends.

A key the schema does not know fails the file, so a misspelt field never goes missing in silence.

{
    "name": "Level 1",
    "track": {
        "points": [
            { "x": 0, "y": 0, "z": 0, "width": 6.3, "zone": "snow" },
            { "x": 3, "y": -4, "z": -46, "width": 6.3, "zone": "snow" }
        ]
    },
    "placements": { "trees": [{ "at": 8, "side": -14, "scale": 1.5 }] },
    "triggers": { "pickups": [{ "at": 12, "side": 1.2 }] },
    "finish": { "at": 40 }
}

Reading a level as numbers

game track describe <game> <level> prints a level as numbers, so you can tune a course without drawing a frame. It builds the engine’s Track from the points through the game’s own Vite, so each number describes the curve the rider follows rather than the points in the file. Add --json for one object an agent parses.

The command prints the following:

The length along the centerline, the drop from the first point to the last, and the height range.
The steepest drop and the steepest climb, as percent grade, and where each lies.
The tightest turn seen from above: its radius over 2 m of track, its direction, and where it lies.
The lane’s narrowest and widest width.
Each run of points in one zone, from the first point’s distance to the last one’s.
The finish, and every placement and trigger by kind, as metres along and across, with a trigger’s lift where it has one.

For sled’s level 1, game track describe sled 1 prints:

track Level 1: 76.6 m long, drops 9 m, height -9 to 1.2 m, finish at 66 m
  steepest drop 42.9% at 41.1 m, steepest climb 6.4% at 16.5 m
  tightest turn 20.9 m radius, left, at 58.6 m
  lane 6.3 m wide
  zone snow from 0 to 76.6 m
placements trees 3: 8 m -14, 57.1 m +13, 71.1 m -15
triggers pickups 7: 12 m +1.2, 18 m -1.2, 24 m +1.2, 32 m -1.2, 46 m +1.5, 50 m +1.5, 54 m +1.5
triggers slabs 1: 39 m 0
triggers boulders 1: 60 m -2