Forge Community Wiki - User contributions [en-gb]

Getting Started

2021-11-30T07:21:35Z

Paint Ninja: Modern Windows uses PowerShell by default which is same syntax as Linux for running local commands

'''Minecraft Forge''' is a modding framework, designed to allow different mods to load and work together to be compatible. Through the years, there has been many changes in the Forge tooling to make working with mods as seamless as possible. It is now easier than ever to start making your own mod.

== The Mod Development Kit ==
The '''Mod Development Kit''' or '''MDK''' is a downloadable archive that contains the basic skeleton for starting a new mod. It contains the following files and folders:

{{Tree list}}
* '''The Mod Development Kit'''
** <code>gradle/wrapper/</code> - The folder containing the [https://docs.gradle.org/7.2/userguide/gradle_wrapper.html Gradle wrapper]'', Forge uses Version '''7.2'''''
** <code>src</code> - The sources folder
*** <code>main</code> - The <code>main</code> source set
**** <code>java</code> - The java sources for the <code>main</code> source set
***** ...
**** <code>resources</code> - The resources for the <code>main</code> source set
***** <code>META-INF</code> - The folder for '''meta'''data '''inf'''ormation files<ref>[https://stackoverflow.com/a/6075320/14416954 StackOverflow answer]: ''... Basically, if it was stored in META-INF, it was Meta-data Information...''</ref>
****** <code>mods.toml</code> - The [[Mods.toml file|<tt>mods.toml</tt> file]], where mods are declared
***** <code>pack.mcmeta</code> - File used by Minecraft to [[mc:Data Pack#pack.mcmeta|identify data and resource packs]]
** <code>.gitattributes</code> - Used by [[wikipedia:Git|Git]] for specifying attributes for files<ref>[https://git-scm.com/docs/gitattributes Official git documentation on <tt>.gitattributes</tt>]</ref>
** <code>.gitignore</code> - Used by Git for specifying intentionally untracked/ignored files<ref>[https://git-scm.com/docs/gitignore Official git documentation on <tt>.gitignore</tt>]</ref>
** <code>build.gradle</code> - The Gradle buildscript, which defines the project and tasks<ref>[https://docs.gradle.org/7.2/userguide/tutorial_using_tasks.html Gradle User Guide for 7.2: ''Build Script Basics'']</ref>
** <code>changelog.txt</code> - The Forge version changelog
** <code>CREDITS.txt</code> - Forge's credits/''thank you'' file
** <code>gradle.properties</code> - The Gradle properties file, for defining additional variables and options<ref>[https://docs.gradle.org/7.2/userguide/build_environment.html#sec:gradle_configuration_properties Gradle User Guide for 7.2: ''Build Environment § Gradle properties'']</ref>
** <code>gradlew</code> - The *nix shell file for executing the Gradle wrapper
** <code>gradlew.bat</code> - The Windows batch file for executing the Gradle wrapper
** <code>LICENSE.txt</code> - File containing the licensing information for Forge and libraries
** <code>README.txt</code> - Readme file with the basic setup instructions
{{Tree list/end}}

== Basic MDK Setup ==
# Download the MDK from the [https://files.minecraftforge.net/ official Minecraft Forge download site] and extract the MDK into an empty folder.
# Open your IDE of choice, and import the project as a Gradle project.
#* For '''Eclipse''': <tt>File > Import > Gradle > Existing Gradle Project</tt>, select the folder for the <tt>Project root directory</tt>, click <tt>Finish</tt>
#* For '''IntelliJ IDEA''': <tt>File > Open</tt>, select and open the folder, select the <tt>build.gradle</tt> file, click <tt>OK</tt>, click <tt>Open as Project</tt>
#* For '''Visual Studio Code''': Run <code>./gradlew buildNeeded</code> and then <code>./gradlew eclipse</code>, then <tt>File > Open Folder...</tt> and select the folder
# Wait for the setup process to complete and the Minecraft sources are decompiled.
#* For '''Visual Studio Code''': This step can be skipped as it was already done in the previous step
# Generate the run configurations for your IDE using the appropriate Gradle task. <br>These tasks can be run in the terminal using <code>./gradlew gen***Runs</code>.
#* For '''Eclipse''': the task is <code>genEclipseRuns</code>; to run in the IDE directly, open the <tt>Gradle Tasks</tt> tab on the bottom panel, ''wait until the tasks have loaded'' then expand the folder, expand the <tt>fg_runs</tt> folder, then double-click <tt>genEclipseRuns</tt>.
#* For '''IntelliJ IDEA''': the task is <code>genIntellijRuns</code>; to run in the IDE directly, open the <tt>Gradle</tt> on the right, expand the project folder, double-click <tt>Tasks > fg_runs > genIntellijRuns</tt>.
#* For '''Visual Studio Code''': the task is <code>genVSCodeRuns</code>; the [https://marketplace.visualstudio.com/items?itemName=vscjava.vscode-java-pack Extension Pack for Java] and [https://marketplace.visualstudio.com/items?itemName=vscjava.vscode-gradle Gradle for Java plugin] should both be installed for smoother integration.

{{Tip|The most popular IDEs used by Forge and mod developers are [https://www.eclipse.org/eclipseide/ Eclipse] and [https://www.jetbrains.com/idea/ IntelliJ IDEA]. While Visual Studio Code has a run generation task, because of its relative unpopularity as an IDE for Minecraft modding, the user will have to self-diagnose any issues that may arise from their use of it.}}

== Customizing the MDK ==
The MDK provides default values for the buildscript and <tt>mods.toml</tt> file. These values should be replaced with your own mod's information.

All edits should be done below the <code>apply plugin: 'net.minecraftforge.gradle'</code> line. The lines above it are required for the Forge MDK to work correctly, and should not be modified without proper knowledge.
* All references to <code>examplemod</code> in the buildscript should be replaced with your modid.
** Use your IDE's find-and-replace function to quickly replace these values.
** Pick a unique and memorable modid. The modid must be between 2 and 64 characters, and must consist of lowercase letters, numbers, underscores (<code>_</code>) and hyphens (<code>-</code>). The recommendation is to avoid using acronyms and abbreviations.
* Change the <code>archivesBaseName</code> variable to your modid. This is used as the base name for the JAR file when you build your mod, and as the <tt>artifactId</tt> of your mod's [https://maven.apache.org/pom.html#Maven_Coordinates maven coordinates].
* Change the <code>group</code> to your [[Proper Mod Structuring#Packaging|unique root java package]]. This is used as the <tt>groupId</tt> of your mod's maven coordinates.
* In the <code>jar</code> task, change the values of the <code>Specification-Vendor</code> and <code>Implementation-Vendor</code> keys to your username/brand name or other form of identification.
* ''Optional suggestion: '' Change the <code>version</code> variable to have a 0 as the major version (ex. <code>'0.1'</code>. This is to follow [[Semantic Versioning#During Development|semantic versioning guidelines]] for versions in active development.

== Building and Testing ==
You can test your mod in the development environment using either your IDE's run configurations and built-in debugging utilities, or by running the <code>run*</code> task as defined by the buildscript's run configurations.

There are three default run configurations with the MDK:
* <code>runClient</code>, for starting the client.
* <code>runServer</code>, for starting the dedicated server. ''You will need to accept the EULA through the <tt>eula.txt</tt> after running the server for the first time.''
* <code>runData</code>, for starting the client in [[Datageneration|data generation]] mode.

{{Tip|Always test your mod in both the client and the dedicated server, even if you are making a one-sided mod. Mods should not crash when running on both sides, and one-sided mods should not crash if they run on the wrong side.}}

You can build your mod's final JAR using the <code>build</code> task. The resulting JAR will be located in the <code>build/libs</code> folder under your project directory.

[[Category:Getting Started]]

[[Category:Beginner Topics]]

Getting Started

2021-11-30T07:19:15Z

Paint Ninja: Improved VS Code instructions

'''Minecraft Forge''' is a modding framework, designed to allow different mods to load and work together to be compatible. Through the years, there has been many changes in the Forge tooling to make working with mods as seamless as possible. It is now easier than ever to start making your own mod.

== The Mod Development Kit ==
The '''Mod Development Kit''' or '''MDK''' is a downloadable archive that contains the basic skeleton for starting a new mod. It contains the following files and folders:

{{Tree list}}
* '''The Mod Development Kit'''
** <code>gradle/wrapper/</code> - The folder containing the [https://docs.gradle.org/7.2/userguide/gradle_wrapper.html Gradle wrapper]'', Forge uses Version '''7.2'''''
** <code>src</code> - The sources folder
*** <code>main</code> - The <code>main</code> source set
**** <code>java</code> - The java sources for the <code>main</code> source set
***** ...
**** <code>resources</code> - The resources for the <code>main</code> source set
***** <code>META-INF</code> - The folder for '''meta'''data '''inf'''ormation files<ref>[https://stackoverflow.com/a/6075320/14416954 StackOverflow answer]: ''... Basically, if it was stored in META-INF, it was Meta-data Information...''</ref>
****** <code>mods.toml</code> - The [[Mods.toml file|<tt>mods.toml</tt> file]], where mods are declared
***** <code>pack.mcmeta</code> - File used by Minecraft to [[mc:Data Pack#pack.mcmeta|identify data and resource packs]]
** <code>.gitattributes</code> - Used by [[wikipedia:Git|Git]] for specifying attributes for files<ref>[https://git-scm.com/docs/gitattributes Official git documentation on <tt>.gitattributes</tt>]</ref>
** <code>.gitignore</code> - Used by Git for specifying intentionally untracked/ignored files<ref>[https://git-scm.com/docs/gitignore Official git documentation on <tt>.gitignore</tt>]</ref>
** <code>build.gradle</code> - The Gradle buildscript, which defines the project and tasks<ref>[https://docs.gradle.org/7.2/userguide/tutorial_using_tasks.html Gradle User Guide for 7.2: ''Build Script Basics'']</ref>
** <code>changelog.txt</code> - The Forge version changelog
** <code>CREDITS.txt</code> - Forge's credits/''thank you'' file
** <code>gradle.properties</code> - The Gradle properties file, for defining additional variables and options<ref>[https://docs.gradle.org/7.2/userguide/build_environment.html#sec:gradle_configuration_properties Gradle User Guide for 7.2: ''Build Environment § Gradle properties'']</ref>
** <code>gradlew</code> - The *nix shell file for executing the Gradle wrapper
** <code>gradlew.bat</code> - The Windows batch file for executing the Gradle wrapper
** <code>LICENSE.txt</code> - File containing the licensing information for Forge and libraries
** <code>README.txt</code> - Readme file with the basic setup instructions
{{Tree list/end}}

== Basic MDK Setup ==
# Download the MDK from the [https://files.minecraftforge.net/ official Minecraft Forge download site] and extract the MDK into an empty folder.
# Open your IDE of choice, and import the project as a Gradle project.
#* For '''Eclipse''': <tt>File > Import > Gradle > Existing Gradle Project</tt>, select the folder for the <tt>Project root directory</tt>, click <tt>Finish</tt>
#* For '''IntelliJ IDEA''': <tt>File > Open</tt>, select and open the folder, select the <tt>build.gradle</tt> file, click <tt>OK</tt>, click <tt>Open as Project</tt>
#* For '''Visual Studio Code''': Run <code>./gradlew buildNeeded</code> and then <code>./gradlew eclipse</code>, then <tt>File > Open Folder...</tt> and select the folder
# Wait for the setup process to complete and the Minecraft sources are decompiled.
#* For '''Visual Studio Code''': This step can be skipped as it was already done in the previous step
# Generate the run configurations for your IDE using the appropriate Gradle task. <br>These tasks can be run on the command line using ''(Windows)'' <code>gradlew gen***Runs</code> or ''(*nix)'' <code>./gradlew gen***Runs</code>.
#* For '''Eclipse''': the task is <code>genEclipseRuns</code>; to run in the IDE directly, open the <tt>Gradle Tasks</tt> tab on the bottom panel, ''wait until the tasks have loaded'' then expand the folder, expand the <tt>fg_runs</tt> folder, then double-click <tt>genEclipseRuns</tt>.
#* For '''IntelliJ IDEA''': the task is <code>genIntellijRuns</code>; to run in the IDE directly, open the <tt>Gradle</tt> on the right, expand the project folder, double-click <tt>Tasks > fg_runs > genIntellijRuns</tt>.
#* For '''Visual Studio Code''': the task is <code>genVSCodeRuns</code>; the [https://marketplace.visualstudio.com/items?itemName=vscjava.vscode-java-pack Extension Pack for Java] and [https://marketplace.visualstudio.com/items?itemName=vscjava.vscode-gradle Gradle for Java plugin] should both be installed for smoother integration.

{{Tip|The most popular IDEs used by Forge and mod developers are [https://www.eclipse.org/eclipseide/ Eclipse] and [https://www.jetbrains.com/idea/ IntelliJ IDEA]. While Visual Studio Code has a run generation task, because of its relative unpopularity as an IDE for Minecraft modding, the user will have to self-diagnose any issues that may arise from their use of it.}}

== Customizing the MDK ==
The MDK provides default values for the buildscript and <tt>mods.toml</tt> file. These values should be replaced with your own mod's information.

All edits should be done below the <code>apply plugin: 'net.minecraftforge.gradle'</code> line. The lines above it are required for the Forge MDK to work correctly, and should not be modified without proper knowledge.
* All references to <code>examplemod</code> in the buildscript should be replaced with your modid.
** Use your IDE's find-and-replace function to quickly replace these values.
** Pick a unique and memorable modid. The modid must be between 2 and 64 characters, and must consist of lowercase letters, numbers, underscores (<code>_</code>) and hyphens (<code>-</code>). The recommendation is to avoid using acronyms and abbreviations.
* Change the <code>archivesBaseName</code> variable to your modid. This is used as the base name for the JAR file when you build your mod, and as the <tt>artifactId</tt> of your mod's [https://maven.apache.org/pom.html#Maven_Coordinates maven coordinates].
* Change the <code>group</code> to your [[Proper Mod Structuring#Packaging|unique root java package]]. This is used as the <tt>groupId</tt> of your mod's maven coordinates.
* In the <code>jar</code> task, change the values of the <code>Specification-Vendor</code> and <code>Implementation-Vendor</code> keys to your username/brand name or other form of identification.
* ''Optional suggestion: '' Change the <code>version</code> variable to have a 0 as the major version (ex. <code>'0.1'</code>. This is to follow [[Semantic Versioning#During Development|semantic versioning guidelines]] for versions in active development.

== Building and Testing ==
You can test your mod in the development environment using either your IDE's run configurations and built-in debugging utilities, or by running the <code>run*</code> task as defined by the buildscript's run configurations.

There are three default run configurations with the MDK:
* <code>runClient</code>, for starting the client.
* <code>runServer</code>, for starting the dedicated server. ''You will need to accept the EULA through the <tt>eula.txt</tt> after running the server for the first time.''
* <code>runData</code>, for starting the client in [[Datageneration|data generation]] mode.

{{Tip|Always test your mod in both the client and the dedicated server, even if you are making a one-sided mod. Mods should not crash when running on both sides, and one-sided mods should not crash if they run on the wrong side.}}

You can build your mod's final JAR using the <code>build</code> task. The resulting JAR will be located in the <code>build/libs</code> folder under your project directory.

[[Category:Getting Started]]

[[Category:Beginner Topics]]

Tinted Textures

2021-11-17T16:56:43Z

Paint Ninja: Add Groovy language code examples

Many blocks and items in vanilla change their texture color depending on where they are, such as grass. Models support specifying “tint indices” on faces, which are integers that can then be handled by <code>BlockColor</code>s and <code>IItemColor</code>s. See the wiki for information on how tint indices are defined in vanilla models.

=== BlockColor / ItemColor ===
Both of these are single-method interfaces. <code>BlockColor</code> takes a <code>BlockState</code>, a (<code>nullable</code>) <code>BlockAndTintGetter</code>, and a (<code>nullable</code>) <code>BlockPos</code>. <code>ItemColor</code> takes an <code>ItemStack</code>. Both of them take a parameter <code>tintIndex</code>, which is the tint index of the face being colored. Both of them return an <code>int</code>, a color multiplier. This int is treated as four unsigned bytes, alpha, red, green, and blue, in that order, from most significant byte to least. For each pixel in the tinted face, the value of each color channel is <code><nowiki>(int)((float)base * multiplier / 255)</nowiki></code>, where <code>base</code> is the original value for the channel, and <code>multiplier</code> is the associated byte from the color multiplier. Note that blocks do not use the alpha channel. For example, the grass texture, untinted, looks white and gray. The <code>BlockColor</code> and <code>ItemColor</code> for grass return color multipliers with low red and blue components, but high alpha and green components, (at least in warm biomes) so when the multiplication is performed, the green is brought out and the red/blue diminished.

If an item inherits from the <code><nowiki>builtin/generated</nowiki></code> model, each layer (“layer0”, “layer1”, etc.) has a tint index corresponding to its layer index. For blocks, the “particle” layer is index 0.

=== Creating Color Handlers ===
<code>BlockColor</code>s need to be registered to the <code>BlockColors</code> instance of the game. <code>BlockColors</code> can be acquired through <code>ColorHandlerEvent$Block</code>, and an <code>BlockColor</code> can be registered by <code><nowiki>BlockColors#register</nowiki></code>. Note that this does not cause the <code>BlockItem</code> for the given block to be colored. <code>BlockItem</code> are items and need to colored with an <code>ItemColor</code>.
{{Template:Tabs/Code_Snippets
|java=public void registerBlockColors(final ColorHandlerEvent.Block event) {
event.getBlockColors().register(myBlockColor, coloredBlock1, coloredBlock2, ...);
}
|groovy=void registerBlockColors(final ColorHandlerEvent.Block event) {
event.blockColors.register(myBlockColor, coloredBlock1, coloredBlock2, ...);
}
|}}
<code>ItemColor</code>s need to be registered to the <code>ItemColors</code> instance of the game. <code>ItemColors</code> can be acquired through <code><nowiki>ColorHandlerEvent$Item</nowiki></code>, and an <code>ItemColor</code> can be registered by <code><nowiki>ItemColors#register</nowiki></code>. This method is overloaded to also take <code>Block</code>s, which simply registers the color handler for the item <code><nowiki>Block#asItem</nowiki></code> (i.e. the block’s <code>BlockItem</code>).
{{Template:Tabs/Code_Snippets
|java=public void registerItemColors(final ColorHandlerEvent.Item event) {
event.getItemColors().register(myItemColor, coloredItem1, coloredItem2, ...);
}
|groovy=void registerBlockColors(final ColorHandlerEvent.Item event) {
event.itemColors.register(myItemColor, coloredItem1, coloredItem2, ...);
}
|}}
This registration must be done client-side, in the initialization phase.

Registration

2021-11-17T16:37:59Z

Paint Ninja: Add a couple of Groovy language examples

{{Under construction}}

Registration is the process of making an object (such as an item or block) known to the game during runtime. If some objects are not registered, this could cause crashes even before the game is fully loaded or arbitrary behaviors such as bottlenecking mod compatibility for world generation.

Most objects that are known within the game are handled by a <code>Registry</code>. Each registry uniquely defines each object through a "registry name" via a [[Using Resources#ResourceLocation|ResourceLocation]]. This "registry name" can be accessed with its respective getter and setter: <code>#getRegistryName</code> and <code>#setRegistryName</code>. You can only set the "registry name" of a given object once; otherwise, an exception will be thrown.

{{Tip|In a global context, each object is universally unique through its <code>ResourceKey</code>: a concatenation of its registry's id and the object's registry name.}}

Due to the inconsistent ordering and registration process vanilla uses, Forge wraps most vanilla registries using <code>IForgeRegistry</code>. This guarantees that the loading order for these wrapped registries will be <code>Block</code>, <code>Item</code>, and then the rest of the wrapped registries in alphabetical order. All registries supported by Forge can be found within the <code>ForgeRegistries</code> class. Since all registry names are unique to a specific registry, different registry objects within different registries can have the same name (e.g. a <code>Block</code> and an <code>Item</code> each hold a registry object named <code>examplemod:object</code>.

{{Tip/Warning|If two registry objects within the same registry have the same name, the second object will override the first. The only registry that will throw an <code>IllegalArgumentException</code> is the <code>DataSerializerEntry</code> registry.}}

== Methods for Registering ==

There are two proper ways to register objects within an associated wrapped Forge registry: the <code>DeferredRegister</code> class, and the <code>RegistryEvent$Register</code> lifecycle event.

For objects with '''no''' associated Forge registry, you can register the associated entry during the <code>FMLCommonSetupEvent</code> lifecycle event. In some cases, although not recommended, you may also statically initialize and register these entries.

=== DeferredRegister ===

<code>DeferredRegister</code> is an abstraction layer over the registry event used to register objects. It maintains a map of "registry name" to their associated suppliers and resolves those suppliers during the proper <code>RegistryEvent$Register</code> event. This method is the currently recommended, and documented, way to handle these objects as it provides convenience and safety for those who want to statically initialize objects while avoiding some issues associated with it.

An example of a mod registering a custom block:

{{Template:Tabs/Code_Snippets
|java=private static final DeferredRegister<Block> BLOCKS = DeferredRegister.create(ForgeRegistries.BLOCKS, MODID);

public static final RegistryObject<Block> EXAMPLE_BLOCK = BLOCKS.register("example_block", () -> new Block(BlockBehaviour.Properties.of(Material.STONE)));

public ExampleMod() {
BLOCKS.register(FMLJavaModLoadingContext.get().getModEventBus());
}
|kotlin=private val BLOCKS = DeferredRegister.create(ForgeRegistries.BLOCKS, MODID)

val EXAMPLE_BLOCK: RegistryObject<Block> = BLOCKS.register("example_block") { Block(BlockBehaviour.Properties.of(Material.ROCK)) }

internal class ExampleMod {
init {
BLOCKS.register(FMLJavaModLoadingContext.get().modEventBus)
}
}
|scala=object ExampleMod {
private final val BLOCKS = DeferredRegister.create(ForgeRegistries.BLOCKS, MODID)

final val EXAMPLE_BLOCK = registerBlock("example_block", () => new Block(BlockBehaviour.Properties.of(Material.ROCK)))
}
class ExampleMod {
BLOCKS.register(FMLJavaModLoadingContext.get.getModEventBus)
}
|groovy=private static final DeferredRegister<Block> BLOCKS = DeferredRegister.create(ForgeRegistries.BLOCKS, MODID);

public static final RegistryObject<Block> EXAMPLE_BLOCK = BLOCKS.register("example_block", () -> new Block(BlockBehaviour.Properties.of(Material.STONE)));

ExampleMod() {
BLOCKS.register(FMLJavaModLoadingContext.get().modEventBus);
}
|}}

{{Tip|When using a <code>DeferredRegister</code> to register any object, the name inputted will be automatically prefixed with the mod id passed in, giving the above object a "registry name" of <code>examplemod:example_block</code>.}}

=== RegistryEvent.Register ===

The <code>RegistryEvent</code>s are another, more slightly flexible way to register objects. These [[Events|events]] are fired synchronously after <code>FMLConstructModEvent</code> and before the configs are loaded.

The event used to register objects is <code>RegistryEvent.Register<T></code>, where the type parameter <code>T</code> is the object type being registered. You can grab the associated registry using <code>#getRegistry</code> and register the objects within using either <code>#register</code> (pass in a single object) or <code>#registerAll</code> (pass in ''varargs'' or an array of objects). The latter is useful for minimizing calls to <code>#register</code>, although it provides no benefit time-complexity wise.

{{Tip/Important|The type parameter specified must be the exact class used within the Forge registry, not its superclass nor its subclass. If the class specified is not referenced as a type parameter within the associated Forge registries, then the event will not be called.}}

Here is an example: (the event handler is registered on the '''mod event bus''')

{{Template:Tabs/Code_Snippets
|java=@SubscribeEvent
public void registerBlocks(RegistryEvent.Register<Block> event) {
event.getRegistry().registerAll(new Block(...).setRegistryName(new ResourceLocation(MODID, "example_block1")), new Block(...).setRegistryName(new ResourceLocation(MODID, "example_block2")), ...);
}
|kotlin=@JvmStatic
@SubscribeEvent
private fun registerBlocks(event: RegistryEvent.Register<Block>) =
event.registry.registerAll(Block(...).setRegistryName(new ResourceLocation(MODID, "example_block1")), Block(...).setRegistryName(new ResourceLocation(MODID, "example_block2")), ...)
|scala=@SubscribeEvent
def registerBlocks(event: RegistryEvent.Register[Block]): Unit =
event.getRegistry.registerAll(new Block(...).setRegistryName(new ResourceLocation(MODID, "example_block1")), new Block(...).setRegistryName(new ResourceLocation(MODID, "example_block2")), ...)
|}}

{{Tip/Important|Since all objects registered must be singleton, some classes cannot by themselves be registered. Instead, <code>*Type</code> classes are registered and used in the formers' constructors to wrap the flyweight objects. For example, a [[Basics_of_Block_Entities|<code>BlockEntity</code>]] is wrapped via <code>BlockEntityType</code>, and <code>Entity</code> is wrapped via <code>EntityType</code>. These <code>*Type</code> classes hold factories that simply create the containing type on demand.

These factory holders are created through the use of their <code>*Type$Builder</code> classes. An example: (<code>REGISTER</code> here refers to a <code>DeferredRegister<BlockEntityType<?>></code>)

{{Template:Tabs/Code_Snippets
|java=public static final RegistryObject<BlockEntityType<ExampleBlockEntity>> EXAMPLE_BLOCK_ENTITY = REGISTER.register(
"example_block_entity", () -> BlockEntityType.Builder.of(ExampleBlockEntity::new, EXAMPLE_BLOCK.get()).build(null)
);
|kotlin=val EXAMPLE_BLOCK_ENTITY: RegistryObject<BlockEntityType<ExampleBlockEntity>> = REGISTER.register("example_block_entity") { BlockEntityType.Builder.of(::ExampleBlockEntity, EXAMPLE_BLOCK.get()).build(null)) }
|scala=final val EXAMPLE_BLOCK_ENTITY = REGISTER.register("example_block_entity", () => BlockEntityType.Builder.of(() => new ExampleBlockEntity(), GeneralRegistrar.EXAMPLE_BLOCK.get).build(null))
|}}
}}

=== Non-Forge Registries ===

Not all vanilla registries are wrapped as a Forge registry. This is because the registry is fully independent from any other registry, completely data driven, or just has not been wrapped yet.

These registries include:
* Custom Stats (a <code>ResourceLocation</code> registry)
* <code>RuleTestType</code>
* <code>PosRuleTestType</code>
* <code>RecipeType</code>
* <code>GameEvent</code>
* <code>PositionSourceType</code>
* <code>VillagerType</code>
* <code>LootPoolEntryType</code>
* <code>LootItemFunctionType</code>
* <code>LootItemConditionType</code>
* <code>LootNumberProviderType</code>
* <code>LootNbtProviderType</code>
* <code>LootScoreProviderType</code>
* <code>FloatProviderType</code>
* <code>IntProviderType</code>
* <code>HeightProviderType</code>
* <code>StructurePieceType</code>
* <code>TrunkPlacerType</code>
* <code>FeatureSizeType</code>
* A <code>Codec</code> of <code>BiomeSource</code>
* A <code>Codec</code> of <code>ChunkGenerator</code>
* <code>StructureProcessorType</code>
* <code>StructurePoolElementType</code>
* All registries within <code>BuiltinRegistries</code> excluding <code>Biome</code>

To register objects to any one of these registries, you will need to call <code>Registry::register(Registry, ResourceLocation, T)</code> where the type parameter <code>T</code> is the object instance being registered. The method can then be called and registered during the highest priority of <code>FMLCommonSetupEvent</code>. We can also utilize a <code>Lazy</code> above to store the result on first access and use within our code.

Here is an example: (the event handler is registered on the '''mod event bus''')

{{Template:Tabs/Code_Snippets
|java=public static final Lazy<ConfiguredFeature<?, ?>> EXAMPLE_CONFIGURED_FEATURE = Lazy.of(() ->
register("example_configured_feature",
Feature.NO_OP.configured(NoneFeatureConfiguration.INSTANCE)
.decorated(FeatureDecorator.NOPE.configured(NoneDecoratorConfiguration.INSTANCE))
)
);

@SubscribeEvent(priority = EventPriority.HIGHEST)
public void register(FMLCommonSetupEvent event) {
event.enqueueWork(EXAMPLE_CONFIGURED_FEATURE::get);
}

private static <T extends ConfiguredFeature<?, ?>> T register(String name, T value) {
return Registry.register(BuiltinRegistries.CONFIGURED_FEATURE, new ResourceLocation(MODID, name), value);
}
|kotlin=val EXAMPLE_CONFIGURED_FEATURE: ConfiguredFeature<*, *> by lazy {
register("example_configured_feature",
Feature.NO_OP.configured(NoneFeatureConfiguration.INSTANCE)
.decorated(FeatureDecorator.NOPE.configured(NoneDecoratorConfiguration.INSTANCE)))
}

object Events {

@SubscribeEvent(priority = EventPriority.HIGHEST)
fun register(event: FMLCommonSetupEvent) {
event.enqueueWork(EXAMPLE_CONFIGURED_FEATURE::getConfig)
}
}

private fun <T: ConfiguredFeature<*, *>> register(name: String, value: T): T =
Registry.register(BuiltinRegistries.CONFIGURED_FEATURE, ResourceLocation(MODID, name), value)
|scala=class Events {
@SubscribeEvent(priority = EventPriority.HIGHEST)
def register(event: FMLCommonSetupEvent): Unit = {
event.enqueueWork(Events.EXAMPLE_CONFIGURED_FEATURE.getConfig _)
}
}
object Events {
final lazy val EXAMPLE_CONFIGURED_FEATURE = register("example_configured_feature",
Feature.NO_OP.configured(NoneFeatureConfiguration.INSTANCE)
.decorated(FeatureDecorator.NOPE.configured(NoneDecoratorConfiguration.INSTANCE)))

private def register[T <: ConfiguredFeature[_, _]](name: String, value: T): T =
Registry.register(BuiltinRegistries.CONFIGURED_FEATURE, new ResourceLocation(MODID, name), value)
}
|}}

{{Tip/Warning|Vanilla registry methods are not thread-safe, so they must be wrapped within the synchronous queue provided within the common setup event via <code>#enqueueWork</code>.}}

Besides the registries within <code>BuiltinRegistries</code>, all other '''non-forge''' wrapped registries can be statically initialized like so:

{{Template:Tabs/Code_Snippets
|java=public static final RecipeType<ExampleRecipe> EXAMPLE_RECIPE = RecipeType.register(MODID + ":example_recipe");
|kotlin=val EXAMPLE_RECIPE: RecipeType<ExampleRecipe> = RecipeType.register("${MODID}:example_recipe")
|scala=final val EXAMPLE_RECIPE = RecipeType.register(s"${MODID}:example_recipe")
|groovy=public static final RecipeType<ExampleRecipe> EXAMPLE_RECIPE = RecipeType.register("$MODID:example_recipe");
|}}

If you attempt to make one of these instances require an instance of another registry object, you must use the lazy initialization method mentioned above to register the object in the correct order.

=== Data Driven Entries ===

Registries are considered to be data driven if they are located within <code>RegistryAccess</code> with the exception of <code>LevelStem</code> and <code>Level</code>.

The following registries are data driven:
* <code>ConfiguredSurfaceBuilder</code>
* <code>ConfiguredWorldCarver</code>
* <code>ConfiguredFeature</code>
* <code>ConfiguredStructureFeature</code>
* <code>StructureProcessorList</code>
* <code>StructureTemplatePool</code>
* <code>Biome</code>
* <code>NoiseGeneratorSettings</code>
* <code>DimensionType</code>
* <code>LevelStem</code>
* <code>Level</code>

These registry objects only need to be registered within code if they are to be used within a pre-existing registry object (e.g. a <code>ConfiguredFeature</code> for ore generation within an overworld <code>Biome</code>). Otherwise, their instance can be purely registered using a JSON file.

If a data driven registry object has to be registered within code, a dummy object should be supplied to hold a "registry name" and then constructed within a JSON file.

== Referencing Registered Objects ==

Each forge registered object should not be statically initialized nor reference another instance being registered. They must always be a new, singleton instance that is resolved during their respective <code>RegistryEvent$Register</code> event. This is to maintain a sane loading order for registries and their objects along with dynamic loading/unloading of mods.

Forge registered objects must always be referenced through a <code>RegistryObject</code> or a field with <code>@ObjectHolder</code>.

===Using RegistryObjects===
<code>RegistryObject</code>s can be used to retrieve references to registered objects once they become available. Their references are updated along with all <code>@ObjectHolder</code> annotations after the associated <code>RegistryEvent$Register</code> has been dispatched and frozen.

A <code>RegistryObject</code> can be retrieved as a result of using <code>DeferredRegister</code> or calling the static constructor <code>RegistryObject::of</code>. Each static constructor takes in the "registry name" of the object being referenced and either a <code>IForgeRegistry</code> or, if custom registries are used, a supplier of the object class implementing <code>IForgeRegistryEntry</code>. The <code>RegistryObject</code> can be stored within some field and retrieve the registered object using <code>#get</code>.

An example using <code>RegistryObject</code>:
{{Template:Tabs/Code_Snippets
|java=public static final RegistryObject<Item> EXAMPLE_ITEM = RegistryObject.of(new ResourceLocation("examplemod:example_item"), ForgeRegistries.ITEMS);

// Assume that 'ExampleRegistry' is a valid registry, and 'examplemod:example_object' is a valid object within that registry
public static final RegistryObject<ExampleRegistry> EXAMPLE_OBJECT = RegistryObject.of(new ResourceLocation("examplemod", "example_object"), () -> ExampleRegistry.class);
|kotlin=val EXAMPLE_ITEM: RegistryObject<Item> = RegistryObject.of(ResourceLocation("examplemod:example_item"), ForgeRegistries.ITEMS)

// Assume that 'ExampleRegistry' is a valid registry, and 'examplemod:example_object' is a valid object within that registry
val EXAMPLE_OBJECT: RegistryObject<ExampleRegistry> = RegistryObject.of(ResourceLocation("examplemod", "example_object")) { ExampleRegistry.class }
|scala=final val EXAMPLE_ITEM = RegistryObject.of(new ResourceLocation("examplemod:example_item"), ForgeRegistries.ITEMS)

// Assume that 'ExampleRegistry' is a valid registry, and 'examplemod:example_object' is a valid object within that registry
final val EXAMPLE_OBJECT = RegistryObject.of(new ResourceLocation("examplemod", "example_object"), () => classOf[ExampleRegistry]);
|}}

{{Tip/Important|All vanilla objects are bootstrapped and registered before mods are loaded. As such, they can be referenced as is without any issues, assuming the entries are not replaced.}}

=== Using @ObjectHolder ===

Forge registry objects can also be injected into <code>public static</code> fields with either their class or that field annotated with <code>@ObjectHolder</code>. There must be enough information to construct a <code>ResourceLocation</code> to identify a single object within a specific registry.

The rules for <code>@ObjectHolder</code> are as follows:

* If the class is annotated with <code>@ObjectHolder</code>, its value will be the default namespace for all fields within if not explicitly defined
* If the class is annotated with <code>@Mod</code>, the modid will be the default namespace for all annotated fields within if not explicitly defined
* A field is considered for injection if:
** it has at least the modifiers <code>public static</code>; and
** one of the following conditions are true:
*** the '''enclosing class''' has an <code>@ObjectHolder</code> annotation, and the field is <code>final</code>, and:
**** the name value is the field's name; and
**** the namespace value is the enclosing class's namespace
**** ''An exception is thrown if the namespace value cannot be found and inherited''
*** the '''field''' is annotated with <code>@ObjectHolder</code>, and:
**** the name value is explicitly defined; and
**** the namespace value is either explicitly defined or the enclosing class's namespace
** the field type or one of its supertypes corresponds to a valid registry (e.g. <code>Item</code> or <code>ArrowItem</code> for the <code>Item</code> registry)
** ''An exception is thrown if a field does not have a corresponding registry.''
* ''An exception is thrown if the resulting <code>ResourceLocation</code> is incomplete or invalid (non-valid characters in path)''
* If no other errors or exceptions occur, the field will be injected
* If all of the above rules do not apply, no action will be taken (and a message may be logged)

<code>@ObjectHolder</code> annotated fields are injected with their associated object values after their corresponding registry's <code>RegistryEvent$Register</code> event is fired, along with <code>RegistryObject</code>s.

{{Tip/Warning|If the object does not exist in the registry when it is to be injected, a debug message will be logged, and no value will be injected. If the object is found, but the field cannot be set, a warning message will be logged instead.}}

As these rules are rather complicated, here are some examples:
<div class="mw-collapsible mw-collapsed" style="border: solid 2px; padding: 2px 5px; margin-top: 3px">
<div style="font-weight:bold;line-height:1.6;">Example uses of <code>@ObjectHolder</code></div>
<div class="mw-collapsible-content" style="overflow: auto; white-space: nowrap;">
<syntaxhighlight lang="java">
@ObjectHolder("minecraft") // Inheritable resource namespace: "minecraft"
class AnnotatedHolder {
public static final Block diamond_block = null; // No annotation. [public static final] is required.
// Block has a corresponding registry: [Block]
// Name path is the name of the field: "diamond_block"
// Namespace is not explicitly defined.
// So, namespace is inherited from class annotation: "minecraft"
// To inject: "minecraft:diamond_block" from the [Block] registry

@ObjectHolder("ambient.cave")
public static SoundEvent ambient_sound = null; // Annotation present. [public static] is required.
// SoundEvent has a corresponding registry: [SoundEvent]
// Name path is the value of the annotation: "ambient.cave"
// Namespace is not explicitly defined.
// So, namespace is inherited from class annotation: "minecraft"
// To inject: "minecraft:ambient.cave" from the [SoundEvent] registry

// Assume for the next entry that [ManaType] is a valid registry.
@ObjectHolder("neomagicae:coffeinum")
public static final ManaType coffeinum = null; // Annotation present. [public static] is required. [final] is optional.
// ManaType has a corresponding registry: [ManaType] (custom registry)
// Resource location is explicitly defined: "neomagicae:coffeinum"
// To inject: "neomagicae:coffeinum" from the [ManaType] registry

public static final Item ENDER_PEARL = null; // No annotation. [public static final] is required.
// Item has a corresponding registry: [Item].
// Name path is the name of the field: "ENDER_PEARL" -> "ender_pearl"
// !! ^ Field name is valid, because they are
// converted to lowercase automatically.
// Namespace is not explicitly defined.
// So, namespace is inherited from class annotation: "minecraft"
// To inject: "minecraft:ender_pearl" from the [Item] registry

@ObjectHolder("minecraft:arrow")
public static final ArrowItem arrow = null; // Annotation present. [public static] is required. [final] is optional.
// ArrowItem does not have a corresponding registry.
// ArrowItem's supertype of Item has a corresponding registry: [Item]
// Resource location is explicitly defined: "minecraft:arrow"
// To inject: "minecraft:arrow" from the [Item] registry

public static Block bedrock = null; // No annotation, so [public static final] is required.
// Therefore, the field is ignored.

public static final CreativeModeTab group = null; // No annotation. [public static final] is required.
// CreativeModeTab does not have a corresponding registry.
// No supertypes of CreativeModeTab has a corresponding registry.
// Therefore, THIS WILL PRODUCE AN EXCEPTION.
}

class UnannotatedHolder { // Note the lack of an @ObjectHolder annotation on this class.
@ObjectHolder("minecraft:flame")
public static final Enchantment flame = null; // Annotation present. [public static] is required. [final] is optional.
// Enchantment has corresponding registry: [Enchantment].
// Resource location is explicitly defined: "minecraft:flame"
// To inject: "minecraft:flame" from the [Enchantment] registry

public static final Biome ice_flat = null; // No annotation on the enclosing class.
// Therefore, the field is ignored.

@ObjectHolder("minecraft:creeper")
public static Entity creeper = null; // Annotation present. [public static] is required.
// Entity does not have a corresponding registry.
// No supertypes of Entity has a corresponding registry.
// Therefore, THIS WILL PRODUCE AN EXCEPTION.

@ObjectHolder("levitation")
public static final Potion levitation = null; // Annotation present. [public static] is required. [final] is optional.
// Potion has a corresponding registry: [Potion].
// Name path is the value of the annotation: "levitation"
// Namespace is not explicitly defined.
// No annotation in enclosing class.
// Therefore, THIS WILL PRODUCE AN EXCEPTION.
}
</syntaxhighlight>
</div>
</div>

== Creating Custom Registries ==

Creating custom registries for your mod might be useful if you want other mods to add new things to your system. For example, you might have magic spells and want to allow other mods to add new spells. For this you will want to make a registry (eg. "mymagicmod:spells"). This way, other mods will be able to register things to that list, and you won't have to do anything else.

Just like with registering a new item or block you have two ways of making a new registry. Each method takes in a <code>RegistryBuilder</code> which is used to build an <code>IForgeRegistry</code> for an object class that implements <code>IForgeRegistryEntry</code>. Each builder should have its name and type set via <code>#setName</code> and <code>#setType</code> respectively before being created.

For the class that implements <code>IForgeRegistryEntry</code>, it is recommended in most cases to extend the default implementation of <code>ForgeRegistryEntry</code>. For interfaces, it should extend <code>IForgeRegistryEntry</code> with its implementations extending <code>ForgeRegistryEntry</code>.

=== With DeferredRegister ===

The first method involves the second static constructor: <code>DeferredRegister::create(Class, String)</code>. The class supplied must extend <code>IForgeRegistryEntry</code>. From there, we can construct the registry using <code>#makeRegistry</code>. This will already populate <code>#setName</code> and <code>#setType</code> for us. This method also returns a supplier of the registry which we can use after the <code>RegistryEvent$NewRegistry</code> event.

Here is an example:

{{Template:Tabs/Code_Snippets
|java=public static final DeferredRegister<ExampleRegistry> EXAMPLE = DeferredRegister.create(ExampleRegistry.class, MODID);

public static final Supplier<IForgeRegistry<ExampleRegistry>> REGISTRY = EXAMPLE.makeRegistry("example_registry", RegistryBuilder::new);
|kotlin=val EXAMPLE: DeferredRegister<ExampleRegistry> = DeferredRegister.create(ExampleRegistry::class.java, MODID)

val REGISTRY: IForgeRegistry<ExampleRegistry> by lazy {
EXAMPLE.makeRegistry("example_registry", ::RegistryBuilder).get()
}
|scala=final val EXAMPLE = DeferredRegister.create(classOf[ExampleRegistry], MODID)

final lazy val REGISTRY = EXAMPLE.makeRegistry("example_registry", () => new RegistryBuilder).get
|}}

=== Using RegistryEvent$NewRegistry ===

The second method can be done during the <code>RegistryEvent$NewRegistry</code> event. This will call a new instance of the builder directly. From there, the registry can be built and stored via <code>RegistryBuilder#create</code>. This will cause the registry to be registered to the <code>RegistryManager</code> and returned to the caller for additional processing.

Here is an example: (the event handler is registered on the '''mod event bus''')

<syntaxhighlight lang="Java">
public static IForgeRegistry<ExampleRegistry> registry = null;

@SubscribeEvent
public void onNewRegistry(RegistryEvent.NewRegistry event){
RegistryBuilder<ExampleRegistry> registryBuilder = new RegistryBuilder<>();
registryBuilder.setName(new ResourceLocation(MODID, "example_registry");
registryBuilder.setType(ExampleRegistry.class);
registry = registryBuilder.create();
}
</syntaxhighlight>

== Handling Missing Entries ==

When loading a pre-existing world after removing mods or updating versions, there are cases where certain registry objects will cease to exist. In these cases, it is possible to specify actions to remove a mapping, prevent the world from loading, or remap the name as needed. This can be done through the third of the registry events: <code>RegistryEvent$MissingMappings<T></code>, where the type parameter <code>T</code> is the object type being registered. Within the event, you can grab an immutable list of missing mappings associated with a mod id via <code>#getMappings</code> or a list of all mappings via <code>#getAllMappings</code>.

For each <code>Mapping</code>, you can either execute one of the following methods:
* <code>#ignore</code> which abandons the entry when loading
* <code>#warn</code> which warns the user about the missing entry but continues loading
* <code>#fail</code> which prevents the world from loading
* <code>#remap</code> which remaps the entry to the specified non-null object in the same registry

If none of the above are specified, then the default action of notifying the user about the missing mappings occur.

Here is an example: (the event handler is registered on the '''mod event bus''')

{{Template:Tabs/Code_Snippets
|java=// This will ignore any missing test items from the specified world
@SubscribeEvent
public void onMissingItems(final RegistryEvent.MissingMappings<Item> event) {
event.getMappings(MODID).stream()
.filter(mapping -> mapping.key.getPath().contains("test"))
.forEach(Mapping::ignore);
}
|groovy=// This will ignore any missing test items from the specified world
@SubscribeEvent
void onMissingItems(final RegistryEvent.MissingMappings<Item> event) {
event.getMappings(MODID).stream()
.filter(mapping -> mapping.key.path.contains("test"))
.forEach(Mapping::ignore);
}
|}}

[[Category:Common Concepts]]

Stages of Modloading

2021-09-06T19:08:44Z

Paint Ninja: Document config loading stage

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 <code>mod lifecycle events</code>, 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 <code><nowiki>net.minecraftforge.fml.ModLoadingStage</nowiki></code>. Their states are split between the <code><nowiki>net.minecraftforge.fml.core.ModStateProvider</nowiki></code> for mod states (construct, common setup, etc.) and <code><nowiki>net.minecraftforge.fmllegacy.ForgeStatesProvider</nowiki></code> for forge injected states (creating registries, injecting capabilities, etc.) Most of the mod lifecycle events are stored in the <code><nowiki>net.minecraftforge.fml.event.lifecycle</nowiki></code> 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 <code><nowiki>ParallelDispatchEvent</nowiki></code>.

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 <code><nowiki>#enqueueWork</nowiki></code> method, which is a member of all events which extend <code><nowiki>ParallelDispatchEvent</nowiki></code>.

== Common Transition Stages and Events ==

{| class="wikitable sortable" border=1
! Name !! Enum Constant !! Lifecycle Event !! Parallel? !! Description
|-
| Construction || <code><nowiki>CONSTRUCT</nowiki></code> || <code><nowiki>FMLConstructModEvent</nowiki></code> || 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 || <code><nowiki>CREATE_REGISTRIES</nowiki></code> || <code><nowiki>RegistryEvent.NewRegistry</nowiki></code> || No || Fired for mods to create and initialize their custom registries.
|-
| Registry Population || <code><nowiki>LOAD_REGISTRIES</nowiki></code> || <code><nowiki>RegistryEvent.Register</nowiki></code> || No || Fired when a registry is open to registrations for any registrable objects, such as blocks, items, etc.
|-
| Config Loading || <code><nowiki>CONFIG_LOAD</nowiki></code> || (inlined in <code><nowiki>ModStateProvider</nowiki></code>) || ? || 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 || <code><nowiki>COMMON_SETUP</nowiki></code> || <code><nowiki>FMLCommonSetupEvent</nowiki></code> || Yes || Used for doing any work or action that should be run on both '''physical''' sides.
|-
| Sided Setup || <code><nowiki>SIDED_SETUP</nowiki></code> || <code><nowiki>FMLClientSetupEvent</nowiki></code> for physical client, <code><nowiki>FMLDedicatedServerSetupEvent</nowiki></code> for physical server || Yes || Used for doing any physical side-specific initialization work.
|-
| IMC Enqueue || <code><nowiki>ENQUEUE_IMC</nowiki></code> || <code><nowiki>InterModEnqueueEvent</nowiki></code> || Yes || Fired for mods to enqueue messages for other mods using the <code><nowiki>InterModComms</nowiki></code> system.
|-
| IMC Processing || <code><nowiki>PROCESS_IMC</nowiki></code> || <code><nowiki>InterModProcessEvent</nowiki></code> || Yes || Fired for mods to process messages from other mods sent using the <code><nowiki>InterModComms</nowiki></code> system in the previous stage.
|-
| Loading Complete || <code><nowiki>COMPLETE</nowiki></code> || <code><nowiki>FMLLoadCompleteEvent</nowiki></code> || 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.
|-
|}

User talk:Paint Ninja/Installer

2021-05-13T00:30:37Z

Paint Ninja: Created page with "see <code>Actions.java</code>, <code>Action.java</code>, <code>ClientInstall/ServerInstall/ExtractAction.java</code> example with <code>ExtractAction</code>: <code>final Acti..."

see <code>Actions.java</code>, <code>Action.java</code>, <code>ClientInstall/ServerInstall/ExtractAction.java</code>

example with <code>ExtractAction</code>:
<code>final Actions action = Actions.EXTRACT;</code>

<code>action.getAction(installProfile, monitor)</code> will refer to the <code>BiFunction<Install, ProgressCallback, Action></code> action
inside the <code>Actions.java</code> enum which <code>Actions.EXTRACT</code> specifically populates as a new instance of
<code>ExtractAction.java</code> as the <code>BiFunction</code> (a <code>BiFunction</code> being an <code>Object</code> that takes two inputs, can do some work and has one output).

The <code>Install installProfile</code> and <code>ProgressCallback monitor</code> arguments are then applied to the <code>BiFunction</code>,
which causes <code>ExtractAction</code>'s constructor to be called with those arguments.

<code>ExtractAction</code>'s constructor calls its parent constructor (Action.java) with <code>super(profile, monitor, true)</code>.
true being <code>isClient</code> here.

<code>Action.java</code>'s constructor populates some variables and instantiates <code>PostProcessors.java</code>, which calls
the <code>installProfile</code>'s <code>getProcessors("client")</code> and <code>getData(true)</code> methods and stores their results in a
<code>List<Processor></code> and a <code>Map<String, String></code>, respectively. <code>Install#getProcessors()</code> will return an empty list
and <code>Install#getData()</code> will return a new, empty <code>HashMap</code>, this is just to set things up for when the action
is ran.

<code>action.getAction(installProfile, monitor).run(target, a -> true)</code>

The <code>ExtractAction.java</code> overrides the <code>run(File, Predicate<String>)</code> method. In this case, the args from the
run method invocation above provide the target directory to extract to and what's basically an unused
truthy boolean value.

This run method returns true if successful and false otherwise. It gets the <code>path</code> variable from the parsed
<code>installProfile</code>, which is the Maven artifact path for the 'main' jar and is an instance of <code>Artifact.java</code>.

<code>Artifact.java</code> uses an <code>Adapter</code> subclass that implements a JSON deserializer and serializer that gets the
JSON primitive String and calls the Artifact#from(String) to split the maven descriptor into its parts and
build a path to it inside the Installer jar.

It then calls DownloadUtils#extractFile(Artifact, File, String) with the Maven artifact path to extract from,
the target path to put it in when extracted and a <code>null</code> (meaning don't verify its checksum after extracting it).

Extracting the <code>Artifact</code> is easier than it sounds, it just grabs a file embedded within the jar under the
maven folder (similar to how the install_profile.json is obtained) and copies it to the target path,
overwriting any existing files there and creating directories to put them in when necessary.

<code>if (action.getAction(installProfile, monitor).run(target, a -> true)) {</code>

User:Paint Ninja

2021-05-13T00:18:29Z

Paint Ninja: Created blank page