Testing a pack locally

Status: Works. Every earlier-format pack is loaded in one place, Home > Experiments > Mods, kept in your browser's storage, and switched on, off or removed there. Texture packs and the HD texture pack then apply on every page; mods and model packs apply in the test room only; a rules pack runs in the Forge's local Play; a v2 pack is checked and stored but not applied. Each section below carries its own status.

Packs are tried in the browser, on your own computer. Nothing you load is uploaded, and a pack changes only what your screen draws: the game's data in a match, the simulation and what is sent to other players are untouched (What a pack may change).

You need the game set up in your browser with your own disc, as for playing: a pack changes what the game draws or does, so the game has to be there first.

At a glanceCopy Anchor Link

The formats themselves are described on The earlier formats and Pack kinds.

Home > Experiments > ModsCopy Anchor Link

Status: Works. The viewer's console/render/mods.ts draws the screen; console/adapters/mods.ts reads and writes the one pack store behind it (packs/registry.ts).

On the launcher's Home, open Experiments, then Mods. The screen has, from the top:

1. Drop a pack here, or choose a file. Drop a zip, a folder or loose files anywhere on the screen, or press the row (Cross on a pad, or a click) to open the file picker -- the page's file input #mods-file, which takes several files at once. A folder is walked file by file. While a pack is read and kept, the row says so ("Reading…", "Keeping… n files") with a bar.
2. Texture pack: Original, or one installed texture pack (a map's texture pack or the HD pack). One choice only: two packs never replace the same texture.
3. A line with the last outcome: "name added.", "name removed.", or a refusal in words.
4. Installed: one row per pack -- its name, its kind, its number of files and its size, and where it applies ("Every page, every map" for the HD pack, "Every page, on map" for a map's texture pack, "The test room" for a mod or a model pack). Each row has a switch and Remove; a mod row also moves up or down in the order. A v2 pack has no switch: its row says "Stored".
5. Add test HD texture pack (temporary; see below).

What a drop is read as (the viewer's packs/classify.ts), in this order:

• A Thunderstore package. A zip whose root (or one top folder) holds the store's manifest.json -- its keys are the store's name, version_number, website_url, description and dependencies -- is unwrapped: the store's root files (manifest.json, icon.png, README.md, CHANGELOG.md) are checked against the store's rules and set aside, and the pack inside is read as below. A texture pack's own root manifest.json has other keys, so it is never mistaken for the store's.
• An HD texture pack: experimental-packs/hd/current.json anywhere in the zip. Drop it as its zip; loose files are refused.
• A mod: mod.json at the root or in one folder.
• A model pack: models.json.
• A built texture pack for one map: a manifest.json with its payloads.
• A v2 pack: s2u-pack.json. Checked and stored, never applied.

A drop that is none of these is refused, with the reason on the screen, and nothing is kept. The reasons you may see:

Adding a texture pack does not choose it: the outcome line says "Choose it as the texture pack to see it", and the choice is yours. A texture pack chosen here is applied at once on every open page of the game in this browser, a match in another tab included; a mod's change is read when the test room loads its map again.

The HD pack's size: decodedCopy Anchor Link

An HD pack's row gives its size decoded ("… MB decoded"): the size of its images once unpacked, as its manifest counts it, which is several times the zip you downloaded. Every other pack's size is what is kept.

Add test HD texture pack (temporary)Copy Anchor Link

The last row, Add test HD texture pack ("Temporary: downloads our test HD pack into this list and chooses it, until the HD pack is on Thunderstore"), downloads the project's own test HD pack, adds it to the list as an HD texture pack, and chooses it. While it runs it counts files: "Downloading the test HD pack… n of N files, x MB downloaded" -- the files fetched of the files to fetch, beside the bytes so far. Where the project's server does not serve the pack, it says "The test HD pack is not available yet." and keeps nothing; pressed again with the pack already kept, it downloads nothing more and only chooses it.

The row is temporary by name in the code (TEST_HD_PACK_BUTTON_ADAPTATION, the viewer's console/adapters/mods.ts): it goes once the HD pack is on Thunderstore and the project owner says to remove it. Until the pack has a store page the screen draws no link to one (HD_PACK_STORE_PAGE_PLACEHOLDER is empty).

Where a pack appliesCopy Anchor Link

Status: Works for texture packs; Test room only for mods and model packs (the viewer's packs/pagePacks.ts; the screen's "where" column, console/adapters/mods.ts).

• The HD texture pack, once chosen, applies on every page: the main game's matches, online lobby matches included, its menus (the HD menus follow the HD pack), the Forge and the test room -- under both pictures, MODERN and PS2.
• A map's texture pack, once chosen, applies on every page, on its own map only; the other maps draw their originals.
• Mods and model packs are kept, ordered and switched in Mods, but apply only in the test room (the next section).
• A v2 pack is never applied.

There is no HD picture any more: VIDEO MODE offers two pictures, MODERN and PS2 (the ui package's screens/videoPicture.ts), and the test room has no HD switch and no texture-pack import of its own. Choosing the HD pack in Mods is how HD is turned on.

Applying a pack: the overlayCopy Anchor Link

Status: Works (the viewer's packApplyOverlay.ts, PACK_APPLY_OVERLAY_ADAPTATION).

A texture pack chosen while a page is open applies at once, not at the next map. While it applies, the page shows the pack's name, "Applying pack... n/N" (the textures replaced of the textures the pack replaces on this map) and a bar; it goes at N/N. A pack that cannot be applied shows "name: not applied -- why" for a few seconds.

• Outside play -- the Forge's editor, the test room's Explore, a match while you are dead or spectating -- it is a panel over the whole screen.
• In live play -- alive in a running match, or walking in the test room's Play -- it is a small strip in the top right corner, so it never hides the play.
• At a map's load it is the corner strip, drawn over the loading screen with the loading art still visible. The apply starts with the map and never makes the load wait.

The overlay never pauses the game: the match keeps running and your seat keeps sending.

How smooth an apply isCopy Anchor Link

The work is spread over frames: each frame gives the apply a time budget (MODS_APPLY_FRAME_BUDGET_MS_ADAPTATION, the viewer's hdTexturePack.ts), large images are drawn in slices (HD_DRAW_TEXELS_PER_SLICE_ADAPTATION), and the HD pack's images are decoded off the main thread. The project's target for the worst frame during an apply is 50 ms.

Measured, with the all-maps HD pack (3,421 images) chosen from a second tab while the test room ran MP2, on one machine -- an NVIDIA GeForce RTX 4070 SUPER under headless Chromium (WebGL2 through ANGLE Direct3D 11): the worst frame of the apply was 57 ms in one run and 48 ms in another, with one frame and no frame over 50 ms; before the spreading it was 535 ms and 363 ms. So the target is met in one of two runs, not yet in every one. Not fixed: a single stall of about a third of a second at the moment the pack is chosen, before the overlay appears; its cause is not known yet. WebGPU was not measured. (The MODS loader plan's Log, task ML-9, 2026-11-07.)

MemoryCopy Anchor Link

Measured on the same machine (headless Chromium, WebGL2 through ANGLE Direct3D 11) with the all-maps HD pack chosen in the test room's offline Play (the HD plan's Log, 2026-11-07, for the MODS loader's task ML-8):

The whole pack is 4,658.7 MiB decoded; one map uses about a seventh of the applied cap. A lobby match on the front end was not measured.

What a pack may changeCopy Anchor Link

Status: Works.

A pack changes what is drawn on your screen, and nothing else. A texture pack replaces images; it never changes the map, the collision, the rules, the timing, or anything sent to the match's server or to other players, and the other players see their own textures. In every match of the main game, and in the test room while it is joined to a room on a server, a replacement for an image that is opaque in the original is drawn opaque, whatever its own transparency (the fairness guard: opaqueGuard in the viewer's hdTexturePack.ts, switched on by matchMount.ts and main.ts); in the test room offline and in the Forge's editor, a pack is drawn as it was made. Mods and model packs, which can change the game's data or what you can see through, stay in the test room.

Mods in the test room (s2u-mod)Copy Anchor Link

Status: Test room only.

Add a mod in Home > Experiments > Mods and switch it on there; the order there is the order the mods apply in, from the top down, so when two mods replace the same file the lower one wins. The test room's side panel keeps one line, "Mods: N on -- Home > Experiments > Mods.", with any conflict and its winner after it, and Reload map: a mod applies when a map loads, so after a change in Mods press Reload map (the viewer's mods/panel.ts).

Mods apply in every build of the test room, offline and online. They are not used in a lobby match reached through the normal menus, nor in the replay viewer: there, the game always reads its own files.

Model packsCopy Anchor Link

Status: Test room only.

A model pack draws your own GLB models in place of some of the game's meshes. Add it in Home > Experiments > Mods (a folder or a zip with models.json and the GLB files it names) and switch it on there. It applies only on the test room's page and with modmodels in the address, for example /testroom?modmodels (the viewer's modelPack.ts, MODEL_PACK_PARAM); the test room's Settings then show one line for it. A model pack changes what is drawn only; what you collide with stays the game's.

Rules packs: the Forge's PlayCopy Anchor Link

Status: Forge, local only. The Forge is the game's level editor, at /forge. Its work is paused while other parts of the game come first, so it may change before rules packs reach anywhere else.

A rules pack, such as your first pack, runs only in the Forge's own Play: an offline match on the layout you are editing, on your computer. There are two ways to give the Forge your rules:

• By hand, in the Rules panel. Open the Rules panel (right side, under Edit), press New rules, then Add rule and type each rule as JSON text, the same text as in your rules file. Check rules lists any refusal with the field it is about.
• Through an agent. The Forge's Agent tab (Connect your agent) lets an AI agent or tool you connect yourself work in the editor. Its rules.import takes a rules pack's files (s2u-pack.json and the rules file) and checks them with the same checker, then makes them the layout's rules.

Then choose Play the layout. The match runs your rules: in the first pack's case, a message at the start of each round, and every hit at half damage. With no rules, the layout plays as before.

Rules never travel with a share code, and a layout with rules cannot be played in a lobby: both are refused by name today.

A v2 pack's import: checked and stored, not appliedCopy Anchor Link

Status: Format only.

A v2 pack dropped into Home > Experiments > Mods is checked and stored, and listed with "Stored" in place of a switch. Any v2 pack, of any kind, can also be given to the pack library through an agent connection's packs.import, with the kind pack, as a zip or a folder. Two places offer one:

• The test room. At the bottom of the solo test room's settings panel, Connect your agent lets an AI agent or tool you connect yourself bring packs in. It is there in the solo room only (not in an online match or a replay), and it imports or removes a pack only while the room is in Build, not during Play (the viewer's agent/testroomInstall.ts, line 29, and agent/testroomTarget.ts, line 23).
• The Forge. The Forge's Agent tab (Connect your agent) does the same in the editor (the viewer's agent/forgePacks.ts, line 17).

What happens, in either place:

1. The pack is read: s2u-pack.json at the top of the zip, or in the one folder a zipped directory adds.
2. It is checked with the same checker as everywhere else: every field, every file's hash and size, every path. A pack that fails is refused with a report, each line naming a code from the Refusal codes and the file or field it is about.
3. A pack that passes is stored in this browser and listed with its id, version and kinds.

That is all, for now: nothing in the game applies a v2 pack yet, and asking to apply one is refused. Storing a pack is still useful as a check: if the library takes it, the pack is valid. Rules packs are the exception above, run through the Forge's Rules panel rather than from the library.

When something is refusedCopy Anchor Link

Every refusal names a code or a reason, and most name the file or field. Refusal codes lists the v2 pack's codes, and Troubleshooting has a fix for each. Your pack never changes the game's own files: switch it off or remove it in Mods, and the game is as it was.