Upgrade Core

Upgrade Core is a developer library for registering upgrade definitions, querying a shared catalog, and storing persistent ownership and activation for players or item models. It does not add upgrades or acquisition mechanics by itself.

Developer API

Register content with UpgradeApi.Register(...), discover it through UpgradeApi.Catalog, and grant or query it through UpgradeApi.State. Upgrade providers remain responsible for implementing their gameplay behavior; gacha, shop, achievement, and event mods only decide when registered upgrades are granted.

UpgradeApi.Register(new UpgradeDefinition(
    id: "YourTeam.YourMod/double-jump",
    displayName: "Double Jump",
    scope: UpgradeScope.Player,
    iconPng: iconBytes,
    badgeColor: Color.cyan,
    acquisitionTags: new[] { "shop", "achievement" }));

UpgradeTarget target = UpgradeTarget.ForPlayer(player);
UpgradeApi.State.Grant(target, "YourTeam.YourMod/double-jump");

if (UpgradeApi.State.IsEnabled(target, "YourTeam.YourMod/double-jump"))
{
    // The provider applies its own gameplay behavior here.
}

Acquisition mods can discover compatible content without referencing its provider assembly:

IEnumerable<UpgradeDefinition> shopPool =
    UpgradeApi.Catalog.CompatibleWith(target, "shop");

Use globally unique, permanent IDs in Team.Mod/upgrade-name form. Catalog order is not a network identity; synchronize the string ID or maintain a deterministic provider-owned mapping.

The initial API supports player-wide and item-model upgrades. Reapplying ownership is idempotent, and enabled state is stored independently from ownership. Ownership is deliberately local in 0.1.0: a multiplayer acquisition mechanic must validate the reward authoritatively and invoke Grant(...) on the owning client. Upgrade Core does not yet define a trust model for purchases or achievements.

AI Disclosure

This mod was developed with assistance from generative AI for programming, documentation, and promotional artwork. The author reviewed, tested, and approved the final implementation and assets.