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 sidebar row 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.

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.

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 sidebar 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: the symbol isn'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 both replace the same target; neither applies. Coordinate, or use before/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.

Where do I report bugs or ask questions?

github.com/roowus/TSPML/issues.