Gear Registration

GearRegistry tells Masterwork what to do with a mod’s own items; VariantRegistry (with VariantTransformer and SalvageTransformer) edits every graded item and salvage recipe Masterwork mints, in bulk; ItemResyncStep keeps a mod’s own item instances in line through Masterwork’s resync sweep. Reached through MasterworkApi.gear(), MasterworkApi.variants() and MasterworkApi.registerItemResync().

1. Why this exists
2. GearRegistry
3. VariantRegistry, VariantTransformer, SalvageTransformer
   1. Contract both hooks share
4. ItemResyncStep

Why this exists

Masterwork decides what is gradeable by reading an item’s own stat blocks: a weapon has a Weapon block, armor an Armor block, and so on. That inference is right for everything the base game ships, but it is still an inference, and a modded item built in an unusual shape can be missed, mis-typed, or graded when its author never wanted it to be. GearRegistry is the recourse.

GearRegistry

MasterworkApi.get().gear()
    .register("YourMod", "Weapon_Spear_Bronze", GearCategory.WEAPON);

source is the registering mod’s own name, used in the boot log and to answer “who registered this item?” later, on a server that might be running dozens of mods.

One hard limit: a stackable item (MaxStack > 1) can never be graded, registered or not. A grade and a crafter stamp live in per-instance metadata, and stacking would merge that metadata away.

The server owner’s own blacklist in masterwork-config.json is evaluated separately from registration and always wins: blacklisting a registered item degrades it to the plain base exactly as it would any vanilla item.

Register from the depending plugin’s own setup(), or from a LoadAssetEvent listener at a priority below PRIORITY_LOAD_LATE (64). The registry freezes the moment the boot injection mints the graded variants; a call made after that point is refused with a logged warning, since the variants for that item would already not exist.

VariantRegistry, VariantTransformer, SalvageTransformer

GearRegistry says what an item is. VariantRegistry is the bulk counterpart: a hook that sees, and can rewrite, every graded item Masterwork mints, and every salvage recipe it mints alongside them, the way a mod changes gear in bulk instead of shipping a pack override per item.

MasterworkApi api = MasterworkApi.get();

api.variants()
    .register("YourMod", (context, variant) -> {
        Grade tier = api.gear().gradeOf(context.variantId());

        if (tier.qualityValue() >= Grade.EXQUISITE.qualityValue()) {
            variant.put("YourMod.SalvageBonus", new BsonString("Ingredient_Forge_Essence"));
        }

        return variant;
    });

Masterwork builds a variant by encoding the resolved base item to a BsonDocument, patching it (quality, durability, the stat families), and decoding it back under the new id. A VariantTransformer is invoked at the last moment of that round trip: after Masterwork’s own patches, before the decode. So it sees the finished document, scaled numbers included, and can change anything the item’s JSON can express. SalvageTransformer is the same shape over the cloned salvage recipe Masterwork mints for each tier (input re-pointed at the variant id, outputs still the base’s), called only for the tiers Masterwork mints a recipe for at all.

VariantContext, passed to both, describes what is being minted:

Gear that toggles between states while held (a throw stance, an area-break mode) carries them under State in the variant’s document, one entry per state holding only what that state restates. A VariantTransformer edit that must survive the toggle has to be applied to each of those entries as well as to the top level.

Contract both hooks share

• Return the document to continue with. Editing it in place and returning it is the normal shape; returning a different instance is equally fine.
• Transformers chain in registration order, each seeing the previous one’s output, so two mods editing the same key resolve last writer wins, in plugin load order.
• A throw is contained, logged against the offending mod’s name, and the variant continues from the document as it stood before that call. One bad transformer must not cost the server its other roughly 2,600 variants.
• A null return is treated as no change, and warned about once per source rather than per item.
• Called a lot: roughly gradeable items times seven (one call per tier). Filter on VariantContext first and return immediately when a variant is not yours to touch.
• Whatever is written must survive a decode. The document is handed to the engine’s own item or recipe codec next; a malformed value fails that build, and the variant (or recipe) is skipped and counted in the boot log.

Called only for the graded variants, the base tier rewrite and the neutral placeholders included; never for the crafting hammers or the injected qualities, which are Masterwork’s own assets rather than transformations of the game’s.

Register during setup(), like GearRegistry: this registry freezes at the same boot injection point, for the same reason.

ItemResyncStep

Some of what an item instance carries is derived from something else on it and does not follow on its own: a display name baked from a metadata key, a description composed from a setting. A stack handed over by /give --metadata= carries the key and nothing derived from it; a stack minted before a key was renamed carries the old shape. Masterwork repairs its own crafter stamp and grade data with the item resync sweep, which runs when a player joins, when an inventory changes, when a container is opened, and on /masterwork item resync. registerItemResync lets a mod add one step of its own to that same sweep, for its own items, instead of building a second sweep with the same triggers:

api.registerItemResync("YourMod", stack -> {
    if (!"YourMod_Charm".equals(stack.getItemId())) {
        return null;
    }

    Integer charge = stack.getFromMetadataOrNull("YourMod.Charge", Codec.INTEGER);

    if (charge == null) {
        return null;
    }

    Message name = Message.translation("server.items.YourMod_Charm.charged").param("n", charge);

    return stack.withMetadata(ItemDisplayMetadata.KEYED_CODEC, new ItemDisplayMetadata(name, null));
});

The step is offered every stack the sweep reaches, after Masterwork’s own repairs on that stack, in registration order, and its contract is short:

• Return null for a stack that needs nothing, which is nearly every stack in the world. A returned stack is written back into its slot, and a write is itself an inventory change that runs the sweep again, so a step that always returns a stack never settles.
• Be cheap on the way out. The step sees every stick and stone a player carries or handles. Ask the item id first, a keyed metadata read second, and never clone the whole document before either has said yes.
• Touch only your own items. A metadata key changes what a stack stacks with, and a foreign item you stamped stops matching the template an interaction spends it against. Masterwork holds itself to the same rule.
• Do not throw. A step that throws once is switched off for the rest of the run with one logged warning naming its source, so a bug in one mod cannot take the sweep down for everyone.

Unlike the two registries above, this never closes: the sweep runs for the server’s whole life and a step joins it the moment it is registered. Register from setup() all the same, so the first join is swept with it. Since 1.3.0.