# Basic Mapping
If you are a new mapper, read this page from top to bottom. Every word. Every picture. This page will give you all the info and best practices you need to make a solid first map!
Many thanks to contributors from across the mapping community who made this expanded wiki possible!
# Ready to Map?
- [x] Downloaded Audacity and chosen a map editor?
- [x] Set up your audio file to confirm your bpm and make sure you’ve got a good intro/outro?
- [x] Exported your song file as an OGG?
Are all these things done?
GREAT! You're ready to dive into your favorite editor and start mapping! If not, click the links on the task list for more information.
# The Essentials
Before you can even think about mapping, you need to understand the basics.
# Map Files
Regardless of what editor you choose to map with, every map needs:
- Song File: OGG format, you must have this ready before you can map. Name it
- Cover Image: JPG or PNG, must be perfectly square and 512 pixels per side is recommended. You must have this before you can release your map. Name it
- Info File: All of the metadata for your map as a whole. Things in this file apply to ALL difficulties (i.e., song name, artist name, mapper name, song file name, cover image name, etc.). This file is automatically created by your editor.
- Difficulty Files: One per difficulty in your map. Things in this file apply to just the one difficulty (i.e., note placement, light placement, note jump speed, etc.). These files are automatically created by your editor.
Some editors will automatically create an
Autosaves folder where you can retrieve older copies of your work if needed. When you’re ready to prepare your song for upload you must have a minimum of four files.
When you’re ready to prepare your song for upload you must have a minimum of four files.
# Block Types
|Directional Blocks||Dot Blocks||Bombs||Walls|
|Must be hit in the |
direction of the arrow
|Can be hit in any direction||Causes damage when struck |
but safe for players
|Damages players but|
ok to rest sabers
A few notes about walls:
- Standard walls can be read by any headset and have the highest compatibility. New mappers should stick with these until they’re a bit more experienced.
- There are a few types of “hack” walls that do not require the Mapping Extensions mod: fast walls (fly by you fast), hyper walls (fly by you SUPER fast), and fake walls (look like normal walls but don’t cause damage).
- While these wall types are supported in some editors, they exploit base game mechanics and are considered unrankable.
- Read up more on non-Mapping Extensions walls in Intermediate Mapping (link coming soon!) and read more on “fancy” walls in Extended Mapping (link coming soon!)
A few notes about bombs:
- Bomb hitboxes are smaller than block hitboxes, smaller even than the bomb model itself
- Bombs are hard to see when there are no lighting events active. Make sure your map isn’t dark when bombs are coming up. See Basic Lighting for more tips.
- Bombs are disabled once they have passed the player
# Block Distribution
As a very general rule of thumb for new mappers, blocks should be distributed roughly as follows:
- 60-80% on the bottom row
- 10% or less on the top row
- The rest on the middle row
This is one of the more flexible guidelines for new mappers but it's still helpful to stay in this range for your first map or two before experimenting. Certain styles of maps (like dance maps) will have a higher percentage of blocks on the top row but always remember to consider your target audience and their comfort.
If you’re using Mediocre Map Assistant 2 as your editor you can hit SHIFT+TAB to open the error checker then click the Stat Panel button to see this breakdown.
For more on row usage in different difficulties, see Gauging Difficulty.
# Timing & Rhythm
Before you start mapping in earnest you need to think about the rhythm of the song you want to map. You’ll place blocks on one or more of the main instruments in the song: the drum beat, lead instrument, bass, synths, or even vocals.
To place blocks in time with the rhythm you’ll need to change your cursor precision. Most (but not all) songs will use 1/1, 1/2, or 1/4 cursor precision to get on beat. Some songs may use “triplets” or 1/3 cursor precision but this is more rare. You should not need to use less than 1/4 cursor precision for most songs including mapping to vocals.
90% of the time, mapping with high precision (1/8, 1/16, 1/32, or 1/64) will make your song mistimed. If you need high precision to get your notes to line up then you have an issue with your audio file setup. STOP and review Basic Audio Setup to ensure you’re in sync!
|1/1 Cursor Precision||1/2 Cursor Precision||1/4 Cursor Precision|
|1 block per beat||2 blocks per beat||4 blocks per beat|
When timing out your map you’ll want to double check EARLY that the waveform in your editor is lined up with the major lines of the editor track. If your waveform isn't lined up, revisit the Basic Audio Setup page of the wiki for tips.
If your waveform isn’t lined up it will make it very difficult to place blocks in time with the music. Get this right before you start or risk remapping later!
|Audio Not Lined Up||Audio Properly Synced|
|Needs audio edits, start offset, or has wrong bpm||You’re ready to map!|
# Timing Notes
Consider starting the mapping process with placeholder or “timing” notes. Dropping a “dot note” placeholder can help you figure out whether or not your map is on time and where you should consider using extra emphasis before you invest a ton of time creating patterns. Listen to make sure the editor hit sounds are in time with the beat.
Not everyone uses timing notes but they can be a helpful way to ensure your maps are timed correctly as a new mapper.
# Overmapping & Undermapping
Deliberately place blocks that match the music. Don't place more blocks than necessary just for the sake of making the map difficult. Some songs were never meant to be super-dense ExpertPlus maps and that’s ok.
- Overmapping is the (bad) practice of placing more blocks than there are sounds. Don’t do it.
- Undermapping is the very acceptable practice of skipping some notes/beats (especially at lower difficulties)
# Emphasis & Consistency
We’ll go into more detail on this in Intermediate Mapping (link coming soon!) but as a new mapper you should understand at least the basic ideas of emphasis and consistency and how they impact your map.
Emphasis is how much “weight” you give each hit.
- Consider the base sound your mapping to to be a single hit (one block), including quiet or chill sections
- When the sound is “bigger” or you have two different instruments hitting on the same beat you can think about using a double hit or a stack (two blocks).
- For only the biggest sounds in the song you could use a double tower (four blocks, two for each hand) or other heavyweight pattern, but many songs never need this amount of emphasis.
Many new mappers instinctively want to use double hits all the time, but remember that those are heavy emphasis and if every sound is emphasized then nothing feels like it has extra weight.
Consistency is mapping the same sound with the same weight when it appears. Mapping consistently does NOT always mean to copy/paste/mirror, though there are some times when that is appropriate. If you choose to map a particular big sound as a double, for example, that same sound should always be mapped with a double.
# Pattern Best Practices
Much of this section is derived from Awfulnaut's incredibly helpful Beat Saber Custom Mapping Best Practices for Block Placement guide. Many thanks to Awfulnaut for blazing a trail and documenting it for new mappers!
# Vision Blocks
Vision blocks are any patterns that obscure the player’s vision and make it difficult to sight read a map, if not outright uncomfortable. The primary cause of vision blocks is use of the middle two positions of the track, but there’s risk of a block any time the middle row is used.
Vision blocks can be avoided by:
- Not using the center two positions of the track or
- Ensuring that blocks following anything in the middle row are either far enough away or in another position to the right or left of the block.
- Making sure that your player is pushed to the side with either obstacles or patterns so the center positions no longer completely block the player
|Ideal Block Placement||Vision Block Placement|
|When you’re getting started, stick |
to the perimeter of the track
|These are called face notes.|
Avoid them as a new mapper
Mediocre Map Assistant 2 has a built-in handy-dandy error checker that can find vision blocks. Learn more in the MMA2 User Guide
# Double Directionals & Resets
Double directionals (or DDs) are what you get when you have two blocks of the same color in the same direction within a very short span of time. Diagonals, or any change of only 45 degrees between blocks, are considered to be DDs with both the cardinal directions they combine.
is a DD with both and
Double directionals cause the player to double their swing speed compared to a “standard” up/down pattern. They have to swing downwards, then bring their hand back up to swing downwards again, which is a lot of unnecessary motion. Alternate the direction of every other block for better flow.
Many new mappers use DDs to simulate the feel of drumming. While this feels like it makes sense, drums have rebound when you hit them and imaginary computer blocks… don’t. The game is called Beat Saber, not Beat Drummer!
|Standard Flow||Double Directionals|
|A good mapping practice||Yikes! Don't do this.|
Resets DDs do have their uses (typically in more “dancey” maps) if you give the player enough time to reset their hands back to neutral position. This usually means no DD’s within 2 beats for “normal” bpm songs and longer for high bpm songs.
If you’re using intentional DDs in a dance-style map you’ll need to make your NJS slower and spawn offset longer to give the player enough time to react.
Wrist resets are when you change the forehand/backhand flow of a a pattern mid-stream causing your player to roll their wrist to reset flow. They can break normal human body mechanics and put players at serious risk of joint damage. Do not use wrist resets at high precision!
When long periods of time pass between notes, the player will reset their arm position so it’s often preferable to start the new section with a down block. In gray areas of time, like 3 seconds without notes, it is up to the mapper to reset the player or to continue the flow.
Want to learn more about resets? Read Intermediate Mapping(link coming soon)!
# DO: Mapping with Flow
Outside of easy and normal difficulties, mapping with Flow is an absolute must. Human bodies are incredible machines but there are certain ways that joints are meant to move and using patterns that violate those mechanics is a recipe for injuring your player.
Parity is the concept that Each block direction is played with either a backhand swing or a forehand swing. The black line in the diagram below illustrates this forehand (above the line)/backhand (below the line) divider for the left and right sides.
When mapping with flow you are striving to always cross this parity line with the most natural movement possible. Effectively, your player should always be alternating between forehand and backhand every swing.
When proper flow is achieved the player should be physically capable of getting full points on each block, even if they don’t have the skill or interest in doing so. See the Scoring section of the wiki for more info.
|0° Angle||45° Angle||90° Angle||135° Angle||180° Angle|
|No. (DD)||No. (DD)||Maybe in E/N/H.||Yes.||Yes.|
Basic Flow Concepts:
- The higher your note precision, the more you want to stick to 180° (up/down) and 135° (up/down/diagonal) patterns.
- 90° transitions that cross the parity line should only be considered with 1-2 beats in between, more if your map is high tempo. Avoid 90° transitions entirely at Expert and ExpertPlus
- Make sure that you have the right setup (the pattern immediately before) and escape (the pattern immediately after) for a comfortable swing at whatever speed you’re mapping.
- Be conscious of your timing, you can get away with more at sub-160 BPM tempos with lower note precision than you can in high BPM songs. Map for the style of song you’ve selected.
# DON’T: Forbidden Patterns
These are called forbidden patterns for a reason. There is no reason in the world to use these because they're dangerous to either the player's hardware, the player's joints, or they go against the scoring system. You may have played maps that included these but that doesn't make them ok.
|Pointing blocks at each other may cause the player to smash their controllers together when playing for max points. Don’t do it, no exceptions.|
Note: Different VR sets have different controllers. Vive wands are much bigger than Oculus touch controllers and Index knuckles... don’t put your players’ hardware at risk! AKA Controller clash, Controller smash
# Hammer Hits
|Any directional block pointing towards a bomb on the same plane is just evil (and undermines the scoring system. Don’t do it. No exceptions.|
# Disembodied notes
|Do not hide blocks on the other side (or inside) of walls. Most of the time, these are simple mistakes that people don’t find because they don’t adequately playtest their maps (NOTE: Always playtest your maps!)|
# Rapid Wall Dodge
|Keep head movement slow and predictable. Do not force the player to very quickly move from one side of their play space to the other. Wall dodges are fine (and fun!) to use but allow at least 1.5 beats for the player to switch sides for higher BPM songs. You don’t want to risk them bumping into things or falling over.|
# Danger Dash
|Never force the player into the far edge of their playspace with 3-width walls or a 2-width wall in the middle. Walls that encompass the two middle columns gives the player very little room to play, and you don’t know how large their play area is or how far they will dash in response to these walls.|
# Bomb Spam
|Bombs are good for forcing precision, or for punctuating silence, but overuse of bombs should be avoided. Also note that most people hate bombs in general, so they should be used sparingly.|
Note: Precision bombs shouldn't be used more than once per beat.
|This large, awkward pattern is difficult to read and can lead to smashed controllers, tangled arms, and ugly vision blocks. Players will likely not read it correctly the first time they see it, but even if they do, it’s not a satisfying motion anyway. Consider using a different pattern altogether.|
# Hidden Blocks
|Blocks should never be stacked on top of one another or in walls. Any combination of blocks are technically stackable in the editor (including bombs and walls). Sometimes these are hard to spot if two identical blocks are stacked. Use the error checker in MMA2 to find these!|
# Hitbox Abuse
|Leave room for the player to swing at each block. In the patterns depicted here, there is not enough room for the saber to slice each block without hitting the other. These are technically still possible to hit, but only by coming in at an angle, and if you have to come in at an angle, you may as well change the block direction to a diagonal anyway.|
The illustration below from Split, one of the game devs, shows the size of the block hitbox. The large outer box is for good hits and the small inner box is for bad hits.
# Wide Precision
|These bombs are incredibly hard to avoid for players with short arms. When the player swings through these blocks, their arms come inward, and hit the bombs.|
|“Flicks” of two or more blocks of the same color at 1/4 precision are a difficulty spike, regardless of song tempo. It is the precision here that is important, not the patterns since these examples follow proper flow techniques. Even though flicks are more easily playable in lower tempo songs, they are incredibly difficult to use appropriately and should be avoided.|
|Triangles are patterns that cause incredibly uncomfortable wrist resets when used at high precision and speed. The pattern breaks the forehand/backhand mechanic and can injure your player. See the Mapping with Flow to revisit this explanation.|
Note 1: Not all triangle shaped patterns are cursed triangles. Make sure you are always crossing the parity line with each swing.
Note 2: This sort of pattern plays differently at hard difficulties and below when there are a couple of beats between each swing but stay away at Expert and ExpertPlus
# MAYBE: Highly Situational Patterns
These patterns are OK to use but only in very specific circumstances or with very specific setup. It’s best to steer clear of these until you’re much more comfortable with mapping.
# Incorrect Side Hits
|Generally speaking, when making a double crossover, you should put RED on top when slicing left, and put BLUE on top when slicing right. This is a best practice because you don’t have to move your opposite hand as far. The exception is Expert/ExpertPlus, but only if the flow of patterns leads to these placements naturally.|
# Rapid Crossovers
|Give the player time to prepare, and don’t make them cross sides too fast or too often. This pattern takes time to process and it’s a larger motion in-game than it looks in the editor. Also, never put this pattern in the top row. It's also recommended to offset the hits and put one of the two notes on the bottom row to reduce handclap risk.|
# Wide Inward Doubles
|Inward facing double blocks on the edges or downward facing blocks on the top row are very difficult to hit for small/short players, and uncomfortable for the rest. This should generally be avoided. The exception is Expert/ExpertPlus, but only if the flow of patterns leads to these placements naturally.|
# Excessive Towers
|Placing 3 blocks of the same color, vertically or horizontally, may seem fun, but you can achieve the same “hard hitting” effect with just 2. 3 feels excessive in-game. Even when using 2, don’t place anything directly behind them, since visibility will be low.|
At Expert/+ if you are going to use this for major emphasis, each block needs to be staggered after each other at 1/16 (<200 bpm) or 1/12 (>200 bpm) precision, turning this into what is known as a slider.
# Awkward Curves
|Do not place two or more blocks of the same color together that do not face the same way. It is harder to read, feels awkward, and undermines the scoring system. Often, these patterns are used as a way to introduce flair to a map, but it’s really just a crutch for unimaginative mapping. Instead, add flair by introducing original patterns that flow well together.|
# Detached Walls
|Combine your adjacent/ touching walls for a cleaner, less visually cluttered experience. Click and drag (left to right) to create walls wider than 1 column. Scroll to create walls shorter/longer than one beat (or whatever your cursor precision is set to) and click again to finish placing your wall. Don’t ever cover the entire grid with walls as depicted in the illustration. |
Note: This rule goes out the window when you get into wall mapping with Mapping Extensions, though this is NOT recommended for new mappers.
# Extended Crouch
|Consider your target audience when using extended sections of top walls. You can't predict all players' physical ability, so use this in moderation. If you have notes immediately following a crouching section, make the starting direction UP, and consider visibility due to the player’s lower position.|
Note: Avoid placing blocks under a crouch wall, but if you must, always place them on the bottom row sides with horizontal slice directions (or dots)
# Corner Crouch
|Consider your target audience when forcing the player to crouch in one corner. As stated above, crouching sections should be kept short because you can't predict all players' physical ability. Forcing the player to additionally move left/right while crouching increases the threshold of full-body range of motion. While this tactic may be fun for some, you don't want to ostracize the players that are incapable of this motion.|
# Sky Streams
|Avoid repetitive use of blocks in the top row. This causes shoulder strain in addition to top row down notes being annoying to score well on.|
Note: Blocks on the top row in Easy and Normal should be dots and used sparingly.
# Visual Clutter
|Avoid unnecessary visual clutter. Having a directional block point towards/away from a dot block does not serve any functional purpose, and it’s hard to read at a glance. If you’re telling the player to slice in a particular direction, be consistent and make both blocks directional to increase readability.|
Note: At Expert/+ when making sliders it is common to start with an arrow then use dots afterward.
# Easy to Miss Patterns
|Generally, try to avoid patterns with overlapping hitboxes, as this makes the pattern difficult to hit consistently. The hitboxes are larger than the note, and most players rarely hit the actual note when they swing, making it easy to hit the smaller hitbox within notes that detects bad hits on patterns like this. See Hitbox Abuse for more info.|
# Arm Tangles
|Crossing hands is usually fine, but crossing hands and going in opposite directions vertically causes the player’s arms to hit each other. Reverse these colors and you’re good to go. This is only one example of an arm tangle. Always be aware of where you're leaving your player's arms and how they are going to escape from that position to hit the next pattern.|
# Gauging Difficulty & Down-Mapping
Many mappers tend to map the difficulty level at which they play but there are plenty of benefits to mapping lower difficulties:
- Full spreads widen your audience leading to more downloads
- They look more professional when cruising for new maps... like official game maps
The actual difficulty level of a song is a combination of note density, pattern complexity, and note speed and spawn point. When down-mapping it’s important to understand what skills players at different levels have and how to use that information to develop a sense of progression in your levels.
# Relative Difficulty
Maps should always have a progression of complexity from Easy through Expert+. The actual difficulty range of these levels in terms of note density has been creeping up since the game first came out.
While it’s best to stick within conventional ranges to start, as long as your levels have a clear progression of difficulty they don’t need to fit neatly into a box. If you’re only doing one difficulty you should stay within the expected range. Your map’s difficulty should fit the song - a 200 BPM Camellia song is going to be more challenging than a 120 BPM pop song.
The above table of average notes per second (NPS) for the OST Extras shows how tracks like “What The Cat!?” are quite dense at the highest difficulty and the easy is also more dense than other easy levels. In each of these cases there is still a progression from Easy to ExpertPlus
# Pattern Complexity
Map difficulty should come from pattern complexity with a great deal of attention given to how well they flow together. You might have a lower density expert, for example, that includes a lot of technical patterns that require more time to adequately sightread.
Remember that you are teaching players different patterns and sight reading skills with your maps. Make sure you give them time to react before you throw something new at them at each level of difficulty.
|Easy||‣ All cardinal directions (down, left, right, the occasional up)|
‣ Knock yourself out with DDs. Players will reset after every hit at this speed.
‣ Use up/down doubles for big emphasis if the music calls for it before or after a break.
‣ Blocks placed generally every other beat (depending on tempo)
‣ Very few obstacles, if any, which are easy to avoid with no simultaneous notes
‣ Almost all blocks should be in the bottom row. Use the middle row as a flourish for emphasis.Use the top row very sparingly with dot notes only
‣ Red stays in lanes 1 and 2, Blue stays in lanes 3 and 4
|Normal||‣ All cardinal directions and the very occasional diagonal with lots of time to react and recover|
‣ Begin to introduce up/down flow, especially anywhere you have notes that are close together, but DDs are still present especially after breaks
‣ Up/down and left/right doubles used for emphasis as appropriate
‣ Blocks generally placed every beat to two beats - mix it up a bit
‣ Keep your obstacles easy to avoid but start to introduce blocks sprinkled in with lots of time to react
‣ Almost all blocks still on the bottom row but higher use of middle row sides. Keep top notes rare and still as dots
‣ OK to let your red start drifting into lane 3 and your blues into lane 2 but still not crossing over each other
|Hard||‣ All cardinal directions and limited diagonals with time to react|
‣ Flow is now critical unless you have a break of 5+ beats. Try to cross the parity line with every swing.
‣ All doubles are fair game including inverted doubles with sabers going opposite directions, ok to start introducing stacks with plenty of reaction time
‣ Notes mostly every beat with some 1/2 beats and the occasional 1/4 thrown in with the rhythm.
‣ Keep 1/2 sections short, no more than 6-8 beats without a break. If a burst of 1/4 is used, keep it to 3-4 blocks with a break.
‣ All obstacles are fair game but make sure you’re not creating vision blocks
‣ Mixing bottom, middle, and top rows with top notes transitioning from dots to directional blocks
‣ Any color, any lane is fine but give lots of reaction time before any occasional “true” crossover where the players arms have to cross to hit.
|Expert||‣ Anything goes in expert but players are still improving sight reading skills. Keep patterns either fast and basic or slower and more technical… combine the two and you have an ExpertPlus!|
‣ All note types viable here in any proportion
‣ Flow is critical; DDs will make or break your map
All emphasis options on the table including sliders with 1/12 or 1/16 precision
‣ Mostly 1/2 beats with 1/4 mixed in to fit the rhythm. Make sure there is the occasional break in long streams.
‣ Anything good obstacle placement practices available - the gloves are off!
‣ Expert introduces a lot more jumps, though they still require enough reaction time
‣ Crossovers should be used wisely and not combined with other weird patterns.
|ExpertPlus||‣ Welcome to the wild wild west! You can throw any good mapping practices at your player here.|
‣ At high tempo and note density, patterns you could use effectively at hard and maybe expert start to become cursed. Players are often using their wrists instead of arm movements so body mechanics change at this level.
‣ Breaking the parity line with every swing is now crucial. You will get skewered if you don’t
‣ Stay away from any 90° hits, dot notes, triangles, DDs, VBs, same-lane crossovers, 1/4 precision gallops, top row far-lane crossovers (face-punchers), and 1/4 single hand hits (flicks). Courtesy of Hexagonial
# Note Density
Notes per Second is a measure of note density - how many notes does the player have to hit in a certain amount of time. The values below are from the OST Analysis Spreadsheet which shows NPS ranges for all OST, Extras, and DLC content.
|Difficulty||Notes per Second|
|Easy||0.8 - 2.4 NPS|
|Normal||1.0 - 3.2 NPS|
|Hard||1.6 - 3.9 NPS|
|Expert||2.2 - 5.7 NPS (yes, you read that right)|
|ExpertPlus||3.2 - 6.4 NPS (no upper limit here, really)|
# Note Jump Speed
There are several terms related to how the speed of gameplay feels. These are all interrelated and modified by the song’s tempo:
- Note Jump Speed (NJS) is the rate at which blocks move down the track at the player. The higher the number the faster the blocks.
- Spawn Distance is how far down the track the blocks will spawn in distance (meters).
- Half Jump Distance is how far in advance blocks appear in time (beats).
- Spawn Distance Offset is a modifier which increases the spawn distance. This can make the NJS feel slower since the blocks will spawn further away and the player has more time to react.
Changing the NJS or Offset values will modify the half jump and spawn distance. Community editors will show you how these values change when making adjustments. Fine-tuned NJS and offset are a matter of personal taste but try to hit a half jump of 2 or 3 beats and a spawn distance of 26-30 meters.
Spawn distance should run on the higher end of this range for expert and lower difficulties. Very dense ExpertPlus maps often have very short spawn distances to minimize clutter.
|Difficulty||Note Jump Speed Range|
When mapping very fast Expert+ maps, make sure you increase the Note Jump Speed, though you shouldn’t need to go higher than 22. This will make the notes come at the player faster with more space in between them, increasing readability.
Setting your NJS really high is not the right way to increase difficulty. Use higher note density and more complex patterns (with good flow).
Already mentioned in detail on the Mapping Home Page it’s important enough to mention again here:
- Test your own work early and often, especially when you’re just starting out
- If you can’t test your own work have a friend play it. Just remember that a friend may be more likely to say ”that’s awesome, man!” than to give you honest advice and risk hurting your feelings… even if that’s what you need.
- Even if you test your own work you can become “map blind” because you know it so well and may not see playability issues
- Use the #testplays channel on BSMG wisely. There are experienced mappers who will play your pre-release map and provide constructive feedback. Sometimes there’s a LOT of constructive feedback and that’s ok. Those experienced mappers were once newbies with terrible maps themselves. If you’ve read and absorbed the info on this page you will be much better off!
HAPPY MAPPING! Visit
#mapping-discussion on the BSMG Discord with questions!