Fresh from the Forge 2024

[Jonathing]

Fresh from the Forge 2024

Good morning! Since Minecraft 1.20, there have been a plethora of changes to Forge, its related subprojects, and the project structure as a whole. The end of 2024 is approaching, and now is as good a time as ever to highlight those changes and additions that you may not know about!

A quick disclaimer before we begin: this forum post is a new format we'd like to try where we go over the various additions and changes that we've made. Since it's relatively new and we haven't been writing it over the course of the entire year, this post is not a comprehensive recollection of all the major additions and changes the project has received over the past year. However, it does make sure that the most important parts of each change is detailed enough so that you know what is new.

Quick Highlights (the tl;dr)

This forum post is rather long and goes into some details, so here is a quick and dirty rundown of what's new:

- Our new discord server has a restructured development process that is more transparent and open to the public.
- We have a new tiered support policy that allows for more versions of Minecraft to be supported.
- The Forge server jar is now executable again.
- JS CoreMods have several bugs fixed, has new ASMAPI methods, and now supports ES6 language features.
- The mod sorter now properly sorts nested mods within a single `mods.toml` file.
- Forge mods now have access to a `FMLJavaModLoadingContext` parameter in their constructors.
- Forge now includes de-facto common tags for use by datapackers and modders.
- Forge mods can now declare their own Java modules.
- Stacktraces provided by ModLauncher have been cleaned up.
- Forge now uses the official Mojang mappings in production.
- AccessTransformers have received major performance improvements.
- Extension points have been simplified for display tests and configuration screens.
- A new `clientSideOnly` property has been added to `mods.toml`.
- Launch times have been significantly improved and large amounts of internal code have been cleaned up.
- Crash reports now have a small system that attempts to make debugging crashes easier.
- The networking system has been rewritten to be simpler and more extensible.
- EventBus now has a `MONITOR` phase for event listeners (non-cancellable).
- ModLauncher and EventBus are being rewritten to be more maintainable and performant.

Development Transparency and Improvements

One of the biggest criticisms that was levied against the Forge team in the past was the lack of transparency regarding the development cycle, process, and discussion between team members or other related contributors. Since our project restructuring and the opening of our new Discord server in 2023, we have since changed the way development discussion takes place.

Project Discussion

Discussion surrounding the development of Minecraft Forge is now completely open to the public. The Discord server contains two main channels for project development:

- #github-discussions is the channel where anyone from the server is able to discuss current GitHub issues and PRs to any of Forge's projects.
- #triage-discussions is the channel where the Triage team and Core team members can discuss implementation details and other topics that don't require input from the general public. This channel is viewable by all members so they have a clear view on internal discussion, while also being able to raise concerns in other channels if necessary.

Community Improvements

There have been several efforts put into improving the general experience of the Forge community. More specifically, discussion surrounding the community harbored by Minecraft Forge is now encouraged through dedicated channels. The Discord server contains a few key points in this regard:

- #community-discussion is the channel where anyone from the server is able to discuss the state of the Forge community, including work that needs to be done related spaces such as the Forums site.
- All staff chat is publicly viewable in #staff-chat where discussion amongst the staff regarding community concerns and internal implementations is publicly available. The only exception to this is the moderation appeals channel.
- Points of discussion which were previously instantly shunned by the former Discord policy (such as CoreModding and Legacy Versions) no longer are. As long as discussions are productive and modders understand the risks (such as being easier to accidentally break mod compat compared to using existing Forge APIs instead, or that manpower is limited with regards to older versions), it is not an offense.

Additionally, community-oriented sites such as the forums have been cleaned up and gained improvements in spam protection, and the Forge website all-around has faster site and web services.

Revised Version Support

Compared to today, the version support of Forge was much tighter and a lot stricter. There were two tiers of support: latest and LTS. The latest version would, as the name entails, encompass only the latest version of the game. The LTS version, on the other hand, would cover the last minor patch of the previous major version of the game. As an example, during the Minecraft 1.18 lifecycle, the latest version was 1.19.4 and the LTS version was 1.18.2.

As Minecraft's release cycle began to change to what it is today, this posed one significant problem: what if a minor point release brings about changes that would be comparable to a major version update? Examples of these versions included 1.16.2, 1.19.3, and 1.20.2, where many users stuck with the older version due to mods not updating quickly enough.

As a result, we have completely overhauled how we handle version support. Our new system, the tiered support policy, was created to accommodate for the vast number of active versions Minecraft continues to harbor. In short, this means that there are many more versions of Minecraft that Forge is able to provide technical support, features, and bug fixes for. While the latest version of the game will always have the Forge team's top priority, all versions covered by full support are fair game for technical support, pull requests, backports, and others.

You can read the full details of the new tiered support policy on this forum post by our very own Paint_Ninja from the Core team: New tiered support policy

It is important to note that even if an older version of Forge is not covered under active support, we are still open to look at any potential contributions to legacy versions of the game. For example, 1.18.2 still occasionally gets backports of newer Forge version features!

New Features and Improvements

Now that we've covered the structural changes within the Forge project, it's finally time to talk about the jam-packed new features, some of which have been long awaited, that have been added into Forge since then! Grab a snack and buckle in, because this is going to be a long ride.

Mod Registration Convenience Features

FMLJavaModLoadingContext in @Mod constructor parameter: Introduced in 1.21.1, backported and available as far back as 1.19.2
Simpler Extension Point Registration: Introduced in 1.20.4, backported and available as far back as 1.18.2

As Forge continues to age with several new features added each year, it can be difficult to keep track, at least for modders, as to what is internal or not, what you should or shouldn't use, and what you truly have access to. Since 1.13, the @Mod construction annotation has come with these little caveats for a while now and has made it difficult for modders to keep track of what they can use, and do, in their constructors. So, our solution to this was to simplify the way modders can interact with Forge during the loading stage to avoid this type of confusion.

FMLJavaModLoadingContext in @Mod constructor parameter

Historically, the way you would get your mod's event bus is by making a direct call to `FMLJavaModLoadingContext.get()`. Despite that, you needed to use a different method call to `ModLoadingContext.get()` if you wanted to register configurations. This caused some confusion and was ambiguous as to what the mod constructor actually had access to when it was created. The solution to this was to add an optional constructor parameter containing a single `FMLJavaModLoadingContext` variable that mod constructors can use directly, without needing to make any external calls. This new `FMLJavaModLoadingContext` is an extension of `ModLoadingContext`, so it now has the powers that both used to have in older versions.

/* OLD */
public MyMod() {
    // getting the mod bus - uses FMLJavaModLoadingContext
    var modBus = FMLJavaModLoadingContext.get().getModEventBus();
  
    // registering configs - uses ModLoadingContext
    ModLoadingContext.get().registerConfig(/* ... */);
    // ...
}

/* NEW */
public MyMod(FMLJavaModLoadingContext context) {
    // getting the mod bus
    var modBus = context.getModEventBus();

    // registering configs
    context.registerConfig(/* ... */);
    // ...
}

As an additional clarification: making the mod have a single optional parameter containing everything is a deliberate design choice so that everything can be contained within the single `FMLJavaModLoadingContext` variable. Adding additional parameters could cause ambiguity when it comes to what the Mod constructor should access (for example, an IEventBus parameter would be ambiguous by its type alone whether it refers to the Mod bus or Forge bus).

Simpler Extension Point Registration

In addition to the mod bus, modders also had to be aware of specific ways to register additional extensions with Forge itself, such as config screens and display tests. Extension points have existed in Forge for a while, but using them was a little esoteric. They were mostly used solely to register display tests or configuration screens, so these extension points now have a simpler, dedicated way to register.

Since Forge 49.0.12 for Minecraft 1.20.4, `DisplayTest` registration has been simplified to a single method that accepts a DisplayTest. See below for an example. Of course, the old way of registering display tests still exists for backwards compatibility.

/* OLD */
ModLoadingContext.get().registerExtensionPoint(IExtensionPoint.DisplayTest.class, () -> new IExtensionPoint.DisplayTest(() -> "ANY", (remote, isServer) -> true));

/* NEW */
ModLoadingContext.get().registerDisplayTest(IExtensionPoint.DisplayTest.IGNORE_ALL_VERSION);
// HINT: If your @Mod constructor contains JavaFmlModLoadingContext, you should use that instead of ModLoadingContext.get()

A similar treatment was done in Forge 49.0.33 for configuration screens. Please note that this registration exists in `MinecraftForge` and not in `ModLoadingContext`.

/* OLD */
ModLoadingContext.get().registerExtensionPoint(ConfigScreenHandler.ConfigScreenFactory.class, () -> new ConfigScreenHandler.ConfigScreenFactory((mc, modsScreen) -> new MyConfigScreen(modsScreen));

/* NEW */
MinecraftForge.registerConfigScreen(modsScreen -> new MyConfigScreen(modsScreen));

The work for the FMLJavaModLoadingContext as constructor parameter feature was done by RealMangorage and is included in Forge 52.0.9, found in MinecraftForge#10074.
The work for the extension point registration improvements was done by Paint_Ninja. The simplified display test registration is included in Forge 49.0.12, found in MinecraftForge#9822. The simplified config screen registration is included in Forge 49.0.33, found in MinecraftForge#9884.

De-facto Common Tags

Introduced in 1.21.1

Not too long ago, many popular mod loaders have begun implementing a universal modded tag solution commonly referred to as "common tags". These tags were created to support cross-loader support for datapacks and/or low-code mods. As of Forge 52.0.20 for Minecraft 1.21.1, Forge now includes these de-facto common tags for use by datapackers and modders alike!

This was a long, arduous, and meticulous process that took a lot of effort, specifically from Paint_Ninja, in order to implement. This included the necessity of staying on par with the implementations found in Fabric and NeoForge, which are not always 100% up-to-date with each other at all times. Forge's implementation is very comprehensive, with detailed migration docs, clear markers for loader-specific tags and strong parity guarantees backed by an open-source tool dedicated to identifying tag differences between loaders that has helped drive significant improvements to parity across all loaders since our initial announcement.

If you would like to learn more about common tags in Forge, I once again invite you to visit another forum post by Paint_Ninja: Common tags in Forge

Finally, we are still not quite done with our common tags implementation. An automation system is in the works, with the help of Paint_Ninja and Jonathing's Common Tags Dumper, to greatly aid us in the process of keeping Forge up-to-date with the common tags implementation between Fabric and NeoForge by notifying us of any changes that we need to account for. We hope that datapacks and low-code mods will be able to greatly benefit from the unification of tags between all mod loaders!

The work for this feature was done by Paint_Ninja and is included in Forge 52.0.20, found in MinecraftForge#9955.

Improvements to Mod Loading for Modders

Proper Java Module Support: Introduced in 1.21.1
Nested Mod Sorting: Introduced in 1.21.3

As Forge Mod Loader has continued to evolve over the past several years, several features have been added to it that aim to make the mod loading process as painless as possible for the modder. Some of these features were not fully realized until very recently, so we have dedicated some time this year to ensuring that they get the functionality and polish they deserve, starting with module support.

Proper Java Module Support

Module support has been a long time coming, with initial work starting as early as the MC 1.17 days. Forge has recently fully realized mod support for the Java Platform Module System. As of Forge 52.0.26 for Minecraft 1.21.1, Forge mods are now able to declare their own modules, as well as declare additional `Add-Opens` and `Add-Exports` to be able to access the internals of other mods. Forge itself also integrates into this system by using an `Automatic-Module-Name` of `net.minecraftforge.forge`.

This addition offers a variety of features that modders can now take advantage of. One of the most important ones is the fine-tuned access control that is offered by modules at both compile-time and runtime. Another is the ability to declare services through a compiled `module-info.java` file as opposed to using static service files that do not necessarily have compile-time validation without additional effort.

I invite you to read more about it in Paint_Ninja's forum post, Proper Java module support in Forge mods, where he has described in detail what this means for mods and how you can best take advantage of it. Also, you can read more about how to take full advantage of modules on Java's own website here: java.dev - Introduction to Modules in Java.

The work for this feature was done by LexManos and is included in Forge 52.0.26, found in MinecraftForge#10125.

Nested Mod Sorting

Until very recently, the mod sorter did not account for nested mods inside mod files, instead only accounting for each mod file that was found. The mod loader will now properly sort nested mods found within a single `mods.toml` within a mod file.

The work for this improvement was done by LexManos and is included in Forge 53.0.12, found in MinecraftForge@384286a.

JavaScript CoreMods Improvements

Introduced in 1.21.3, backported and available as far back as 1.18.2

The CoreMods framework recently received a sizable update that expands upon the utility of `ASMAPI` while also addressing and fixing a numerous amount of longstanding issues. Additionally, CoreMods now supports ES6 language support, which means you can finally use `let`, `const`, and `for..of` in your CoreMods! A lot of work went into CoreMods 5.2, so I invite you to check out the full CoreMods 5.2 changelog. While we do plan to eventually phase out the JS CoreMods system in favor of Mixins, ModLauncher services, and a Java-based CoreMods system, JS CoreMods will continue to get smaller updates that expand upon its use within the already tightly limited sandbox.

The work for the JS CoreMods improvements was done by Jonathing and is included in CoreMods 5.2, found in [email protected] and included Forge 53.0.11.

On the topic of CoreMods, there was also some cleanup done with Forge's own CoreMods, which resolved some issues that would arise when porting to newer versions. It takes advantage of the new features provided by CoreMods 5.2, so if you're interested in that, feel free to browse the work for yourself.

The work for the Forge CoreMods cleanup was done by Jonathing and is found in MinecraftForge#10271, which will be merged in at a later date.

Debugging Improvements

Stacktrace Elements Cleanup: Introduced in 1.21.1
CrashReportAnalyzer: Introduced in 1.20.2, backported and available as far back as 1.18.2

One of the many kinds of improvements we've been working on is cleaning up our debugging output to make it easier to solve problems with the development environment or the game. The two main improvements made this year in this regard was the cleanup of stacktraces in ModLauncher and the addition of CrashReportAnalyzer.

The stacktraces provided by ModLauncher have previously included all transformers that affected every line of the stacktrace. These transformers have been moved below the stacktrace to make reading it easier, without omitting the transformers. This makes it a lot easier to see what transformers have modified the original classes that have been dumped by the stacktrace, without making the stacktrace itself difficult to read by appending each transformer on the same line.

Crash reports in Minecraft has had a long history of being hard to navigate. Knowing how to read stacktraces can be rather difficult, especially for players who aren't used to how crashes work in Java. Forge now has a small system that attempts to make debugging crashes much easier. CrashReportAnalyzer is a one-class system that automatically attempts to identify the mod that caused a crash. This is done by checking the stacktrace of the exception of a crash report for the base package name of a mod. If a mod is identified, it adds the position of where the error occurred in the stacktrace and the mod info of the suspected mods. Any mods that are found in the stacktrace are gathered and appended to the crash report with its name, version, position of the exception, and the issue link if available. This also accounts for any injected mixins from mods.

The work for the stacktrace elements cleanup was done by LexManos and is included in ModLauncher 10.2.2, found in ModLauncher@c712cba and included with Forge 52.0.17.
The work for CrashReportAnalyzer was done by The_Dead_2 and is included in Forge 48.0.27, found in MinecraftForge@3b6bb5e.

Official Mojang Mappings in Production

Introduced in 1.20.6

For many years now, the official obfuscation mappings provided by Mojang have been considered to be the best way to work with the game. Forge itself has been using Mojmap in the dev environment since 1.16, and at runtime has used class names mapped in Mojmap. It became clear that using SRG mappings was becoming less and less of a necessity and more of a cumbersome limitation when trying to read, and work with, our bin patches.

The first step we took to moving away from SRG mappings in the development environment was in Forge 48 for Minecraft 1.20.2. Patches were changed so that they would use Mojmap in the repository, and then would be converted to SRG at compile-time. Shortly after, in Forge 50 for Minecraft 1.20.6, Forge now uses Mojmap at runtime, eliminating the need to use SRG name remappers for modders and makes debugging issues in production many times easier, with stacktraces and crash logs now using officially mapped names as opposed to SRG names. While SRG names are still used to decompile the game with MCPConfig and apply pre-patch transformations such as AccessTransformers, Forge has taken major strides in being less reliant on obfuscated names for Minecraft. The reason why we still use SRG in some cases is to support Parchment mappings, however, we intend on moving to full Mojmap once the toolchain rewrite is complete.

This entire process also involved switching to a new decompiler called VineFlower, due to its superior support for modern Java features. There was a great team effort in doing both the Minecraft version port and migrating all of the patches to the new mapped format.

The work for this feature was done by LexManos and is included in Forge 50.0.0, found in MinecraftForge@7b782e5.

Improvements to Performance and User Convenience

AccessTransformers Performance Improvements: Introduced in 1.20.6
Executable Server Jar: Introduced in 1.20.4
Removing UnionFS in mod dev env: Introduced in 1.20.4
Internal cleanups and optimisations: Introduced in 1.20.2 onwards and often backported as far back as 1.18.2

An uphill battle for a long time in Forge was battling the performance bottlenecks that came with a lot of the tools we use to ensure that the compatibility layer is stable so that mods do not have the issues they used to back in the ancient days. Unfortunately, sometimes this came at the cost of user convenience. This year, we've made some improvements in that regard in attempt to maintain the trio of compatibility, convenience, and performance.

AccessTransformers Performance Improvments

AccessTransformers have historically suffered from high complexity, largely attributed to its reliance on ANTLR. Over the past year, ATs have received major performance improvements, which includes the removal of this dependency.

The work for these improvements was done by LexManos and Paint_Ninja and is included in AccessTransformers 8.2.0, found in [email protected] and included in Forge 50.0.0.

Executable Server Jar

In Forge 37 for Minecraft 1.17.1, the Forge team began initial support for the Java Platform Module System. While the process of including the support is now finished, the initial work came at the cost of the removal of the executable forge server jar. It was replaced with a `run.sh` and `run.bat` file which ran Forge using the new module classpath system. While this has been accounted for nowadays, it caused a lot of problems with server hosts and automated scripts, since they are mostly meant for running a jar file directly, allowing for a custom java path to be applied (i.e. `/home/uname/.sdkman/candidates/java/current/bin/java -jar forge-server.jar`).

After many long years, with the release of Forge 49 for Minecraft 1.20.4, we have revived the executable jar file for servers! Of course, the old system with `run.sh` and `run.bat` still exist for backwards compatibility. Most importantly, this new jar file was built in a way that preserves all existing JPMS features. You can have your cake and eat it, too.

The work for this feature was done by LexManos and is included in Forge 49.0.0, found in MinecraftForge@6f9f0f0.

Faster Launch Times and Internal Cleanups

Since Forge 49 for Minecraft 1.20.4, launch times have significantly improved overtime. One reason for this is not using UnionFS for everything during load. Since most mod runs will have no usage of the UnionFS system, the overhead associated with it will no longer be present. Additionally, the development environment has received a similar treatment by merging the sourcesets at compile-time instead of relying on the UnionFS per launch.

Aside from just that one example, there has been a mountain of effort put into cleanup the Forge and its related subprojects. These cleanups include: cleanups to the early loading screen to make the information it displays easier to read, cleanups to configs, optimizations to registries, optimizations to capabilities, cleaning up and improving how errors and exceptions are handled in mod loading, various cleanups and optimizations to FML and EventBus, cleaning up the FML bindings, and more general cleanups to the mod loading and jar location process.

As we continue to work on continuing the code base and doing thorough cleanups of internal code, faster launch times will continue to both be a byproduct of said cleanup and a goal of Forge as we continue to do so. If you're interested in seeing how we plan on tackling internal code, see the "What's Next?" section near the end of the forum post! Additional work continues to be made on speeding up the launch process for Minecraft within Forge. We hope to have more to share with you some time next year!

Client-Side Only in mods.toml

Introduced in 1.20.4

A new `mods.toml` property was added, `clientSideOnly`, which marks a mod to only be loaded on the client. This eliminates the need to use `DistExecutor` to safely run your mod only on the client, as your mod will be skipped on the server before it is loaded if you use this flag.

This can be easily added to your client-side mod by adding this to your `mods.toml` file:

# This goes in the root of your mods.toml file
clientSideOnly = true

[[mods]]
# ...

As a byproduct of this feature, DistExecutor is being deprecated since it was primarily used to ensure that specific mod code would only be run on the client. Additionally, it was used to workaround some quirks with Java 8, which are no longer necessary since an if-check using FMLEnvironment.dist is now sufficient in modern Java versions.

The work for this feature was done by Paint_Ninja and is included in Forge 49.0.6, found in MinecraftForge#9804.

Additional Values Added to ForgeConfigSpec

Introduced in 1.20.4

ForgeConfigSpec now includes three additional values: ByteValue, ShortValue, and FloatValue. This gives more options for modders to use instead of IntValue and DoubleValue, which prevents needless casting.

Along with this, the ForgeConfigSpec underwent a lot of internal code cleanups and refactoring without causing any breaking changes.

The work for this feature was done by SrRapero720 and is included in Forge 49.0.40, found in MinecraftForge#9902.

Networking Rewrite

Introduced in 1.20.2

The entire networking system was rewritten to be far simpler, with a reduction in generic types and arguments. The handshake system in particular was designed to use the new handshake connection that Mojang added (a system which Forge has historically used its own version of). This way, modders and server developers can easily extand the handshake for more information with needed, and allows for non-Forge clients to work properly. Additionally, this adds support for direct payload channels to allow vanilla-like communications, and adds inherent direction safety to enforce the set direction of the packet (if server -> client, ONLY server -> client).

For an example of how this system is used within Forge, see the diff of the file NetworkInitialization.java.

The work for this feature was done by LexManos and is included in Forge 48.0.0, found in MinecraftForge@516b35c.

EventBus MONITOR Phase

Introduced in 1.20.2

As you may know, EventBus has a priority system for event listeners that allow them to set their priority for when their listener should be invoked by the event bus. The lowest priority that existed was `LOWEST`, which could have been used to get your listener to be the very last to listen to an event.

As of EventBus 6.1, however, a new priority, `MONITOR`, was created and is the new lowest priority. The goal of this phase is to simply "monitor" an event after all other listeners have received it and applied applicable modifications to it. Because of this, `Event#setCanceled()` will throw an exception if you attempt to call it during the `MONITOR` phase.

The work for this feature was done by LexManos and is included in EventBus 6.1.0, found in EventBus@c510e2c and included with Forge 48.0.32 as part of the buildscript cleanup.

What's Next?

Aside from the countless features, improvements, and bug fixes that have been made to Forge over the past year, a lot of work has begun on making substantial changes to the project as a whole. While progress on this has been relatively slow, there has been a decent amount of work completed so far and we'd like to share in this forum post exactly what we're cooking.

ModLauncher and friends

ModLauncher is an extremely useful tool that allows us to divert specific abilities, such as class transformations and module loading, to a single library. In theory, this means that projects which use it, such as FML and CoreMods, do not need to worry about dealing with the burdens of setting up the class transformations by themselves, and can instead feed to ModLauncher what they want transformed. The only problem is that ModLauncher and FML are an absolute beast of complexity, which has made it difficult for us to build on it properly.

Our first steps towards reducing that complexity are now underway, with our very own Paint_Ninja leading the charge on an effective rewrite of ModLauncher. The main benefit of doing this is to allow us not only to further utilize its potential, but also to make it easier to maintain (a common theme throughout our various projects' restructurings). EventBus is also getting this treatment, with a new and revitalized focus on performance. Both ModLauncher and EventBus are also being written with Java 25, the next expected LTS, in mind, taking advantage of the new ClassFile API, Project Valhalla, and many other new and interesting features that can help to boost performance and reduce complexity (as much as possible, of course).

As we continue down this path of restructuring, rewriting, and repurposing, our two primary goals will continue to be maintainability and performance (especially for loading).

Conclusion

It has certainly been a very long year and a half for Minecraft Forge. While we've undergone various project and development team restructurings, we are proud of the work we've put into Forge thus far. Huge progress is being made on our current toolchain changes, and we're excited to put into action what we've been cooking over the course of the next year. Stay safe and enjoy the rest of the year. Cheers to a good 2025!