Skip to content

Calculation of Combination Ids

BluePsyduck edited this page Feb 18, 2021 · 1 revision

The Combination API takes over the task of actually calculating the IDs used to identify a combination of mods. Because these IDs get used throughout the whole project of the FIB, it is important to have stable IDs for all of them. This page explains how they get calculated.

It is discouraged to calculate the Combination ID in a client application. If the ID is needed, e.g. for accessing the main API, simply request the status of the mods from the Combination API, which will contain the ID for these mods.

# Step Description Example
0. Initial mod list The initial list of the mod names used to calculate the combination id. base, Foo, Bar
1. Sort mod names The mod names get sorted by their name using their ASCII codes. Bar, Foo, base
2. JSON encode The mod names get encoded as a simple string array to minimal JSON. ["Bar","Foo","base"]
3. Calculate md5 hash The md5 hash of the JSON string is calculated. 83f899a6ba398f56a70492907650dc3e
4. Transform to UUID The md5 hash is transformed into a UUID. 83f899a6-ba39-8f56-a704-92907650dc3e

Notes:

  • The sorting uses the ASCII codes of the characters. This is why capital letters gets sorted before small ones, i.e. why "Foo" is before "base" in the example above.
  • The transformation to a UUID is only cosmetic, but makes it a little more readable. The API uses UUIDs across many places. UUIDs are stored in their binary form in the database.
  • The combination id of Vanilla is 2f4a45fa-a509-a9d1-aae6-ffcf984a7a76.

Combination ID vs. Short Combination ID

The combination id actually has two representations: The "full" representation uses the UUID format as described above, thus consisting of 32 hexadecimal characters separated by four hyphens. E.g. the main database uses the UUID in binary form as primary keys for mostly all datasets.

The Short Combination ID is a more compact representation of the same ID, converting it to base62. This ID is exactly 22 characters long, and uses numbers, big letters and small letters as character set. Because of its shorter form, it is used by the portal in the URLs. For example, the Vanilla combination 2f4a45fa-a509-a9d1-aae6-ffcf984a7a76 has the short id 1reA6H5z4uFpotvegbLIr4.

The Combination API always provides both representations of the combination id. Through the main API only accepts the full representation for its requests.