final revisions

Author: officialMECH

wiki/mapping/map-format.md

@@ -26,7 +26,7 @@ to ensure that legacy versions of a schema will work as intended in future updat
 These schemas are also enforced when uploading your map to [BeatSaver](https://beatsaver.com/)
 in order to determine whether or not your map is appropriate for upload.
 
-::: warning
+::: 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**.
@@ -90,6 +90,16 @@ For all collections, objects use abbreviated fields to define subsequent propert
 
 ### v4
 
+::: danger DISCLAIMER
+While support for this schema has been officially introduced to custom levels as of the latest update,
+some aspects of its implementation are still relatively unknown or have been deemed unstable
+based on community testing and indications from the official developers.
+
+This means that any potential support or widespread adoption of the schema by mods, editors, or other services
+(Offical Editor, ChroMapper, BeatSaver, etc.)
+may either be unavailable or delayed at this time.
+:::
+
 The "v4" schema was introduced in the **1.34.5** update,
 and completely reworks the serialization of all beatmap items.
 

wiki/mapping/map-format/beatmap.md

@@ -6,7 +6,7 @@
 The beatmap file defines collections and associated metadata for all _interactable_ beatmap items,
 such as notes and obstacles.
 
-::: warning
+::: info
 In v4 and later,
 any collections for non-interactable beatmap objects are located in the corresponding [Lightshow](./lightshow.md) file.
 You can refer to the sample files included there
@@ -581,7 +581,7 @@ If the head of a chain matches a note's time and position,
 then the chain will connect with the note and alter how the note is scored.
 
 ::: tip
-In v4, the metadata for the head and tail notes are pulled from the [Color Notes](#color-notes) collection.
+In v4, the metadata for the head note is pulled from the [Color Notes](#color-notes) collection.
 :::
 
 ::: code-group
@@ -688,24 +688,29 @@ Indicates the direction the player should swing to successfully cut the head of
 
 An integer value which represents the number of segments in the chain. The head counts as a segment.
 
-- A value of `1` will create a chain with no links,
-  but will still affect the visual look and scoring potential of the head note.
+::: warning
+A value of `1` will create a chain with no links,
+but will still affect the visual look and scoring potential of the head note.
+:::
 
 ### Squish Factor {#chains-squish-factor}
 
 An integer value which represents the proportion of
 how much of the path from `(x, y)` to `(tx, ty)` is used by the chain.
 This does not alter the shape of the path.
 
-- A value greater than `1` will extend the path beyond the specified end point.
-- A value of `0` will crash the game.
+Any value greater than `1` will extend the path beyond the specified end point.
+
+::: danger
+A value of `0` will crash the game.
+:::
 
 ## Spawn Rotations
 
 Allows you to rotate the position where interactable objects should spawn.
 
-::: warning
-These events are assumed to be deprecated starting from v4,
+::: info
+While these events are technically available in v4, they are assumed to be deprecated
 in favor of a new object-level syntax for assigning lane rotations to individual objects.
 :::
 
@@ -793,7 +798,7 @@ Controls the magnitude and direction of the lane rotation.
 
 A negative value will turn the player counter-clockwise, and a positive value will turn clockwise.
 
-::: tip
+::: info
 For v2, the magnitude is determined by an enumerated value,
 of which all possible values are listed in the corresponding table for [Basic Events](./lightshow.md#rotation-events-legacy-value).
 :::
@@ -802,7 +807,7 @@ of which all possible values are listed in the corresponding table for [Basic Ev
 
 Allows you to alter the BPM of the chart at the indicated time.
 
-::: warning
+::: info
 These events are deprecated in v4 or later,
 in favor of automated BPM calculations as determined by the [Audio](./audio.md) file.
 :::

wiki/mapping/map-format/info.md

@@ -115,7 +115,7 @@ The artist(s) of your song.
 
 ## Related Files
 
-::: tip
+::: info
 All filename references are assumed to be located in the same relative directory as the info file.
 :::
 
@@ -361,10 +361,10 @@ which can be defined on a per-beatmap level using the same template-like index a
 All color properties are normalized to a range of `0-1`.
 
 ::: warning
-Any colors in the scheme that are not defined will appear as a "null" color in-game, and may cause unintended effects.
+Any colors in a scheme that are not defined will appear as a "null" color in-game, and may cause unintended effects.
 :::
 
-::: warning
+::: danger
 For v4, **you must define at least one valid color scheme for your map to load properly**,
 regardless of whether the map explicitly sets a color scheme override.
 :::
@@ -514,8 +514,9 @@ organized by their [characteristic](#characteristic) and [difficulty](#difficult
 For v2, all beatmaps are grouped into "sets",
 which dictate corresponding behaviors to apply at a higher level to all beatmaps located within that set.
 
-This behavior went unused in the base-game throughout the lifetime of the schema,
-and support was subsequently removed in v4.
+Support for beatmap sets was subsequently removed in v4,
+due to set-specific behaviors being exclusively controlled by the defined characteristic
+and no additional fields being introduced for beatmap sets throughout the lifetime of the schema.
 
 ::: code-group
 
@@ -542,12 +543,18 @@ and support was subsequently removed in v4.
 The level file associated with your map.
 Must point to a valid JSON file.
 
-::: tip
+::: info
 Starting from v4, all corresponding beatmap data will be divided into two separate files:
 
-- A [Beatmap](./beatmap.md) file, for interactable objects.
-- A [Lightshow](./lightshow.md) file, for non-interactable objects.
-  :::
+- A [Beatmap](./beatmap.md) file, for interactable objects (such as notes and obstacles).
+- A [Lightshow](./lightshow.md) file, for non-interactable objects (such as lighting and environment effects).
+
+:::
+
+::: info
+If a v2 or v3 beatmap file is defined, the lightshow file will subsequently be ignored,
+since v2 and v3 beatmap files already contain the relevant lighting objects for the beatmap.
+:::
 
 ::: code-group
 
@@ -597,13 +604,14 @@ The list of acceptable values and their corresponding behaviors are listed below
 
 <!-- markdownlint-enable MD013 -->
 
-::: warning
+::: danger
 Some mods may add additional characteristics that are not supported within the base game,
 such as SongCore's `Lightshow` and `Lawless` characteristics.
 
 When loading maps with these characteristics on un-modded versions of the game,
 affected maps will not be compatible with the Official Editor,
-and affected beatmaps may be filtered out of the available difficulties for the player to select in-game.
+and affected beatmaps may be filtered out of the available difficulties for the player to select in-game
+or fail to load correctly on un-modded instances.
 :::
 
 ::: code-group

wiki/mapping/map-format/lightshow.md

@@ -9,7 +9,7 @@ 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.
 
-::: warning
+::: info
 In v3 and earlier,
 any collections for non-interactable beatmap objects are located in the corresponding [Beatmap](./beatmap.md) file.
 You can refer to the sample files included there
@@ -140,7 +140,7 @@ For more information on how these events are assigned on a per-environment level
 [Environment Previews](../basic-lighting.md#environment-previews) section.
 :::
 
-::: warning
+::: info
 Types `5`, `14`, `15`, and `100` are deprecated in v3 or later,
 in favor of more flexible data structures for the respective behaviors.
 :::
@@ -212,7 +212,7 @@ See [Color Boost Events](#color-boost-events) for more details.
 |  `0`  | Disable Color Boost |
 |  `1`  | Enable Color Boost  |
 
-::: warning
+::: info
 These events are deprecated in v3 or later, in favor of more robust implementations and data structures in future schemas.
 :::
 
@@ -232,7 +232,7 @@ See [Spawn Rotations](./beatmap#spawn-rotations) for more details.
 |  `6`  |     45 Degrees Clockwise     |
 |  `7`  |     60 Degrees Clockwise     |
 
-::: warning
+::: info
 These events are deprecated in v3 or later,
 in favor of an updated syntax that allows for more freedom for the available increments of lane changes.
 :::
@@ -248,7 +248,7 @@ A value of 0 will turn the light off.
 
 #### BPM Events (Legacy) {#bpm-events-legacy-float-value}
 
-The value is used to alter the BPM at the indicated beat. See [BPM Events](#bpm-events) for more details.
+The value is used to alter the BPM at the indicated beat. See [BPM Events](./beatmap.md#bpm-events) for more details.
 
 <!-- markdownlint-enable MD013 -->
 
@@ -312,7 +312,7 @@ Determines whether the color boost effect is enabled.
 Used to control the TinyTAN figures that are exclusive to the BTS environment.
 
 ::: tip
-For more detailed information on implementation, check out the following [document](https://docs.google.com/spreadsheets/d/1spW7LS-RvenLQBVXJl9w_iOwqr9r_ozxYo3JUlXq9Lc).
+For more detailed information on how to control the TinyTAN figures, check out the following [document](https://docs.google.com/spreadsheets/d/1spW7LS-RvenLQBVXJl9w_iOwqr9r_ozxYo3JUlXq9Lc).
 :::
 
 ::: code-group
@@ -1284,9 +1284,9 @@ This allows the event box to pull its corresponding base event data from the col
 For example, setting `l` to `[0, 1]` will pull the data from the first two base events defined in the collection,
 where those base events will become children of the event box.
 
-::: warning
-While this schema supports defining a collection of "integer" FX events, their implementation went unused in v3,
-and support was subsequently removed in v4.
+::: info
+While v3 technically supports defining a collection of "integer" FX events,
+their implementation went unused, and support was subsequently removed in v4.
 :::
 
 ::: code-group
@@ -1438,7 +1438,7 @@ when overriding the environment to a different one than what was assigned in the
 Any environments that feature event box groups will have this setting disabled by default in the Official Editor,
 while use of "legacy" environments will leave this setting enabled.
 
-::: info
+::: tip
 Unlike the [basic lighting system](#basic-events), the [group lighting system](#event-box-groups) does not guarantee
 that group assignments will be cross-compatible with other environments,
 which may cause certain lightshows to produce unintended effects and unwanted behaviors as a result.