Skip to content
wcko87 edited this page Mar 23, 2023 · 77 revisions

Note: If you have problems or questions about beatoraja or BMS, or have any comments on the guide, please make a post on the Discussions Page or Discord. I actively monitor the Discussions page for messages.

Please don't create issues in beatoraja's issue tracker! The issue tracker is not for troubleshooting.

What is beatoraja?

beatoraja is an open source BMS Player in active development.

If you're here just for more information about BMS (and not beatoraja), check out the links below. These links are useful even if you are using LR2 or some other BMS player.

Another popular BMS player is Lunatic Rave 2 (LR2). Most of this guide is for beatoraja.

Note that judge timings and gauges in beatoraja differ slightly from LR2. There a version of beatoraja that has been modified to use LR2 judge timings and gauge (but it does not support beatoraja's internet rankings). It can be found here.


Page Contents


Getting Started with beatoraja

This is a step-by-step guide that explains how to set up beatoraja properly, with the UTF-8 fix applied. We apply the UTF-8 fix now to avoid potential locale-related issues later on.

Note: If you run into any issues during setup, checking the Troubleshooting section might help.

There are two options for setting up beatoraja.


Setting up beatoraja without Installing Java

This is for Windows only. For Mac/Linux, you can follow these instructions, while using a portable version of Java instead.

1. Download beatoraja

  • Download beatoraja from here.
    • You should see multiple links to choose from. Use the "-jre-win64" link.
  • The "-jre-win64" link includes a portable build of Java in the download, which we will be using to run beatoraja.
  • You might notice a "beatoraja.exe" file in the download. You can ignore (and even delete) this, as using the .exe means beatoraja will run without the UTF-8 fix. More information: What is beatoraja.jar?

2. Apply the UTF-8 fix

3. Run beatoraja

  • Double-click beatoraja-config.bat to run beatoraja.
    • Don't run beatoraja through double-clicking beatoraja.jar or beatoraja.exe. Using these skips the UTF-8 fix and can corrupt config files.
  • See Configuring beatoraja for information on things you may want to configure before you start playing.

Setting up beatoraja with Java

You might want to set up beatoraja this way if you already have Java installed in your computer.

Note: If you are on Mac/Linux, use beatoraja-config.command instead of beatoraja-config.bat.

1. Download 64-bit Java

2. Download beatoraja

3. Apply the UTF-8 fix

  • After extracting beatoraja, you should see a beatoraja.jar and a beatoraja-config.bat file in the folder.
  • The easiest way to apply the UTF-8 fix is to replace beatoraja-config.bat with the one over here.
  • Alternatively, you can just edit beatoraja-config.bat to apply the UTF-8 fix. Instructions are over here.

4. Run beatoraja

  • Double-click beatoraja-config.bat to run beatoraja.
    • Don't run beatoraja through double-clicking beatoraja.jar (or beatoraja.exe if you have it). Using these skips the UTF-8 fix and can corrupt config files.
  • See Configuring beatoraja for information on things you may want to configure before you start playing.

Locale Fix

Note: Also known as the UTF-8 fix. If you have followed the earlier instructions and have applied this fix, you may skip over this section.

Effects of locale issues

Not being on the correct locale can cause some issues in beatoraja. Most of the time, if you are experiencing crashes in beatoraja, it is due to a locale issue. Thankfully, there is an easy fix for all these crashes.

The problems locale issues will cause:

  • On skins like ModernChic or LITONE5 which have option names in Japanese, these option names will not save. When beatoraja is closed, the skin-specific settings will be reset.
  • On skins like LITONE5 which have folder names in Japanese, beatoraja might not be able to access resources inside those folders, and this can cause beatoraja to crash.
  • If you load a bms with file or folder names containing Japanese characters or garbled characters, certain parts of the bms may not load properly. Playing the bms twice in a row may cause beatoraja to crash.

Fixing locale issues

There are two ways to fix locale issues in beatoraja. This fixes all the problems listed above.

  • Method 1: Switch to Japanese locale on your PC
  • Method 2: Run beatoraja using the UTF-8 encoding (Recommended solution)

Method 2 is highly recommended. If you are running beatoraja using the UTF-8 encoding, switching to Japanese locale is NOT required (I have not once switched to JP locale). Also, even if you are already using the Japanese locale, switching to UTF-8 encoding is still recommended, as this resolves crashes that happen if a BMS folder name is garbled.

Note: Opening .zip files is another reason frequently cited for switching to JP locale. Switching just for this reason is not recommended however, as there are better solutions to this. More info here - locale issues when opening zip files.

How to run beatoraja with UTF-8 encoding

  • Remark: If you don't want to try applying the fix manually, you can instead just replace your beatoraja-config.bat file with this file over here, which already has the fix applied.

The UTF-8 fix is applied by making a simple edit to the beatoraja-config.bat file (note that beatoraja-config.bat is what you are using to open beatoraja).

Open up beatoraja-config.bat (or beatoraja-config.command, depending on which you use to start beatoraja), and add -Dfile.encoding="UTF-8" to the end of the _JAVA_OPTIONS= line.

Note: The -Dfile.encoding="UTF-8" argument must be placed outside of the inverted commas ''. This sounds odd, but the setting will do nothing otherwise. There must also be a space before -Dfile.encoding="UTF-8".

The line should look like this:

set _JAVA_OPTIONS='-Dsun.java2d.opengl=true -Dawt.useSystemAAFontSettings=on -Dswing.aatext=true -Dswing.defaultlaf=com.sun.java.swing.plaf.gtk.GTKLookAndFeel' -Dfile.encoding="UTF-8"

Skin settings might reset after switching to UTF-8, because the skin settings may have been saved in the default encoding. It shouldn't be too much trouble to set the skin settings again, since you only need to do this once.

It might be possible that switching encodings might cause your player config file (in player/player1/config.json) to be unreadable. If the config file can't be fixed, you may have to replace the config file with a new one.

How to replace (clear) your config file

  1. Backup the player's config.json (player/player1/config.json)
  2. Clear the contents of the file and replace it with just the characters {}. This forces beatoraja to generate a new config.json file from scratch (Note: beatoraja won't start without the {} in the file).
  3. After the player profile has been cleared, open the beatoraja config again, go to the skin select menu and make sure a skin is properly set (i.e. not blank) for each of the important categories (e.g. 7KEYS, DECIDE, RESULT, SKIN SELECT). beatoraja crashes if it tries to load a blank skin.

Note: The player's config.json is different from the config.json you see in the main beatoraja folder! The player's config json is in the player/player1 (or player2 etc) folder, and contains settings that are specific to the player profile, like skin settings.

There should be no more crashes / issues after that.


beatoraja Settings/Options

This covers some of the more important things to configure when first starting the game. Refer to beatoraja Configuration for more detailed information on what you can configure in beatoraja.

Downloading Songs and Skins

[Songs] If you are looking for BMS songs, see downloading songs/charts for more information on where to find them.

  • I recommend downloading the GENOSIDE 2018 starter pack if you don't know where to start, it gives a good initial selection of songs to start off with.

[Skins] The default skin, ModernChic, is already a pretty good skin. Refer to the List of beatoraja Skins for other skins.

  • If you can't find a play skin that looks exactly like what you want, I recommend the Simple Play skin, as it is extremely customizable (you can customize the positions and dimensions of just about every aspect of the skin, including things like the individual widths, heights and colors of notes).

In the Configuration Screen (before starting the game):

Most of the settings under Play Option can be configured after you started the game.

[Adding Songs] Go to the Resources tab to add your song folders. (add them under BMS Path, not Table URL!)

[Difficulty Tables] (not necessary) If you wish to use difficulty tables, add table links to the Table URLs and click Load difficulty table to load all the listed difficulty tables into the game.

[Controller Turntable] If you are using a IIDX controller with axis input, you might want to turn on ANALOG SCRATCH under the Input tab. This needs to be turned on individually for each mode (7KEYS, 5KEYS, etc). See Analog Scratch for more information.

[Skin Settings] If you have other skins downloaded, place them in the skin folder. You should be able to see them in the config menu, in the "skin" tab. For more information, see: Skin settings

  • If you are using ModernChic (the default skin), you should also be able to set the language shown in the music select menu to English.
  • If you play on the P2 side (turntable on right), you can switch to P2 in the skin settings.

Options in the Music Select Screen (in-game):

[Key Config] Press 6 on the keyboard to open key config.

  • Note: You also need to bind your controller turntable in the key config.

[Play Options] In the key config, you should have bound the START and SELECT buttons (default Q and W on keyboard). Hold START, SELECT or START+SELECT to access the three play options menus. These menus cover the majority of the play options available in the config.

  • The default gauge is ASSIST EASY, but it might be a good idea to switch to the EASY, NORMAL or HARD gauges as these are more commonly used. See: Gauges

[Skin Settings] Press F12 to open skin settings in-game.

Check the Music Select page to find out what else you can do in this screen.

Settings while Playing a Song:

[Scroll Speed and Lane Cover] Before the song starts, the game gives you some time to adjust your scroll speed settings.

  • Double-tap START to turn on the SUDDEN+ lanecover
  • Hold START + turn turntable to adjust lanecover height (white number)
  • Hold SELECT + turn turntable to adjust green number (related to scroll speed)

The song will not start until you have finished adjusting.


How to Navigate Menus

The main menu screen you are on is called the "Music Select" menu.

  • The Music Select page explains what you can do on this menu.

The turntable (scratch up / scratch down) is used to scroll through menus.

Notation: keys 1 to 7 are the keys from left to right. White keys are 1,3,5,7 and black keys are 2,4,6.

Generally, white keys go forward in menus and black keys go backward. However, in beatoraja, each key actually has a slightly different purpose.

  • Key 1: Go forward / start song
  • Key 3: Go forward / start song on practice mode
  • Key 5: Go forward / start song on autoplay mode
  • Key 7: Go forward / play selected replay
  • Key 2,4: Go back / change sort order if you are on topmost level
  • Key 6: Select replay

After a song has started, you can press Escape, or hold START + SELECT to quit the song.


Tips for Beginner Players

  1. Songs in the level range 1-4 are suitable for new players.
    • If playing from a song folder instead of a table, check the note count of a song before playing it. Some songs are labeled "1" but the "1" actually represents the difficulty ★1 (Insane 1) instead of a normal 1 (☆1). Usually, these songs are marked with the "Insane" difficulty (black/purple) instead of the standard Beginner(green)/Normal(blue)/Hyper(yellow)/Another(red) difficulties so they are not too difficult to avoid. The easiest way to identify them though is to check the note count. Songs rated on the insane scale usually have over 1000 notes.
    • Alternatively, play charts from a difficulty table like Stardust or Normal2 to avoid mis-rated charts.
  2. A good green number (scroll speed) to start with is around 350-450. You can decrease it (i.e. speed it up) later on as you get more comfortable with the game. Most experienced players use a green number somewhere in the range 260-320.
  3. The initial levels will feel awkward to play, as new players will struggle to hit the correct keys. This is normal, and eventually hitting the correct button for each lane will come naturally to you. I feel like the game only starts to really "click" once you get to around level 8.
  4. If it feels uncomfortable reading or hitting the notes, oftentimes this is due to a scroll speed (green number) or offset issue. Try experimenting with different green numbers, lane cover heights, and offsets (maybe turn on judge auto adjust). Everything may magically suddenly feel far more comfortable to play at certain specific values for these settings.
  5. Set the gauge to EASY or ASSIST EASY and don't worry about failing. As long as you aren't completely flatlining a song, you are learning. You can try harder gauges later.
  6. Try not to skip "awkward" patterns like simultaneous notes, scratches, notes+scratches simultaneously, or long scratch (BSS) notes. If you find yourself consistently skipping these patterns and taking the damage instead, open up practice mode (Key 3) and try performing these actions manually to "teach" yourself how to do them (e.g. scratching the turntable at the same time as you hit the note directly adjacent to it). This way, you don't have to figure out how to execute this action on the fly while under pressure.
  7. Play a wide variety of charts for experience, and don't try to memorize patterns.
  8. At levels 8+ (or 10+), you may want to start experimenting with the RANDOM or R-RANDOM option (don't bother with S-RANDOM) to expose yourself to more patterns. Before you reach that level, you may want to stick with NORMAL or MIRROR mode. MIRROR mode is especially applicable if you play on the P2 (turntable on right) side.
  9. Don't worry too much about scoring in the initial stages. It is normal to get grades like C, D or lower in the initial levels as timing is difficult while still learning the keys. You'll find that your typical scores will also be higher (A/AA/AAA) when you have progressed to higher levels in the game (10-12). At that point it will be easier to practice timing.
  10. Note that good accuracy does not always correspond with good clears and vice versa.
  11. Useful playstyle resources when playing on a

Further Help

For further help, you might want to check the Frequently Asked Questions page or ask a question in the Discussions tab.