The compilations array

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

Tip

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

You add compilations to the groups of each individual title that's found in the compilation. For example, for a compilation of Example Title 1 & Example Title 2 (Europe) (En,De,Fr+En,Ja) you add it to the groups Example Title and Example Title 2.

Even if a title in the compilation is not available separately, for Retool to work properly you must create a group as if the standalone title exists, and add the compilation to it.

A compilations 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}
    ],
    "compilations": [
      {"searchTerm": "Example Title 1 & Example Title 2", "titlePosition": 1}
    ]
  },
  {
    "group": "Example Title 2",
    "compilations": [
      {"searchTerm": "Example Title 1 & Example Title 2", "titlePosition": 2}
    ]
  }
]

When Retool is comparing titles, a compilation inside a group is treated as if it is only one of the titles in the compilation. For example, Example Title 1 & Example Title 2 inside a group of Example Title 2 is treated as if it is only Example Title 2 for comparison purposes. This is known as a virtual title.

You can use the following keys in an object that's in a compilations 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. Setting a priority on a compilation sets it for the virtual title, not the compilation itself. Virtual title priorities are compared against `titles` and `supersets` priorities.
`titlePosition`	`int`	Optional. Sometimes No-Intro uses the `+` notation in language tags for compilations, using it as a separator to assign different languages to each title in the compilation. For example, Example Title 1 + Example Title 2 (Europe) (En,De,Fr+En,Ja) means that Example Title 1 in the compilation supports English, German, and French, whereas Example Title 2 supports English and Japanese. To assign the correct languages to the appropriate virtual title when the `+` notation is used, you need to set a `titlePosition`. As Example Title is first in the compilation name, in the `Example Title` group you set a `titlePosition` of `1` on the compilation. This creates the virtual title :V: Example Title (Europe) (En,De,Fr), which is used to compare against the individual variants of that title also listed in the group. In the `Example Title 2` group you set a `titlePosition` of `2`. This creates the virtual title :V: Example Title 2 (Europe) (En,Ja) for the sake of comparison.
`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.

How it works

Assume a DAT file contains the following titles:

Example Title (USA)
Example Title (Europe)
Example Title Budget Edition (USA)
Example Title 1 & Example Title 2 (Europe) (En,Fr,De+En,Ja)
Exemple de Titre (France)
Titolo di Esempio (Italy)
Example Title 2 - Special Edition (USA)

They are all individual titles, except for Example Title 1 & Example Title 2 (Europe) (En,Fr,De+En,Ja), which is a compilation of Example Title and Example Title 2. How do we make sure that compilation is properly compared against the individual titles it's made of?

The answer is to add the compilation to a group for each individual title.

"variants": [
  {
    "group": "Example Title",
    "titles": [
      {"searchTerm": "Example Title"},
      {"searchTerm": "Exemple de Titre"},
      {"searchTerm": "Titolo di Esempio"},
      {"searchTerm": "Example Title Budget Edition", "priority": 2}
    ],
    "compilations": [
      {"searchTerm": "Example Title 1 & Example Title 2", "titlePosition": 1}
    ]
  },
  {
    "group": "Example Title 2",
    "titles": [
        {"searchTerm": "Example Title 2 - Special Edition"}
      ],
    "compilations": [
      {"searchTerm": "Example Title 1 & Example Title 2", "priority": 2, "titlePosition": 2}
    ]
  }
]

Assuming a user sets USA as their highest region, here's what happens when Retool processes these groups:

Retool looks at the Example Title group, and finds Example Title 1 & Example Title 2 (Europe) (En,Fr,De+En,Ja) in the DAT file via the compilations search term Example Title 1 & Example Title 2.
That compilation is assigned a virtual name that matches the group name, and includes region and language information: :V: Example Title (Europe) (En,Fr,De). The languages of En,Fr,De are added because a titlePosition of 1 has been set, so Retool knows to use the first set of languages out of (En,Fr,De+En,Ja).

Creating a virtual title effectively splits out that indvidual title from the compilation for comparison, meaning the second title in the compilation isn't considered when comparing titles in this group. Because no priority is defined, the virtual title is assigned a priority of 1.
Retool looks at the Example Title 2 group, and finds Example Title 1 & Example Title 2 (Europe) (En,Fr,De+En,Ja) in the DAT file via the compilations search term Example Title 1 & Example Title 2.
Although it's the same compilation as before, it's assigned a virtual name that matches the Example Title 2 group name: :V: Example Title 2 (Europe) (En,Ja). The languages of En,Ja are added because a titlePosition of 2 has been set, so Retool knows to use the second set of languages out of (En,Fr,De+En,Ja).

This means the first title in the compilation isn't considered when comparing titles in this group. This variant of the title inside the compilation is a lower version than Example Title 2 - Special Edition (Europe), so it is assigned a priority of 2.
Example Title (USA) wins against other individual titles in its group, because the user has set USA as their highest region, and Example Title Budget Edition has been set to a priority of 2.
Example Title 2 - Special Edition (Europe) wins as the individual title in its group, because it is the only individual title in the Example Title 2 group.
Retool compares the virtual compilation titles against the individual titles in the same groups:
- Example Title (USA) is compared against :V: Example Title (Europe) (En,Fr,De). The individual USA title wins due to region priority.
- Example Title 2 - Special Edition (Europe) is compared against :V: Example Title 2 (Europe) (En,Ja). The latter is discarded because it has a lower priority.

Ultimately Example Title (USA) and Example Title 2 - Special Edition (Europe) become the 1G1R titles, and Example Title 1 & 2 (Europe) (En,Fr,De+En,Ja) is discarded.