docs: document #1154 (songTitle+artist matching) (#1218)

docs/docs/codebase/batch-manual/index.md

@@ -75,6 +75,7 @@ The properties are described as this:
 | `matchType` | "songTitle" \| "ddrSongHash" \| "tachiSongID" \| "bmsChartHash" \| "inGameID" \| "uscChartHash" | This determines how `identifier` will be used to match your scores' chart with Tachi's database of songs and charts. |
 | `identifier` | String | A string that Tachi uses to identify what chart this is for. How this is used depends on the `matchType`. |
 | `difficulty` (Conditional) | String | If `matchType` is "tachiSongID", "inGameID", "ddrSongHash" or "songTitle", this field must be present, and describe the difficulty of the chart this score is for. |
+| `artist` (Conditional) | String | If `matchType` is "songTitle", this field can be present, and describe the artist name for less equivocal matching. This field is optional for legacy purposes. |
 | `timeAchieved` (Optional) | integer \| null | This is *when* the score was achieved in unix milliseconds. This should be provided if possible, as Tachi uses it for a LOT of features. |
 | `comment` (Optional) | string \| null | A comment from the user about this score. |
 | `judgements` (Optional) | Record<Game Judgement, integer> | This should be a record of the judgements for your game + playtype, and the integer indicating how often they occured. |
@@ -95,14 +96,29 @@ in a different way.
 
 - songTitle
 
-As the name implies, this searches for a song who's title
-resembles `identifier`. **THIS IS NOT FUZZY MATCHING**,
+As the name implies, this searches for a song whose title
+is exactly `identifier`. **THIS IS NOT FUZZY MATCHING**,
 and is by far the least reliable way to send scores to
 Tachi. This is kept for compatibility purposes with poor quality APIs.
 
 This match type *necessitates* that `difficulty` be defined
 and set to a valid difficulty for this game + playtype.
 
+This match type can be augmented with a secondary identifier `artist`
+which resolves title clashes:
+
+```json
+{
+	"score": 500,
+	"lamp": "HARD CLEAR",
+	"matchType": "songTitle",
+	"identifier": "5.1.1.",
+	"artist": "dj nagureo",
+	"difficulty": "ANOTHER",
+	"timeAchieved": 1624324467489
+}
+```
+
 - tachiSongID
 
 This uses `identifier` as if it were an integer, to match
@@ -167,6 +183,7 @@ looks like this:
 		"lamp": "HARD CLEAR",
 		"matchType": "songTitle",
 		"identifier": "5.1.1.",
+		"artist": "dj nagureo",
 		"difficulty": "ANOTHER"
 	}, {
 		"score": 123,

docs/docs/game-support/common-config/match-types.md

@@ -43,14 +43,10 @@ If `"ANY_INF"` is the difficulty, then that difficulty will try to find a chart
 
 ### `songTitle`
 
-Looks up the song on its title or any of its defined `altTitles`.
+Looks up the song on its title or any of its defined `altTitles`. Can also match the artist field of the song if an `artist` property is defined.
 
 !!! warning
-	This *requires* that your game never has two songs with the same title. By enabling
-	this, the seeds tests will check and enforce this for you.
-
-	You should generally *never* enable this option, as you *really* can't guarantee
-	the uniqueness of song titles short of the game being dead.
+	It is generally not recommended to enable this method, as it's particularly error-prone. Scores that can't be unequivocally identified will get rejected.
 
 ### `tachiSongID`
 

docs/docs/game-support/games/ongeki-Single.md

@@ -14,7 +14,7 @@ For more information on what metrics are and how they work, see [TODO]!
 | Metric Name | Type | Description |
 | :: | :: | :: |
 | `score` | Integer | Known in-game as 'Technical Score'. It ranges between 0 and 1,010,000, where notes are worth 950,000, and bells 60,000. |
-| `noteLamp` | "LOSS", "CLEAR", "FULL COMBO", "ALL BREAK" | The primary lamp. A clear is either a draw or a win. |
+| `noteLamp` | "LOSS", "CLEAR", "FULL COMBO", "ALL BREAK" | The primary lamp. A clear is a draw or a win in-game. |
 | `bellLamp` | "NONE", "FULL BELL" | Tracks whether all bells in the chart have been collected. |
 
 ### Derived Metrics
@@ -27,12 +27,12 @@ For more information on what metrics are and how they work, see [TODO]!
 
 | Metric Name | Type | Description |
 | :: | :: | :: |
-| `fast` | Integer | The amount of mistakes in this score that were a result of hitting early. |
-| `slow` | Integer | The amount of mistakes in this score that were a result of hitting late. |
+| `fast` | Integer | The number of non-critical mistakes in this score that were a result of hitting early. |
+| `slow` | Integer | The number of non-critical mistakes in this score that were a result of hitting late. |
 | `maxCombo` | Integer | The largest combo in this score. |
 | `damage` | Integer | The number of damage ticks received. |
 | `bellCount` | Integer | The number of bells collected. |
-| `totalBellCount` | Integer | The total number of bells. |
+| `totalBellCount` | Integer | The maximum number of bells that could have been obtained at the time of the play's end. |
 | `platScore` | Integer | The Platinum Score value. Only exists in MASTER and LUNATIC charts. |
 
 ## Judgements
@@ -82,11 +82,17 @@ The folowing judgements are defined:
 
 | ID | Pretty Name |
 | :: | :: |
-| `brightMemory3` | bright MEMORY Act.III |
-| `brightMemory3Omni` | bright MEMORY Act.III Omnimix |
+| `brightMemory3` | bright MEMORY Act.3 |
+| `brightMemory3Omni` | bright MEMORY Act.3 Omnimix |
 
 ## Supported Match Types
 
 - `songTitle`
 - `tachiSongID`
-- `inGameID`
+- `inGameID`
+
+### Song Title matching
+There are numerous songs with non-unique names (e.g. Singularity, Singularity and Singularity), but this can be resolved by providing the `artist` field. The only exception is Perfect Shining, which uniquely has two LUNATIC charts and has to be matched by `inGameID`:
+
+- LUNATIC 0 (Loctest chart) `inGameID: 8003`
+- LUNATIC 13+ (Re:Master) `inGameID: 8091`