Multiple Interface Version Support

[Meorawr]

This request has been implemented as described in the linked comment.

---

We'd like to request a way to specify multiple versions in a TOC file that will permit addons to no longer be flagged as out-of-date unless zipped up and distributed as separate packages for each client.

For the past couple of years of Classic's existence the approach used by addons which support both game clients has generally been to ship two possibly otherwise identical copies of their addon with the TOC interface version corrected for each client. Depending on how the upcoming TBC client is released, we could be looking at doing this a third time if the client for it were separate from the existing Classic one.

---

The proposal is to have the client support different Interface version fields per client flavour, allowing addons to fill these in as needed and only provide a single TOC file that'll work on all of them. As an example of what we'd like to do:

## Interface-Retail: 90100
## Interface-BC: 20501
## Interface-Classic: 11307
## Title: My Awesome AddOn

If the above TOC file were loaded into a client which supported per-flavour versioning, what we'd like to see is that this addon not be flagged as out of date on either the Retail or Classic/TBC clients so long as the interface versions given match their respective client.

Note that the particular names associated with each client ("Retail", "BC", and "Classic") are for exposition only and can be changed as needed, however community support appears to favour these three names.

One additional extension that we'd like is the ability to also flag addons as completely incompatible with a client flavour, such that they'll show as "Incompatible" in the addon list and the client will refuse to load them entirely. As the feature and API difference between Classic and Retail has grown, a number of addons have either had to add code to explicitly detect being loaded on the wrong client, or simply aren't compatible to begin with.

## Interface-Retail: Incompatible
## Interface-BC: 20501
## Interface-Classic: 11307

The expectation is that if the above were loaded into the Classic/TBC client then the addon would be loadable, whereas if it were loaded into the Retail client then it would be marked as "Incompatible" in the addon list and the client wouldn't permit it to be loaded.

For compatibility with existing addons and processes, the existing "Interface" tag should remain as-is, such that its usage specifies the supported interface version for the current client regardless of flavour. In the case where an author uses both a flavour-specific and the general "Interface" tag the behaviour should probably be that the most-specific tag is used:

## Interface: 20501
## Interface-Retail: Incompatible

With the above the expectation is that the addon would be marked as "Incompatible" on Retail clients, and flagged as supporting interface version 20501 on everything else.

---

One final idea that's been suggested a few times is to permit specifying multiple interface versions as a comma-delimited list primarily to assist with flagging addons as compatible with a currently-released and in-test patch.

Note that while this would be nice to have, it shouldn't be considered as high priority as the rest of the proposal, and can be omitted if the risk of addons abusing this is considered undesirable.

## Interface-Retail: 90005, 90100
## Interface-BC: 20500, 20501
## Interface-Classic: 11306, 11307

If support for comma-delimited versions were added, the expectation is the above would be marked as not being out-of-date for any of the listed interface versions.

[Meorawr]

Just to elaborate on some of the choices in this proposal based on feedback from Discord so far, the primary goals are for it to be:

• Additive, such that any existing addons don't suddenly break in fundamental ways when 9.1/TBC hit.
• Solve problems currently experienced in real-world usage of the interface versioning system.
• Structured so that if an individual piece isn't considered desirable, it can be removed and the entire proposal won't collapse in on itself.
• Simple enough that it doesn't take Blizzard long to implement.

To answer a few common queries...

Why not just have comma-delimited "Interface" versions?

We could go with a minimal proposal where only the Interface tag exists and it supports comma-delimited versions, however this causes two issues.

1. We'd either entirely forego or need weird syntax to support the notion of marking addons as Incompatible with a client flavour.
2. It may not be desirable to allow addons to flag themselves as supporting multiple interface versions on a single client.

In the "Incompatible" case by using individual per-flavour tags we can just use the literal word "Incompatible", whereas if we reused the existing "Interface" tag and made it comma-delimited the only representation we'd be left with to implement this would be strings like "!TBC" or "!2*", which is likely to be harder to implement not only on Blizzard's side but also that of external tooling like the packager which may parse the TOC to grab version metadata.

Why do we want "incompatible" tagging?

A number of addons either don't work without separate packaging steps for each client or simply don't make sense on a client that's lacking specific features. Additionally as the APIs have diverged, and will likely continue to do so, authors may not want to support specific client flavours if the effort is too great - one such area being the new and old Auction House APIs.

A pattern that's developed over the past couple of years is to use the packager to include metadata on an "intended" client flavour and have addon code confirm that the environment an addon is being executed in matches this expectation, and to take action if there's a mismatch.

A prime example from my favourite go-to repository would be the WeakAuras one which embeds such a check and early-returns in every single script file.

Being able to support this at the TOC level removes the need for these things and additionally provides external tooling that parses TOC files with a way to verify whether or not any package for a given client would be entirely incompatible.

Why could multiple versions for each client flavour be undesirable?

One concern that's been raised a few times is that an addon could ship a package and claim it's compatible with every predictable interface version from the current patch until three expansions down the line.

While I personally think any such addon would be shooting itself in the foot by doing so, the concern is of course valid - but I also feel that the ability to do so anyway is worthwhile to deal with the case of an addon that's compatible with both a currently released and in-development patch, especially if updates to multiple client flavours are occurring near one another.

An additional benefit we'd get from this externally is addon hosting sites may be less heavily loaded with regards to backend processing on patch days if authors can ship updated addons in the week or two prior to a patch release in a state that's compatible with both a live and in-test version, instead of holding out from uploading updates to avoid being flagged as "out-of-date" due to an impending client patch.

Isn't having multiple "Interface-Client" lines in the TOC more verbose than a single "Interface" line?

It's no worse than the current solution. It's again also likely to be easier for external tooling to process.

Why not treat unlisted clients as incompatible by default?

Any proposal that isn't backwards compatible isn't likely to be very popular; I don't really want to be responsible for breaking every existing Classic addon because they don't have an "Interface-Classic" in their TOC today. We'd also have a significant issue communicating this change since most authors aren't engaged with any real central hub of sorts, and even an official forum post that would cover such a change is likely to go unread.

Is it likely this would even be implemented?

We won't really know unless we ask, and now's probably the best time since otherwise we'll be stuck with the status quo for another two years until Classic WotLK.

[Meorawr]

Updated the proposal to cover the possible case of having three clients, using "Interface-BC" to represent versions targeting the BC client. If anyone's got a better name for it then feel free to suggest, since I'm split between "BC", "TBC", "BCC", and "TBCC".

[mooreatv]

If blizzard ever reads this (which would be awesome!) my vote goes to keep things simple and backward compatible:

## Interface: v1, v2, v3

Simple and does the job (if none of the version specified match the game main version then obviously that means incompatible/untested, no need to make things complicated and not scaling with -Retail -Classic -Tbc -Watlk -Cata...)

[Nevcairiel]

Changing a long-established line is the least backwards compatible option. :)

The original approach above maintains the singular ## Interface line that has existed for years, if the developer wishes, and only adds additional information in additional lines. Backwards compatibility is maintained with existing addons as well as all externals tools that may look for this line.

For the record, the point of the "Incompatible" suggestion is to have a distinct difference from "untested", to inform both the game and the user immediately that the addon was in fact tested and found to not be working (or the user downloaded the wrong version), instead of being showered in unspecific Lua errors or general non-functioning. This is an actual real-world problem that many addons face, and either have to solve manually by littering every single file with various checks, or facing unactionable error reports, and thus it would help immensely to immediately get feedback from the game that a wrong version was installed (for example).

And no, this is not a place to "cast a vote". The available options have been discussed quite a bit among various active members of the community before this suggestion was posted, weighing the pros and cons, and the additional flexibility that separate tags provide has simply won out in the end. The same arguments made are also fully represented in the description above.

TL;DR: We try to present the options here, as cleanly and thought out as possible. Discussion can be held on the common communications channels, and not here. :)

[Meorawr]

Please read the updates made in this linked comment for upcoming changes to suffixes in future patches.

---

In a future set of builds the client will support loading distinct TOC files on a per-client basis. The implementation we've been informed about is as follows:

• If an addon is loaded on the BCC client, the client will first look for a TOC file whose name is suffixed by "-BCC" (eg. "MyAddOn-BCC.toc") and load that if present. If not, the client will fall back and load "MyAddOn.toc".
• If an addon is loaded on the Classic client, the client will first look for a TOC file whose name is suffixed by "-Classic" (eg. "MyAddOn-Classic.toc") and load that if present. If not, the client will fall back and load "MyAddOn.toc".
• If an addon is loaded on the Retail client, the client will first look for a TOC file whose name is suffixed by "-Mainline" (eg. "MyAddOn-Mainline.toc") and load that if present. If not, the client will fall back and load "MyAddOn.toc".
• If an addon fails to find a client-specific TOC and no fallback "MyAddOn.toc" is present, the addon will not be loaded.

The envisioned advantages of this approach are that it will enable us to control the files that are loaded on a per-client basis without requiring separate packages - which the initial request didn't account for - and the same also applies to other TOC attributes such as dependencies.

The request for "Incompatible" tagging can be suitably emulated by only including TOCs for clients that you support and not providing a fallback "MyAddOn.toc" file. Note that at present doing this will mean your addon will not show in the addon list for unsupported clients, however this may be iterated upon in the future.

We'll likely see some work put into the packager to have it support the automatic creation of the additional TOC files if requested by authors to deal with the common case where the only difference would otherwise be the interface version.

This has been implemented as of the following client versions:

• Retail: 9.1.0.38627 (PTR)
• BCC: 2.5.1.38548 (Beta/PTR)
• Classic: 1.13.7.38631 (Live)

[Meorawr]

Future patches will make a tweak to the suffixes supported by each client.

• For Classic, the client will now additionally search for AddonName_Vanilla.toc.
• For BCC, the client will now additionally search for AddonName_TBC.toc.
• For Retail, the client will now additionally search for AddonName_Mainline.toc.

The existing suffixes (-Classic.toc, -BCC.toc, and -Mainline.toc) will still be supported.

Additionally, the separator between the addon name and the client suffix can be either _ or -; so AddonName-TBC.toc is valid as well as AddOnName_BCC.toc.

The new suffixes will be supported in an upcoming client hotfix for patch 2.5.1 and 9.1, and are presently implemented on the patch 2.5.2 PTR.

---

For avoidance of doubt, these are all the file name formats presently supported on all clients and the order that each client will attempt to load them in currently. On the wiki we're recommending that people use a single specific suffix for each client for overall consistency, which corresponds to the first file in each sub-list below and is the format used by Blizzard.

- Retail
  1. AddOnName_Mainline.toc
  2. AddOnName-Mainline.toc
  3. AddOnName.toc

- BCC
  1. AddOnName_TBC.toc
  2. AddOnName_BCC.toc
  3. AddOnName-TBC.toc
  4. AddOnName-BCC.toc
  5. AddOnName.toc

- Classic Era
  1. AddOnName_Vanilla.toc
  2. AddOnName_Classic.toc
  3. AddOnName-Vanilla.toc
  4. AddOnName-Classic.toc
  5. AddOnName.toc

[Meorawr]

Updated the above comment with new information re: backwards compatibility. Note that the current BCC PTR build (2.5.2.39570) only supports the new suffix; this should be temporary.

[p3lim]

@Meorawr do you know if all those new suffixes also apply to the TOC ## Interface* fields?
E.g. does ## Interface_Vanilla: 11300 work?

[Meorawr]

@Meorawr do you know if all those new suffixes also apply to the TOC ## Interface* fields?
E.g. does ## Interface_Vanilla: 11300 work?

TOC files don't support client-specific interface directives - they were just the initial proposal before Blizzard gave us client-specific files instead.

The Packager is the only thing that adopted the per-client Interface directives for convenience in the common case, and because the syntax was much nicer than the old approach.

[p3lim]

Ah yeah ofcourse, forgot about that (I even had it mentioned in my notes 😛).

Do you happen to know more specificly which builds the additional formats are supported in?

[Meorawr]

The new suffixes are supported in all current live clients for each game flavour. Can't remember exact build numbers where each one was added - for 2.5.2 it was early PTR, 1.13 had it patched in a straight-to-live build, and 9.1 the same.

[Ketho]

CurseForge seemingly added support for, -Mainline, -BCC and -Classic
But they're still going to add _Mainline, _TBC and _Vanilla or whatever prefix character combination I'm still missing

https://curseforge-ideas.overwolf.com/ideas/CF-I-1832

[DFortun81]

For the purpose of planning ahead, can we have support for Cataclysm, MOP, WOD, Legion, BFA, Shadowlands, and Dragonflight? This might be more specific to an addon like ATT, but having these TOCs in place ahead of time will make testing updates for future Betas/Alphas a lot more streamlined for us.

[Meorawr]

Blizzard aren't going to lock themselves into a set of TOC suffixes today for Classic expansions that won't be relevant for years - if ever. Nothing is stopping you from guessing the suffixes now and just renaming them in 2/4/6/... years if you're wrong of course.

[DFortun81]

My issue is that ATT's classic version has a TOC file for Classic, TBC, Wrath, and Cataclysm right now. Uploading to CurseForge the addon processes as expected. Uploading to WAGO, the package fails to process due to having "different named TOC files in the addon". As this GitHub issue is referenced in official documentation for both addon hosting websites, it might be a good idea to establish expectations as the community sees fit ahead of time so that addon providers such as these can update their systems to account for the future. If I remove the Cataclysm TOC variant WAGO successfully processes my addon. Unless submission requirements are established ahead of time, we may encounter similar issues later prior to every new expansion release. This inadvertently also makes testing addons for Expansion Alphas and Betas using this new TOC structure less reliable as deploying an addon that supports the new expansion without the addon providers supporting the new expansion TOC file(s) will mean delayed availability for testers.

[Nevcairiel]

Future-proofing is frankly just not a thing in AddOns. You'll just need to add the TOCs as those versions actually begin existing. And at the same time react to all the changes in those potential future versions.

[nihilistzsche]

Yep you can't predict the future, it will happen as it happens, and nothing else.

[DFortun81]

Yep you can't predict the future, it will happen as it happens, and nothing else.

In this case, you don't need to seeing as how we're dealing with expansions that have already come and gone. :)

[Meorawr]

I'm just going to lock this ticket as this is long since solved. The issue of hosts or tooling rejecting invalid TOC names is an entirely separate topic best discussed with their support channels.

With respect to Wago, their validation requirements are aimed at preventing cases where an addon is uploaded that wouldn't be loadable if installed. As-is their requirements sound stricter than is needed - a package need only contain either an unsuffixed TOC file (MyAddon.toc) or a single recognized-suffixed one (MyAddon_TBC.toc). If either of those is met, the package should realistically be considered loadable. Any other extraneous TOC files in that same archive with an _Unrecognized.toc suffix could just be ignored or produce a warning rather than a hard error.

Given that future Classic expansions are years away and may not even happen I don't think it's sensible for any addon hosts or tooling to take guesses at "valid" suffixes.

For addons; even if you ship a package today with future expansion TOCs compensated for I'd find it highly unlikely that anyone this very same version as-released today in 2/4/... years when those expansion betas are actually released. Consider also that there's often a small time lag between the initial alpha builds wherein we can determine the suffix and addons actually being enabled - such a window is when both addon hosts and external tooling can update to accommodate the new suffixes to be "ready" for general use.