Mapping ​

Too many anime maps? Not enough anime maps?
Take matters into your own hands and learn to map here!

• Mapping Term Glossary

Mapping Quick Start ​

The wiki is your building blocks, the community is your inspiration, and you are the creativity.

Great mappers are not made in a day. It takes dedication with no one really able to hold your hand. The best we can do is provide you the tools with this wiki and clarify any questions you have to succeed in your mapping career!

1. Download the necessary tools for mapping: an audio editor and a map editor.
2. Set up your audio file, find and confirm the BPM, and export in OGG format.
3. Set up your song in your mapping editor (steps vary by editor).
4. Get mapping! Review basic mapping practices before you start. Playtest your own work early and often while mapping.
5. Get lighting! Review basic lighting information. Simple manual lighting is easier than you think!
6. Get your map playtested! Third-party playtesting via the BSMG Discord is highly recommended to get constructive feedback and to get past your own "map blindness."
7. Once your song has been mapped, lighted, and playtested you're ready to release your song to the world on BeatSaver.

Video Tutorials ​

Text guides aren't your thing? Checkout these video series!

Recommended ​

• Helen Carnate's Mapping Tutorial - A 17 minute guide to get started mapping using Mediocre Map Assistant 2!
• Fruhead's Beginners Guide to Mapping - A comprehensive lecture series on making your first map using Mediocre Map Assistant 2.
• ChroMapper Editor Guide - A series of videos on how to use the core features of the ChroMapper Editor.
• Cyrix's Patterns to Avoid as a New Mapper - Covers the most common issues discussed in Basic Mapping.
• TranquillizeMe's Beat Saber Lighting Techniques Tutorial - Covers various lighting techniques and general lighting tips.

Legacy Videos ​

• BennyDaBeast's Mapping Tutorials
• Freeek's Mapping and Editor Tutorials

Audio Editing Resources ​

Before mapping, you need to get your audio file ready so that it works with your map editor. This section will walk you through how to set up and edit your audio file using a free program called Audacity.

Basic Audio Setup ​

Can't make a map without audio. Learn how to setup your audio for easy mapping!

Advanced Audio Editing ​

A deeper dive in adjusting audio files such as making shorter versions or working with variable BPM.

Map Editing Resources ​

Community Editors ​

Keyboard shortcuts for these editors are available inside their respective in-editor menus with a cross-reference between all of them available here.

ChroMapper ​

Now in open beta! A 3D editor that has stellar support for lighting, Chroma, Noodle Extensions, 360/90 mapping, and shares similar assets with Beat Saber, allowing for a more accurate preview. By FAR the most feature-rich editor available to the community.

Joining the ChroMapper Discord is encouraged to access plugins, scripts, and application support (mapping support is available in BSMG).

• ChroMapper Launcher Download
• ChroMapper First Time Setup Guide
• ChroMapper Wiki

Mediocre Map Assistant 2 ​

MMA2 was used by the majority of the mapping community until the ChroMapper open beta.

• Mediocre Map Assistant 2 Download
• Mediocre Map Assistant 2 User Guide

Beatmapper.app ​

A 3D editor that runs in the browser, allowing anyone with a web browser to map. It works best for standard mapping without any extensions, but new features are being added.

• Beatmapper Website
• Beatmapper User Manual

Official Editor ​

The official editor is developed and supported by Beat Games and pre-installed with the Steam VR or Oculus PC versions of Beat Saber.

• Official Editor Documentation

Migrating from Official Editor to a Community Editor ​

Although it is recommended to start setup again following the Quick Start guides with a Community Editor, it is possible to transfer your work in the Official Editor over.

1. Install a Community Editor
2. Locate your map files in your game's CustomLevels folder.
   • Steam Example Location: C:\Program Files (x86)\Steam\steamapps\common\Beat Saber\Beat Saber_Data\CustomLevels
   • Oculus Example Location: C:\Program Files\Oculus\Software\Software\hyperbolic-magnetism-beat-saber\Beat Saber_Data\CustomLevels
3. Move it to the folder your editor is looking in. This is commonly the CustomWIPLevels in the Beat Saber_Data folder.
   • Steam: C:\Program Files (x86)\Steam\steamapps\common\Beat Saber\Beat Saber_Data\CustomWIPLevels
   • Oculus: C:\Program Files\Oculus\Software\Software\hyperbolic-magnetism-beat-saber\Beat Saber_Data\CustomWIPLevels
4. Convert your audio file to the .ogg format from .wav if you have not done so.
   1. Download and Install Audacity
   2. Open the .wav file in Audacity
   3. Click the File menu -> Export -> Export as OGG.
   4. Name your file song.ogg and click Save.
   5. Place the song.ogg file into the map folder.
      • You no longer need the .wav song file in this folder
5. Open the map in the community editor and change the song file name to song.ogg and click the save button.

You are now ready to continue editing your map!

Data Loss Prevention and Cloud Storage ​

Updating your game may remove all Custom Level data, one way you can prevent complete data loss is with Symbolic Links! This allows you to store your maps in a different place on your computer, such as a folder synchronized to the cloud, and mirror them in the game directory. The link created will not delete your maps if it is removed due to updating or uninstalling the game however, recursive deletion will remove your maps.

Using a cloud storage folder is useful if you jump between multiple computers or extra security for your files in case of storage disk corruption.

The following instructions are for Windows 10 and 11.

1. Move the current levels folder over to your new location. (Ctrl + x the folder instead of Ctrl + c)
   • If this is a cloud location make sure to set the folder to be available offline!
2. Open command prompt
3. Run this command adjusting the parameters to match your situation.
   mklink /j "Path to Beat Saber Install folder" "Path to New Location" * Heres an example command:
   mklink /j "C:\Program Files (x86)\Steam\steamapps\common\Beat Saber\Beat Saber_Data\CustomLevels" "C:\Users\cmb\CloudStorage\CustomLevels"

If it's on a network drive, replace /j with /D. Note that you will need to open command prompt as administrator for this to succeed.

Additional Mapping Tools ​

• BS Viewer by +1 Rabbit
  A convenient way to see how your map might look in game without the game.
• +1 Rabbit's Mapping Tools by +1 Rabbit
  A suite of tools for mappers that includes:
  • Schema Fixer: Easily fix maps made in Mediocre Mapper Mk4.1 and Mk5 for upload to BeatSaver.
  • Tempo Changer: Change the BPM of an entire map and shift block placements accordingly.
  • Offset Remover: Removes editor offset and snaps notes/obstacles/events to common precisions to try and mitigate floating point error.
  • Note Sorter: Sorts unordered notes/obstacles/events in the map file to fix stack spawning.
  • Copy Timing: Moves notes in one difficulty based on another within a certain window. Useful to apply small timing changes across all difficulties for specific sounds.
  • Copy Lighting: Copies all of the lights, with the option to include/exclude custom events from one difficulty to all other difficulties.
  • Map Diff: Compare between two versions of a map. Useful for testplayers and Ranking Team members to see if any changes were made.
• Parity Checker by GalaxyMaster
  An error checker tool that focuses on finding issues with parity in a map.
• Map Check by Kival Evan
  An error checker tool that is much more versatile than the one built into MMA2.
• noodleLister by Bloodcloak
  Easily compile a game playlist from a txt file containing BeatSaver map keys.

Legacy Tools ​

These tools may no longer be supported, compatible with the latest software, or relevant with current practices, but could still fulfill a niche use case.

• BeatMerge by DarkGrisen
  Ever thought that it is a lot of annoying work to make big maps with other people or to perfectly cut the audio files so you can merge them manually later? This tool allows you to merge two or more maps into one single super long map.
• Cinder by zhaey
  Python program that converts stepmania .sm files to Beat Saber .dat files for timing notes.
• osu! Editor Timing Tutorial by Fayhe
  Video guide on using the timing feature of osu!'s editor to find map bpm.

Useful Mods ​

Here are some mods that might make your mapping workflow a little easier.

• SiraUtil by auros
  With the First Person Flying Controller (FPFC) launch parameter, this allows you to control the game while a map is playing with your keyboard and mouse without using a headset. See the section in Basic Lighting for links to the mods and how to set it up.
• PracticePlugin by denpadokei
  Mod for Beat Saber to control playback speed, seek through songs and set up looping sections. Install the latest version from Mod Assistant!
• ReLoader by Kyle1413
  Allows you to hot reload beatmaps in practice mode without needing to return to the menu to refresh. Really convenient for wall mapping.

Mapping Practices ​

"You have to know the rules before you can break them."
- Uninstaller

There is no holy bible of mapping but this section of the wiki includes a lot of tribal knowledge from the community on best practices at all levels of mapping. Our advice is to follow these rules until you're comfortable with your skills and then get creative, experiment, and innovate!

Basic Mapping ​

All new mappers need to read this, no exceptions!

Intermediate Mapping ​

A more in-depth look at many mapping topics

Downmapping ​

A comprehensive guide to making lower difficulties.

Extended Mapping ​

Mapping Extensions, Extra Characteristics, and 360°/90° mapping

Mapper Roles ​

To apply for the Mapper role on the Beat Saber Modding Group Discord you must have released three solid/playable maps (collaborations are acceptable) and complete the Mapper Role Submission Form. Your application and maps may take a decent amount of time to be reviewed and approved.

Curation ​

Mappers can submit high quality maps, free of objective issues to the #curation-request channel on the BeastSaber Discord. Maps selected for curation are given extra visibility on the site and included in the Curator Recommended feed.

Modding & Ranking ​

Maps that meet specific Ranking Criteria and go through an intensive review process called "modding" have the potential to become ranked, awarding players Performance Points (PP) toward global leaderboards. More information and an in-depth FAQ is available on the ScoreSaber Discord

• Prior to requesting ranking, mappers should thoroughly review the ranking criteria and metadata standards and have their map modded by a knowledgeable source.

• Once your map has been modded and revised, it's ready to be presented to a ranking team member or recruit to review.
• If the ranking team member deems the map acceptable it will be added to the ranking request queue to be voted on by the full ranking team.

Mapping Anxiety ​

If you're finding it difficult to muster up the courage to upload your map, or are finding it emotionally taxing coping with a lack of downloads or a lot of dislikes, you're not alone. Many mappers have experienced these feelings. You can read more about it on the Coping with Mapping Anxiety page.

Lighting Practices ​

A map is not finished until some form of lighting is included. Lighting can range from very basic to incredibly detailed using additional mods to enable more features.

Basic Lighting ​

Learn the various aspects to lighting your map manually

Intermediate Lighting ​

Master more environments and get into strobing, ring spins and contrast practices

Advanced Lighting ​

Advanced and nuanced techniques

Extended Lighting ​

Lighting for custom platforms and Chroma RGB

Automated Lights ​

Not ready to make your own lighting? Here are some programs to do it for you. Keep in mind, creating simple manual lighting is not difficult and will always be better at expressing the atmosphere of the song than using these programs.

• Lolighter by Loloppe#6435 - Standalone program for automated lighting and has other features to modify your map.
• LiteMapper by ItsOrius - A website that automatically generates lights based on pacing, emphasis, and note placement. For more information on the algorithm check out the Readme.
• Lightmap - It is integrated into Mediocre Map Assistant 2 and can be accessed in the error checker menu.

Playtesting ​

Testing your work is a critical part of mapping. Testing as you work helps you adjust for major playability issues and get a feel for your map. Third-party or "outside" playtesting is when someone other than yourself tests your pre-release map and provides constructive feedback and is helpful in highlighting issues to which you may be "map blind."

• If your map is using the 1.0 map format (your files are .json and .ogg) you must convert your map by updating your editor, opening and saving the map. See Community Editors for links to modern editors.
• If your map is using the 2.0 or 3.0 map format (your files are .dat and .ogg/.egg) you're ready to test.

Testing on a PC ​

Follow these steps to test any of your maps made with a community editor using PC-based VR.

1. If your WIP song folder isn't already in Beat Saber_Data\CustomWIPLevels then place a copy there.
2. Access your map in-game via the CustomWIPLevels category in the song pack menu. Use practice mode to play (the button next to the play button).

Made changes to your map while the game is open?
Click on the game window. Then while you are on the Main Menu or Song Select Menu press Ctrl + r on your keyboard. Your changes will be loaded without needing to restart the game!

Testing on a Quest ​

Follow these steps to test any of your maps made with a community editor using an Oculus Quest. You must have SideQuest and BMBF installed.

1. Locate your WIP song folder on your PC.
2. Establish a connection to your Quest from your PC with a USB cable.
3. Open SideQuest on your PC and click the folder icon on the top right.
4. Navigate to sdcard/ModData/com.beatgames.beatsaber/Mods/SongLoader/CustomWIPLevels. If this folder does not exist, you can create it yourself.
5. Upload your WIP song folder from your PC to that folder on your Quest with SideQuest.
   • NOTE: You need to upload the actual song folder, not a zip file!
6. Your map will now show up on the CustomWIPLevels song pack inside your game. Keep in mind that you will only be able to play your map using the practice mode, and not with the regular Play button!

Community / Third Party Testing ​

The #testplays channel in the Beat Saber Modding Group Discord makes it easy to have your work checked by knowledgeable mappers. Playtesters will provide constructive feedback on how to improve your map in either video or text format in a DM or in the #mapping-discussion channel.

1. Create a compressed .zip file of the individual song files.
   • If you are using CM, you can press the Create Zip button in the Song info Settings to create a compressed .zip of your map.
     
   • If you are using MMA2, you can press the Package Song to Zip button in the Song Info Settings to create a compressed .zip of your map.
     
   • If you are using Beatmapper.app, follow their downloading instructions.
   • You can manually create the zip by following this How to Video if you are not using a web based editor.
2. Upload your map to #testplays using the following format:

• Map: The name and artist of your map
• Length: The length of the song
• BPM: The BPM of the song
• Difficulty: Which difficulties are included
• NPS: The notes per second of each difficulty available
• Feedback: Any requests for feedback (specific difficulties to be tested, things to look for etc.)
• Status: What state is the map in? (i.e., First draft complete, no lights; 1:45 mapped; release candidate w/ lighting; etc.)

3. Testers will usually look at your map within 1-7 days and will use a number of reaction emojis (listed in #testplays pinned posts) to track testing status.

You can copy and paste the following template into Discord:

**Map:**
**Length:**
**BPM:**
**Difficulty:**
**NPS:**
**Feedback:**
**Status:**

**Map:**
**Length:**
**BPM:**
**Difficulty:**
**NPS:**
**Feedback:**
**Status:**

Help Playtest ​

Do you like the idea of playing new songs before they are ever released on BeatSaver? Do you want to help shape the mapping community? Consider becoming a testplayer! Check out the How to Testplay guide to get started!

Publishing Songs ​

Once your song has been mapped, lighted, and playtested and it's a finished product you're ready to release it to the world!

BeatSaver ​

BeatSaver is the public repository for all custom Beat Saber maps.

How to Release a Map ​

BeatSaver Troubleshooting ​

Here are solutions for some common errors when uploading a Beatmap.
Encountered something not listed here? Drop into #mapping-discussion for assistance.

Map already uploaded ​

• The exact map files were uploaded previously. You must change something small in your map (i.e., remove a light block, save the map, replace the light block, and save again) to be able to upload.

_difficultyBeatmapSets[]._difficultyBeatmaps[].`Difficulty.dat`._version: Must not be null ​

• You are using an old, outdated editor that is not compliant with the current data schema. See Community Editors for the current options.

_difficultyBeatmapSets[]._difficultyBeatmaps[]`Difficulty.dat`._notes[]_time: Must be between 0 and x ​

• Your map contains notes outside of the playable map (usually from a copy and paste error). Remove them and reattempt your upload.

Internal Server Error ​

This is the default error message, causes include:

• An upload that is close to or over the actual file size limit of 15 MB. Reduce the audio export quality slightly to make space.
• Unsupported characters are present in a file. Make sure your metadata and bookmarks don't contain special characters such as, Japanese (日本語/にほんご), Kaomoji (٩(◕‿◕｡)۶), Chinese (汉语/漢語), Arabic (اَلْعَرَبِيَّةُ‎), and accented characters (Ä/é/õ/Æ/ø/ß/Œ/Ð/ƒ).
  • +1 Rabbit's Mapping Tools by +1 Rabbit may be useful in finding the specific problem.
• Expired web session. If you refresh the page, you should be logged out. Login and try to upload again.

Could not verify user [] ​

• This error is related to recaptcha. Please reload the page.

Beatmap zip contains an illegal file! OLD ​

• Usually caused by extra/unsupported files, such as gifs, in the zip.

Beatmap does not contain an Info.dat file! OLD ​

• Usually caused by having the files in a subfolder. You need to zip the files instead of the folder. How to Video Or use the handy export button in your editor instead. NOTE: MMA2's export button does not include contributor images in the zip.

One or more beatmap difficulty files cannot be found! OLD ​

• You might have forgotten to include all of your difficulty files are in the zip.
• A difficulty's "_beatmapFilename" in the Info.dat might be using a different file name than what is present in the folder.
• A deleted difficulty is still being referenced in your Info.dat file. Check to make sure you do not have unintended difficulties in the "_difficultyBeatmaps" cluster of each present characteristic.

Error in MapDifficulty.dat. Root should NOT have additional property: _time. OLD ​

_time is the common error for this type of message. However, the same solution applies if a different property is flagged.

• Your files are not compliant the map schema. See Schema Change for solutions.

Beatmap could not be parsed! OLD ​

• This could be caused by extreme server load. Try again later or ask in #mapping-discussion.

Field ._customData._contributors[]._iconPath contains an invalid filename. OLD ​

• Utilizing the contributors field requires all aspects to be included. Make sure all 3 aspects (Role, Name, iconPath) are filled and there is a unique square image for each iconPath entry in your zip.

BeastSaber ​

BeastSaber is a song review and curation site with social features including reviewing and commenting on songs. All songs published on BeatSaver are mirrored to BeastSaber within 10-15 minutes. Additionally, maps deleted from BeatSaver may take up to a day to be removed from BeastSaber.

Credits ​

Over thirty different mapping guides and tutorials have been combined into this wiki so that it can be maintained by the community as a whole. Many many MANY thanks to the mappers who blazed this trail and contributed content. Check out the whole list here!