Stages of Modloading

From Forge Community Wiki

The FML mod loading process is broken into several stages, with each stage having associated events fired alongside with it on the mod-specific event bus. These events are known as the mod lifecycle events, as they are fired during the different phases of a mod's life.

The different mod loading stages are represented each by a value in the enum class net.minecraftforge.fml.ModLoadingStage. Their states are split between the net.minecraftforge.fml.core.ModStateProvider for mod states (construct, common setup, etc.) and net.minecraftforge.fmllegacy.ForgeStatesProvider for forge injected states (creating registries, injecting capabilities, etc.) Most of the mod lifecycle events are stored in the net.minecraftforge.fml.event.lifecycle package.

Parallelism

The mod loading system is parallelized to some extent. While all of the stages are changed at the same time across all mods, most of the events are fired in parallel to each mod. That is, all mods will concurrently receive the event, then FML will wait until all mods have processed the event before moving to the next stage and firing the next event. These concurrently dispatched events are distinguished by them extending ParallelDispatchEvent.

This does means that in these parallel mod lifecycle events, care must be taken to be thread-safe, like when calling external methods which are backed by non-thread-safe collections. Most of the systems in Forge are protected for this; however, vanilla systems and external mods' APIs may not be thread-safe. FML provides a way for mods to defer tasks/work until the event is finished dispatching, where it will be run sequentially along with other events on the main thread. This is done with the #enqueueWork method, which is a member of all events which extend ParallelDispatchEvent.

Common Transition Stages and Events

Name Enum Constant Lifecycle Event Parallel? Description
Construction CONSTRUCT FMLConstructModEvent Yes Fired when the mod's constructor has been called. Can be used to initialize listeners outside of the constructor. There is usually no reason to use this event, as any code should be placed in the mod constructor instead.
Registry Creation CREATE_REGISTRIES NewRegistryEvent No Fired for mods to create and initialize their custom registries.
Registry Population LOAD_REGISTRIES RegisterEvent No Fired when a registry is open to registrations for any registrable objects, such as blocks, items, etc.
Config Loading CONFIG_LOAD ModConfigEvent$Loading No Loads config files associated with registered mod configs. Before this stage, mod config values only return their default values unless manually loaded earlier.
Common Setup COMMON_SETUP FMLCommonSetupEvent Yes Used for doing any work or action that should be run on both physical sides.
Sided Setup SIDED_SETUP FMLClientSetupEvent for physical client, FMLDedicatedServerSetupEvent for physical server Yes Used for doing any physical side-specific initialization work.
IMC Enqueue ENQUEUE_IMC InterModEnqueueEvent Yes Fired for mods to enqueue messages for other mods using the InterModComms system.
IMC Processing PROCESS_IMC InterModProcessEvent Yes Fired for mods to process messages from other mods sent using the InterModComms system in the previous stage.
Loading Complete COMPLETE FMLLoadCompleteEvent Yes Fired when mod loading is complete, before handing control back to the main game. There is usually no reason to use this event, as most actions can be done during the Common or Sided Setup stages.