Mods / Guides
Modding guide
The mod folder, the manifest, script mods, and how to share a mod. File and folder names in this guide are paths inside the game’s project.
Counterbeat is a web page. There is no binary to patch, so a mod is a folder of files the game knows how to read: JSON for content, and one optional JavaScript file for behaviour. This guide covers the formats, the manifest, the script API, and how to host and share a mod.
The reasoning behind the design, and how it maps to Beat Saber's mod scene, is in docs/MODDING-RESEARCH.md.
Code: src/mods.js (loader, script API, MODS panel), src/mod-schema.js (manifest checks, shared with the tools). Tools: tools/make-mod.mjs, tools/validate-mod.mjs. Examples: mods/example-fight, mods/example-look, mods/example-script, mods/example-song.
Game and API version: 1.0.0.
Quick start
node tools/make-mod.mjs my-mod --name "My Mod" --author "Me" --look tape-201:A
node tools/validate-mod.mjs mods/my-mod
python3 -m http.server 8818
Open http://localhost:8818/index.html?mod=mods/my-mod and play Onyx v Flint from the blue corner (&fight=tape-201&side=B) to see Onyx in the new trunks. Add &demo=1 to watch the scripted player box.
What a mod can change
contributes key |
What it adds | Needs code? | State in 1.0.0 |
|---|---|---|---|
fights |
Fight packs: a chart in beats plus a song (docs/CUSTOM-FIGHTS.md) |
No | Works |
music |
Another song for a fight that is already in the game: a recording, or a score for the game's band (docs/SONGS.md) |
No | Works |
looks |
How a boxer is drawn: skin, build, hair, trunks, boots | No | Works |
arena |
Colours of the arena: background, fog, lamps, lights | No | Colours work. signs and textures are planned |
cues |
Colours of the two hands and of his punches | No | Colours are wired, sizes are planned (see below) |
campaign |
Extra campaign levels that play a fight or one round of it | No | Works |
script |
One ES module that listens to game events and can add modifiers | Yes | Works, behind a confirm |
Everything except script is data. The game checks data against fixed lists of fields, so a data mod cannot run code.
The manifest: mod.json
{
"format": "counterbeat-mod",
"id": "my-mod",
"name": "My Mod",
"version": "1.0.0",
"author": "Me",
"description": "One or two sentences.",
"game": ">=1.0.0",
"requires": { "some-other-mod": ">=1.2.0" },
"suggests": { "example-fight": ">=1.0.0" },
"contributes": {
"fights": ["fight/fight.json"],
"music": [{ "fight": "tape-202", "song": "war.mp3", "bpm": 126, "offset_ms": 310 }],
"looks": { "tape-201:A": { "trunks": "#0f7a3c", "band": "#e0b22a" } },
"arena": { "background": "#1a0a12", "fog": "#1a0a12", "fogDensity": 0.04, "lamps": "#ff8a3c" },
"cues": { "left": "#ff1f35", "right": "#1c7dff", "threat": "#ffc21a" },
"campaign": [{ "id": "one", "title": "My Level", "fight": "my-fight", "side": "A", "round": 1, "pass": "C", "goal": "Text for the round card" }],
"script": "main.js"
}
}
| Field | Rule |
|---|---|
format |
Always counterbeat-mod. |
id |
2 to 40 characters: lowercase letters, digits, dashes. This is the mod's identity. Two mods with one id cannot load together. |
name, author |
Text, at most 60 characters. Both are shown before a script is allowed to run. |
version |
major.minor.patch. Raise it every time you publish. |
game |
The game versions the mod works with, as a range. The game is at 1.0.0. Write >=1.0.0, or ^1.0.0 if you use the script API and want to stop loading when version 2 changes it. |
requires |
Other mods that must be installed and switched on, each with a version range. If one is missing, this mod does not load and the player is told which one. |
suggests |
Other mods that make this one better. Missing ones only produce a note. |
contributes |
What the mod adds. Unknown keys are ignored with a warning, so a mod written for a newer game still loads its known parts. |
Version ranges: 1.2.3, >=1.2.0, >1.0.0, <2.0.0, <=1.9.0, ^1.2.0 (same major), ~1.2.0 (same minor), 1.x, *, and several parts separated by spaces (>=1.0.0 <2.0.0).
Paths are relative to mod.json. A path may point outside the mod folder (../../packs/example/fight.json) when the mod is loaded from a URL. A zip or a picked folder only holds its own files, so keep everything inside the folder if you want it to work both ways.
fights
A list of paths to fight.json files. The format is in docs/CUSTOM-FIGHTS.md. Each pack names its own audio file, relative to the fight.json, or carries a score for the game's band, or both. In the game a pack's fight id is custom-<pack id>; that is the id to use in looks, music and campaign.
music
fight is the id of a fight in the game (tape-201 Onyx v Flint, tape-202 Cobalt v Ember, tape-203 Slate v Gold, tape-204 Tide v Hammer, first-bell, or a pack's custom-<id>). song is the audio file. bpm and offset_ms (where the first beat falls in the file) come from node tools/bpm.mjs <song>. Every round of that fight then runs at the song's tempo.
An entry can name a score in place of the audio file, or as well as it: { "fight": "tape-201", "score": "scores/tape-201.json" }. The score can be a song that carries a tune (a melody): the game fits it to the fight. A score is a song for the game's own band: the style, key, chords, form and the note each punch plays (docs/SONGS.md). The fight keeps its own tempo. node tools/make-mod.mjs my-mod --score tape-201 writes one to start from. A score that is not valid, or whose rounds do not match the fight's, is left out and named in the mod's errors; the fight keeps the song it had.
mods/example-song is a mod of this kind. It gives Onyx v Flint (tape-201) the Jarabe Tapatío in place of El Choclo: one mod.json and one score file with a melody. Try index.html?mod=mods/example-song&fight=tape-201&demo=1. A score that is not valid is left out, the mod's error list says why (for example "melody.notes last 18 beats, melody.chords has 5 bars of four beats: they must be the same length"), and the fight plays its own song.
looks
Keys are <fight id>:<corner>, corner A or B. Fields are the ones in src/looks.js. A look is laid over the fight's built-in look field by field, so you only write what you change.
| Field | Values |
|---|---|
skin, trunks, band, stripe, boot, bootTop, hairCol, glove, cuff |
A colour: "#rrggbb" or [r, g, b] (linear, 0 to 1) |
hair |
bald, cropped, afro |
hairSize |
0.8 to 1.3 |
tache, goatee, chops |
0 or 1 |
trunkLo |
Hem height in metres on the 1.82 m model, 0.6 to 0.9 |
bootH |
Boot top in metres, 0.05 to 0.45 |
stripeW |
Half width of the side stripe in metres |
bulk, wide |
Build: skin pushed out (m, -0.006 to 0.016), shoulders pushed out (m, 0 to 0.03) |
cm, reachCm, kg |
Listed height, reach and weight. Height sets his size against yours. |
A new look shows from the next fight that starts.
arena
Colours of things the arena already has. Nothing is added to the scene.
| Field | What it colours |
|---|---|
background, fog |
The dark behind the crowd and the haze |
fogDensity |
0 to 0.2 |
lamps |
The lit bulbs or LED strip |
key, rimLeft, rimRight |
The three spotlights on the ring |
dust |
The dust in the light |
Planned, not read yet: signs (the texts on the canvas and banners) and textures (image files for the canvas and banners). The validator accepts both keys and says so.
If two mods set the same field, the one loaded later wins. Mods load requirements first, then in the order they were added.
cues
left, right: the colours of your two hands, used by the gloves and the punch targets. threat: the colour of his punches and the defence cues. They are read when a glove or a cue is next built, so a change shows from the next fight.
Planned, not read yet: punchSize and defenceSize (0.5 to 2). The checker accepts them and says they are not read.
campaign
Each entry is a level at the end of the ladder. fight is a fight id (a pack id without custom- also works). side is A or B. round picks one round, counted from 1; leave it out for the whole fight. pass is the grade needed (default C). Mod levels are always open; they do not wait for level 16. Progress is stored under mod-<mod id>-<level id>.
Three ways to load a mod
- A link.
index.html?mod=<url of mod.json or of its folder>. Repeatmod=for several. The mod lasts for that visit and is not stored. If it brings a fight, that fight opens. A script in a linked mod does not run until the player allows it on the start screen. - The MODS panel on the start screen. ADD MOD takes the mod's files or one
.zipof the folder. FOLDER takes the folder. The mod is stored in the browser (IndexedDB) with its files and comes back on every visit. Each mod has a checkbox to switch it off and a REMOVE button. On a Quest, do this before pressing ENTER VR. - A mod index. BROWSE reads
mods/index.json(or?modindex=<url>), lists the mods in it, and INSTALL stores one. This is the repository a community can host.
Storage is per browser and per site. A mod installed on the desktop is not on the headset.
When something is wrong
The game checks every mod when the page loads.
- A requirement is missing or too old. The mod is not loaded. The MODS panel opens by itself and shows, for example,
NOT LOADED: NEEDS THE MOD "NOODLE-CORE" >=2.0.0, WHICH IS NOT INSTALLED. The first two problems are also shown as text in front of you when the menu first appears. Mods that require the blocked mod are blocked too. - The game is too old or too new for the mod. Same message, with the
gamerange. mod.jsonis not valid. The mod is listed by its file name with every error, for exampleid must be 2 to 40 characters. Nothing from it is loaded.- One file is bad. That one fight, song or level is left out and named. The rest of the mod loads.
- A script throws. The error goes to the console. After 5 errors the script is stopped and the fight goes on.
Other mods and the game itself are not affected by a broken mod. mods.problems() returns the same messages for a menu to show.
Script mods
A script is one ES module. The game calls its default export once with the api. Return a function if you need to clean up when the mod is switched off.
export default function (api) {
let landed = 0;
api.on('fightStart', () => { landed = 0; });
api.on('punch', (e) => { if (e.hit) landed++; });
api.on('roundEnd', (e) => api.ui.toast(`ROUND ${e.round} · ${landed} LANDED`));
return () => { /* switched off */ };
}
Keep the script in one file. It is loaded from its text, so relative imports (./other.js) do not resolve. Use api.THREE for three.js. import ... from 'three' also works, through the page's import map.
Trust
A script runs with the same privileges as the game: it can read the page, the browser storage for this site, and send requests. So:
- A script never runs because a link named it. The start screen shows the mod's name, its author and where it came from, with ALLOW SCRIPT and NOT NOW. The data parts of the mod load either way.
- The permission is for that exact script text (its SHA-256). If the file changes, the game asks again.
- Any fight with a script running, or a modifier on, is marked MODDED on the results card, and
modded: truegoes into the results and the session log. A modded fight does not record campaign progress. - Only allow scripts from people you trust. Read
main.jsfirst; it is one file.
api
| Member | What it is |
|---|---|
api.version |
"1.0.0". Check it if you depend on something added later. |
api.mod |
{ id, name, version } of your mod. |
api.on(event, fn) |
Listen. Returns a function that stops listening. api.off(event, fn) does the same. |
api.state |
Read-only: phase (cal, menu, fight, results), time (song clock, seconds), fight ({ id, title, side, me, him, rounds, bpm, start, end, tutorial, level } or null), score, combo, health (0 to 1), round (from 1), modded. |
api.THREE |
The game's three.js. |
api.scene.add(obj) |
Adds an object to your mod's own group in the scene. The group is removed, with its geometries and materials disposed, when the mod is switched off. api.scene.remove(obj), api.scene.group. Game space is metres, the ring is in front of you along -z. |
api.ui.toast(text, seconds) |
Short text on the page and in front of the player in the headset. At most 80 characters. |
api.settings.get(key, default), .set(key, value), .all() |
Options stored for your mod in this browser. |
api.registerModifier({ id, name, description, apply }) |
Adds a gameplay modifier (below). |
Events
| Event | When | Data |
|---|---|---|
fightStart |
A fight, drill, tutorial or level begins | fight (as in api.state.fight), modifiers (ids applied), modded |
beat |
Every beat of a round, intro bars included | round, beat (from 0 in the round), bar, inBar (1 to 4), time, bpm, live (false during the intro) |
cue |
A cue appears | kind (punch or defence), time (when it is due), round; for a punch hand, punch, target, feint, counter; for a defence move, defence |
punch |
One of your punches is judged | judgement (PERFECT, GOOD, LATE, MISS), hit, hand, punch, target, feint, push, counter, offsetMs, why, time, round |
defence |
You made a defence | defence (slip, roll, guard, lean), move, form (0 to 1), time, round |
hit |
His punch landed on you | move, defence (the one you needed), knockdown, health, time, round |
ko |
Someone goes down | who (you or him), time, finisher |
roundEnd |
A round ends | round, score, health, time, last |
results |
The results card is drawn | A copy of the results (grade, score, accuracy, counts, modded) |
frame |
Every rendered frame | t, dt, phase |
Handlers run inside the frame, so keep them short. frame runs 72 to 120 times a second in a headset.
Modifiers
A modifier changes the rounds of a fight just before it starts.
api.registerModifier({
id: 'early-cues', name: 'Early cues', description: 'cues show 1.5 times as early',
apply(rounds, info) { for (const r of rounds) if (r.tell) r.tell *= 1.5; },
});
rounds is a copy you may edit in place. Each round has bpm, bars, intro (bars before it is live), tell (beats of warning), his (his punches: b beat, move, def) and you (your punches: b, hand, punch, target). info is { id, side, tutorial }. If apply throws, or leaves the rounds in a state the game cannot play, the change is dropped and the fight starts unmodified.
A modifier is off until the player ticks it in the MODS panel (stored), or the link names it: ?modifiers=<mod id>/<modifier id>. Its full id is <mod id>/<modifier id>.
Share a mod
Host it. Any static host works: put the folder online and share https://your.site/index.html?mod=https://you.example/my-mod/. A mod on another site needs CORS headers (Access-Control-Allow-Origin: *) on every file. GitHub Pages and Cloudflare send them for public files.
Or zip it. Zip the folder and send the file. The player drops it on ADD MOD.
Or list it in an index. An index is one JSON file:
{
"format": "counterbeat-mod-index",
"version": 1,
"name": "My mod list",
"mods": [
{ "id": "my-mod", "name": "My Mod", "version": "1.0.0", "author": "Me", "description": "...", "url": "my-mod/mod.json", "script": false, "hash": "sha256-<64 hex digits>" }
]
}
url is relative to the index file or absolute. hash is the SHA-256 of the mod.json bytes; the game refuses to install a mod whose mod.json does not match. script tells the player before installing that the mod wants to run code. node tools/validate-mod.mjs --index mods/index.json --write fills in the hashes, and without --write it checks them. Players open your index with index.html?modindex=<url> and BROWSE.
The hash covers mod.json only. The files it names are not hashed in 1.0.0, so host a mod and its files in one place you control.
Only share music you have the right to share.
Tools
node tools/make-mod.mjs <id> [--name "..."] [--author "..."] [--out mods/<id>] [--fight packs/x/fight.json] [--look tape-201:A] [--arena] [--script]
node tools/validate-mod.mjs <folder or url> [more mods ...]
node tools/validate-mod.mjs --index mods/index.json [--write]
validate-mod.mjs runs the game's own manifest checks, reads every file the mod names, checks its fight packs, and resolves requires against the other mods you pass on the same command line. It exits with 1 if anything is wrong, so it can run in CI.
For the game's own code
src/mods.js exports what a menu needs:
| Call | Returns or does |
|---|---|
mods.list() |
Every mod found: { id, name, version, author, description, source, origin, enabled, state, contributes, script, fights, errors, warnings, notes }. state is active, off, blocked, error or duplicate. script is confirm, running, refused, error, off or null. |
mods.setEnabled(id, on) |
Switches a mod on or off and reloads all mods. Stored for installed mods. |
mods.problems() |
One line per mod that did not load. |
mods.pending() |
Mods waiting for a script confirm. mods.confirmScript(id, yes) answers one. Call it only from a player's own action. |
mods.modifiers(), mods.setModifier(id, on) |
The modifier list and its switches. |
mods.remove(id), mods.addFiles(fileList), mods.addUrl(url, hash), mods.index(url) |
Install and remove. |
mods.modded() |
True when the current fight has a script or a modifier on. |
The same calls are on window.__mods for tests. main.js calls mods.modify (rounds before a fight), mods.punch, mods.defence, mods.hit (where each is decided) and mods.frame (once per frame; it finds fight starts, beats, cues, round ends, knockouts and results by reading the game's state).
Limits in 1.0.0
- A script is one file. No workers, no extra assets through the API (a script can still
fetchits own files by full URL). - Scripts are not sandboxed. The confirm, the hash and the MODDED flag are the protection.
- Modded sessions cannot be replayed exactly in
sessions.htmlwhen a modifier changed the rounds. - There is no MODS screen inside the headset yet. Install and allow on the start screen, then enter VR.
- No online leaderboard exists, so "modded" only marks the results card, the session log and campaign progress.
- Arena signs and textures, and cue sizes, are defined but not read.