Map Format

The following guides will aim to document the full internal workings of a Beat Saber map, with detailed information regarding the various schemas that are supported in the most recent version of the game.

This may be useful for those looking to develop specialized software or tooling for processing map files, such as beatmap editors or scripting frameworks.

Schemas

A schema, by definition, is a declarative format for defining how your beatmap data should be structured. You can think of it like a "blueprint" that defines the rules for how your objects and their corresponding properties should be modeled.

The base game will parse and validate the contents of your map files using an internal compatibility layer to ensure that legacy versions of a schema will work as intended in future updates to the game.

These schemas are also enforced when uploading your map to BeatSaver in order to determine whether or not your map is appropriate for upload.

TIP

While legacy schemas are internally supported by the base game, it's recommended that mappers and developers prioritize support for the latest available version(s) of the schema, as legacy schemas are not guaranteed to receive proper support or maintenance for new features or bugfixes.

v2

The "v2" schema was introduced in the 1.0.0 update. It is the oldest supported schema for the game, which makes it compatible with legacy tooling and editors.

v3

The "v3" schema was introduced in the 1.20.0 update, and significantly alters the naming conventions of various fields for the purposes of faster processing.

For all collections, objects use abbreviated fields to define subsequent properties:

v2	v3
{ "_items": [ { "_time": 10.0 // Beat } ] }	{ "items": [ { "b": 10.0 // Beat } ] }

v4

DISCLAIMER

While this schema is officially supported by the Official Editor and custom levels on vanilla instances, any proper support of the schema by mods, community editors, or other services may be unavailable or unstable at this time.

The "v4" schema was introduced in the 1.34.5 update, and utilizes a manual compression strategy for the serialization of all beatmap items.

Any specialized metadata for an object is now stored in a dedicated "metadata" array for each corresponding object type. Within the defined object, a new "index" field is available to retrieve the object's metadata at the specified index of its corresponding metadata array.

In the following example, by setting i to 0, the corresponding metadata from the first item in the itemsData array will be applied to the object in the items array, producing the same result as the v3 object.

v3	v4
{ "items": [ { "b": 10.0, // Beat "x": "foo" // Metadata Property } ] }	{ "items": [ { "b": 10.0, // Beat "i": 0 // Metadata Index } ], "itemsData": [ { "x": "foo" // Metadata Property } ] }

The idea here is that objects that use similar metadata can now store their metadata once, and the same metadata can be used across multiple objects. This allows multiple beatmap elements to share common metadata without bloating the overall filesize, especially for copy/pasted objects or more heavily nested data structures.

Serialization

The base game supports the following behaviors for serializaing the contents of your map files.

File Format

All metadata files are serialized as JSON by default, and any file extension may be used when attempting to serialize related metadata files within your map. The Info file is the only exception to this rule, of which the file must specifically be named Info.dat for the game to properly parse your custom level.

Defaulted Properties

Starting from the 1.31.0 update, the base game has support for defaulted properties when parsing beatmap entities. This means that any fields that are omitted in your metadata will be autopopulated with fallback values, to allow the user to safely omit unused or unchanged properties of any particular object.

This behavior means that the following objects will be equivalent when serialized by the base game:

Input	Output
{ "items": [ { "b": 10.0 } ] }	{ "items": [ { "b": 10.0, "x": 0, "y": 0 } ] }

WARNING

For Quest users who have CustomJSONData installed, there is currently a known bug where maps using defaulted values will load incorrectly with unintended behaviors.

A known fix for these values will be released in the near future, but until then mappers should be wary of how to better control or prevent this behavior.

• The Official Editor (1.31.0+) will always save your maps with defaulted properties. Any versions of the editor should still parse your beatmap as intended on un-modded versions.
• ChroMapper has an explicit setting that allows you to toggle defaulted properties upon saving the map, and this behavior is disabled by default.
• BeatLeader will add an explicit tag to leaderboards for maps that use defaulted values.

Any maps using defaulted values should still be compatible on un-modded instances of the game, allegedly as far back as 1.20.0, but proceed with caution!

The v4 format also extends this functionality to collections under this schema. Any undefined array values will automatically fallback to an empty array, meaning you can safely omit collections that are not explicitly used in your beatmap.

// This is a valid beatmap/lightshow file in v4.
{ "version": "4.0.0" }

WARNING

For NPS and note/bomb/obstacle counts to be displayed properly on the song selection screen, all three corresponding top-level collections (colorNotes, bombNotes, and obstacles) must be explicitly defined.

Metadata fields can be safely omitted, but the base game requires all three top-level fields to be defined in order to properly display these statistics.

Checksums

A checksum is associated with all corresponding map files for verifying internal relationships and leaderboard integrity for OST/DLC maps.

While remnants of these checksums can be found within current or previous iterations of the v4 schema, these fields are either ignored or explicitly set to an empty string when parsing metadata files for custom levels on un-modded instances.

File Deflation

As of the 1.34.5 update, nearly all of the OST/DLC levels use gzip compression to deflate the contents of associated metadata files (audio data, beatmaps, and lightshows). While not directly used or supported by certain editors, the base game will support any custom levels which use deflated metadata files.

Map Files

The base game reads the following files in order to process the contents of a map:

Info

The Info.dat file is the main entry point for your map. It describes basic metadata about your song, as well as point to other files to use for difficulties, cover art, audio, and other references.

Audio

The audio file stores all information regarding how your audio file should be processed.

This file was introduced alongside the beta release of the Official Editor in the 1.22.2 update, and is typically referenced as BPMInfo.dat or AudioData.dat by most editors.

Beatmap

The beatmap file defines collections and associated metadata for all interactable beatmap items, such as notes and obstacles.

Lightshow

Similar to the beatmap file, the lightshow file defines collections and associated metadata for all non-interactable beatmap items, such as environment objects and lighting effects.

This file was introduced alongside the v4 format in the 1.34.5 update.

Custom Data

You may find maps that contain customData fields within various structures in the map files. This functionality is provided by CustomJSONData for PC and Quest, which allows external mods or plugins to extend the basic functionality of a map by parsing any arbitrary metadata listed in these fields.

v2

{
  ...
  "_customData": {
    "foo": "bar"
  }
}

v3

{
  ...
  "customData": {
    "foo": "bar"
  }
}

v4

{
  ...
  "customData": {
    "foo": "bar"
  }
}

While these fields allow you to extend the basic capabilities of a map, this functionality is not compatible with un-modded versions of the game, and may lead to unintended behaviors or issues depending on how different mods and environments may parse this data.

The functionality provided by these fields will also vary, as different mods and plugins will tend to utilize these fields in a variety of ways.

As such, we will not be providing any documentation surrounding these capabilities ourselves, and highly recommend you read through the existing documentation on the various mods and tools that support or utilize custom data and their behaviors:

• SongCore
• Heck (Chroma, Noodle Extensions)
• Cinema

Useful Tools

Community members have developed various tools and scripting frameworks to better support the processing and validation of map files, which may serve useful for mappers and/or developers.

Frameworks

• Beat Saber Deno - A general-purpose scripting framework for Beat Saber maps.
• ReMapper - A scripting framework with more involved utilities for modcharting.

Conversion Tools

• bs-map-converter - A web-based tool that converts v4 maps to v3 format.
• Beat Saber Deno - A collection of TypeScript scripts that support conversion between all supported schemas. See README for instructions on setup and general usage.
• V4-to-V3-lighting - A simple Python script to convert v4 lightshows to v3 format.

Credits

Content in these sections was authored by officialMECH, with additional documentation courtesy of the following resources and contributors:

• Official Editor Documentation
• Kival Evan
• Caeden117
• Bullet
• McEndu