Motocross RPG: The Road to Legend

A single-player, offline motocross career RPG. Start as an unknown rider with a broken 50cc and work your way up to legend.

Home Town: the player by the old rusty truck	Race day at Farmland MX: bikes in the air over the double

This is Alpha v1.1: the whole career loop from a broken bike to race days at three venues, player-made tracks, and now the Local Champion Championship for the Area 1 badge. All art is placeholder art in the agreed style, imported from the project's art threads.

A hobby project, offered as-is

This is a hobby project, made for fun in spare time. It is offered as-is, with no warranty, no support and no promised updates. There may be bugs, and some may never be fixed. Issues are turned off on this repository and I'm not able to answer questions, take requests or fix problems. You're welcome to play it, learn from it and change it for your own use under the terms of the MIT license, at your own risk. Back up anything you care about: your career is saved in the browser you play in, so use Load → Export save now and then to keep a copy as a file, and keep copies of your own tracks (the .track.json files in public/mods/tracks/, or the editor's Export).

What Alpha v1.1 offers

The game loop: earn money, keep the bike going, race, level up, repeat.

1. Start a career in Home Town with a broken 50cc. Paul Phoenix, the mechanic at Phoenix MX, gets it running in the tutorial and teaches the basics.
2. Earn money on shifts in the Industrial Zone: the fabrication shop (frame brackets) and the engine rebuilder (pistons). Pay is per part made, and is boosted 5× while testing.
3. Look after the bike. Every lap wears its parts, and a part at 0% breaks. Buy new or better-grade parts at Moto78 (the bike shop) and the tyre shop in Home Town (fitted free, or kept as spares in your bag), and pay the local garage to repair or fit them.
4. Get a van and load your bike to reach the tracks on the venue road.
5. Race. Three venues are open: Farmland MX, Riverside Arena and Longmoor Enduro, each with a track official at the race office (at Farmland it's Joseph Halden, who owns the track and introduces himself the first time you talk to him). A race day is two motos against 15 riders (5 laps a moto, or 8 at Longmoor Enduro, and 8 in a motocross or endurance championship round), including the Local Champion: £20 entry (your first race day is free), gate picks, a start official and a pit board, with prize money to 10th in each moto. Free practice is 25% of the entry, and the backyard loop at home is free.
6. Win the badge. After your first race day, enter the Local Champion Championship at any race office: three rounds, one at each track, against the same 16 riders, with qualifying and points for every moto. Win it for the Area 1 badge. The six-round Area 1 Championship is listed but locked until Area 2 is ready (Boss, 29 Oct 2026); its prize money stays as it is until the game is further along.
7. Level up. Racing and practice train your Rider Ability skills, and better skills and better parts make you faster.
8. Race your own tracks with Mod Track on the venue road (see Making and installing mod tracks below).

It runs in a browser on desktop or on a phone held sideways, and saves automatically.

Play it

• In a browser: once GitHub Pages is switched on (Settings > Pages > Source: GitHub Actions), every push to main publishes the game to this repo's Pages site.

• On your own computer: install Node.js (LTS), then:

  npm install
  npm run dev
  

  and open the address it prints (usually http://localhost:5173).

Controls

Action	Keyboard and mouse	Touch
Walk	WASD or arrow keys, or click where you want to go	Tap where you want to go
Talk to an NPC or use an object	Click it, or face it and press E or Space	Tap it
Next line of dialogue	Click, E, Space or Enter	Tap the box
Zoom (50% to 200%)	Mouse wheel, + and -, or the on-screen zoom control	The on-screen zoom control: a Zoom button with a slider, or + and − buttons (Settings > Display > Zoom control)
Bike, bag and current task	Tab, I or B	Bike button
Skills	K, or the Skills tab in the Bike panel	Bike button, then Skills
Pause menu (save, settings)	Esc	☰ button

Playing on a phone

Hold the phone sideways: the game is laid out for landscape, and asks you to turn the phone if it is upright. For the most room, use the browser's Add to Home Screen: the game then opens full screen with no browser bars. The game draws at the phone's full screen resolution, and panels shrink to fit a short screen.

Backing up and moving your career

Your career is saved in the browser you play in, so another browser or device starts empty. Load → Export save gives you your career as a file (mxrpg-<rider>-<date>.save.json): a download on a computer, the share sheet on a phone or tablet (Save to Files on iPhone and iPad, Drive or Downloads on Android). Load → Import save on any browser or device picks that file and carries on the career there; Load is open even with no career saved, for this. Importing over a career keeps the one it replaces as Backup 1 under Load. A save from an older build is upgraded on import like any other; one from a newer build, or a damaged one, is refused with the reason. Export now and then as a backup: Safari can clear a website's storage after about a week without a visit (a Home Screen app is not affected). The code is in src/core/saves.ts (the file format) and src/ui/files.ts.

Making and installing mod tracks

Mod tracks are race tracks made with the game's track editor and raced in the game from Mod Track on the venue road. A mod race day plays exactly like Farmland MX: the same entry fee, field, AI riders, prize money, XP and parts wear. Picking a mod track goes straight to the gate pick, without a venue area to walk round, and race day is the only mode (no practice): that is how mod tracks stay (Boss, 29 Oct 2026), with no modders' town area planned.

1. Build the track on a computer: the track editor needs a mouse and keyboard and isn't usable on a phone (racing mod tracks on a phone works, through Import track file). Open the track editor: tools/track-editor.html on the published site, or http://localhost:5173/tools/track-editor.html when running npm run dev. Choose New, draw the route, then add:

• a start straight, which needs its own gate and must join the lap;
• a finish line;
• a start board official, with a walk that ends clear of the track.

Then use Ready to race, which runs the game's checks.

2. Save it. The editor opens on the mod tracks: the example in public/mods/tracks/ and any saved there; the game's own four tracks are not listed (the Development edition has a Show the game's own tracks tick under the list, remembered in the browser, for working on the game itself). Tracks made with New, Duplicate or Import are mod tracks. The first Save asks for the track's name, and the track is saved as its own file, public/mods/tracks/<name>.track.json, never into the game's tracks.json. It can't overwrite another track: a name already in use is refused.

• With npm run dev, use the track editor at http://localhost:5173/tools/track-editor.html and Load the tracks from this server. Save then writes straight into public/mods/tracks/, and the game picks the track up on its next page load. Saved mod tracks are listed in the editor too, to carry on editing.
• If you Open folder… on the project in Chrome or Edge, Save writes into the public/mods/tracks/ folder there.
• Anywhere else, Save downloads the file for you to put in public/mods/tracks/.

Export still saves any track as a .track.json to share.

3. Race it. On your own copy, a track in public/mods/tracks/ shows under Mod Track in the game. For a built copy, rebuild with npm run build, because the build writes the folder's index.json (a website can't list a folder by itself). With npm run dev, Race it in the game in the editor opens a race day on a saved mod track straight away. On any copy, including the published site, you can also use Mod Track → Import track file in the game to pick a .track.json from your device. It is kept in that browser only, and can be removed from its race office. farmland-example.track.json is in the folder as an example.

What a mod track must meet. The game runs the same checks as on its own tracks:

• it is a track file from the editor (or a bare track), and is not marked as an unfinished draft;
• it is not practice-only;
• it has a start straight with its gate, long enough and joined onto the lap;
• every section type is one the game knows;
• it uses only the game's own surfaces, ground and scenery (custom art isn't supported yet);
• the start official stands and walks clear of the track, the line-up and solid scenery.

A track that fails stays in the list, and picking it shows the reasons. An import that fails isn't added. Each track is listed by its name, with its file name under it. Mod tracks get their own ids, so they never clash with the game's tracks. The code is in src/core/modTracks.ts.

What's new in Alpha v1.1

Older builds (Alpha v1 and the test builds) are in docs/CHANGELOG.md.

Championships

Checked against the last open line of the "Starter career slice" checklist (Systems Specification section 22): the Local Champion championship (3 rounds, one per track, 16 riders with qualifying) awards the badge, and the main area championship (6 rounds) then unlocks.

• Two championships in a new content file, championships.json (checked at start-up): the Local Champion Championship (rounds at Farmland MX, Riverside Arena and Longmoor Enduro) and the Area 1 Championship (two rounds at each, in the same order), both 50cc (Spec 12.5, 18.6).
• Entering. Every race office has a Championships choice: enter one, see where you stand, Start again from round 1 against a new field, or Give it up. The Local Champion one opens after your first race day; the Area 1 one needs the badge and waits for Area 2 (area2.ready, which nothing sets yet). Entering is free; each round is entered at its own track's race office, where Local Champion round N replaces the local race day while your next round is on there (Spec 18.6, 6C). There is no calendar, so a championship waits until you ride its next round.
• The field. 15 CPU riders drawn from the Area 1 pool (16 with you, on two rows of gates) when you enter, the same at every round. Each championship has a main rider, the one to beat and the best rider in it on skill (Boss, 28 Oct 2026): Louis Jonez (now level 15) is the Local Champion, and Dean Marsh is the placeholder Area 1 Champion. Dean stays out of the Local Championship; Louis races in both. Everyone else races 10% better in a championship (skills and bike condition), set by buff in championships.json. Normal race days and challenges are unchanged.
• Qualifying at every round (Spec 12.2): an untimed out lap from the gate, then 3 timed laps with the pit board as in a moto (or Auto-complete). The best timed lap sets the gate pick order for moto 1; it scores no points. The live tower shows the order of best timed laps. Qualifying wears the bike and gives the laps' XP (no finishing bonus), and counts as one step for the ruts (Round 111).
• Field of 16. Championships race 16 riders on two rows of 8, the same start as a race day (Boss, 28 Oct 2026: it looks cleaner than 20 on three rows).
• Motors stay on the road, on the left (Boss, 28 Oct 2026). A motor's body keeps to the road, car parks, gravel and concrete; only its front or back (two tiles for the Factory Hauler) pokes over the pavement or grass to turn round (kerbs in vehicles.json). Two-lane roads are driven on the left: east in the top lane, west in the bottom one, north on the left, south on the right. Steering and click-to-drive keep to the lane and a U-turn swaps lanes; junctions, car parks and entrances shorter than 4 tiles have no lanes. Too long to turn round on a two-lane road, the hauler turns at junctions instead.

World map (Boss, 28 Oct 2026)

The Map button (or M) opens Boss's world map: Areas 2 to 8, the Race Hub with its tracks, Home Town and the Industrial Zone, the Tracks badges and the roads between them. The only marker is your biggest bike, in its brand colour with no outline, standing in the middle of the zone you're in. Inside a building, that's the zone of the map its door is on. Travel is still by the roads out.

• The art comes from tools/art/world-map.py, which draws the map, a version of Home Town and the Industrial Zone without their little pictures, and a map bike for every class and brand.
• data/world.json worldMap lists each zone's maps and where its bike stands (src/core/worldMap.ts).

Tutorial markers (Boss, 28 Oct 2026)

Every step of the opening chain shows where to go next (src/core/waymarks.ts, drawn by src/world/Waymarks.ts):

• The NPC to talk to has an orange "!" bubble over their head.
• The equipment to use has a glowing orange outline with sparkles. On a step that needs two, like the two customer bikes, only the ones still to do are marked.
• The building to go into has a big orange arrow over each of its doors and a glow on the doormat.
• The way to go is an arrow on the exit, or out of a building, that leads there. While the marker is off screen, an arrow at the screen edge points to it with the place's name, such as "Industrial Zone, Engine rebuilder".

Markers come from story.json and the maps' doors and exits, so a new step needs no marker data. They never point down a road that is still shut. Reduced effects (Settings) keeps them still.

After the tutorial: challenges, errands and records (Boss, 28 Oct 2026)

• Story after the tutorial. Paul Phoenix, the mechanic at Phoenix MX, gives a word of advice the first time you talk to him after the opening chain: level up your skills, watch your parts wear and upgrade them, and how repairs work (one grade down at 100%; Grade 1 and broken parts can't be repaired). Then he points you to Mickey Alington by the practice track gate. The fabrication shop boss tells you about Dan Smyth by the Industrial Zone practice yard. Both are in the Task journal until you've heard them (a talk rule with sets in npcs.json is said once).
• Challenges (challenges.json, src/core/challenge.ts). Mickey Alington at the Home Town practice track gate races you for £50, 8 riders over 3 laps. Dan Smyth by the Industrial Zone practice yard races you one on one for £70 over 3 laps. Win, and you get your entry back plus the same again; anything but first wins nothing. Win or lose, you can race again straight away, with normal wear and XP. Each challenge needs its own new track, so until that track is in tracks.json the challenger says it's still being built. Both tracks are now in (Boss, 29 Oct 2026): Home Town Practice (challenge-home) and Industrial Zone (challenge-industrial), so both challenges are open.
• Boss's Area 1 tracks (29 Oct 2026). Farmland MX, Riverside Arena and Longmoor Enduro in tracks.json are replaced by Boss's versions from the track editor. The example mod track is now First Try MX (public/mods/tracks/first-try-mx.track.json); the Farmland copy and the Industrial Zone draft are gone from the mods folder.
  • Win chance comes from the bike. It averages every part's condition across the bike, so a part at 100% and one at 40% count as two at 70%. On a 50cc with all parts at 75% it is 50%, going up or down 1% per 1% of condition, between 5% and 85%. Bigger classes are easier: 65cc is 85% at 75% (95% at most) and 85cc small wheel is 97% (99% at most). Nothing is ever 100%. Rider skill doesn't count in Area 1. The odds are a table per challenge in challenges.json, to balance with Boss, ready for Areas 2 to 8 to aim at bigger classes.
  • Walk-off hint after a loss (Boss, 28 Oct 2026). The challenger says one more line, a general hint that never names a part, so you learn what to upgrade. If the bike averages under 75% it's the bike ("Your bike sounded a bit tired out there"); otherwise you were just unlucky. From Area 2 (to agree with Boss) a bike in good shape gets a riding hint, then a fitness one, when that skill is below the challenger's level.

Fitness training (Boss, 29 Oct 2026)

• Strength: bodyweight drills on the exercise mat in your room. It's a rep timing bar: tap as the marker crosses the green zone.
• Endurance: running sessions with Tasha Reid, the running coach by the Running Club pavilion. Hold to run faster and keep your pace in the green band for each lap split.
• Agility: comes from walking about, 1 XP every 10 tiles.
• How rounds work: a round lasts about 40 seconds, can't be failed and gives 50 XP whatever the score (training.json, src/core/training.ts).
• In races (racing.json sim.fitness), at level 99:
  • Strength is up to 1.5% faster through rough sections and 0.5% faster late in a moto.
  • Endurance is up to 1.5% faster late in a moto, because you fade less.
  • All Fitness together is capped at 3% of lap time. Agility already shortens crash recovery.

Tyres are only ever replaced (Boss, 28 Oct 2026)

Wheels and tyres can't be repaired or sold to any shop (consumables in shops.json). Ride them until they hit 0% and break, then buy a new set. Buying and fitting a new set in the shop trades in the set on the bike for money off: the old set's new price × its condition, the full amount one grade up and a third less for each grade beyond, nothing from 4 grades up, and never more than half the new price (tradeIn in src/core/shops.ts; table in alpha-v1.1/tyres/tyre-trade-in.md in the project files). A set bought as a spare and fitted later at the garage still puts the old set in your bag. The scrapyard owner's repair errand no longer lends tyres.

Driving fixes, track editor, buildings and the world map

The driving controls and feel are unchanged (no driving or physics code was touched), Home Town's map file is byte-for-byte the same (pinned by a hash test), and the race-day camera stays fixed.

• Driver over the van: on turning frames the van sheets mark the whole cab as the window, so the seated driver was drawn whole on top of the van. A turning frame's window is now used only when it is about the size of real glass; otherwise the driver is hidden by the roof (src/world/VanView.ts).
• Panel text overlap (Bike, Skills, Local garage): one-line labels and list columns (such as the garage's repair notes) are narrowed to fit their column instead of running into the next, the Bike stats sit below the bike's note, the Skills rows share the room above the footer note, and the shop title stays above its tabs. Checked at 100%, 130% and 180% text size.
• New tracks start empty: in the track editor, New track makes an unfinished (draft) track with no lap. Build the lap lists the section types; the piece follows the pointer, Q/E turns it, F mirrors it, B bends it, , and . shorten and lengthen it, a click or Enter places it and Esc cancels. A piece must join the end of the last one (gaps and kinks over 20° are refused with the reason); the piece that meets the first closes the lap. Ready to race runs the game's checks. The game leaves draft tracks out. Existing tracks are unchanged.
• Start straight, start official and a deeper ground range (refinement): Build the lap now has a Start and finish box. Start straight places it like a piece: it follows the pointer and snaps onto the lap (or stands free on an empty draft, and the lap is then built from its end), Q/E turn it, F changes the side it comes in from, , and . shorten and lengthen it, it shows green or red with the reason, a click or Enter places it and Esc cancels. Move start straight and Remove start straight are beside it. The race starts from the gate along it and the run to the lap is not counted as a lap. Start board official (with a picture of the official and board) picks the official in Scenery or selects the one placed; it can be placed, turned and routed before there is a start straight, and stands where placed until there is one. Checks on a new track say when the start straight, the official or its route is missing. Raise and Lower now go to ±36 m (was ±24 m, 1.5 times), with a 3 m strength added and a message when a dab reaches the limit; nothing is clamped silently. Where the start straight runs into the lap on sloping ground, it eases to the lap's level so the two surfaces meet. Tracks without elevation (all the shipped ones) are unchanged.
• Editor camera turns: Turn left, Turn right and Reset view buttons at the bottom left of the race view, the [ and ] keys, or Shift + middle-drag to turn freely. Clicks land on the ground under the pointer at any angle; the race keeps its fixed camera.

Tests: npm test (232 tests) and npx tsc --noEmit pass. For the elevation tool overhaul, a Playwright suite drove the editor's UI and race view through 21 checks, all passing: the Height pane opening on Raise the track with its length and height; the preview highlighting 16 units centred under the pointer on a straight, on the map and as a band in the race view, changing at once with the length setting, following the route round a corner, and changing nothing; a click applying exactly the previewed stretch; a raised straight with its peak at the centre, monotonic, symmetric and back to level at both ends; a lowered straight the same; a raised corner with every lane's position, banking, centre profile and skirt byte-identical; a hill on a section boundary changing no section or feature; a hill over the finish line wrapping as one hill; the same stretch clicked twice more stepping one hill to 3 m; undo and redo; the riding surface's edges exactly on the surface model through the hill with the bank's foot under the ground; the grass side graded from the track's level down to the land at no more than 1 in 1.5 on the terrain mesh with the ground texture; collision matching the surface; the five hills saved and reloaded identical with the track still race-ready; and the shipped tracks byte-identical. Unit tests cover the hill profile, wrapping, cutting at open ends and overlap, the lift and the unchanged cross-section on Farmland, continuity, grades, the steep warning and the height error, the schema and a race. Then the holder walk and four full races (Race 8×, 4×, 2× and 1×, 16 riders, 5 laps) on the suite's track with its five hills all finished in order with every rider on 5 laps, nobody stuck or going backwards and no errors, riders slowing over the 3 m hill. For the first-marker, first-corner and free-placement refinement, a Playwright suite drove the editor's UI and race view through 36 checks: the first click shown at once with its preview, undone, redone, dragged while drawing, place-move-place reversed by three undos, Esc clearing the preview; a route of five points with two rounded corners making one plain section and no typed corners; a flat corner on a straight, a hairpin on a 90° corner and a rutted corner on a sweep placed by hand, stretched, moved and the route reshaped under them with every type kept and no shape warning; a feature placement cancelled and undone leaving everything as it was; the start straight joined with no First corner section made, the first corner reported from the join to the next point and moving with the join; the draft saved, reloaded and made Race-ready; Farmland byte-identical with its own first-corner section kept, and Use features keeping every corner type. Unit tests cover the first corner's span, its own timed stretch each lap, its difficulty applied to that stretch only, lap 1's incident landing in it, and any type on any drawn shape passing the layout check. For refinement 4, three more Playwright suites drove the editor's UI and race view through 35 checks, all passing: every kind of join (straight to corner, corner to straight, straight to jump, jump to straight, corner to hairpin, hairpin to straight, turned and mirrored) leaving every earlier section's points, metres and type unchanged, heights under the track kept, the start straight added and the lap closed with nothing moved, saved and reloaded identical, a section deleted leaving a gap with nothing else moved; five moulding points on straights, jumps and the start straight, a middle point dragged moving only its own section's metres, undo, redo, save and reload; the boundary crossed by a dragged point and by a placed piece (named in Checks, not race-ready, reloaded as a draft, a second piece refused while one is out, far out refused, back inside ready again), scenery outside to the margin; and fans placed, set up, routed, refused on the track, saved and reloaded, built in the race view with their own timing, walking in at walking pace to exactly the end of the route, and reacting to a passing bike and resting. Unit tests cover the fans' checks and schema and the first-corner incidents and pile-ups (10–60% of races, sizes vary, in the first corner on lap 1 only, the player not always down, laps intact). For refinement 3, a second Playwright suite drove the editor's UI and race view through 29 checks, all passing: a circuit built and closed with no start straight (nothing laid, no finish line, valid draft, saved and reloaded); the finish line placed, moved, put on a selected point, dragged, removed, undone, saved and reloaded in place with no extra key; the start straight joined part way round and about a metre before and after the finish line with the lap untouched, Ready to race passing, an invalid join explained; the green ring dragged freely before there is a lap, placing a piece on it, dragging it along the lap, a broken join flagged and dragged back on; the Geometry warning for knife-edge corners and Round corner clearing it; and an existing track's checks, Reverse and export unchanged. Unit tests cover a start joining just before and after the line (5 laps, no extra or missing lap), the mitred corner (no lane folds, lip stands as a kerb, same on slopes and reversed, AI riders through), bikes kept moving and on the surface through the tightest corners of every shipped track, and a race on the track built in the suite. For refinement 2, a Playwright suite drove the editor's own UI and race view through 30 checks, all passing: building from a start straight placed first through a First corner and on round, rotating and moving pieces, the refusals and their reasons, Close the lap, a continuous loop, saving and reloading open and closed; deleting pieces (no track triangles left where they were, open ends shown, neighbours kept, old views disposed, undo and redo, repeated delete and close, save and reload with a gap); and the holder near the gate, mid-straight and at the far end, Plan walk, the walk timed in the race view itself (at A until 5 s, at B from 1 s, no jumps, the whole route walked), refusals, the start straight turned and moved, and save and reload. Then three full races (Race 8×, 16 riders, 5 laps) on the circuit built in the suite, with its holder, and one on Farmland all finished in order with every rider on 5 laps and no errors. In one of the three, a serious crash in the first corner held most of the field for about 15 seconds behind it, which is the race simulation's existing passing rule. For the earlier refinement, a brand-new track was built through the editor's own UI (start straight placed first, turned, moved, cancelled and undone, a lap built from its end and closed, saved and reloaded as a draft, the official placed, turned, routed, saved and reloaded, Ready to race passing), and full races (Race 8×, 16 riders, 5 laps) were run on Farmland flat, at ±24 m and at ±36 m (four times), and on the new track flat, on a 36 m hill and in a 36 m dip: every race finished in order with every rider on 5 laps, nobody stuck or going backwards, no errors. In-game runs through the real UI with Playwright: a full race on Farmland (Race 8×, 16 riders, 5 laps, results in order, no editor camera), an Auto Complete start on Farmland (riders still through the hold, board sequence, official in frame, gate drop at 0), all 10 Home Town doors walked in and out, a custom building walked into and out of, every route walked and the van driven out by a route.

Known limits: a finish line placed inside a bend splits that section, and a short remainder may then need retyping (the ghost warns; a straight is the usual place). Bikes drawn right on the edge of a knife-edge corner swing round its centre of curvature, a few centimetres back for a moment, while the surface there is a mitred point; the Geometry check names such corners. In deep valleys the fixed race camera can lose riders behind nearer high ground. Bikes dip up to about 0.6 grid units into the surface for a moment at some jump crests, flat or not (as before this change). Ground steeper than the 35% warning is still allowed. Opened straight from disk, the editor runs the published game, which gets these changes only once PR 20 is merged. The marshals reuse the running coach's sprite (no art for them yet). Buildings can't be rotated, since each picture is drawn for one view. The L-shaped engine rebuilder with lock-up is in the library but not placed on any map. The 35×18 example block fits on no shipped map and was tested on a blank map.

To resume: npm install, npm test, npm run dev, then open /tools/ (the toolkit) or /tools/track-editor.html or /tools/map-editor.html.

Before release

Testing aids to take out before the final release:

• Shift pay boost. testPayMultiplier in world.json (5× for Alpha v1.1). The moneymoneymoney money cheat was removed for the Alpha v1.1 release.

Later, once Area 2 is under way

Logged so they are not forgotten, not planned for a build yet:

• Blender-made models in the race view (Boss, 30 Oct 2026). Everything in the race view is built in code from three.js boxes and planes: the track, jumps, tunnels, riders, bikes, scenery and the start official. No model files are loaded. To let a modeller work in Blender: add a glTF loader, let each scenery type in trackParts.json name a .glb under public/assets/, and match the scale (one grid unit is one metre). Static scenery first (bales, stands, arch, pit boards); riders and bikes need rigging and animation and come later.

How the project is laid out

Path	What it holds
src/core/	Game rules with no graphics: pathfinding, saves, settings, content checks, doors and exits, money, bikes and the opening chain (career.ts), story changes to maps (mapState.ts), skills and XP (skills.ts), the race simulation (race.ts), race days, practice and venues (raceDay.ts), and shops, repairs and spares (shops.ts). Covered by tests.
src/scenes/	Phaser screens: boot, menus, settings, the world, the on-screen HUD, and the race and practice screen.
src/world/	Drawing maps, characters and the van (VanView.ts).
public/data/	Game content as JSON: NPCs, dialogue, bikes, items, the opening chain (story.json), the world map, locks and shift jobs (world.json), shops and repairs (shops.json), and the vans (vehicles.json). Every file is checked when the game starts.
public/assets/	Art and baked maps, written by the import tool. Don't edit by hand.
tools/import-art.mjs	Copies the art from the shared art folder and bakes each Tiled map into one game-ready file.
tools/index.html	The toolkit's front page (/tools/ beside the game), listing each editor as its own page, with placeholders for the outfit and character designers to come.
tools/map-editor.html	Standalone map and tile editor for the game maps and the Tiled sources.
tools/track-editor.html	Standalone editor for the race tracks in public/data/tracks.json.
tests/	Unit tests, plus checks that every door, exit and NPC on the real maps works.

Technology

TypeScript, Phaser 3 and Vite, with Vitest for tests. Saves are JSON in the browser's storage; a desktop app wrapper (Tauri) with saves as files comes in a later build. None of the Adventure Land code is used.

Updating the art

When the art threads change a map or sprite, run the import tool against the shared art folder and commit the result:

npm run import-art -- /path/to/art
npm test

To update only the van sheets (from art/vehicles/sheets/map/) without re-baking the maps: npm run import-art -- --vehicles /path/to/art.

The toolkit

The editors are kept apart from the game as the Motocross RPG Toolkit: its front page is tools/index.html, published at …/tools/ beside the game (http://localhost:5173/tools/ with npm run dev), listing the Track Editor and the Map Editor, with the Outfit Designer and Character Designer to come. How to use each editor, mode by mode, is in docs/TOOLKIT_INSTRUCTIONS.md (the toolkit's own instructions, linked from its front page). The track editor builds everything from motocross tracks to supercross (triples, step-downs, dragon's backs, tunnels through a tabletop with the lap riding under it, podiums, pyro and a stadium tunnel). The track editor builds everything from motocross tracks to supercross (triples, step-downs, dragon's backs, tunnels through a tabletop with the lap riding under it, podiums, pyro and a stadium tunnel). To add a tool, put its page in tools/, add a card to tools/index.html, and add its file to TOOLKIT_PAGES in vite.config.ts so the build publishes it.

Races on screen

The race simulation (src/core/race.ts) decides every result. The rider AI (src/core/riderAI.ts) then acts the race out: each rider picks a line, brakes into corners and drives out, swings out to pass or tucks in behind, jumps, skims whoops, crashes and remounts, always reaching the end of each section when the simulation says. How each rider rides comes from their skills, their bike and their race message (src/core/riderProfile.ts), plus an optional style for CPU riders in riders.json (line, aggression, jumps). The race view (src/world/RaceView.ts) draws it all as an isometric 3D scene with three.js, in the spirit of Super Off Road. The track is a solid surface (src/core/trackSurface.ts): jumps have take-off faces, tables and landings, whoops and braking bumps ripple, berms bank up, hills rise out of the ground, and a raised lip and earth bank mark both edges. Each bike's wheels are put on that same surface, so bikes pitch over jumps, lean into corners and land on the track. The camera follows your rider (the orange one with the arrow), or the leader once you are out, and a map in the corner shows the whole lap, the start straight and every rider. Tall scenery such as stands and trees fades when a rider is behind it.

The race opens on the start straight: the field lines up behind the gate on a concrete pad, wider than the track so a row of 8 fits, in two rows of 8 for a full field, and the straight narrows as it runs onto the lap, where the lap's lip and bank open up so the two surfaces merge.

The gate you pick is your slot: gates 1 to 8 are the front row from one end to the other, 9 to 16 the second row behind them, and riders arrive at the line-up in gate order. A gate past the field's size, or one already taken, is refused rather than swapped.

The start procedure is the same for a Race and for Auto-complete. When the race opens, 4 front-row riders are already in their slots (more for a bigger field) and the rest wait scattered just behind the pad. Over about 6 seconds they ride up to their own slots at different moments and speeds, several at once, easing onto their lane line, without touching. A second-row rider only sets off once the front-row rider in their own lane has stopped in their slot, so second-row riders in lanes that are already filled go early while other lanes are still filling. The line-up is drawn from a seed made of the track and the gate order, so each moto lines up differently but the same race always looks the same. An official (drawn at 90% of their first size, board included) waits beside the straight near the gate (A) from the moment the race screen opens, with the START 30 board low and its plain white back out. When everyone is still and the 5-second hold starts they raise it face out and walk up the straight to B, upright at 5 and 4, turned sideways at 3 and 2, and lower it white side out at 1, just before the gate drops; they stay at B with it lowered for the rest of the race. A, B and the whole walk are planned per track (src/core/startOfficial.ts) clear of the track, its lip and slope, and the scenery, with room for every turn of the board, and a track with nowhere clear fails the checks. There is no countdown on screen; the board and the riders show it. The procedure runs in real time at any playback speed, and Pause stops it. Practice has no line-up or board.

After the flag each finisher rides a slow cool-down lap down the nearer edge of the track, in single file behind the finisher ahead on that edge, giving way to riders still racing (before, every finisher stopped in one heap on the track about 40 m past the line at Farmland, where riders still racing rode through them).

Riders sit on the race-day bike model from the vehicles thread (Boss, 25 Oct 2026: "use the model from the coloured race day rides"): a youth bike for the 50 to 85 classes and an adult bike above, in the bike's brand colours, with the rider in their gear colours (src/world/raceBike.ts). It only changes how a rider looks. The tyres touch the ground exactly where the old bike's wheels did, so every rider takes the same line round every track as before.

Scenery may not stand on the racing surface, the start straight included; the game's checks and the track editor's Checks refuse it (see the toolkit instructions).

Checks

npm test          # unit tests and map checks
npm run build     # type check and production build into dist/