### Configure Song Preview

Source: https://bsmg.wiki/mapping/map-format/info.html

Defines the start time and duration of the audio track preview played in-game. Supports both legacy v2 and modern v4 structures.

```jsonc
{
  "_previewStartTime": 10.0,
  "_previewDuration": 12.0
}
```

```jsonc
{
  "audio": {
    "previewStartTime": 10.0,
    "previewDuration": 12.0
  }
}
```

--------------------------------

### Define Obstacles in JSON

Source: https://bsmg.wiki/mapping/map-format/beatmap.html

Examples of obstacle data structures across different schema versions. Includes legacy formats and the updated v3-like structure.

```jsonc
{
  "_obstacles": [
    {
      "_type": 0,
      "_time": 10.0,
      "_duration": 5.0,
      "_lineIndex": 1,
      "_width": 1
    }
  ]
}
```

```jsonc
{
  "_obstacles": [
    {
      "_type": 2,
      "_time": 10.0,
      "_duration": 5.0,
      "_lineIndex": 1,
      "_lineLayer": 0,
      "_width": 1,
      "_height": 5
    }
  ]
}
```

```jsonc
{
  "obstacles": [
    {
      "b": 10.0,
      "d": 5.0,
      "x": 1,
      "y": 0,
      "w": 1,
      "h": 5
    }
  ]
}
```

```jsonc
{
  "obstacles": [
    {
      "b": 10.0,
      "r": 0,
      "i": 0
    }
  ],
  "obstaclesData": [
    {
      "d": 5.0,
      "x": 1,
      "y": 0,
      "w": 1,
      "h": 5
    }
  ]
}
```

--------------------------------

### Event Box Groups Configuration (JSONC)

Source: https://bsmg.wiki/mapping/map-format/lightshow.html

Defines the structure for Event Box Groups, including event data and filter properties. This example shows a basic configuration with type and parameter settings.

```jsonc
{
  "...EventBoxGroups": [
    {
      "e": [
        {
          "f": {
            "f": 1, // Type
            "p": 1, // Parameter 0
            "t": 0, // Parameter 1
            "r": 0, // Reverse
          }
        }
      ]
    }
  ]
}
```

--------------------------------

### v2 Schema Example - Beat Saber Map Data

Source: https://bsmg.wiki/mapping/map-format

Demonstrates the structure of a Beat Saber map file using the v2 schema. This schema is compatible with legacy tooling and editors, introduced in the 1.0.0 update.

```json
{
  "_items": [
    {
      "_time": 10.0 // Beat
    }
  ]
}
```

--------------------------------

### Set Note Jump Metadata

Source: https://bsmg.wiki/mapping/map-format/info.html

Configures movement parameters for objects, including speed and start beat offsets, which influence gameplay difficulty.

```jsonc
{
  "_difficultyBeatmapSets": [
    {
      "_difficultyBeatmaps": [
        {
          "_noteJumpMovementSpeed": 18.0,
          "_noteJumpStartBeatOffset": 0.5
        }
      ]
    }
  ]
}
```

```jsonc
{
  "difficultyBeatmaps": [
    {
      "noteJumpMovementSpeed": 18.0,
      "noteJumpStartBeatOffset": 0.5
    }
  ]
}
```

--------------------------------

### Define Song Metadata

Source: https://bsmg.wiki/mapping/map-format/info.html

Sets the song title, subtitle, and author name. Provides examples for both v2 and v4 schema structures.

```jsonc
{
  "_songName": "Example",
  "_songSubName": "Example",
  "_songAuthorName": "Example"
}
```

```jsonc
{
  "song": {
    "title": "Example",
    "subTitle": "Example",
    "author": "Example"
  }
}
```

--------------------------------

### v3 Schema Example - Beat Saber Map Data

Source: https://bsmg.wiki/mapping/map-format

Illustrates the v3 schema for Beat Saber map files, which uses abbreviated fields for faster processing. This schema was introduced in the 1.20.0 update.

```json
{
  "items": [
    {
      "b": 10.0 // Beat
    }
  ]
}
```

--------------------------------

### Custom Data Field Examples in Beat Saber Maps

Source: https://bsmg.wiki/mapping/map-format

These examples demonstrate the structure of `_customData` and `customData` fields within Beat Saber map files. These fields are used by mods and plugins to extend map functionality and are not compatible with un-modded game versions.

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

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

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

--------------------------------

### Define Info.dat Metadata Structure

Source: https://bsmg.wiki/mapping/map-format/info.html

JSON schema examples for Info.dat versions 2.0.0 and 2.1.0. These files define song attributes, difficulty beatmap sets, and optional color scheme overrides for custom environments.

```json
{
  "_version": "2.0.0",
  "_songName": "Magic",
  "_songSubName": "ft. Meredith Bull",
  "_songAuthorName": "Jaroslav Beck",
  "_levelAuthorName": "Freeek",
  "_beatsPerMinute": 208,
  "_songFilename": "Magic.wav",
  "_coverImageFilename": "cover.png",
  "_difficultyBeatmapSets": [
    {
      "_beatmapCharacteristicName": "Standard",
      "_difficultyBeatmaps": [
        {
          "_difficulty": "Easy",
          "_difficultyRank": 1,
          "_beatmapFilename": "Easy.dat",
          "_noteJumpMovementSpeed": 10,
          "_noteJumpStartBeatOffset": 0
        }
      ]
    }
  ]
}
```

```json
{
  "_version": "2.1.0",
  "_songName": "Magic",
  "_colorSchemes": [
    {
      "useOverride": true,
      "colorScheme": {
        "colorSchemeId": "Weave",
        "saberAColor": { "r": 0.78, "g": 0.07, "b": 0.07, "a": 1 },
        "saberBColor": { "r": 0.15, "g": 0.55, "b": 0.82, "a": 1 }
      }
    }
  ],
  "_difficultyBeatmapSets": [
    {
      "_beatmapCharacteristicName": "Standard",
      "_difficultyBeatmaps": [
        {
          "_difficulty": "Easy",
          "_beatmapFilename": "Easy.dat",
          "_beatmapColorSchemeIdx": 0,
          "_environmentNameIdx": 0
        }
      ]
    }
  ]
}
```

--------------------------------

### v4 Schema Example - Beat Saber Map Data with Metadata

Source: https://bsmg.wiki/mapping/map-format

Shows the v4 schema for Beat Saber map files, featuring a manual compression strategy and metadata separation. Introduced in the 1.34.5 update, it allows for shared metadata across objects.

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

--------------------------------

### FX Event Box JSON Configuration

Source: https://bsmg.wiki/mapping/map-format/lightshow.html

Examples of FX Event Box structures for different versions. The v3 format utilizes a collection array for base events, while v4 separates event boxes, filters, and event data into distinct top-level arrays.

```jsonc
{
  "vfxEventBoxGroups": [
    {
      "b": 2.0,
      "g": 0,
      "e": [
        {
          "f": {},
          "w": 1.0,
          "d": 1,
          "s": 1.0,
          "t": 1,
          "b": 1,
          "i": 0,
          "l": [0]
        }
      ]
    }
  ],
  "_fxEventsCollection": {
    "_fl": [
      {
        "b": 0.0,
        "p": 0,
        "i": 1,
        "v": 100.0
      }
    ],
    "_il": []
  }
}
```

```jsonc
{
  "eventBoxGroups": [
    {
      "b": 2.0,
      "g": 0,
      "t": 4,
      "e": [
        {
          "f": 0,
          "e": 0,
          "l": [
            {
              "b": 0.0,
              "i": 0
            }
          ]
        }
      ]
    }
  ],
  "indexFilters": [{}],
  "fxEventBoxes": [
    {
      "w": 1.0,
      "d": 1,
      "s": 1.0,
      "t": 1,
      "b": 1,
      "e": 0
    }
  ],
  "floatFxEvents": [
    {
      "p": 0,
      "e": 1,
      "v": 100.0
    }
  ]
}
```

--------------------------------

### Configure Beatmap and Lightshow Filenames

Source: https://bsmg.wiki/mapping/map-format/info.html

Shows how to link data files to a beatmap. In v4, interactable objects and lighting are split into separate files.

```jsonc
{
  "_difficultyBeatmapSets": [
    {
      "_difficultyBeatmaps": [
        {
          "_beatmapFilename": "Easy.dat"
        }
      ]
    }
  ]
}
```

```jsonc
{
  "difficultyBeatmaps": [
    {
      "beatmapDataFilename": "Easy.dat",
      "lightshowDataFilename": "Lightshow.dat"
    }
  ]
}
```

--------------------------------

### Configure Audio and Cover Files

Source: https://bsmg.wiki/mapping/map-format/info.html

Defines the filenames for audio tracks and cover art. v4 requires explicit separation of primary and preview audio files.

```jsonc
{
  "_songFilename": "song.ogg",
  "_coverImageFilename": "cover.png"
}
```

```jsonc
{
  "audio": {
    "songFilename": "song.ogg"
  },
  "songPreviewFilename": "song.ogg",
  "coverImageFilename": "cover.png"
}
```

--------------------------------

### Configure Color Boost Events

Source: https://bsmg.wiki/mapping/map-format/lightshow.html

Defines the structure for color boost events, which allow swapping environment colors at specific beats. Supports legacy and modern JSON schemas.

```jsonc
{
  "_events": [
    {
      "_time": 10,
      "_type": 5,
      "_value": 1
    }
  ]
}
```

```jsonc
{
  "colorBoostBeatmapEvents": [
    {
      "b": 10,
      "o": true
    }
  ]
}
```

```jsonc
{
  "colorBoostEvents": [
    {
      "b": 10,
      "i": 0
    }
  ],
  "colorBoostEventsData": [
    {
      "b": 1
    }
  ]
}
```

--------------------------------

### Beatmap JSON Schema Versions

Source: https://bsmg.wiki/mapping/map-format/beatmap.html

Examples of Beatmap file structures across various versions (2.0.0 to 2.6.0). These JSON objects demonstrate the evolution of the schema, including the addition of waypoints, special event keyword filters, and float values for events.

```json
{
  "_version": "2.0.0",
  "_notes": [
    { "_time": 10, "_lineIndex": 1, "_lineLayer": 0, "_type": 0, "_cutDirection": 1 },
    { "_time": 10, "_lineIndex": 1, "_lineLayer": 0, "_type": 3, "_cutDirection": 0 }
  ],
  "_obstacles": [
    { "_type": 0, "_time": 10, "_duration": 5, "_lineIndex": 1, "_width": 1 }
  ],
  "_events": [
    { "_time": 10, "_type": 1, "_value": 3 },
    { "_time": 10, "_type": 5, "_value": 1 },
    { "_time": 10, "_type": 14, "_value": 4 },
    { "_time": 15, "_type": 15, "_value": 4 },
    { "_time": 10, "_type": 10, "_value": 128 }
  ]
}
```

```json
{
  "_version": "2.2.0",
  "_notes": [...],
  "_obstacles": [...],
  "_events": [...],
  "_waypoints": [
    { "_time": 10, "_lineIndex": 1, "_lineLayer": 0, "_offsetDirection": 1 }
  ]
}
```

```json
{
  "_version": "2.4.0",
  "_notes": [...],
  "_obstacles": [...],
  "_events": [...],
  "_waypoints": [...],
  "_specialEventsKeywordFilters": {
    "_keywords": [{ "_keyword": "SECRET", "_specialEvents": [40, 41, 42, 43] }]
  }
}
```

```json
{
  "_version": "2.5.0",
  "_notes": [...],
  "_obstacles": [...],
  "_events": [
    { "_time": 10, "_type": 1, "_value": 3, "_floatValue": 1 },
    { "_time": 10, "_type": 100, "_value": 0, "_floatValue": 128 }
  ],
  "_waypoints": [...],
  "_specialEventsKeywordFilters": {...}
}
```

--------------------------------

### Compare Basic Events Schema Versions

Source: https://bsmg.wiki/mapping/map-format/lightshow.html

Evolution of the Basic Events schema across different BSMG versions. Shows the transition from simple event objects to the split data structure used in 4.0.0.

```jsonc
// 2.0.0
{
  "_events": [
    { "_time": 10, "_type": 1, "_value": 3 }
  ]
}
```

```jsonc
// 2.5.0
{
  "_events": [
    { "_time": 10, "_type": 1, "_value": 3, "_floatValue": 1.0 }
  ]
}
```

```jsonc
// 3.0.0
{
  "basicBeatmapEvents": [
    { "b": 10, "et": 1, "i": 3, "f": 1.0 }
  ]
}
```

```jsonc
// 4.0.0
{
  "basicEvents": [{ "b": 10, "i": 0 }],
  "basicEventsData": [{ "t": 1, "i": 3, "f": 1.0 }]
}
```

--------------------------------

### v4 Schema Minimal Beatmap Definition

Source: https://bsmg.wiki/mapping/map-format

Shows a minimal valid beatmap or lightshow file using the v4 schema. While metadata can be omitted, top-level collections must be defined for proper UI statistics display.

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

--------------------------------

### Spawn Rotation Data Structure (JSONC)

Source: https://bsmg.wiki/mapping/map-format/beatmap.html

Details spawn rotation data, linking beats to metadata indices and providing execution time and magnitude for rotation effects. This allows for precise control over object spawning rotations.

```jsonc
{
  "spawnRotations": [
    {
      "b": 10.0, // Beat
      "i": 0, // Metadata Index
    },
    {
      "b": 15.0, // Beat
      "i": 1, // Metadata Index
    },
  ],
  "spawnRotationsData": [
    {
      "t": 0, // Execution Time
      "r": 15.0, // Magnitude
    },
    {
      "t": 1, // Execution Time
      "r": 15.0, // Magnitude
    },
  ],
}
```

--------------------------------

### Define Environments

Source: https://bsmg.wiki/mapping/map-format/info.html

Sets the game environment for the map. Uses a collection-based indexing system in newer versions to allow per-beatmap environment selection.

```jsonc
{
  "_environmentName": "DefaultEnvironment",
  "_allDirectionsEnvironmentName": "GlassDesertEnvironment"
}
```

```jsonc
{
  "_environmentName": "DefaultEnvironment",
  "_allDirectionsEnvironmentName": "GlassDesertEnvironment",
  "_environmentNames": ["DefaultEnvironment", "GlassDesertEnvironment"],
  "_difficultyBeatmapSets": [
    {
      "_difficultyBeatmaps": [
        {
          "_environmentNameIdx": 0
        }
      ]
    }
  ]
}
```

```jsonc
{
  "environmentNames": ["DefaultEnvironment", "GlassDesertEnvironment"],
  "difficultyBeatmaps": [
    {
      "environmentNameIdx": 0
    }
  ]
}
```

--------------------------------

### Define Beatmap Sets and Difficulty Structure

Source: https://bsmg.wiki/mapping/map-format/info.html

Demonstrates the grouping of beatmaps into sets. Note that v4 removed the set structure in favor of direct difficulty definitions.

```jsonc
{
  "_difficultyBeatmapSets": [
    {
      "_difficultyBeatmaps": [...]
    }
  ]
}
```

```jsonc
{
  "difficultyBeatmaps": [...]
}
```

--------------------------------

### Configure Color Schemes

Source: https://bsmg.wiki/mapping/map-format/info.html

Defines custom color palettes for sabers, obstacles, and lights. Uses normalized RGB values for v2 and hex strings for v4.

```jsonc
{
  "_colorSchemes": [
    {
      "useOverride": true,
      "colorScheme": {
        "colorSchemeId": "Weave",
        "saberAColor": { "r": 0.7843137, "g": 0.07843138, "b": 0.07843138, "a": 1 },
        "saberBColor": { "r": 0.1568627, "g": 0.5568627, "b": 0.8235294, "a": 1 },
        "environmentColor0": { "r": 0.85, "g": 0.08499997, "b": 0.08499997, "a": 1 },
        "environmentColor1": { "r": 0.1882353, "g": 0.675294, "b": 1, "a": 1 },
        "obstaclesColor": { "r": 1, "g": 0.1882353, "b": 0.1882353, "a": 1 },
        "environmentColor0Boost": { "r": 0.8218409, "g": 0.08627451, "b": 0.8509804, "a": 1 },
        "environmentColor1Boost": { "r": 0.5320754, "g": 0.5320754, "b": 0.5320754, "a": 1 }
      }
    }
  ],
  "_difficultyBeatmapSets": [
    {
      "_difficultyBeatmaps": [
        { "_beatmapColorSchemeIdx": 0 }
      ]
    }
  ]
}
```

```jsonc
{
  "colorSchemes": [
    {
      "useOverride": true,
      "colorSchemeName": "Weave",
      "saberAColor": "C81414FF",
      "saberBColor": "288ED2FF",
      "obstaclesColor": "FF3030FF",
      "environmentColor0": "D91616FF",
      "environmentColor1": "30ACFFFF",
      "environmentColor0Boost": "D216D9FF",
      "environmentColor1Boost": "00FFA5FF"
    }
  ],
  "difficultyBeatmaps": [
    { "beatmapColorSchemeIdx": 0 }
  ]
}
```

--------------------------------

### Add New Characteristic to Info.dat (JSON)

Source: https://bsmg.wiki/mapping/extended-mapping.html

Demonstrates how to add a new characteristic to the Info.dat file in JSON format. This involves modifying the '_beatmapCharacteristicName' and '_beatmapFilename' within the '_beatmapSets' array. Ensure the difficulty file is renamed to include the characteristic name.

```json
"_difficultyBeatmapSets": [{
 "_beatmapCharacteristicName": "Lightshow",
 "_difficultyBeatmaps": [{
  "_difficulty": "Easy",
  "_difficultyRank": 1,
  "_beatmapFilename": "EasyLightshow.dat",
}]
```

--------------------------------

### Chroma 2.0 Gradient Lighting Event (JSON)

Source: https://bsmg.wiki/mapping/extended-lighting.html

Defines a lighting gradient using the _lightGradient property within a customData object. This allows for smooth color transitions over a specified duration with optional easing.

```json
{
  "_customData": {
    "_lightGradient": {
      "_duration": 2,
      "_startColor": [1,0,0],
      "_endColor": [0,0,1],
      "_easing": "easeLinear"
    }
  }
}
```