Item updater

[Huskydog9988]

Reopening #754 in preparation of custom item rework

[okx-code]

How is this class initialised?

[Huskydog9988]

Its really weird. The class is meant to be extended, by a migrator for an item, which then calls

Civ/plugins/civmodcore-paper/src/main/java/vg/civcraft/mc/civmodcore/inventory/items/custom/CustomItemsUpdater.java

Line 123 in d101628

public static <T extends CustomItemsUpdater> @NotNull T init(

itself, or something similar to that.

[Protonull]

Yup. Give #754 a read through. It started off as a really simple predicate-with-side-effects: it takes an item and returns a boolean of whether the item was modified or not. You'd do all your checks within that predicate, returning early wherever possible.

Then I added event handler classes which handle specific events and updating their respective items. For example, UpdatePlayerItemsOnJoin listens for player joins and then invokes the predicate for each item in the player's inventory and ender chest. UpdateInventoryItemsOnOpen listens for players opening chests (and other contains), updating its items. UpdateContainerItemsOnLoad listens for chunk loads and updates all the items in its container blocks.

package uk.protonull.civ.example;

import org.bukkit.inventory.ItemStack;
import org.jetbrains.annotations.NotNull;
import vg.civcraft.mc.civmodcore.ACivMod;
import vg.civcraft.mc.civmodcore.inventory.items.updater.listeners.UpdatePlayerItemsOnJoin;

public final class ExamplePlugin extends ACivMod {
    @Override
    public void onEnable() {
        super.onEnable();
        registerListener(new ItemUpdateListener());
    }

    private static final class ItemUpdateListener implements UpdatePlayerItemsOnJoin /** , UpdateInventoryItemsOnOpen */ {
        @Override
        public void updateItem(final @NotNull ItemStack item) {
            // if (item.needsUpdating()) {
            //     item.updateSomehow();
            // }
        }
    }
}

If you wanted your item-updater to run whenever a chest was opened, all you needed to do was uncomment that implements part. All the work was done for you.

However, Okx wanted more of a DataFixer-esque system. Take a look at net.minecraft.util.datafix.DataFixers for what that looks like. As mentioned here: instead of entirely replacing what was already built, I instead created the CustomItemUpdater as a layer of abstraction on-top of it. This meant there was a simpler system if you wanted it, and a complexer system if you needed it.

However, I do admit that the type shenanigans were a mistake. It seemed clever at the time but it's definitely a struggle to read, even for me now and I wrote it. Basically, since UpdatePlayerItemsOnJoin extends ItemUpdater but does not implement it, you can effectively combine/union them with an implementation of ItemUpdater via casting, eg:

package uk.protonull.civ.example;

import org.bukkit.inventory.ItemStack;
import org.jetbrains.annotations.NotNull;
import vg.civcraft.mc.civmodcore.ACivMod;
import vg.civcraft.mc.civmodcore.inventory.items.updater.listeners.UpdatePlayerItemsOnJoin;

public final class ExamplePlugin extends ACivMod {
    @Override
    public void onEnable() {
        super.onEnable();
        registerListener((UpdatePlayerItemsOnJoin) ExamplePlugin::updateItem);
    }

    private static void updateItem(final @NotNull ItemStack item) {
        // if (item.needsUpdating()) {
        //     item.updateSomehow();
        // }
    }
}

[okx-code]

is a first migration necessary?

[Huskydog9988]

My understanding that items like fossils are registered custom items, so they would need a migration like this to be put into the system essentially. The problem is I have no idea how they are targeted by a migration if they lack a custom item key. IIRC the migration code just looks for items with a custom item key?

[Protonull]

There are two purposes to the item updater system:

1. Provide a means to update legacy custom items (those that are "custom" by virtue of having names and/or lore) to be registered custom items.

2. Provide a means to update registered custom items through migrations.

The 0th migration just ensures that EVERY registered custom item has both a custom-item key and migration version, as stated explicitly in the comments. It establishes a baseline of what data can be accessed from the item without concern for NPEs. It also prevents stacking issues where one person's item has an explicit 0th migration-version set, and another whose 0th migration-version is implied by its absence (related: null != emptyList()).

The 0th migration is not strictly necessary but it does offer a benefit, "speculative" as that may be. That said, I maintain that the vast majority of this migration system would be utterly unnecessary if Okx simply agreed to permit ephemeral display data (ie, setting names and lore to items at network-time): this whole migration system exists to fix typos in lore, or to remove outdated parts of lore, etc. It's silly.

[Huskydog9988]

To clean up the api, and make the usage clearer, I made a demo implementation Huskydog9988#1