[Branding Patch] API V2

[SpaceWalkerRS]

This issue serves as a discussion post for coming up with a new spec for the Branding Patch API, its scope, what features it should have, and implementing it into a V2 for the API.

API V1

The current API allows modifying branding information in two branding contexts: the title screen and the debug overlay. These are the contexts in which Minecraft itself modifies branding information in 16w05b and above.

What is considered branding information is the string that displays the Minecraft name and version, e.g. "Minecraft 16w05a". What is considered modifying branding information is either replacing (part(s) of) the existing string, or adding (a) new part(s) before or after the existing string.

Mods can register modifier components to one or multiple contexts. All components that are registered to a context are sorted and combined into one branding modifier that is applied to the branding information in that context. Applying a branding modifier means applying each of its constituent components in order, passing the result of each component to the next.

A modifier component exists of five parts:

• a key - a string that uniquely identifies the component
• a operation - this defines the way in which the component modifies the branding information
• a value - any string this component adds to the branding information
• a priority - priority with which this component is sorted into the branding modifier
• whether it is required - some operations must be unique within a branding modifier, and if multiple required components use one of those operations, an exception is thrown since the branding modifier cannot be constructed

There are four operations to choose from:

• prepend - insert a string at the start of the branding information
• append - insert a string at the end of the branding information
• replace - replace the original branding information (i.e. the branding information before any components have been applied with a new string
• set - set the entire branding information to a new string

Issues

• No support for localized information.
• No support for conditional components, like components that can be toggled through a setting, components that only apply on a Tuesday, or components that behave differently if the player is a half a heart of health, etc.
• No support for adding new lines.
• No support for components that depend on other components.
• No support for targeting specific components as opposed to the entire string.

API V2

this section will be updated once an initial draft is made, and then tweaked further until a final spec is agreed upon

[SpaceWalkerRS]

Firstly we should discuss the scope of the API. Listed below are several features and whether they are in scope. Each of these features can be discussed before they are moved into definitely in scope or definitely not in scope.

Since the patch emulates a Vanilla feature in 16w05b and above, there are a few minimal requirements:

• Modifying branding information in two locations: the title screen and the debug overlay.
• Appending the content of the --versionType program argument to the branding information.

The API aims to expand this to allow mods add their own branding information.

Definitely in scope:

• Appending or prepending strings registered by mods.

Probably in scope:

• Support for localized strings by passing in translation keys that are resolved when the branding modifier is applied.
• Support for conditional components. Each time the branding modifier is applied, each of its components is only applied if that component's condition evaluates to true.
• Support for multiple lines in the title screen.

Maybe in scope:

• Components that depend on other components.
• Components that target and modify other components.

Probably not in scope:

• Adding dynamic information (think of, displaying the current time, or the player's current health).
• Formatted strings, like colored text, bold text, obfuscated text, etc.

Definitely not in scope:

• Displaying branding information in new locations.
• Moving where branding information is displayed in existing locations.
• Overhauling the look of the title screen and/or debug overlay.
• Adding anything other than text to the branding information.

[SpaceWalkerRS]

In versions before 1.0, branding information is also display in the regular in-game GUI overlay (i.e. in-game but when the debug overlay is not enabled), that could also be covered.

Perhaps the window title could be covered too?