Install a beatmap

A beatmap is one .blockymap file. There are four ways to get it into your game; the first one needs nothing but the game.

Before you start

Beatmaps need the Blocky Music mod for Minecraft 1.21.1 on NeoForge. Install the mod first, start the game once, and let it create its folders.

Get the mod from qwu.world

1. From the in-game browser (easiest)

Press Alt+B in game. The same screen is on the title screen’s Workshop button and in Blocky Music settings, so you can rebind or ignore the key.
Search for a title, an artist, a mapper or a map number, listen to the preview, and open the map you want.
Press Install. The map downloads, is checked, and appears in your track list straight away, with nothing to unpack and no file to move.

The browser asks once whether the mod may talk to this site. Until you agree, the Workshop screens stay offline; the file routes below still work, and the helper waits until you answer.

2. One click from this site (the helper)

The QwU Workshop Helper is a small separate program. With it installed, “Install in game” on a map page goes straight to Minecraft: the map is queued in the game and installs the next time you look at the Workshop, whether the game is running or closed.

Installing it, once, teaches your computer three things:

that blockymusic:// links belong to the helper, so “Install in game” here reaches your game;
that .blockymap files belong to the helper, so a double click on a downloaded map installs it;
which Minecraft instance to use: it looks for the mod itself, and asks you once if you have more than one.

The helper downloads nothing, opens no network connection and needs no account. All it does is write a small file into your game’s workshop_inbox folder; the mod does the rest, under the network permission you already gave it.

Download

The helper is not code-signed yet, so macOS Gatekeeper and Windows SmartScreen will warn the first time. On macOS, open the app from the Finder’s right-click menu and choose Open; on Windows, choose “More info” then “Run anyway”. Check the SHA-256 sum above against the file before you do.

Removing it

Run the helper once with --unregister in a terminal. That gives the .blockymap file type and blockymusic:// links back to whatever had them before, and touches nothing else.

qwu-workshop-helper --unregister

Then delete the program itself. Nothing is left behind except a small settings file that remembers which instance you picked (QwU/workshop-helper.json in your user folder).

3. Drag and drop a file

On a map page here, press Download and save the .blockymap file.
With Minecraft running, drag the file onto the game window: the title screen, the track list or any Workshop screen all accept it.
The mod checks the file and installs it, and a toast tells you which map arrived.

4. The inbox folder

If the game is not running, or you install maps for somebody else, put the files here instead:

<game folder>/music_battle_tracks/workshop_inbox/

The folder is read when the game starts, when you open the Workshop, and every few seconds while a Workshop screen is open. Every valid package is installed and removed from the inbox.

A file that cannot be installed moves to workshop_inbox/rejected/ with a .txt file next to it that says why.

Where the files live

Everything Blocky Music uses sits in music_battle_tracks inside your game folder. Installed maps get one folder each, next to the tracks you added yourself.

Official launcher: .minecraft (Windows: %appdata%\.minecraft, macOS: ~/Library/Application Support/minecraft, Linux: ~/.minecraft).
Modrinth App, Prism and CurseForge give every instance its own folder. Use that instance’s folder, not .minecraft.

Not sure which one the game uses? Open the Workshop, go to Installed, and use “Show files”.

If a map does not install

Check that the mod and Minecraft versions match the ones on the map page. A map built for a newer mod will not load on an older one.
Look in workshop_inbox/rejected/: the .txt file next to your map says exactly what was wrong.
Some maps ship without audio and ask you for your own copy of the song. How “bring your own audio” works
A map that was taken down cannot be installed any more, even from a file you saved earlier.