What is TSPML?

TSPML, The Skibiti PolyModLoader, is a mod loader for PolyTrack, the online 3D low-poly racing game by Kodub. It lets you run mods (HUDs, custom keybinds, custom tracks, sound packs, behavior tweaks) inside the real game, in your browser, with nothing to install.

Where it fits

PolyTrack modding was pioneered by PolyModLoader (PML), the first mod loader for the game. TSPML takes a different architectural approach to the same goal. In PML, mods work with the game's internals directly. In TSPML, all knowledge of the game's internals is concentrated in two artifacts that the project maintains: a mappings file (one per game build) and an API bridge. Ordinary mods only ever talk to stable names and a stable API, so when PolyTrack updates, TSPML updates its two artifacts and published mods keep working unchanged. Different trade-offs; use whichever fits how you like to mod.

The core ideas

1. A stable API (Tier 1)

Most mods never touch game internals. They subscribe to events:

api.events.on('checkpoint.passed', ({ index, carId, isReplay }) => { ... });
api.events.on('race.finished',     ({ frames, carId, isReplay }) => { ... });
api.events.on('car.control',       ({ up, down, left, right, reset }) => { ... });

and use registries:

api.keybinds.register({ id: 'my-mod.toggle', key: 'KeyH', onDown: ... });
await api.tracks.register({ code: 'PolyTrack2…' });   // add a custom track
await api.audio.register({ key: 'engine', url: ... }); // override a game sound

These names never change. When PolyTrack ships a new build, TSPML updates its own internals; your mod keeps working.

2. Mixins (Tier 2, the escape hatch)

When events and registries aren't enough, a mod can declare mixin patches: surgical, declarative JSON transforms applied to the game bundle before it runs:

{
  "patches": [
    { "op": "after", "symbol": "Car.controlCar",
      "inject": "console.log('car', __TSPML_PARAM0__);" }
  ]
}

The symbol is a stable name resolved through TSPML's mappings; your mod never hardcodes minified identifiers. If the mapping can't be resolved (say, after a game update), the patch fails closed with a per-patch report instead of silently patching the wrong function. See the mixin guide.

3. Physics patches located structurally

The driving model lives in a compiled WebAssembly binary that no JavaScript patch can reach. A mod can declare a physics file that rewrites float constants inside it:

{
  "wasmHash": "d4ef0267…",
  "patches": [
    { "name": "grip", "signature": "d0d92e0a…", "oldValue": 1.100000023841858, "newValue": 1.4 }
  ]
}

A signature names the constant's containing function by its structure — the set of float constants and the mix of opcodes inside it — rather than by a byte offset. A stale offset doesn't fail to match; it writes into whatever moved into that address. A structural match can refuse, and does: zero matches or two matches both mean vanilla physics with a reason. Authors derive one with find-constant, which reports every place a value occurs and refuses to guess which one governs grip.

4. Never redistribute the game

TSPML ships metadata and mod code only. The portal fetches your own live copy of PolyTrack from the official servers, transforms it in memory, and serves it to an iframe on your machine. No game files are ever stored, uploaded, or shared.

What the portal gives you

The player-facing side of TSPML is the portal at tspml.vercel.app. Its mod manager has grown into a full workflow:

• Add mods three ways: paste a mod's files directly, import from a URL (a hosted mod.json, or a bare .js file), or import a modpack (a .txt file of mod URLs).
• Reload in place: the reload button re-fetches every URL-imported mod from its source and reloads the whole set, so picking up a mod author's new build is one click.
• Share your setup: the share button builds a link that carries your enabled URL-imported mods. The link contains only URLs, never code, and opening one always shows a confirmation list before anything is fetched or run.
• See what you're running: every mod card shows its origin (the URL it came from, or "pasted"), and a source button reveals the exact stored manifest, code, and mixins.
• Know what applied, and what didn't: mixin and physics patches that were refused, capped, or left out are named with the reason. A patch that quietly did nothing is the failure mode TSPML is built to avoid.
• Recover from anything: broken mods are reported in their own row and never take down the game or other mods.

The full tour is in Playing with mods.

What TSPML is not

• Not a cheat tool. TSPML labels physics- and multiplayer-affecting mods (warn-only) and plainly discloses that uploading modded runs to leaderboards is at your own risk. See Safety & fairness.
• Not affiliated with Kodub. It's a fan project. If Kodub ever objects, the project's stated policy is to comply and cooperate.
• Not a sandbox. Mods are JavaScript running in your browser tab with the same trust level as the page. Only add mods you wrote or trust. The portal says this out loud in the UI, and the docs won't pretend otherwise.

Where to go next

You are…	Start here
A player who wants mods	Playing with mods
A modder	Your first mod
Curious how it works	Architecture