Map pooling
The role:pooler permission can add, edit, and remove maps. Pool creation/publication is reserved for admins and developers. Use the website map tools where available or the authenticated REST endpoints documented at /docs on the backend.
Pool workflow
- Confirm the target season and have an admin create its named pool.
- Curate a balanced set across intended skill bands and styles. Map categories can label maps as speed, tech, accuracy, challenge, or another useful grouping.
- For every map, provide the BeatSaver key, characteristic, difficulty, map category, and exact modifier array. The server resolves current BeatSaver metadata rather than trusting manually supplied name, hash, duration, or maximum score.
- Verify availability and playtest the exact map with its exact modifiers on every supported game and plugin build.
- Ensure there are at least 10 maps before queue launch. Match creation deals ten distinct maps—five to each competitor—and discard replacement requires additional maps not previously seen in that individual hand.
- Publish only after peer review, then create/enable queues referencing the pool.
Stored competitive identity
A pool entry is unique by pool, SHA-1 hash, characteristic, and difficulty. Hashes must be 40 hexadecimal characters. Duration and maximum score must be positive. Only one of SS, FS, or SFS can apply to a map.
Supported modifiers are:
| Code | Meaning | Code | Meaning |
|---|---|---|---|
| NF | No Fail | NW | No Walls |
| NB | No Bombs | NA | No Arrows |
| SS | Slower Song | FS | Faster Song |
| SFS | Super Fast Song | IF | Insta-Fail |
| 4L | 4 Lives | DA | Disappearing Arrows |
| GN | Ghost Notes | PM | Pro Mode |
| SA | Strict Angles | SN | Small Notes |
| ZM | Zen Mode |
Changing a BeatSaver upload can change its hash, duration, and maximum score. Treat it as a new competitive map and retest it rather than silently substituting it.
Public player resources
GET /maps/hashes lists known hashes, GET /maps/playlist returns a Beat Saber playlist-shaped response, and GET /maps/download/{hash} redirects through BeatSaver. GET /pools/{poolGuid}/maps exposes a pool with map categories. Map categories are managed through /map-categories. The older generic /queue pooling batch routes are placeholders and currently return 404 Not Implemented.