Log inGet started
World

Apex Raceway: Race Tracks, Laps and AI Rivals Kit

Branchmain
Branchesmain
Commit068099240e

README.md

racingKit (raceTrackKit)

Draw a curve, get a race: tracks, checkpoints, laps, live race positions, item boxes and AI opponents for kart and car racing games.

Looking for raceTrackKit? This is it. The kit was published as racingKit and keeps that name, because every world already using it calls require("racingKit.api") and installs it by that name; a rename would break them. Search ZeroMind for "racingKit", "raceTrackKit" or "race track kit with laps, checkpoints and AI kart opponents".

One call turns a curve you draw through your world into a closed race track: a drivable road, barriers down both sides, a start/finish line with a numbered starting grid, and checkpoint gates. A second call puts a race on it: karts on the grid, AI drivers in the karts nobody sits in, item boxes, a traffic-light countdown, live positions and a results screen, the same on every player's screen.

First example

Install racingKit from ZeroMind (search "racingKit"). One install brings what it builds on. A brand-new world already has scenes/main.scene/build.luau with a ground and a player. Add these lines at the end of its content() function:

    local Racing = require("racingKit.api")
    ground.localScale = { 400, 0.2, 400 }   -- room to race: the template floor is 50 m across

    -- the curve: control points in order round the lap (y is height)
    local curve = { { 0, 0, 0 }, { 70, 0, 0 }, { 110, 0, -40 }, { 80, 0, -100 }, { 0, 0, -110 }, { -50, 0, -60 } }
    Racing.track(curve, { surface = "asphalt", gates = "arch", width = 12, laps = 3, checkpoints = 8 })

    -- you against three AI karts
    Racing.race("RaceTrack", { karts = 4, ai = { "careful", "aggressive", "itemHappy", "rubberBand" }, itemBoxes = 3 })

Press Play. You are seated in the first free kart (slot 1, whose AI stands down for you); the traffic lights count down red, amber, green, and the race is on. W/S drive and brake, A/D steer, Shift boost, Ctrl drift, Q (or d-pad up, or the on-screen item button on a phone) fires your item, R puts you back on your wheels.

Tip: the new-world template puts a red crate (shared_crate) and two lamp posts right on this track's start straight. The karts bump them and recover, but for a clean first race delete those lines from content() (or move them off the road).

Change surface = "asphalt" to "ice" and save: the whole track becomes glare ice with snow banks, and drives like it. Change gates = "arch" to "ring": every checkpoint becomes a floating ring.

Surfaces (surface)

Each surface is a look, its own barriers, and a feel: the road's collider carries an engine ground surface (Physics.defineSurface), so the karts' wheels really grip that much less, for players and AI alike.

surfaceLooksBarriersGripDrives
asphaltrace tarmac, red and white kerbstyre walls100%grippy and quick
dirtpacked dirt, grass vergeshay bales62%loose, the back steps out under power
iceglare ice, snow rimssnow banks16%barely any grip: brake early, steer gently
neona glowing rainbow ribbon with sweeping chevronsglowing light rails95%grippy, fast, best at night
offroada rutted muddy trail, real bumps in the roadrock walls55%rough and lively: the bumps are in the collision too
watera concrete channel under running water, spray flying from every kart's wheelschannel walls50%slick, the water drags at your speed

Gate styles (gates)

gatesWhat it is
archClassic Arch: an inflatable red and white racing arch
ringFloating Ring: a glowing ring hovering over the road, slowly turning
buoysSea Buoys: a red and a green channel buoy, bobbing, with lamps
hologramSci-fi Hologram: emitter pylons projecting a cyan light frame with sweeping scan bars
pixelFlagPixel-Art Flag: chunky voxel posts flying blocky checkered flags

The start/finish gate is the same style in checkered black and white, over a checkered line.

AI drivers (ai)

AI karts are the very same vehiclesKit karts a player drives. An aiDrivers AiDriver steers and works the throttle and brake through the kart's own controls (Vehicle:setIntent), along a minimum-curvature racing line with corner speeds from the grip it measures: no karts sliding along a rail, no teleporting. racingKit adds four racing personalities on top:

aiRaces like
carefulsmooth and tidy: brakes early, keeps a safe gap, never dives up the inside, and sits on an item until a clear straight, so it rolls past box rows still holding one and collects the fewest
aggressivefights for every place: late on the brakes, tailgates, pulls out to overtake, leans on whoever is alongside, boosts to pass, drops oil on anyone close behind
itemHappygoes for every item box: at each row it steers for the box off the racing line that is still there (the karts on the line take the one on it first), and fires whatever it gets straight away
rubberBandkeeps races close: up to a third faster when it falls behind, eases off when it is far ahead

They behave like their names. In a measured three-lap race of all four in the gallery, the item-happy driver collected 8 item boxes, the aggressive one 6, the careful and rubber-band ones 4 each. The aggressive one won, and the item-happy one finished last for its detours. Each kart's Racer.itemsCollected counts its boxes, so you can measure your own races.

Turn on showRacingLine = true on a track to paint the AI's racing line on the road as a driving aid: green where it accelerates, amber where it holds, red where it brakes.

Pick a style by kind (tags)

Surfaces, gate styles and AI personalities each carry tags, so a world can pick one by what kind it is instead of by name: Racing.gateStyles("sci-fi") answers { "ring", "hologram" }, Racing.personalities("items") answers { "itemHappy" }. Racing.tags("surfaces"), Racing.tags("gates") and Racing.tags("personalities") list every tag in use.

LibraryName: tags
surfacesasphalt: road, realistic, grippy, classic, daytime. dirt: offroad, rally, loose, natural, dusty. ice: winter, snow, slippery, natural. neon: sci-fi, glowing, neon, arcade, night, grippy. offroad: offroad, rally, bumpy, loose, natural. water: water, splashy, slippery, nautical
gatesarch: classic, inflatable, realistic, daytime, road. ring: floating, glowing, arcade, sci-fi, night. buoys: water, nautical, floating, realistic. hologram: sci-fi, futuristic, glowing, neon, night. pixelFlag: pixel-art, retro, blocky, cartoon, arcade
personalitiescareful: calm, defensive, tidy, holds-items, beginner. aggressive: aggressive, overtaker, fighter, oil, hard. itemHappy: items, item-hunter, chaotic, casual, fun. rubberBand: rubber-band, catch-up, close-racing, adaptive, fair
local Racing = require("racingKit.api")
-- a night race: the first glowing gate style and a fair rival
Racing.track(curve, { surface = Racing.surfaces("night")[1], gates = Racing.gateStyles("glowing")[1] })
Racing.race("RaceTrack", { ai = Racing.personalities("fair") })

Items

Item boxes are pickupsKit mystery boxes that karts collect (one winner per box, in multiplayer too). A box gives one of:

ItemDoes
Speed Boosta 1.6 s push to 1.5x top speed, flames roaring from the exhaust
Triple Boostthree shorter pushes, one per press
Oil Slickdropped behind you; a kart that drives over it spins out

Back markers roll the strong boosts more often, leaders roll oil more often.

Laps and positions

  • A lap counts only when every checkpoint gate was driven through in order, forwards, inside its width. Skip a gate, cut across the infield or reverse over the line, and nothing counts until you go back through the gate you missed.
  • The moment a kart is past a checkpoint without having driven through it (wide of it, or round it), the HUD says so: MISSED CHECKPOINT 3, with "Go back through it: the lap does not count until you do" under it. It stays up until you drive back through that gate. The miss is counted once, right then, in Racer.missed, and Racer.missedGate names the gate.
  • The first crossing of the start line starts lap 1 (the grid is behind it). Crossing it after the last lap finishes.
  • Positions update live: finishers by finish time, then everyone else by gates passed and distance to the next gate (distance past a skipped gate never counts).
  • After the first finisher, the others have finishTimeout seconds (30) to finish; then the race closes and they are placed by how far they got.
  • MatchFlow records each finish on its shared race clock, so the results screen and the live standings give the same order.

HUD looks (hud)

The race HUD (position, lap counter and times, standings list, item slot, banners) comes in six looks, swapped with one word: Racing.race(track, { hud = "cartoon" }), or the look field on the race's RaceHud, which you can change mid-race.

hudLooks like
broadcastdark TV sports graphics, yellow accents, condensed lettering (the default)
scifiglass panels with thin glowing cyan frames, glowing readouts, monospace data
cartooncream speech-bubble panels with thick ink outlines, comic lettering, chunky drop shadows
pixelsquare 8-bit boxes with thick white frames, hard black step shadows, blocky monospace lettering (no pixel font is published yet, so it uses a bold monospace)
minimallight, plain panels
neonglowing magenta and cyan, the arcade cousin of scifi

How to use it

local Racing = require("racingKit.api")

CallDoes
Racing.curve(name, points)A drawable curve: an entity whose children are its control points, as markers you move in the editor.
Racing.track(curve, opts)The track along a curve (a point list, a curve entity or its name). opts: surface, gates, width (12), laps (3), checkpoints (8), showRacingLine, labels, barriers, reverse, gridSlots (8), name ("RaceTrack"), synced. Returns the track entity.
Racing.race(track, opts)A whole race: karts (4), ai (personalities by slot), laps, itemBoxes (rows, 3), finishTimeout (30), countdown ("trafficLight"), results ("podium"), hud ("broadcast", "scifi", "cartoon", "pixel", "minimal", "neon"), autoSeat (true). Call it in a scene's build.
Racing.kart(track, opts)One race kart on grid slot, with an AI driver when ai names a personality.
Racing.itemBoxes(track, rows)Rows of item boxes across the road.
Racing.setSurface(track, name), Racing.setGates(track, name)Switch a track's surface or gate style (the same as setting the field).
Racing.surfaces(tag?), Racing.gateStyles(tag?), Racing.personalities(tag?)The names, in gallery order; with a tag, only the ones of that kind.
Racing.tags(kind)The tags in use, for "surfaces", "gates" or "personalities".
Racing.director()The race on this machine: phase(), getStandings(), placeOf(id), getLaps(), getRaceNumber(), start().

Components, if you prefer the inspector:

  • RaceTrack (any entity): points, surface, gates, width, laps, checkpoints, showRacingLine, labels, barriers, reverse, gridSlots. Every peer builds the geometry from these fields, so a change to any one rebuilds the track everywhere. The shape (laps, gates, grid, the AI's line) is ready at once; the meshes are built a few milliseconds a frame, road and wall colliders first, one track at a time. ready() says when every mesh is in, buildInfo() how long it took, and rebuild() builds it all in one call.
  • RaceDirector (a synced entity, next to a MatchFlow entity named Match): runs the races.
  • Racer (a vehiclesKit kart): laps, gates, progress, items, missedGate (the checkpoint driven past, still due) and itemsCollected. RaceAI (the same kart): the AI driver and its personality.
  • RaceHud: the on-screen race position, lap counter and times, standings list, item slot, and the WRONG WAY, MISSED CHECKPOINT and FINAL LAP banners.
  • KartFx (every race kart): boost flames from the exhaust while the kart boosts, and water spray from the wheels on a water track, played from racingKit's own kartFx effect on every screen from the kart's synced state. Turn either off with its flames or spray field.

Drawing your own curve: call Racing.curve("MyCurve", points) once (or make an empty entity and give it child entities in lap order), move the markers in the editor, then build the track from it with Racing.track("MyCurve", { ... }). The curve is the smooth closed loop through the markers; the start/finish line is at the first one, racing towards the second.

Multiplayer

The world is always multiplayer, and players join through the scene's normal player setup.

  • Same race everywhere. The race entity's owner (the host) is in charge: it decides who races which kart before each race, numbers the races, publishes the live standings in one synced field, and closes the race. MatchFlow keeps the countdown, the race clock and the results in step on every screen.
  • Each kart counts its own laps. The machine that drives a kart (the player's own machine, or the host for an AI kart) tracks its gates at full frame rate and reports its finish, stamped on the shared clock; everyone reads the kart's synced lap and progress fields.
  • Smooth karts. Every other machine draws a kart from the poses its driver sends, with the engine's interpolation (vehiclesKit's hand-over: the driver's machine owns the kart it drives).
  • Seats. Between races each player who is not in a kart is seated in the first free one (its AI stands down). Someone who joins mid-race watches and gets a kart for the next race. If a player leaves their kart, its AI takes over under their name for the rest of the race.
  • Tracks build locally. A track replicates only its fields; every machine builds the same geometry from them.

Known limits

  • #14448: two engines signed in to the same account show up as the same player, so the two-player race was checked with one engine, the replication diagnostics and the kit's tests rather than two players side by side.
  • #20946: the web build has to be checked by someone else, and this release was measured on the native desktop engine only; see "On the web" below for what that covers.
  • #20750: busy scenes run at a lower frame rate on the web build; each kart is a full car-physics vehicle, so keep a race to 4 to 6 karts there.
  • #22492: an entity spawned inside a world test can stay unowned, which is why the tests check the lap logic and the track build directly rather than a live race.
  • #21420 / #22451: installing racingKit brings vehiclesKit, aiDrivers, MatchFlow and pickupsKit with their own dependencies: it takes a while, and a dependency already in your world can be written again as an older extra copy under deps/.
  • #19258: the ZeroMind search description can lag one release behind; the README in your world is the current one.
  • #22667: boost flames and water spray are engine effect plays on a real-time clock, and those plays stand still on their first frame in a running race, so they do not show yet. They draw correctly on the effect preview stage, and the race itself is unaffected.
  • A track's meshes arrive over the first seconds after it loads (one track at a time, a few milliseconds a frame): the road and its wall colliders come first, the barriers and gates follow. A scene with many tracks, like the gallery, fills in over several seconds.
  • Simulated keyboard input (inputSim) steers vehiclesKit karts with A/D; the arrow keys did not steer in that test. Real keyboards were not affected in vehiclesKit's own tests.
  • A track is a closed loop on the heights of its curve; it does not cut into terrain, so lay it on flat ground or give the curve points the heights you want.
  • Installing racingKit also brings aiDrivers 1.1.8 from Torque Valley, whose published dependency list carries a stray groundMaterials.package.pull entry. The engine then shows aiDrivers one file ahead of its origin and suggests a pull request. It is harmless (nothing reads it), and it can only be removed by republishing aiDrivers from Torque Valley, not from a world that installs it. zeromind.silence("/zero/source/aiDrivers.package") mutes the reminder.
  • aiDrivers also lists roadPieces (Torque Valley's road-building kit) as a dependency. In a world that already holds the stray entry above, installing roadPieces is refused ("1 of the 62 files ... left to rows the world already holds"), so Apex Raceway itself runs without it. racingKit does not use roadPieces: tracks, races, AI driving and the tests all work without it, and a fresh world that installs racingKit gets it as usual.
  • In a fresh world the item boxes log one module 'SecondWind.api' not found line each time a kart collects a box. That is pickupsKit checking for its optional health-kit link (SecondWind), which racingKit does not need. Items work normally. Installing SecondWind (zeromind.installAsset("5da0a53c-5953-4adc-80fb-f5afb02f6568")) silences it.

On the web

A track never holds the frame while it builds. Its meshes are made a few milliseconds a frame, one track at a time across the whole scene, road and wall colliders first. The build gives the frame back every 6 ms, so no script runs anywhere near the 30-second limit the web build stops scripts at. Hundreds of tyres, hay bales and rocks are copied from a single finished model each, rather than modelled one by one.

Measured on the desktop engine for the 590 m showcase circuit, as total build work:

Surface1.0.71.0.8
dirt (hay bales)7.8 s0.6 s
asphalt (tyre walls)2.6 s0.4 s
offroad (rock walls)1.4 s0.7 s
ice, neon, water0.2 to 0.6 s0.2 to 0.6 s

Spread over frames, the showcase circuit fills in within a few seconds. The gallery's twelve tracks build one after another through one shared queue. On the desktop engine in edit mode, all twelve were finished within 18 seconds of the scene loading, with the longest single slice 36 ms. A track only loses its turn once every other track has had several turns without it checking in, so a slow frame while a scene loads never stalls a track half-built (1.0.10 and earlier could leave tracks unbuilt when a single frame took over 2 seconds).

Not yet checked in a browser (#20946): expect the web build to do the same work several times slower, so tracks take proportionally longer to fill in. Races there run at the web build's lower frame rate in busy scenes (#20750).

Guides

Two guides ship in the package:

  • How to make a racing game track with laps, checkpoints and positions (racingKit.package/guides/how-to-make-a-racing-game-track-with-laps-checkpoints-and-positions): drawing a track, surfaces and gates, laps and positions, races, items, the HUD, multiplayer.
  • AI opponents for my kart race: draw a track and race 3 AI karts over 3 laps (racingKit.package/guides/ai-opponents-for-my-kart-race-draw-a-track-and-race-3-ai-karts-over-3-laps): from an empty world to a full race against the four AI personalities.

Showcase and tests

  • racingKit.gallery: every surface and every gate style on its own labelled loop (with its tags), and the four AI personalities racing each other on one loop, a name tag over each kart and the standings on screen (zero scene load racingKit.gallery).
  • racingKit.showcase: the Apex Raceway race: you against three AI karts, 3 laps.
  • racingKit.tests.racingKit: 15 tests for the track built from a curve, laps through every gate in order, a skipped checkpoint and a cut across the infield not counting, a missed checkpoint flagged the moment it is driven past and cleared once it is driven through, wrong-way crossings, positions, finish order, the standings sync format, swapping surface and gate style with one field, item rolls and the AI personalities. Run asset.resolve("racingKit.tests.racingKit", "testSuite"):run() in edit mode.

Builds on

KitFor
vehiclesKit 1.0.9 (Joyride Harbor)the karts, their controls, camera, HUD gauges and multiplayer hand-over
aiDrivers 1.1.8 (Torque Valley)the AI driving brain; 1.1.7 added driving vehiclesKit vehicles, aimOffset and pace, 1.1.8 brings roadPieces with it (both sent upstream)
MatchFlow 1.3.1countdown, race clock, finish order, results
pickupsKit 2.3.7 (Treasure Trove)the item boxes; 2.3.7 stops a flood of engine errors from item boxes on today's engine (sent upstream)
groundMaterials (Terra Firma)the dirt, ice, packed snow, gravel, short grass and mud looks
torqueCars and driveSurfaces (Torque Valley, MIT)racingKit.meshkit is torqueCars' meshkit and racingKit.shaders.pavement with the tarmac and concrete materials is driveSurfaces' drivePavement, both carried inside racingKit with credit

Changes

  • 1.0.14: RaceHud:place{ position, item, standings, compact, scale } lets a game lay the race screen out around its other pieces (a speedometer, a minimap, on-screen touch controls): each panel goes where it is told, and compact drops the lap times and shrinks the panels for a phone. Left unplaced, the HUD looks as before. The panels carry the ids rk_position, rk_item and rk_standings. Needs vehiclesKit 1.0.11.
  • 1.0.13: a player's kart drives in a multiplayer race after a kart select changed its type: vehiclesKit 1.0.10 (the new owner rebuilds a drivetrain built on another machine) and aiDrivers 1.1.9 (the AI hands the wheel to a seated player on every machine and follows a kart that changed type).
  • 1.0.12: README only: Known limits now says that in a fresh world the item boxes log an optional SecondWind line per pickup, and how to silence it. Checked on 1.0.11 in a brand-new world: installed from ZeroMind, the first example pasted as written, the AI karts raced (38 to 131 m and up to checkpoint 4 in the first 12 s) with no aiDrivers errors.
  • 1.0.11: a fresh install races again: 1.0.8 to 1.0.10 shipped aiDrivers' modules where a name lookup could not find them, so in a new world the AI karts sat on the grid while the AI driving component failed to load (aiDrivers is reinstalled cleanly in Apex Raceway, and the kit republished from it). Every gallery track builds: the build queue no longer drops a live track after a slow frame (it measures abandonment in other tracks' turns, and a dropped track rejoins). Three new HUD looks, scifi, cartoon and pixel, next to broadcast, minimal and neon. The README says up front that this is the kit to find for "raceTrackKit".
  • 1.0.10: comments only: the long dashes in the gallery and showcase scenes' opening comment blocks are now plain punctuation, and the long dash rulers on section headers in the kit's scripts are now plain comment headers. No behaviour changes.
  • 1.0.9: README only: Known limits now names the stray ground-materials entry in aiDrivers 1.1.8's published dependency list, and the roadPieces package that cannot be installed alongside it in a world that already holds that entry. No code changes: races, laps, AI and the 15 tests are as in 1.0.8.
  • 1.0.8: a MISSED CHECKPOINT banner the moment you drive past a checkpoint, until you go back through it (Racer.missedGate); tracks build a few milliseconds a frame, one at a time, road first, and barriers are copied from one finished model each (the dirt track 7.8 s to 0.6 s of work), so a track loads on the web without the script being stopped; tags on surfaces, gate styles and personalities (Racing.surfaces/gateStyles/personalities(tag), Racing.tags(kind)); the item-happy driver steers for the box still up off the racing line and the careful one holds its items, so they collect clearly more and fewer (Racer.itemsCollected); the gallery shows the four personalities racing each other on one loop; gate animation at 30 Hz.
  • 1.0.7: depends on pickupsKit 2.3.7, which fixes hundreds of engine errors a second (and the frame rate with them) in a race with item boxes on today's engine. Boost flames are round glowing blobs that read the same from every side.
  • 1.0.6: boost flames and water spray. Every race kart roars flames from its exhaust while it boosts and throws spray from its wheels on a water track, on every player's screen, from racingKit's own kartFx effect (the KartFx component plays it). README tip for the new-world template's crate and lamp posts on the first example's start straight.
  • 1.0.5: installs into a brand-new world: the gallery's AI-driver karts are real vehiclesKit karts built at runtime (no baked kart parts tied to one vehiclesKit release), and the dirt verges, offroad trail and snow banks use groundMaterials looks every new world receives (short grass, mud, packed snow).
  • 1.0.4: also carries the paving shader library (pavementLib), and its materials and gallery scene name the groundMaterials release Terra Firma publishes, so a brand-new world can install it.
  • 1.0.3: installs cleanly into a brand-new world. The mesh builder (from torqueCars) and the paving shader with its tarmac and concrete looks (from driveSurfaces) now ship inside racingKit, credited, instead of being referenced from copies that reached a world only inside vehiclesKit, which a new world could not be given.
  • 1.0.2: installs cleanly into a new world: depends on the published aiDrivers 1.1.8 (vehiclesKit driving, aimOffset, pace, roadPieces declared as its dependency).
  • 1.0.1: the showcase and gallery scenes are rebuilt against the recorded groundMaterials copy, so their grass renders in a fresh copy of the world.
  • 1.0.0: first release.