feat: GIDs translation layer between v4 and v5?

[CosminPerRam]

What is this feature about?
PR #415 introduced the biggest breaking change in the next major version, a standard of creating game ids (GIDs).
This is a problem as user cannot migrate easily to this version without rechecking what their game's new id is.

While adding this 'translation' layer, we could find cases where:

• Newly supported Game has id X
• Older supported Game with new id is Y but old id is X

And what would we want to do here? Prioritize newly ids or older ones?
This could go multiple ways:

1. Look only for new ids.
2. Prioritize new ids, if none is found, look for the old ones.
3. Prioritize old ids, if none is found, look for the newer ones.
4. Look only for old ids.

I for one think that we should look only for new ids by default (solution 1) and have an additional field that does solution 3.

Additional context/references
Talked some more about this in #487.

[podrivo]

Maybe instead of having a layer of 'translation' built into the code, should we consider having a separate markdown file with this 'translation' from v4 to v5? A migration document.

Something like a table of GIDs:

v4		v5
cs2	→	counterstrike2
had2	→	hiddendangerous2
left4dead2	→	l4d2

[CosminPerRam]

A 'migration guide' for v4->v5 is also something that I thought about and your suggestion is really good, thanks.

The problem in the grand scheme of things are projects such as Homepage or Uptime Kuma:
If they'll want to migrate from v4 to v5, they cannot do this because it'll break all the current user-set GameDig gids, an option here is to add a 'banner' on their side to indicate this or introduce their own translation layer, but this is really our 'fault', so we should resolve it as smoothly as possible for them.

[podrivo]

I'm not familiar with Homepage or Uptime Kuma. How they work and why can't they migrate versions?

[CosminPerRam]

Let's take a look at the support for GameDig on HomePage (link here):

Now let's suppose the 'type' value was cs2 (to demonstrate this):
The latest homepage version is using gamedig version 4.3.0, in that version the GID for Counter Strike 2 is cs2, but in v5 it will be counterstrike2.
Remember that this is user-made input, and you have a Counter Strike 2 server that you'll want to keep track with Homepage, so you'd enter here cs2.
Some time later you update homepage, from version X to version Y, the only change is that X was running gamedig 4.3.0, so your id is fine, version Y is running 5.0.0, so if you'd update homepage your server will not be tracked anymore and you'll need to do some research to find out why and eventually realise your game has a new id, which isn't ideal.
Also Homepage shouldn't be forced to make a big note saying "Yo, we updated GameDig and your previously-made correct config is now broken, go search for your new GID!" (unless they too release a backwards-breaking version, which in this case that'll be understandable).

Hope I've explained the problem more concisely, please mention if something is still unclear (:

[podrivo]

I see now. Thank you for the explanation! 🙌
And yeah, I agree that we should take care of that ourselves.

I've ran the tools/find-id-changes.js and there's 84 changes out of 326 ids, that's around 25%.
I can see why this is a concern.

Do you know if there's a case where a new id of a game is the same as an old id of a different game?
Did some testing, and I don't think there are duplicates at the moment.

Here's the output:

[
{
  "hash": "c0287ab93229a11d62843302135e2d765ce1686e",
  "changes": [
    [
      "7d2d",
      "sdtd"
    ]
  ],
  "removed": [],
  "added": []
},
{
  "hash": "89515cb6770645152ec8a2b2c54d3737787e8a04",
  "changes": [],
  "removed": [],
  "added": [
    "eldewrito"
  ]
},
{
  "hash": "26a6ee1c08ea72297c695d52339e62ed8ee4f49c",
  "changes": [],
  "removed": [],
  "added": []
},
{
  "hash": "6bfbc883bee463fcc64988d7cfb424f2d31c8712",
  "changes": [],
  "removed": [],
  "added": [
    "beammp"
  ]
},
{
  "hash": "90b3c6044b265a654e39801f61bdefcfd32f2fe9",
  "changes": [],
  "removed": [],
  "added": []
},
{
  "hash": "fccd61c4eaac9a80a1f07021f04435fbc182832d",
  "changes": [
    [
      "americasarmypg",
      "aapg"
    ]
  ],
  "removed": [],
  "added": []
},
{
  "hash": "aa8b20b302e85017bfbe20a049c32a91091b0251",
  "changes": [
    [
      "as",
      "actionsource"
    ],
    [
      "ageofchivalry",
      "aoc"
    ],
    [
      "arkse",
      "ase"
    ],
    [
      "arcasimracing",
      "asr08"
    ],
    [
      "arma",
      "aaa"
    ],
    [
      "arma2oa",
      "a2oa"
    ],
    [
      "armacwa",
      "acwa"
    ],
    [
      "armar",
      "armaresistance"
    ],
    [
      "armare",
      "armareforger"
    ],
    [
      "armagetron",
      "armagetronadvanced"
    ],
    [
      "bat1944",
      "battalion1944"
    ],
    [
      "bf1942",
      "battlefield1942"
    ],
    [
      "bfv",
      "battlefieldvietnam"
    ],
    [
      "bf2",
      "battlefield2"
    ],
    [
      "bf2142",
      "battlefield2142"
    ],
    [
      "bfbc2",
      "bbc2"
    ],
    [
      "bf3",
      "battlefield3"
    ],
    [
      "bf4",
      "battlefield4"
    ],
    [
      "bfh",
      "battlefieldhardline"
    ],
    [
      "bd",
      "basedefense"
    ],
    [
      "bs",
      "bladesymphony"
    ],
    [
      "buildandshoot",
      "bas"
    ],
    [
      "cod4",
      "cod4mw"
    ],
    [
      "callofjuarez",
      "coj"
    ],
    [
      "chivalry",
      "cmw"
    ],
    [
      "commandos3",
      "c3db"
    ],
    [
      "cacrenegade",
      "cacr"
    ],
    [
      "contactjack",
      "contractjack"
    ],
    [
      "cs15",
      "counterstrike15"
    ],
    [
      "cs16",
      "counterstrike16"
    ],
    [
      "cs2",
      "counterstrike2"
    ],
    [
      "crossracing",
      "crce"
    ],
    [
      "darkesthour",
      "dhe4445"
    ],
    [
      "daysofwar",
      "dow"
    ],
    [
      "deadlydozenpt",
      "ddpt"
    ],
    [
      "dh2005",
      "deerhunter2005"
    ],
    [
      "dinodday",
      "ddd"
    ],
    [
      "dirttrackracing2",
      "dtr2"
    ],
    [
      "dmc",
      "deathmatchclassic"
    ],
    [
      "dnl",
      "dal"
    ],
    [
      "drakan",
      "dootf"
    ],
    [
      "dys",
      "dystopia"
    ],
    [
      "em",
      "empiresmod"
    ],
    [
      "empyrion",
      "egs"
    ],
    [
      "f12002",
      "formulaone2002"
    ],
    [
      "flashpointresistance",
      "ofr"
    ],
    [
      "fivem",
      "gta5f"
    ],
    [
      "forrest",
      "theforrest"
    ],
    [
      "graw",
      "tcgraw"
    ],
    [
      "graw2",
      "tcgraw2"
    ],
    [
      "giantscitizenkabuto",
      "gck"
    ],
    [
      "ges",
      "goldeneyesource"
    ],
    [
      "gore",
      "gus"
    ],
    [
      "hldm",
      "hld"
    ],
    [
      "hldms",
      "hlds"
    ],
    [
      "hlopfor",
      "hlof"
    ],
    [
      "hl2dm",
      "hl2d"
    ],
    [
      "hidden",
      "thehidden"
    ],
    [
      "had2",
      "hiddendangerous2"
    ],
    [
      "igi2",
      "i2cs"
    ],
    [
      "il2",
      "il2sturmovik"
    ],
    [
      "insurgencymic",
      "imic"
    ],
    [
      "isle",
      "theisle"
    ],
    [
      "jamesbondnightfire",
      "jb007n"
    ],
    [
      "jc2mp",
      "jc2m"
    ],
    [
      "jc3mp",
      "jc3m"
    ],
    [
      "kingpin",
      "kloc"
    ],
    [
      "kisspc",
      "kpctnc"
    ],
    [
      "kspdmp",
      "kspd"
    ],
    [
      "kzmod",
      "kreedzclimbing"
    ],
    [
      "left4dead",
      "l4d"
    ],
    [
      "left4dead2",
      "l4d2"
    ],
    [
      "m2mp",
      "m2m"
    ],
    [
      "mohsh",
      "mohaas"
    ],
    [
      "mohbt",
      "mohaab"
    ],
    [
      "mohab",
      "moha"
    ],
    [
      "moh2010",
      "moh"
    ],
    [
      "mohwf",
      "mohw"
    ],
    [
      "minecraftbe",
      "mbe"
    ],
    [
      "mtavc",
      "gtavcmta"
    ],
    [
      "mtasa",
      "gtasamta"
    ],
    [
      "ns",
      "naturalselection"
    ],
    [
      "ns2",
      "naturalselection2"
    ],
    [
      "nwn",
      "neverwinternights"
    ],
    [
      "nwn2",
      "neverwinternights2"
    ],
    [
      "nolf",
      "tonolf"
    ],
    [
      "nolf2",
      "nolf2asihw"
    ],
    [
      "pvkii",
      "pvak2"
    ],
    [
      "ps",
      "postscriptum"
    ],
    [
      "primalcarnage",
      "pce"
    ],
    [
      "pc",
      "projectcars"
    ],
    [
      "pc2",
      "projectcars2"
    ],
    [
      "prbf2",
      "prb2"
    ],
    [
      "przomboid",
      "projectzomboid"
    ],
    [
      "quake1",
      "quake"
    ],
    [
      "quake3",
      "q3a"
    ],
    [
      "ragdollkungfu",
      "rdkf"
    ],
    [
      "r6",
      "rainbowsix"
    ],
    [
      "r6roguespear",
      "rs2rs"
    ],
    [
      "r6ravenshield",
      "rs3rs"
    ],
    [
      "redorchestraost",
      "roo4145"
    ],
    [
      "redm",
      "rdr2r"
    ],
    [
      "riseofnations",
      "ron"
    ],
    [
      "rs2",
      "rs2v"
    ],
    [
      "samp",
      "gtasam"
    ],
    [
      "saomp",
      "gtasao"
    ],
    [
      "savage2",
      "s2ats"
    ],
    [
      "ss",
      "serioussam"
    ],
    [
      "ss2",
      "serioussam2"
    ],
    [
      "ship",
      "theship"
    ],
    [
      "sinep",
      "sinepisodes"
    ],
    [
      "sonsoftheforest",
      "sotf"
    ],
    [
      "swbf",
      "swb"
    ],
    [
      "swbf2",
      "swb2"
    ],
    [
      "swjk",
      "swjkja"
    ],
    [
      "swjk2",
      "swjk2jo"
    ],
    [
      "takeonhelicopters",
      "toh"
    ],
    [
      "tf2",
      "teamfortress2"
    ],
    [
      "terraria",
      "terrariatshosck"
    ],
    [
      "tribes1",
      "t1s"
    ],
    [
      "ut",
      "unrealtournament"
    ],
    [
      "ut2003",
      "unrealtournament2003"
    ],
    [
      "ut2004",
      "unrealtournament2004"
    ],
    [
      "ut3",
      "unrealtournament3"
    ],
    [
      "v8supercar",
      "v8sc"
    ],
    [
      "vcmp",
      "vcm"
    ],
    [
      "vs",
      "vampireslayer"
    ],
    [
      "wheeloftime",
      "wot"
    ],
    [
      "wolfenstein2009",
      "wolfenstein"
    ],
    [
      "wolfensteinet",
      "wet"
    ],
    [
      "wurm",
      "wurmunlimited"
    ]
  ],
  "removed": [
    "mumbleping",
    "ts"
  ],
  "added": [
    "aosc",
    "mgm",
    "thespecialists"
  ]
},
{
  "hash": "2ffff5e7d64b70c0a9172ee3e87422eb58eff7b5",
  "changes": [],
  "removed": [],
  "added": []
},
{
  "hash": "861d24898a5af240ac71d01a9558147d8768d531",
  "changes": [],
  "removed": [],
  "added": [
    "codbo3"
  ]
},
{
  "hash": "d4babb078b484d15a7a7301413c32cf72bacf211",
  "changes": [],
  "removed": [],
  "added": []
},
{
  "hash": "e05ac1fd488696c0415ead88232a84734cce7e07",
  "changes": [],
  "removed": [],
  "added": [
    "u2tax"
  ]
},
{
  "hash": "10718d917cb836922649eb10bb9bce41c845c41f",
  "changes": [],
  "removed": [],
  "added": [
    "xonotic"
  ]
}
]

[podrivo]

While adding this 'translation' layer, we could find cases where:

Newly supported Game has id X
Older supported Game with new id is Y but old id is X

Should we consider GIDs as unique keys? So they can't have duplicates. A game might have 2 unique GIDs, an old and a new, but they'll continue to be unique GIDs. A GID can be assigned to only one game. If this is true, than newly added games will need to have an extra rule in naming, to avoid having duplicates. This would address this situation you mentioned.

A game could be something like this:

counterstrike2: {
  name: 'Counter-Strike 2',
  release_year: 2023,
  options: {
    port: 27015,
    protocol: 'valve'
  },
  extra: {
    oldGID: 'cs2'
  }
}

And what would we want to do here? Prioritize newly ids or older ones?

If they're unique, should we test (edit by maintainer: OP meant 'process' here) all GIDs regardless?
We'll be adding 84 new GIDs, total of 410 GIDs. Is performance an issue with this?

[CosminPerRam]

Did some testing, and I don't think there are duplicates at the moment.

Oh, really? While I manually rewrote the gids I thought I skimmed on some that were colliding, I guess we could really see this in the eventual-to-come PR.

A game might have 2 unique GIDs, an old and a new, but they'll continue to be unique GIDs.
[...]

Hope I dont misunderstand, but are you suggesting to just add the old ids as separate entries (resulting in some games having 2 keys, lets say all are unique, no colliders)? Cause if so, I would be against it, cause in that object a game should have only one entry, if we'd like to have alternative ids, it should be inside said game object, not outside of it. Also it will break CI that tests gids formatting.

[podrivo]

Oh, really? While I manually rewrote the gids I thought I skimmed on some that were colliding, I guess we could really see this in the eventual-to-come PR.

I think so, but I'm not 100% haha. Will re-test it to make sure.

Hope I dont misunderstand, but are you suggesting to just add the old ids as separate entries (resulting in some games having 2 keys, lets say all are unique, no colliders)? Cause if so, I would be against it, cause in that object a game should have only one entry, if we'd like to have alternative ids, it should be inside said game object, not outside of it. Also it will break CI that tests gids formatting.

Oh no, what I'm suggesting is something similar to #487, where the old GID is a property:

counterstrike2: {
  name: 'Counter-Strike 2',
  release_year: 2023,
  options: {
    port: 27015,
    protocol: 'valve'
  },
  extra: {
    oldGID: 'cs2'
  }
}

[CosminPerRam]

where the old GID is a property

Oh, then that's alright.

If they're unique, should we test all GIDs regardless?

So by this you mean to also test the old GIDs? If so, no, because they were made before we had any GIDs formatting rules so they have high chances to break.

[podrivo]

So by this you mean to also test the old GIDs? If so, no, because they were made before we had any GIDs formatting rules so they have high chances to break.

Sorry, by test I meant when using the command gamedig --type GID, that we should try new and old GIDs.

CI tests should only test the main/new GID.

[CosminPerRam]

Sorry, by test I meant when using the command gamedig --type GID, that we should try new and old GIDs.

Understood, if that's the case (all unique), then yes (I still suggest to enable/disable this with an option).

[podrivo]

Nice! I'll work on that PR (#487) and implement something closer to what we've discussed.

[CosminPerRam]

Closed by #496.