[1.21.x] Topologically sort reload listeners based on dependency ordering

[Shadows-of-Fire]

Overview

This PR introduces dependency sorting for both client and server reload listeners. The sort is topological, using FML's TopologicalSort class as the backbone. Reload listeners are added to a DAG where an edge from a->b means that a must run before b.

The sorting logic, and the modder-facing API, is in SortedReloadListenerEvent, the parent class of both AddReloadListenerEvent and AddClientReloadListenerEvent (formerly RegisterClientReloadListenersEvent).

Requirements

As a prerequisite, this change enforces that all reload listeners are named. The name must be provided via SortedReloadListenerEvent#addListener at the time of registration. Vanilla listeners are preemptively named, via VanillaClientListeners and VanillaServerListeners, which hold the class->RL maps for all known vanilla listener types.

Note: Mods that are currently using mixins or other non-event means to inject reload listeners will crash after this change.

Sorting

Each SortedReloadListenerEvent maintains a Graph<PreparableReloadListener> which holds the directed edges that dictate the dependency information. An edge from a->b means that a must run before b. New edges are added to the graph via #addDependency(first, second), which creates a new edge from first->second.

When the vanilla listeners are added in the event's constructor, edges are added such that each vanilla listener depends on the previous one in-order. This guarantees that the vanilla order is maintained without relying on implicit behavior from the toposort.

Finally, after the event has concluded, but before the sort, a search is performed to find dangling nodes and attach them to the last vanilla node, such that all mod-added listeners run after vanilla if they do not otherwise specify dependency ordering.

Error Handling

A dependency cycle in the toposort is an unrecoverable error and will cause the game to crash. If any cycles are detected, an IllegalArgumentException will be thrown containing a string representation of the cycle(s).

For example:

java.lang.IllegalArgumentException: Cycles were detected during reload listener sorting:
0: neoforge:branding->neoforge:client_mod_loading->minecraft:language_manager->neoforge:branding

Notes

This PR supersedes #1289.

[neoforged-pr-publishing]

• Publish PR to GitHub Packages

Last commit published: 2601dc47a353d69a67627b17b8cba5638f481e6d.

PR Publishing

The artifacts published by this PR:

• 📦 net.neoforged:neoforge:21.4.89-beta-pr-1915-listener-sort
• 📦 net.neoforged:testframework:21.4.89-beta-pr-1915-listener-sort

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 #1915' // https://github.com/neoforged/NeoForge/pull/1915
        url 'https://prmaven.neoforged.net/NeoForge/pr1915'
        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-pr1915.
On Powershell you will need to remove the -L flag from the curl invocation.

mkdir NeoForge-pr1915
cd NeoForge-pr1915
curl -L https://prmaven.neoforged.net/NeoForge/pr1915/net/neoforged/neoforge/21.4.89-beta-pr-1915-listener-sort/mdk-pr1915.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.

[neoforged-compatibility-checks]

@Shadows-of-Fire, this PR introduces breaking changes.
Fortunately, this project is currently accepting breaking changes, but if they are not intentional, please revert them.
Last checked commit: 2601dc47a353d69a67627b17b8cba5638f481e6d.

neoforge (:neoforge)

• net/neoforged/neoforge/event/AddReloadListenerEvent
  • getListeners()Ljava/util/List;: ❗ API method was removed
  • addListener(Lnet/minecraft/server/packs/resources/PreparableReloadListener;)V: ❗ API method was removed
• net/neoforged/neoforge/common/NeoForgeEventHandler
  • resourceReloadListeners(Lnet/neoforged/neoforge/event/AddReloadListenerEvent;)V: ⚠ API method was removed
• net/neoforged/neoforge/client/event/RegisterClientReloadListenersEvent
  • ❗ API class no longer exists
• net/minecraft/server/packs/resources/ReloadableResourceManager
  • registerReloadListenerIfNotPresent(Lnet/minecraft/server/packs/resources/PreparableReloadListener;)V: ❗ API method was removed