OPie: Slice Token Requirements

If you're creating OPie rings from external code using the OPie.CustomRings API, you will soon need to provide persistent, globally unique slice tokens for each slice in your ring.

A slice token is a string matching the pattern ^[A-Za-z][A-Za-z0-9_=/]*$ (i.e. starting with an English letter and consisting of only alphanumeric ASCII characters and _=/). These tokens are used to distinguish slices from each other, and enable certain OPie functionality, including nested and embedded rings, quick actions, and ring customization; they are generally not shown to the player in-game. Provide a slice token for each slice by setting the sliceToken key on the table describing the slice, like so:

Example
OPie.CustomRings:AddDefaultRing("TrinketSlots", { {id="/use 13", sliceToken="MyAddonTrinkets13"}, {id="/use 14", sliceToken="MyAddonTrinkets14"}, name="Trinkets", })

Slice tokens you provide must be:

  1. Globally unique: you may not reuse the same token for multiple slices in a ring, nor use a token used by another ring.
    Consider prefixing slice tokens with a string based on your addon name and ring name; for example, OPie uses OP as a slice token prefix for its default rings, while AB is used as the prefix for player-created slices.
  2. Persistent: if there are no changes to the slice, its token should not change across reloads or ring updates. If slice content is updated, consider whether the changes are more akin to editing a macro already assigned to an action button (use the original token), or replacing that macro with something else (use a new token).

Older versions of OPie silently generate unique slice tokens for slices with missing or invalid tokens. However, this usually does not produce persistent tokens, and causes some OPie functionality to not work as expected.

Timeline

  1. On July 1, 2023, OPie will begin showing a warning message (as an error message without affecting functionality or control flow) when rings are created with missing or invalid slice tokens. The fraction of users being shown the warning will gradually increase until it reaches all users with such rings two weeks later.
  2. On August 15, 2023, OPie will begin throwing a Lua error when rings are created with missing or invalid slice tokens, preventing those rings from functioning. The fraction of users encountering errors will gradually increase until it reaches all users with such rings two weeks later.
  3. After August 29, 2023, OPie will always throw an error when rings are created with missing or invalid slice tokens.

Early warning for developers

When using OPie version Yuzu 9+2.0 or later, you can set the global DEV_EARLY_WARNING variable to a truthy value prior to calling OPie.CustomRings functions to check for deprecation warnings prior to July 15, 2023.

Please AVOID RELEASING code that sets DEV_EARLY_WARNING without explicit user consent.