FAQ
What does TSPML stand for?
The Skibiti PolyModLoader. The name is a nod to the fact that it wasn't first: PolyTrack modding was pioneered by PolyModLoader (PML), and TSPML is a second loader with a different architecture. See What is TSPML?
Is this safe? Will it break my game?
The portal runs PolyTrack from the official servers inside your browser. Your saves, tracks, and records are your browser's own, exactly as on the official site. The mod layer is designed to fail small: a broken mod is reported in its own row in the Mods menu while the game and every other mod keep working. If everything goes wrong, remove your mods (or clear the site's storage) and you're back to a vanilla game.
The honest caveat: mods are code. A mod runs unsandboxed in the page. Treat adding a mod like installing software, and only add mods you wrote or trust. The per-mod source button shows exactly what's stored and will run, which helps, but reading code is not a substitute for trusting its author.
Will modded runs get me banned?
Maybe, eventually, for physics mods. PolyTrack validates leaderboard entries as deterministic input replays, and Kodub has said server-side anti-cheat is in development. Mods that alter physics or timing can invalidate replays, and uploading such runs risks leaderboard bans. TSPML labels these mods (vanillaSafe: false, physics warnings) but deliberately doesn't block you; the decision and the risk are yours. Cosmetic mods (HUDs, keybinds, sounds, custom local tracks) don't touch the sim.
Can a mod change how the car drives?
Yes. A mod can declare a physics file that rewrites float constants inside PolyTrack's compiled physics binary — grip, gravity, whatever constant you can locate. Authors derive one with the find-constant command; the portal serves the patched binary to the game.
This is the single most leaderboard-relevant thing a mod can do, and TSPML treats it that way: declaring physics raises the ban-risk warning no matter what the manifest claims about vanillaSafe. Every gate around it fails closed, so the worst case is vanilla physics with a reason, never a binary the game can't run.
Is this legal? Does Kodub approve?
TSPML never redistributes the game: the portal fetches your live copy from official servers and transforms it in memory, shipping only loader code, mappings metadata, and mods. That said, running a modified client is a ToS gray area, Kodub has not stated a position, and the project's policy is to comply immediately with any request from them. TSPML is a fan project, unaffiliated with Kodub.
Someone sent me a share link. Is it safe to open?
Opening it is safe: a share link never auto-installs anything. The portal shows you a list of the mod URLs the link carries and does nothing until you click Import. The question to ask before importing is the same as always: do you trust the people who host those mods? The confirmation list shows each URL so you can judge, and the import rules refuse links to suspicious targets outright.
What's the difference between a share link and a modpack?
Both install a set of mods, and both carry links rather than code. A share link is generated from what you're running right now, arrives from someone else, and asks you to confirm before it fetches anything. A modpack is a .txt file you write and host yourself, one mod URL per line, and you import it by pasting it into the Add form — no confirm step, because pasting it and pressing Import is the confirmation.
Use a share link to send someone your current setup. Use a modpack when the set is a thing you maintain: a file you can edit, version, fork, and link to. See Import a modpack.
One mod in the pack I imported failed. Did the rest install?
Yes. A pack fails per mod, not per pack: a line that 404s or points somewhere refused is skipped and named in the Log with its line number, and every other line still installs. The box tells you the count, for example installed 2 of 3, 1 failed to import. Fix or drop the bad line and import again — mods you already have are replaced, not duplicated.
Why doesn't my pasted mod appear in my share link?
Share links carry URLs only, never code. A pasted mod's only copy is your browser's storage; there's no URL anyone else could fetch it from. The share panel names such mods so you know to send them another way. To make a mod shareable, host its files at a URL and import it from there.
I clicked reload but the mod didn't update. Why?
Two possibilities:
- The host is caching. The portal's re-fetch bypasses the browser's cache, but GitHub's raw CDN (
raw.githubusercontent.com) has its own cache of about five minutes that can't be bypassed from a browser. Wait a few minutes and reload again. - The source was unreachable. In that case the portal keeps your stored copy and says so in the session log.
Why does the game need a "restart" when I change mods?
Only mods with mixins (patches to game code) need it. The game bundle is transformed once, when it's served; it can't be re-patched while running. Entrypoint features (events, keybinds, tracks, audio) apply live without any reload.
My mod loaded but my mixin says 0/1 applied. What now?
Check the reason in the Your mixins row:
symbol-unresolved: thesymbolisn't in the current mappings. Check the spelling against the mixin reference; the pinned set is small and growing.not-found/hash-mismatch: the mappings don't match the running bundle (usually right after a game update). This is fail-closed behavior: TSPML refuses to guess. Wait for a mappings update.param-unresolvable: your payload references__TSPML_PARAMn__in a way that can't be resolved safely (out of range, destructured param, or your own code shadows the name).conflict-replace-single-winner: two mods bothreplacethe same target; neither applies. Coordinate, or usebefore/after/around, which chain.
Why do race events fire multiple times?
Ghost/replay cars are cars: they start, pass checkpoints, and finish. Every per-car payload carries isReplay; filter with if (isReplay === true) return;. Details and the null caveat: Events.
Can mods talk to each other?
Indirectly today: mod.json supports depends/provides for ordering and presence, and the custom field carries arbitrary inter-mod data. There is no dedicated inter-mod message bus yet.
Does TSPML work on the official polytrack site, or offline?
Neither, currently. The portal is the delivery surface; it hosts the service-worker and proxy pipeline the transform needs. A browser extension that mods the game on the real kodub.com origin is on the roadmap (#7), which is also the path to modded online play.
How is this different from PolyModLoader (PML)?
They take different architectural approaches. PML, the first PolyTrack mod loader, which pioneered modding for the game, has mods work with the game's internals directly. TSPML puts a stable-names layer between mods and the game (the mappings file plus the API bridge), so mods target names that don't change between game builds; on top of that it adds per-mod failure isolation, fail-closed patching, typed events with unsubscribe, real unload/cleanup, and a zero-install browser portal. Different trade-offs; use whichever fits how you like to mod.
Can I run my PML mods in TSPML?
Not today. The formats differ at load and at execution, so a PML mod imported into the portal is refused by name rather than half-loaded into something that looks installed and does nothing.
Running PML mods is a stated direction, and two seams are already reserved for it: a format discriminator on every stored mod and registry entry, and a format dispatch step in the importer. The honest limit is worth knowing before you plan around it: PML mixins are not translatable in general, because they're keyed to literal substrings of minified game code while TSPML patches structurally through its mappings. Lifecycle hooks, settings, keybinds, audio, and model registration are the parts that could plausibly carry over. See PML compatibility for the full picture.