BMS/BME/PMS Support

Project OutFox contains parsers for the BMS and PMS chart formats, which are the standard formats used in conjunction with mostly the be-mu and po-mu game types. The following page contains details on the BMS/PMS channels that Project OutFox currently supports. This is a living document, and will be updated as progress is made to expand the work to support as much of these as possible.

The BMS file standard was devised by Urao Yane in 1998. It was originally created to be a format to simulate the game Beatmania by Konami. There have been several dozen iterations over the years, and we will talk about some of them here in one easy to contain and read page. Do not be afraid of this format, it is incredibly versatile and have been used to simulate a variety of games.

Project OutFox uses mostly BM98 (1998 to 2003) era definitions for this file standard, though it is improving all the time. The format is used to simulate most of the ‘Down Scroll Rhythm Game Systems’ and is known by several other derivatives which we are also slowly building support for.

BMS charts are mostly composed by artists from Asia, so reading them in non-asian locales can be difficult. OutFox has overcome this limitation in 2022, so if you see any charts in the music wheel with ?????????? and you are updating from a previous build, reset your cache. If you do find a glyph the game does not understand, do let Squirrel know so it can be added.

The other two file types on this page, PMS and BME were born from this format and are used for other types of games. PMS was originally designed to simulate Keyboardmania and had a very different channel layout than BMS, but it’s use moved towards po-mu / feeling po-mu (po-mu is short for Pop’n Music). This had a unique layout for 9 key/button charts.

BME is an Extension of BMS and offers newer features that were not offered in raw simulators of BM98. This was also used in the actual arcade and console games for a few years in the early 2000s. Project OutFox recently fixed a lot of support for this parser, along with adding several of the missing modes often charted by simfile authors. This extension allowed for channel numbers beyond 00-99 (99 values), then extended to base16 for 00-FF (255 values), which was then finally extended to 00-ZZ (1295 values), being based on base36.

The other system we support is BML files, which PMS incorporated by default in 2002. BML adds Long Note (known as holds in StepMania), which again extends the BMS specification. We now fully support both BME and BML fully, including mines and extended hidden note keysounds, as well as player 2 wide channel support.

Again, if you feel any particular command or object should be included, do let us know. There are quite a few bits of the specification that just simply have not been considered or added at this time, I’m documenting what we do have, and you are more than welcome to give suggestions for future additions. - Squirrel

The BMS file format describes how notes are arranged and how the game is meant to behave if/when a player takes a specific action. It is usually a simple plain text file with the command lines starting with the # character.

The file consists of a HEADER FIELD section and a MAIN DATA FIELD section. We will be going through in detail on the most commonly used commands and channels so you have the information here. A lot of the available commands ever offered to BMS/PMS over the years have faded into deprecation/not being used, but the ones we have seen in actual files include what we will be supporting.

If you find a file that is not showing up in OutFox you may need to switch the encoding options of the chart, or just wait until the new string system is added in the future.

#[Command] [Value]

For these commands, a space between the command and value is required or you will have offset issues in most simulators. A Simple Example of some common commands used in the header field are:

*---------------------- HEADER FIELD
#PLAYER 3
#GENRE Dance
#TITLE My Dance Classics
#ARTIST DJ Superstar
#BPM 128
#PLAYLEVEL 5
#TOTAL 100
#RANK 2

#bmp00 miss.bmp
#bmp01 01.bmp
#wav01 01.wav

*---------------------- MAIN DATA FIELD
#00111:01010101
#00211:0101010001010100

Status: ✅ Supported

Usage Example:

#PLAYER 3 

This command defines the play style that the chart is set for. In the earlier versions of BMS they also specified the number of players.

• 1 = 1 Player or Single Play, with 1 life gauge.

• 2 = 1 + 2 Player or Couples Play, with 2 life gauges. Mostly deprecated and not used. OutFox mostly supports these and can parse them under the old iidx-* styles from SM3.x

• 3 = 1 Player on 2 sides, or Double play. Modern sims use this value the most, or just ignore the PLAYER setting completely. Often a lot of PMS files have value of 3, though I have not been able to find out why. OutFox supports the odd use of this command but again most simulators post 2015 ignore this value.

• 4 = 1 vs 2 Player, or Battle Play, with two life gauges, which was removed in iidx19, has fallen out of favour in use. I have actually only found PMS battle mode files with 3 key vs 3 key chart styles from portable 2. OutFox currently can parse these files, but has no battle mode support.

Project OutFox also supports ‘duet’ or normal 2 player mode without needing to be set in the file itself, by joining a second player on the select music screen. As of Alpha 4.9.8 this was extended to PMS offering new modes with a 2 player option of po-mu for the first time. All po-mu styles (3k, 4k, 5k, 7k, 9k) have 2 player support now, with battle mode planned in the future.

Status: ✅ Supported

Usage Example:

#GENRE Blues 

This command sets the genre or type of music that the chart is going to play. It could be used by the simulator for sorting or grouping charts, or to allow for just more information to be displayed on the song select screen. The genre is usually written in SHIFT-JIS on older charts, but UTF8/UTF16 are becoming a lot more common, so do check.

Status: ✅ Supported

Usage Example:

#TITLE Take (Bamboo) 

The title command sets the SongTitle and this will be displayed on the song wheel to be selected, as well on the screen game-play and evaluation screen. It will also be recorded in high scores and on your profile etc. Older charts used SHIFT-JIS.

Status: ✅ Supported

Usage Example:

#ARTIST 立秋 feat.ちょこ

The artist command sets the SongArtist and this is usually displayed on the song wheel when selected and on the evaluation screen. The artist information is usually recorded in high scores and on your profile. Older charts used SHIFT-JIS.

Status: ✅ Supported

Usage Example:

#BPM 140.35

This setting allows the chart to specify the beginning (or starting) BPM of a song. This value will also be shown in the music wheel, and will be setting the speed that will be used as part of the modifiers / scrolling of the notes. This value used to require a whole number. Project OutFox allows for floats here - you are limited to 6 decimal places - so 143.000290 as an example.

Older simulators do not support decimal point BPM values, and you cannot enter a value above 255 as it can crash the simulator. If you are wishing to make your chart portable to other programs, bear this in mind; not every simulator supports this!

This value also can (and will!) be overwritten by channel commands/settings later on in the chart.

Status: ✅ Supported

Usage Example:

#PLAYLEVEL 5

The playlevel sets the number of ‘stars’ (from the old games) or the difficulty specified. In BMS files this difficulty ranges normally from 0 to 6 - 6 being the hardest. The older scale from 0 to 9 was from the BM98 spec, which was never really used much or supported.

In some BME and most PMS files, the playlevel can be from 1 to 49. This reflects the style from other games with the wider difficulty ranges, and po-mu has had a wider difficulty rating for some years.

In older versions of StepMania, this difficulty used to be squished into a 5 tier difficulty system and sometimes didn’t really work that well. It needed to use a hint from the file name to ensure it didn’t make everything an EDIT. This also meant that a lot of charts disappeared/were not parsed correctly and was generally not that suitable for use. OutFox has remedied this by fixing how the parser sees difficulties, and also widens the difficulty arc to out of 10 fields.

Status: ❌ Unsupported

Usage Example:

#RANK 2

The rank entry used in the old BMS specification used to allow the chart artist to select a difficulty on how the ’timing window’ would be set when playing the chart. It was designed for those simulators that didn’t have ways of difficulty or setting different timing windows.

There were 5 different ranks, the last being added by nanasi which was a more relaxed timing window compared to the other simulators. Almost all of the simulators that are active today set 2 as the default. The old ranking timing windows are listed below for historical purposes. They are ignored on OutFox as we have a custom timing window solution, but if you would like us to add this to set a timing system in the future, do let us know!

Most of these timing windows are not really tied to any specific game or methodology of timing, so it is why we made the decision to not support any of the RANK commands: we also do not support the timing system used by Angolmois which uses 6 ranks. We do not support #DEFEXRANK / #EXRANK as they were additions by nanasi and it seems they did not carry over to be commonly used in other simulators. Changing timing mid song is something we could support, but we do not really see a need to add that to the engine at this time.

The ’timing’ windows used in Project OutFox are closer to RANK 2 to follow the standard others use.

Status: ❌ Unsupported

Usage Example:

#TOTAL 430

The TOTAL command is to set the value of what could be considered an extension of the ‘gauge’ in older simulators, before life gauges existed. The value of TOTAL is added to a normal gauge to increase it’s length. if the value was 300, then the gauge would go from 0 to 100% in size, to the intial value (normally around 25% + 300% for a total gauge size of 325%).

This only occurs when the notes are hit and combo is kept, otherwise things would return to the old gauge size. It was more of a consideration on gauge/groove/clear amounts (what you needed to reach to be considered a pass in that song). This did lead to some confusion on how TOTAL should affect the gameplay/level of the chart.

The gauge never changed size; it was an off screen calculation on how you could ‘score’ your chart. Several simulators over the years have changed this value if TOTAL was omitted, we at the moment do not honour the value, mainly because we do not follow the iidx scoring system since 2005.

Status: ✅ Supported

Usage Example:

#MAKER Ima StepChart

or

#CREDIT Ima StepChart

or

#SUBARTIST Ima StepChart

The MAKER or CREDIT command simply allows the author or maker of the chart to add their credit so it will be displayed in the simulator. The main support for MAKER comes from around 2002 onwards. It is common in most 5 Key styles to be used, as well as being used on 10 Key (double play) styles. CREDIT is more recent, being seen from around 2013 in charts. I know not it’s origin, we support both as to not ignore honouring those that take the time to make charts for us to enjoy.

Since around 2017, another command, SUBARTIST began to be used more commonly in BME/PMS files, which was inherited from DTX. The sub artist is not normally displayed until the evaluation screen on earlier simulators, but in OutFox we treat all three of these in the same manner. If you are creating a new BMS chart, then #MAKER is usually safer to use for other simulator support.

Status: ✅ Supported

Usage Example:

#STAGEFILE loadingscreen.png

The stagefile command is used to set an image to the ’loading screen’ of the simulator - when the song and options/modifiers have been set, this file is then placed as part of the loading process on the ’loading screen’.

On older simulators, this loading process could take a long time, so it was wise to incorporate a loading screen system into the simulator. This has also been recently done in Project OutFox so we do not need to freeze the game while loading these files any more. This file is read in and parsed, just no theme at the moment takes advantage of the loading screen as of yet.

Status: ✅ Supported

Definition Usage Example:

#SCROLL01 0.5
#SCROLL02 1.0
#SCROLL03 -2.75

Channel Usage Example:

#003SC:02010001
#005SC:03000002

The scroll command works similar to how it does in native SM5, but if you are unfamiliar with the system, the value is a multiplier of the speed of the movement of any note on the screen.

If your notes were moving at 130BPM, but you did not wish to edit the BPM directly, you could use scroll to change that speed. The game also supports negative values (this has the affect of moving things in the opposite direction), which can provide some very interesting affects.

The channel command to action #SCROLL values are a Base36 value which are #xxxSC. There are several benefits to using this system as legacy BMS use items you need to name on each measure, whereas #xxxSC can last beyond this restriction. You need to be aware, not many clients support this system, so it is not backwards compatible if you are making your chart available to other simulators.

• ✅ Fully supported and used in Mode
• ✓ Fully supported and not used in Mode
• 📝? No Documentation on this channel’s support
• ❌ Not Supported / Not Available
• ~ Not Used

PMSX listed below on some channels, is the wider 2 player mode that outfox supports for 18k mode.

The earlier versions of BMS were based on a 0-9 supported channel value, being 00 to 99. Over time, it was extended to base16 (00 to FF), and then to base36. I won’t list the tables in full base 36, as those extra channels are mostly used for player notes and keysounds, so it would be very long and hard to read. This table takes the most common layout which is base 16 based, and is also the most common supported by most of the other simulators. There are parts where *0 to *Z can be used, and those will be noted.

This table will be updated and modified as information is found out or addenda needed to fix mistakes. If you notice anything on this page that needs correcting, do let Squirrel know, or make a PR to the wiki’s repo!

The lower channels on a BMS / PMS file mostly set up the specifics of the musical side of the chart, enabling BPM, backgrounds, and special effects like Stops and BGA (background) changes and selection.

The most important channel on this table is 01 which sets the ‘backing’ track or ‘master keysound’ of this track as created by some users. Most of the community do not use a completed file here however, it is better practice for the chart author to create keysounded files, as charting for a ‘single’ file is often thought of as lazy.

On PMS files, the BGA transparency settings are set here as well for effects and ‘cool/miss’ events that happen during the song if the user triggers those. On OutFox we support this mechanic, but as of yet we have not seen any files or have had any reported bugs with this, so it is a low priority option. Do reach out to us if you spot a pack or a song which has these channels within them so we can see what they are and how the effects work.

This block of channels is used for visible player notes for player 1. This selection of channels from 10 to 19 is ordered and swapped around depending on the game chosen. This is why in the early 2000s there were arrangements made for pomu / PMS to be split into it’s own file name, as it reused a lot of notes which on some simulators were loaded as BMS files. Do remember your target mode/game/style when you create your chart! This is especially important if you plan to have support with other simulators as they will not be as relaxed and ‘wide supporting’ as OutFox is.

The pomu-extended mode which is very common in BME files is one such example. It uses 11 to 19 which on some simulations are incorrectly loaded. This type of chart was common in nanasi and we have aligned our support to this as it seems to be more common for the extended options than other ‘formats’.

The original Long Note Implementation is now supported in OutFox, and we do parse #LNTYPE. We have tested these with a lot of different charts from the mid 2000s and we are now reproduce these perfectly.

BME and PMS support for these channels is to the LR2 specification, where Player 1 channels are used. The Player 2 Channel options are not included in this specification.

The original Land Mine Implementation is now supported in OutFox after some serious rewriting of the code to ensure these extended (greater than 9) channels were supported. We have tested these with a lot of different charts from the mid 2000s and we are now reproduce these perfectly with mines behaving as expected on BMS/BME and PMS files. Thanks to Bobini for the suggestion on ensuring that these channels were supported.

BME and PMS support for the landmines (mines) is now 100% complete, and work as planned.

These two channels were recent additions to the specification used in the beatoraja and bemuse clients, and are done slightly differently to the specification. Rather than using one of the 30 spare channels in the lower ranges, these two options require full base 36 (00-ZZ) support to work as they use SC/SP instead of a Hex (00-FF) value. OutFox’s BMS-like parsers were updated in 4.9.9 to support base 36 channel values even though not required by specification, so these channels were a trivial addition to our support.

Speed and Scroll segments replicate behaviour done with Channel 02/08/09, without relying on these channels changing. They were introduced in the SSC updates to StepMania and are natively supported in the engine in OutFox. These add a new layer of effects to be utlised without using #BPMxx or #STOPxx.

Written and Maintained with ♡ by Squirrel, with thanks to the feeling-po-mu, BMS command memo, BMS Discord, and Japanese BMS/PMS community