Game Entry Dictionaries

[TheLMiffy1111]

Summary

Add a game entry dictionary system to supersede the ore dictionary, and adding support for other game entries.

Goals

• Replacement of the Ore Dictionary
• Compatibility with existing Ore Dictionary methods
• Dictionary support for all game entries

Non Goals

• Data-driven dictionaries
• A backport of tags
• Immutability

Motivation

• The Ore Dictionary uses some questionable components.
• The Ore Dictionary only supports item stacks.

Description

The Ore Dictionary uses an Ore Name ↔ Incremental ID ↔ ItemStack system, and uses a total of five collections to store data:

• List<String> idToName: List that maps IDs to Ore Names.
• Map<String, Integer> nameToId: Map that reverse maps Ore Names to IDs.
• List<NonNullList<ItemStack>> idToStack: List that maps IDs to ItemStacks.
• List<NonNullList<ItemStack>> idToStackUn: List identical to idToStack.
• Map<Integer, List<Integer>> stackToId: Map that reverse maps ItemStack hashes to IDs.

In addition to only supporting ItemStacks, we can see some additional problems in this implementation:

1. Use of Integer instead of specialized collections, which may cause excessive boxing/unboxing.
2. There is a redundant list.
3. The method used to calculate ItemStack hashes may become a problem with item id range extensions.

Also, the method getOres(String) by default creates a new Ore Dictionary entry, which is usually unwanted and has cause many confusions.

Although an Ore Dictionary replacement could be so that it is directly a Name → Entry system, to allow compatibility with all Ore Dictionary methods, we would still need a Name ↔ Incremental ID ↔ Entry system.
Therefore, we propose a new generic GameEntryDictionary class that reimplements all of Ore Dictionary using fastutil and maintains such a system:

public class GameEntryDictionary<T> {
    private List<String> idToName = new ObjectArrayList<>();
    private Object2IntMap<String> nameToId = new Object2IntOpenHashMap<>();
    private List<List<T>> idToEntries = new ObjectArrayList<>();
    private Map<T, IntSet> entryToIds = new Object2ReferenceOpenHashMap<>();

    public int getOrCreateID(String name) {
        if (nameToId.contains(name)) {
            return nameToId.getInt(name);
        }
        int id = idToName.size();
        idToName.add(name);
        nameToId.put(name, id);
        idToEntries.add(new ObjectArrayList<>());
        return id;
    }

    public String getName(int id) {
        return (id >= 0 && id < idToName.size()) ? idToName.get(id) : "";
    }

    public IntList getIDs(T entry) {
        return entryToIds.contains(entry) ? IntLists.unmodifiable(entryToIds.get(entry)) : IntList.of();
    }

    public List<T> getOrCreateEntries(String name) {
        return getEntries(getOrCreateID(name));
    }

    public List<T> getEntries(String name) {
        return nameToId.contains(name) ? Collections.unmodifiableList(idToEntries.get(nameToId.getInt(name))) : List.of();
    }

    public List<T> getEntries(int id) {
        return (id >= 0 && id < idToEntries.size()) ? idToEntries.get(id) : List.of();
    }

    public boolean contains(String name) {
        return nameToId.contains(name);
    }

    public List<String> getNames() {
        return Collections.unmodifiableList(idToName);
    }

    public Set<String> getNames(T entry) {
        return entryToIds.contains(entry) ? entryToIds.get(entry).intStream().map(this::getName).collect(Collectors.toSet()) : Set.of();
    }

    public void register(String name, T entry) {
        int id = getOrCreateID(name);
        IntSet ids = entryToIds.get(entry);
        if (ids != null && ids.contains(oreID)) {
            return;
        }
        if (ids == null) {
            ids = new IntArraySet<>();
            entryToIds.put(entry, ids);
        }
        ids.add(id);
        idToEntries.get(id).add(entry);
        MinecraftForge.EVENT_BUS.post(new GameEntryRegisterEvent(this, name, entry));
    }

    public void unregister(String name, T entry) {
        if (!nameToId.contains(name) || !entryToIds.contains(entry)) {
            return;
        }
        int id = nameToId.get(name);
        entryToIds.get(entry).remove(id);
        idToEntries.get(id).remove(entry);
    }
}

The Ore Dictionary can then be easily reimplemented by wrapping an Item/ItemStack dictionary.

For types, we should provide the following dictionaries, possibly in a GameEntryDictionaries class:

• Item/ItemStack
• Fluid/FluidStack
• Block/BlockState

To, again, maintain compatibility, we need to somehow handle Ore Dictionary wildcards. This can be done with one of two methods, wrapping new dictionaries in OreDictionary:

• Use a dictionary of Either<Item, ObjectIntPair<Item>>.
• Use a dictionary of a new ItemVariant class.
• Use two dictionaries.

Edit: Entries in dictionaries are ideally immutable and effectively keyable.

Dependencies

• Depending on the implementation, this proposal may require an Either class, which might also be provided by a Serde/Codec implementation.

References

• None

Guidelines

• I have and will continue to adhere to the guidelines

[Rongmario]

Initial thoughts

1. I like keeping the Dictionary term around, just Dictionary could be fine, Game Entry could be quite redundant.

2. I don't see the reason of keeping numerical IDs around, modders shouldn't have cached any of these intermediate values, though it is possible to generate unique IDs on-the-fly in case modders do compare IDs in matches, contains contexts or sending them via packets. But this should be deprecated behaviour.

3. Personally, a desired format would be something bi-directional:

• 1 Dictionary <= 1 Entry (e.g. ItemStackDictionary for ItemStack entries)
• Every Dictionary contains a BiDirectionalMapping<Word, Entry>
• 1 Word => multiple Entry (e.g. plankWood for all wooden plank types)
• 1 Entry => multiple Word (e.g. 1x Lapis Lazuli ItemStack has gemLapis & dyeBlue, multiple Word means the Entry will be deduplicated by default)
• Every Entry points to their corresponding Object or Game Entry mentioned in OP, retrieving said Object should return a defensive copy.
• Using this system can solve ItemStack equality issues, by registering an ItemStack as different types of Entry, they can pick a mix of information to check equals on:
  • Item
  • Damage
  • Size
  • NBT
    • Exact (Tag / Keys)
    • Partial (Tag / Keys)

[TheLMiffy1111]

From a simple GitHub search, it seems that numerical ore IDs were mainly used to check if ItemStacks had certain ore names, as Forge didn't directly provide this functionality, and ItemStacks aren't equality testable.

I think that dictionary entries should ideally be immutable and effectively keyable, so we mostly wouldn't need to worry about copying entries unless we do want to include NBT (which I think isn't needed really).