Mods / Guides

Custom fights and custom music

Fight packs, timing, and playing a built-in fight to your own music. File and folder names in this guide are paths inside the game’s project.

Counterbeat can play fights and songs that are not built into it. A custom fight is a fight pack: one fight.json, with one audio file or with a song for the game's own band written into it (score). The times in the pack are counted in beats of the song, so a punch written on beat 12 is cued on beat 12 of the music at any tempo.

The code is in src/custom.js. The tools are tools/bpm.mjs and tools/make-pack.mjs. A working pack is in packs/example/, and one with no audio file in packs/example-score/.

Three ways to load one

  1. A link. index.html?pack=<url of fight.json> loads the pack and opens it. The song is fetched from the path in song, relative to the fight.json. Try index.html?pack=packs/example/fight.json. Add &side=B to take the blue corner. A pack on another site needs CORS headers on both files.
  2. The start screen. Press LOAD CUSTOM FIGHT and pick fight.json and the audio file together, or press FOLDER and pick the pack folder, or drag both files onto the page. The pack is saved in the browser (IndexedDB) and comes back on every visit. In the game it is the first card under FIGHTS, marked CUSTOM · <bpm> BPM. The Quest browser's file picker works the same way: do it before pressing ENTER VR. REMOVE next to a saved item deletes it.
  3. Your own music on a fight that is already in the game. On the start screen, choose the fight in the list, type the song's BPM and the time of its first beat in milliseconds, then pick or drop the audio file alone. Every round of that fight then runs at the song's tempo with the recording playing in place of the game's own music. By link: ?fight=first-bell&song=<url>&bpm=100&offset=489.

Storage is per browser and per site. A pack loaded on the desktop is not on the headset until you load it there too.

The format

{
  "format": "counterbeat-fight",
  "version": 1,
  "id": "my-first-fight",
  "title": "My First Fight",
  "song": "song.mp3",
  "bpm": 100,
  "offset_ms": 489,
  "intro_bars": 2,
  "tell": 1.0,
  "fighters": {
    "A": { "name": "RED",  "style": "BOXER",   "stance": "orthodox" },
    "B": { "name": "BLUE", "style": "SLUGGER", "stance": "southpaw" }
  },
  "difficulty": { "A": 1, "B": 2 },
  "windows": [
    { "beat": 8, "actions": [
      { "beat": 0,   "who": "B", "action": "jab",   "hand": "lead", "target": "head", "react": "slip" },
      { "beat": 0.5, "who": "B", "action": "cross", "hand": "rear", "target": "head" },
      { "beat": 2.5, "who": "A", "action": "hook",  "hand": "lead", "target": "body" }
    ] }
  ]
}
Field Meaning
song Optional when the pack has a score. Audio file, relative to fight.json. mp3, ogg, wav and m4a decode in Chrome and the Quest browser. A Beat Saber .egg is an ogg file and loads as it is.
score Optional. A song for the game's band, in the format of docs/SONGS.md, written inside fight.json. A pack with a score and no song needs no audio file: the band plays it at the pack's bpm. With both, the recording plays and the score decides the notes your punches play. A score that is not valid does not stop the pack loading; the band plays a song written from the chart and the console says why.
bpm Tempo of the song. One value for the whole song.
offset_ms Where the first beat falls in the audio file, in milliseconds. Beat 0 of the pack is this moment.
intro_bars Bars of music before the round is live (default 1). Keep the first window at or after intro_bars × 4 beats.
tell How many beats ahead his punches and your targets show (default by difficulty: 1.0 easy, 0.85 medium, 0.7 hard).
fighters Names, style (OUTFIGHTER, BOXER, COUNTER, PRESSURE, SWARMER, SLUGGER) and stance (orthodox, southpaw) for corners A and B. You can play either corner. A southpaw leads with the right hand.
difficulty 1 to 3 for each corner.
windows The exchanges. beat is the beat of the song the exchange starts on.
actions The punches. beat is counted from the start of the window. who is A or B. action is jab, cross, hook, upper or feint. hand is lead or rear. target is head or body. react is optional: the defence the other fighter should make (slip, roll, block, lean).

This is the game's own chart shape (charts/sequences.json) with one change: t in seconds became beat in beats.

The punches of the corner you play become your targets. The other corner's punches come at you. Beats are rounded to quarter beats when the fight is built.

What the game adds for you

  • A punch of yours half a beat after his is marked as a counter. Two punches from the same fighter half a beat apart are a double.
  • His last punch gets the replay and your last punch is the finisher.
  • If react is missing: hooks are rolled under, body shots and uppercuts are blocked, straight punches are slipped.

Limits in version 1

  • One round per pack. A long chart is one long round.
  • One tempo per song. A beats array (the time in milliseconds of every beat, for songs that change tempo) is reserved in the format and is not read yet.
  • If the chart is longer than the song, the song loops and the loop point will not be on the beat. make-pack.mjs warns about this.
  • No clinches and no charted footwork in packs yet.

How timing works

The game's clock is the audio clock. A fight is a list of rounds, and every cue in a round is at round start + beat × 60 / bpm (buildFight in src/fight.js). For a pack, src/custom.js builds one round at the pack's bpm, with each cue on the beat the pack names. It then starts the recording so that the audio moment offset_ms lands exactly on the round start. From there, beat n of the chart and beat n of the song are the same instant.

For custom music on a built-in fight, the fight keeps its punches and its beat positions, every round's tempo is set to the song's bpm, and the recording starts the same way. Rounds are whole bars long, so round 2 and round 3 also start on a beat.

Two things decide whether it feels right:

  • BPM. If it is off by 0.5 bpm, the cues drift 150 ms from the music after one minute at 100 bpm. Use tools/bpm.mjs, then listen.
  • Offset. If it is wrong, every cue is early or late by the same amount. If your hits feel late against the drums by a steady amount, change offset_ms by that amount.

tools/bpm.mjs can pick half or double the real tempo, and it can lock to the off-beat (an offset wrong by half a beat). Both are easy to hear and quick to fix by hand.

Make a pack by hand

  1. Put the song in a new folder, for example packs/my-fight/song.mp3.
  2. Find the tempo: node tools/bpm.mjs packs/my-fight/song.mp3. It prints bpm and offset_ms. Pass --min and --max if you know the range, and --write packs/my-fight/fight.json to put the numbers straight into a pack.
  3. Copy packs/example/fight.json and change title, song, bpm, offset_ms and the fighters.
  4. Write the windows. Count the song in bars of four beats. Start each exchange on a bar line (beat 8, 12, 16 and so on). Inside a window, 0 is the first punch, 1 is one beat later, 0.5 is half a beat.
  5. Leave two beats between your last punch and his next one, so his wind-up can be seen. Do not put three punches in a row on half beats.
  6. Play it: python3 -m http.server 8804, then http://localhost:8804/index.html?pack=packs/my-fight/fight.json. Add &demo=1 to watch the scripted player box it.

Make a pack from a fight that is already charted

node tools/make-pack.mjs <chart id> <audio file> [--bpm 100 --offset 489] [--out packs/name] [--title "..."] [--grid 0.5] [--link] [--max-windows N]

This takes a fight from charts/sequences.json (for example tape-001) and moves every punch onto the song's beat grid. Punches from one fighter keep their real spacing, rounded to the grid. A change of fighter gets two beats. Each exchange starts on a bar line. Without --bpm and --offset it measures them with bpm.mjs. --link points at the audio where it is and does not copy it.

Leave the audio file out and give a tempo to make a pack the band plays: node tools/make-pack.mjs tape-001 --bpm 108 --style son --key E --out packs/my-fight. The pack then carries a score written from its own chart. Add --score to a pack that has an audio file to give it one too.

The example pack was made with:

node tools/make-pack.mjs tape-001 assets/arroz-con-pollo.mp3 --out packs/example --title "Arroz Con Pollo Rounds" --link

It uses "Arroz Con Pollo" by Kevin MacLeod (CC BY 4.0, see assets/CREDITS.txt), measured at 100 bpm with the first beat at 489 ms. Only share packs with music you have the right to share.

Ideas from FitBeat and Beat Saber

What was looked at

  • The two FitBeat videos could not be downloaded. YouTube refused yt-dlp with its "sign in to confirm you're not a bot" check, from the Windows PC and from the Mac, with the default client and with the tv, safari and android_vr clients. No frames and no captions were read. Only the titles came back, from YouTube's oEmbed endpoint:
    • Fxq_ZLD9lIg: "New FitBeat Song! Expert+ | 1-Handed | 360 | All FC!" by Tempex.
    • akc02QIaXYg: "K/DA - More [Fitbeat] (Expert+) | Beat Saber Gameplay Preview" by Irahi's beat saber maps.
  • So both videos are Beat Saber. FitBeat is a song in Beat Saber's official soundtrack, written as a workout, and "Fitbeat" has become a label mappers put on custom maps built the same way. The notes below about what FitBeat maps do are from general knowledge of that song and of fitness maps, not from watching these two videos. To watch them, pass cookies to yt-dlp (--cookies-from-browser chrome) and run the frame-sheet step again.
  • Beat Saber's map format was read from the BSMG wiki (bsmg.wiki/mapping/map-format, the Info, Beatmap and Audio pages). No mods or game files were downloaded.

How Beat Saber custom songs work

  • A map is a folder: Info.dat (JSON), one beatmap file per difficulty, the audio, a cover image. The game only insists on the name Info.dat.
  • Info.dat in version 2 has _songName, _songAuthorName, _levelAuthorName, _beatsPerMinute, _songTimeOffset, _songFilename, _coverImageFilename, preview times and _difficultyBeatmapSets (each difficulty with its file name, note jump speed and start-beat offset). Version 4 groups the same things under audio (songFilename, bpm, songDuration, audioDataFilename, lufs).
  • Audio is ogg. Community maps rename it .egg so other apps do not index it.
  • Note times are in beats, not seconds. Version 2 note: _time, _lineIndex (column 0 to 3), _lineLayer (row 0 to 2), _type (0 red/left, 1 blue/right), _cutDirection (9 values: eight directions and "any"). Version 3 shortens these to b, x, y, c, d and adds a (angle offset). Bombs and obstacles (walls) are separate lists, and walls have a duration in beats. The wiki gives the recipe for a crouch wall: layer 2, height 3.
  • Tempo changes are bpmEvents (b beat, m new bpm) in the beatmap, and an audio data file (BPMInfo.dat) that maps sample ranges of the audio to beat ranges (_startSampleIndex, _endSampleIndex, _startBeat, _endBeat). That file is the real link between audio and beats.
  • Tools and sharing, as generally known in that community: maps are made in editors such as ChroMapper, Beatmapper and the official editor; the song is prepared in Audacity or with ArrowVortex to find BPM and offset, and mappers usually add silence so beat 0 falls on a beat rather than rely on the offset field; maps are shared on BeatSaver and installed by one-click links or in-game browsers; ScoreSaber and BeatLeader keep leaderboards per map.

The fight pack copies the parts that matter: a folder, one JSON entry file, the audio beside it, bpm plus offset, and times in beats.

Recommendations, most valuable first

  1. Times in beats with bpm and offset per song. Done in this change. It is what makes custom music work at all, and it is the one idea every Beat Saber tool depends on.
  2. Held defences on the beat, FitBeat's squat walls. Fitness maps are built from walls you duck or lean around for several beats, on bar lines, in sets. Counterbeat is seated, so the match is a lean or a roll held for two to four beats while a long hook or a clinch arm passes. Add a hold length (in beats) to his actions. It adds the workout feel and needs no new input.
  3. Difficulty levels inside one pack. Beat Saber ships Easy to Expert+ for the same song as separate beatmap files. Let fight.json carry levels: { easy: {windows}, hard: {windows} }, or let the game thin a chart (drop half-beat punches) for an easy level.
  4. Approach time as a player setting. Note jump speed and offset decide how long you see a note. Here that is tell. Offer SLOW / NORMAL / FAST reaction time in the menu and scale tell, without changing the chart.
  5. Full combo and accuracy on the results screen. "All FC" is in the first video's title because players chase it. Show FULL COMBO and an accuracy percentage per fight, and store the best per pack id.
  6. One-handed play. The first video is a one-handed run. A "lead hand only" or "one hand" modifier that remaps every punch to one glove is cheap and helps players with one tracked hand.
  7. Share by link and a pack index. BeatSaver works because a map is one URL. ?pack= already does this. Next: a packs/index.json list shown under CUSTOM in the headset, and a single-file pack (zip) for the file picker.
  8. A charting page. Mapping tools are why there are many maps. A desktop page that plays the song with a beat grid and lets you tap J / C / H / U for each corner would write fight.json directly. A recorded play session (sessions.html) could also be saved as a pack.
  9. Tempo maps. Read the reserved beats array (or Beat Saber's sample-to-beat regions) so songs that speed up or were played live stay in time.
  10. Loudness. Version 4 of Beat Saber's format stores LUFS per song. Measure loudness in bpm.mjs and store a gain so custom songs sit at the same level as the game's own music and the hit sounds stay audible.
  11. 360 play. The first video uses 360 mode, where notes come from all around. Counterbeat already has roam and footwork from charted fights. For a seated game this is low value.

Back to mods