Add some QoL APIs to ModelData

[embeddedt]

This PR adds some general quality-of-life improvements to ModelData, not targeting a specific use case. I also added some basic javadoc, might be redundant but no real harm in having it there.

• getOrDefault was added as a companion to get. The semantics are the same as Map#getOrDefault.
• Implement equals(), to allow determining if two model data objects contain the same properties & values.
  • The backing maps are now Reference2Object, rather than Reference2Reference, to make sure equality of the contained values is checked by equals() rather than ==. The keys still use identity equality, which is what matters for the hot path.
  • It does not matter if two ModelData objects use distinct backing map implementations with the same contents, as the Map#equals contract is defined to work across distinct implementations. (Also, in our case it's impossible, because we explicitly use array maps for one size range and hash maps for the rest).
• Implement hashCode(), to fulfill the contract having also implemented equals(). As a side effect this allows using ModelData as a key in a hashmap if desired.

[neoforged-pr-publishing[bot]]

• [x] Publish PR to GitHub Packages

Last commit published: bfa1b198301e6973ebc2b2c9228e4d05cfde7ed2.

PR Publishing

The artifacts published by this PR:

• :package: net.neoforged:neoforge:20.5.22-beta-pr-884-model-data-object-qol
• :package: net.neoforged:testframework:20.5.22-beta-pr-884-model-data-object-qol

Repository Declaration

In order to use the artifacts published by the PR, add the following repository to your buildscript:

repositories {
    maven {
        name 'Maven for PR #884' // https://github.com/neoforged/NeoForge/pull/884
        url 'https://prmaven.neoforged.net/NeoForge/pr884'
        content {
            includeModule('net.neoforged', 'neoforge')
            includeModule('net.neoforged', 'testframework')
        }
    }
}

MDK installation

In order to setup a MDK using the latest PR version, run the following commands in a terminal.
The script works on both *nix and Windows as long as you have the JDK bin folder on the path.
The script will clone the MDK in a folder named NeoForge-pr884.
On Powershell you will need to remove the -L flag from the curl invocation.

mkdir NeoForge-pr884
cd NeoForge-pr884
curl -L https://prmaven.neoforged.net/NeoForge/pr884/net/neoforged/neoforge/20.5.22-beta-pr-884-model-data-object-qol/mdk-pr884.zip -o mdk.zip
jar xf mdk.zip
rm mdk.zip || del mdk.zip

To test a production environment, you can download the installer from here.

[Technici4n]

I am pretty sure that one should never use foreign ModelData as a map key. What is the reasoning here?

[embeddedt]

You can't implement equals and not implement hashCode, because then you could have a.equals(b) while a.hashCode() != b.hashCode().

[Technici4n]

Why should we implement either one?

[embeddedt]

ModelData is a thin wrapper around the backing map; I think there are valid use cases where a mod might want to compare model datas and only perform certain logic if they are the same. Not every model data has "complex" properties.

For instance (something I came up with just now): a worker thread passing back a more populated model data object to a block entity to use for future remeshes, but only if the BE hasn't changed the base properties in that model data since the snapshot. With equals implemented this can be done trivially by comparing the originally provided model data with the one currently on the BE. The same thing can be done without equals but it just means the mod has to reimplement the exact same logic itself (or rely on reference equality only).

[Technici4n]

My problem would be the misuse potential. It can only be useful in cases where you are fully in control of the model data, but could easily set the wrong expectations.