# 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

Go from thinking about mapping to releasing your first map by following this checklist.

1. Download the necessary tools for mapping: an audio editor and a map editor.
2. Set up your audio file including finding and confirming the BPM and exporting to OGG format.
3. Set up your first song in your mapping editor (steps vary by editor but here's the user guide for MMA2).
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 Beat Saver.

# Video Tutorials

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

• BennyDaBeast's Mapping Tutorials Recommended Series

• Freeek's Mapping and Editor Tutorials

# Audio Editing Resources

Before you can start mapping you need to choose a song, find some basic information about it, and set it up using an audio editor. The most commonly used editor is the free Audacity utility. The rest of this audio section will reference how to use this tool to set up and edit your audio file.

• Basic Audio Setup
• Advanced Audio Editing

# Map Editing Resources

There are both official and community-developed editors available and preference is highly personal and frequently shifting as new official and community-developed tools come and go.

# Community Editors

Community editors are often a source of innovation with a lot of beneficial quality of life features for mappers, and can be used by mappers without VR. However, they may also be incomplete, unstable, or unpredictable at times so use with caution.

# Mediocre Map Assistant 2

A fork of a fork of a fork... the most feature rich 3D editor based off of Mediocre Mapper and is used by the majority of the mapping community, now stripped of memes and all the fun stuff. RIP Bongo cat.

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

# BeatMapper.app

A new web-based 3D beat saber editor that runs in the browser so it's platform agnostic. Yes, mac and linux users, this means you can map, too! Works best for standard mapping without mapping extensions but new features are being added regularly.

• BeatMapper Website
• BeatMapper User Manual

# ChroMapper

Coming soon! ChroMapper is a unity-based full-featured editor, developed by Caeden117, which is in the final rounds of bug fixing and is in closed beta. It uses the same engine as Beat Saber, which provides a much more true-to-life preview of lights and environments. ChroMapper also has stellar support for lighting and Chroma RGB.

# Official Editor

The official editor is developed and supported by Beat Games and pre-installed with the Steam VR or Oculus PC versions of the game. It makes playtesting very convenient with one-click access to your work-in-progress in-game. The official editor is 2D and requires good visualization skills to translate well to a 3D play space, which can be challenging for new mappers. The vast majority of mappers use a Community Editor.

• To access, launch the editor from within Beat Saber in your HMD or use fpfc launch parameters to open directly from your PC
• Check out Megalon's Official Editor Tutorial Video for an overview of standard mapping!

# Additional Mapping Tools

• BeatMapperTools by Darkuni A utility for users of Mediocre Mapper and Mediocre Map Assistant 2 to easily convert, test, and package their maps.
• +1 Rabbit's Mapping Tools by +1 Rabbit A suite of tools for mappers using new format .dat files that includes:
  • Schema Fixer: Easily fix maps made in Mediocre Mapper Mk4.1 and Mk5 for upload to Beatsaver
  • Tempo Changer: For those who need to change the BPM of their entire map that will correctly shift block placements
  • 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
• BS Viewer by +1 Rabbit A convienient way to checkout how your map might look in game without the game.
  • IOS and Safari are currently not supported.
• BPM Saber, by Zevdg A utility for mappers who need to change the BPM of their entire map that will correctly shift block placements. Only works on old format .json files
• BPM Saber, by Elliotttate A utility for finding the BPM of a song
• Fayhe's osu! Editor Timing Tutorial

# 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!
• Intermediate Mapping - A more in-depth look at many mapping topics (coming soon... ask in #mapping-discussion if you want more info!)
• Extended Mapping - Mapping Extensions tools and 360/90 mapping (coming soon... ask in #mapping-discussion if you want more info!)

There is also the Best Practices Guide, by Awfulnaut which has been updated and integrated into the Basic Mapping page above.

# 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 will eventually be reviewed, but the wait for approval could be long due to limited staff.

# 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 submitted via the ScoreSaber Discord for review by the ranking team (which involves additional rounds of strict modding and revision).
• If a 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.

# Lighting Practices

A map is not considered complete without some form of lighting 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!
• Advanced Lighting - Satsified with making simple lights? Learn more advanced techniques! (coming soon... ask in #mapping-discussion if you want more info!)

Below are additional lighting resources as we migrate over to the wiki pages.

• Beginner's Guide to Lighting by Puds
• Lighting Environment Guide by ManDynasty
• Using Flash & Fade Lighting Events by ManDynasty
• Side Laser Speed Reference by LittleAsi

Lightmap is an automated way to add lights to your map and is integrated into Mediocre Map Assistant 2 and can be accessed in the error checker menu. Keep in mind that it is not that hard to create simple manual lighting that is better at expressing the atmosphere of the song than lightmap.

# Playtesting

Testing your work is a critical part of mapping. Playing your own maps 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 song format (your files are .json and .ogg) you must convert your map using one of several available tools like Songe Converter by lolPants or BeatMapper Tools by Darkuni. Update your editor to MMA2 or BeatMapper See Community Editors for links
• If your map is using the 2.0 song 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 bottom song pack menu. Use practice mode to play (the small button next to the yellow play button).

# 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. Create a compressed .zip file of the individual song files (not the song folder).
2. Drag and drop the .zip file onto the BMBF upload window.
3. Click Sync to Beat Saber.
4. Access your map in-game via the CustomWIPLevels category in the bottom song pack menu. Use practice mode to play (the small button next to the yellow 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 (not the song folder).
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
• 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:**
**Feedback:**
**Status:**

# 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 on BeatSaver.

# BeatSaver

BeatSaver is the public repository for all custom Beat Saber maps. Songs must be in the 2.0 song format (files are .dat and .ogg/.egg/.wav) to be compatible.

# How to Release a Map

1. Create an account on BeatSaver. If you are not recieving a verification email drop into #mapping-discussion for assistance.
2. Click the Upload link in the top-right nav bar.
3. Add your BeatSaver map name and map description. Only the map name is searchable so be sure to include song name, song artist, and other terms that might make it easier to find your map.

4. Add your .zip file and click the Upload button.”

# BeatSaver Data Schema Change - October 27, 2019

BeatSaver now enforces a schema in order for your maps to be uploaded, of which public MediocreMapper is not compliant with. The most breaking change happened in the difficulty data files, where MM-specific fields were moved inside a _customData object.

Resolution #1 Switch to the Mediocre Map Assistant 2 editor. Open each difficulty file and save it to correct the schema. Use MMA2 going forward.

Resolution #2 Use the Schema Updater Utility by +1 Rabbit to fix your files before uploading.

Resolution #3 (The Hard Way):
If you wish to fix this yourself, here is a quick template which shows you where everything should go in order for your map to be compliant with BeatSaver's new schema.

Alternatively, since _customData is NOT a required field, you can go ahead and remove everything that would be placed in there, and upload that result.

{
  "_version": "2.0.0",
  "_notes": [],
  "_obstacles": [],
  "_events": [],
  "_customData": {
    "_bpmChanges": [],
    "_bookmarks": [],
    "_time": 0
  }
}

To be compliant with the new schema, please also find and remove or fill in any blank fields in your Info.dat or difficulty files.

# BeastSaber

BeastSaber is a song review and curation site with a social side for member profiles, forums, news, and tutorials. 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 including Awfulnaut, BennyDaBeast, Bloodcloak, Checkthepan, Cyan Snow, Freeek, The Good Boi, Helen Carnate, Hexagonial, Kolezan, LittleAsi, Megalon, MandyNasty, Nik, Puds, Ris, Ryger, Scrappy, Silent Caay, Skyler Wallace, Sykes, and Uninstaller.