The supersets array

The supersets array is found in objects inside the variants array. The objects inside the supersets array list variants of titles that belong to a group.

Tip

Make sure you've read how the titles array works before learning about supersets.

Supersets are variants of titles that contain more content, or for some reason are superior to another version. This might include, for example, a Game of the Year edition, an all-in-one pack that bundles a game and all its DLC, or a DVD version of a title previously released on multiple CDs.

A supersets array looks similar to the following example:

"variants": [
  {
    "group": "Example Title",
    "titles": [
      {"searchTerm": "Example Title"},
      {"searchTerm": "Exemple de Titre"},
      {"searchTerm": "Titolo di Esempio"},
      {"searchTerm": "Example Title Budget Edition", "priority": 2}
    ],
    "supersets": [
      {"searchTerm": "Example Title - Game of the Year Edition"}
    ]
  }
]

You can use the following keys in an object that's in a supersets array:

Key	Type	Description
`searchTerm`	`str`	The search term used when looking for a title in an input DAT file.
`nameType`	`str`	Optional. What name type the search term is, so Retool can match it accurately against names in the input DAT file. The valid values are: `short`: Default. The short name. `full`: The full name. `regionFree`: The region-free name. `regex`: A regex match on the full name.
`priority`	`int`	Optional, defaults to `1`. Lower numbers are considered higher priority, with `1` the highest priority. Typically, a title with a higher priority wins when Retool is choosing a 1G1R title. Superset priorities are compared against `supersets` and `compilations` priorities, but not `titles` priorities.
`englishFriendly`	`bool`	Optional, defaults to `false`. An English-friendly title is one that hasn't been marked as supporting English, but an English-speaking player can easily play to completion. Setting `englishFriendly` to `true` makes Retool treat a title as if it supports English.
`localNames`	`obj[str, str]`	Optional. Contains the local names of a title. Add names for all available languages, including English. Language keys must be lowercase versions of languages found in the `user-config.yaml` file or RetoolGUI languages list. For example, `japanese`, `russian`, `chinese (traditional)`. `"localNames": { "english": "Example title", "chinese (traditional)": "標題範例", "japanese": "タイトルの例" }` See Local names for more information on specifying local names.
`filters`	`array[obj]`	Optional. Treat some titles found by a search term differently based on `conditions`. If all `conditions` are true, then Retool executes the `results`. `"filters": [ { "conditions": {"matchRegions": ["Japan"]}, "results": {"group": "Somewhere else"} } ]` See Filters for more information, including the valid `conditions` and `results`.

How it works

Assume a DAT file contains the following titles:

Example Title (USA)
Example Title Budget Edition (USA)
Example Title - Game of the Year Edition (United Kingdom)
Example Title (Europe)
Exemple de Titre (France)
Titolo di Esempio (Italy)

Most are exactly the same title, just different versions or from different regions. Example Title - Game of the Year Edition (United Kingdom), however, contains the latest version of the game plus all of its DLC, but was never released in the USA or Europe. If the user is an English speaker and puts USA first, then how do we make sure this title gets selected as the superior version of the game? With the supersets array.

"variants": [
  {
    "group": "Example Title",
    "titles": [
      {"searchTerm": "Example Title"},
      {"searchTerm": "Exemple de Titre"},
      {"searchTerm": "Titolo di Esempio"},
      {"searchTerm": "Example Title Budget Edition", "priority": 2}
    ],
    "supersets": [
      {"searchTerm": "Example Title - Game of the Year Edition"}
    ]
  }
]

By default, supersets look at language support over a user's region order. If a superset supports the top language found in a group of titles (in this example, that's English), then it's selected over other standard titles in higher regions as it's considered superior.

In this example, because no language order is specified but USA is listed first, Retool infers a preference for English, finds the superset Example Title - Game of the Year Edition (United Kingdom), and selects it as the 1G1R title above the standard USA title, as it supports the same language and is considered superior due to having more content.

Note

A user can force adherence to region order with the Prefer regions over languages option. In that scenario, Example Title (USA) is selected at the cost of losing the extra content in Example Title - Game of the Year Edition (United Kingdom).

Supersets are also useful to manage things like DVD releases of titles that were previously distributed on multiple CDs. For example, if a DAT file contains the following title names, all of which represent the same title:

Example Title (Disc 1) (USA)
Example Title (Disc 2) (USA)
Example Title (Disc 3) (USA)
Beispieltitel (Disc 1) (Germany)
Beispieltitel (Disc 2) (Germany)
Beispieltitel (Disc 3) (Germany)
Example Title (USA)

And Example Title (USA) is the DVD version of the three-disc CD release Example Title (USA) and Beispieltitel (Germany) titles, then you can set up a variants object as follows:

"variants": [
  {
    "group": "Example Title (Disc 1)",
    "titles": [
      {"searchTerm": "Example Title (Disc 1)"},
      {"searchTerm": "Beispieltitel (Disc 1)"}
    ],
    "supersets": [
      {"searchTerm": "Example Title"}
    ]
  },
  {
    "group": "Example Title (Disc 2)",
    "titles": [
      {"searchTerm": "Example Title (Disc 2)"},
      {"searchTerm": "Beispieltitel (Disc 2)"}
    ],
    "supersets": [
      {"searchTerm": "Example Title"}
    ]
  },
  {
    "group": "Example Title (Disc 3)",
    "titles": [
      {"searchTerm": "Example Title (Disc 3)"},
      {"searchTerm": "Beispieltitel (Disc 3)"}
    ],
    "supersets": [
      {"searchTerm": "Example Title"}
    ]
  }
]

Note that the Example Title superset is in all three groups. In this scenario, if a user selects USA as their highest region, then Example Title (USA) is selected as the 1G1R title over the original, multidisc CD version. If they select Germany, then the three German discs are chosen instead.