Development

Everyone can contribute to GTNH in one way or another. One possible way is to improve or expand the source code of the mods.

To get started, you first need a vision for what you want to do.
If you don't have it yet, you can look through issues and try to address some.
If you do have a vision but want to hear more opinions on it, you can discuss it in a new Github issue or in Discord. The appropriate sub-channels are #mod-dev and #github-disccusion.

If you want to modify an existing GTNH mod, first find the correct repository and fork it on GitHub.

If you are not sure which repository contains a particular item or block, identify the mod first, then look it up in this spreadsheet. If there is no GitHub link listed, GTNH may be using the upstream mod without GTNH-specific changes. In that case, ask in Discord #mod-dev.

Once you have the correct repository:

1. Fork it on GitHub. When creating the fork, uncheck Copy the master branch only so the fork includes version tags. The build process uses these tags to determine the mod version; without them, it falls back to the latest commit hash. Some mods have minimum version checks, which can then fail on Minecraft load.
2. Clone your fork locally. Consider cloning with --filter=blob:none, especially for repositories with large histories such as GT5-Unofficial. This uses a partial clone: older file contents are not downloaded up front, and are fetched only on demand when you access them, which saves both disk space and clone time.

This path is for you if you want to develop a new mod.

See the ExampleMod README.md if the instructions below don't work.

1. Unzip project starter into project directory
2. Replace placeholders in LICENSE-template and rename it to LICENSE, or remove LICENSE-template and put any other license you like on your code. This is an permissive OSS project and we encourage you participate in OSS movement by having permissive license like one in template. You can find out pros and cons of OSS software in this article
3. Ensure your project is under VCS. For example initialize git repository by running git init; git commit --message "initialized repository"
4. Replace placeholders (edit values in gradle.properties, change example package and class names, etc.)
5. You are good to go!

1. Import the project into your IDE. We recommend IntelliJ IDEA, which has a free Community Edition.
   1. In IntelliJ IDEA, you can simply open the project folder. In Eclipse, import it as an existing Gradle project.
2. Run ./gradlew build to build the project.
3. If the build fails, check the console output. Common causes include outdated dependencies or Spotless issues. You can usually fix them with ./gradlew updateDependencies or ./gradlew spotlessApply respectively.

If you are unsure how to implement something, look for similar code in GTNH repositories.

Testing in a development environment is handy while you're still working on your changes, because it lets you quickly see the results and debug your code without spending most of your time loading mods you will not use during testing.

To get started, find the Run Client (Java 25, Hotswap) configuration in your IDE and run it. Running with debug and hotswap enabled is recommended, but not required. You also don't have to use Java 25: if you want to check whether your changes behave differently on Java 8, switch to the configuration without a Java version in its name.

It is important to make sure your changes work in the full pack, especially if you changed something that may affect other mods.

1. Build the project with ./gradlew build.
2. In build/libs, find the jar without any suffixes other than -dirty. This suffix does not appear if you committed all your changes before building the jar.
3. Download the latest dev build and import it into the launcher of your choice. We recommend Prism Launcher.
4. Replace the target mod with your built jar, or add it if it is a new mod.
5. Launch the pack and verify that your changes work as expected.

• If your IDE reports missing stuff even after you run ./gradlew build, try deleting the build folder and running ./gradlew setupDecompWorkspace.
• Most mods require at least Java 25 to run the latest Gradle. If you have multiple Java versions installed, you may need to set the JAVA_HOME environment variable to your desired Java installation and configure the same Java version in your IDE.

If you want to avoid signing commits with your real name, then please refer to the page Managing Git Identities.

1. Find something to contribute.
2. Fork the needed repos.
3. Test your changes thoroughly. If you change something, understand the changed class or method in order to understand what to test.
4. Push code into your fork.
5. Open a pull request against master branch and provide a description on what it changes/adds/removes. Include pictures/graphs if necessary. If there is a related issue, link it.
6. Address review problems. Resolve merge conflicts. Wait for the final merge. During this period, your PR might be merged into dev branch manually by project admins, on a case by case basis. If that happens, your changes will go into one of the dailies for border testing. There is no strict rules over whether this merge-into-dev will happen at all, and it's usually not needed anyway. It is expected that the original author fixes any issues that arise from their contributions.

Please do not make multiple changes/features in a single PR, make a separate PR for each. If they depend on each other, you can leave a note in the PR's description.

If you are not sure how to fork and open pull requests, read this gist by Chaser324.

• You can find the Code of Conduct of the GTNH dev community here.
• See which GTNH mods are supported outside of the modpack and see an overview of licenses in this spreadsheet.
• For the GTNH Code Style guidelines please see the dedicated page Code Style.
• For quest development, read the Quests Development Guide.
• The StructureLib documentation can be found here. Use this for your multiblock structures.
• To understand how chemical formulas are balanced in recipes, read Chemical Balance.

All applications that are grouped together can do about the same. This does not mean that you can pick any one of them, as they differ in functionality, style, performance and customizability. It is recommended you look at what they can do and try each one out, so you can decide which application you want to use for which use case.

Additionally, if you choose JetBrains IntelliJ IDEA as your IDE, there are some plugins that can be very helpful in some ways

• Minecraft Development: Autocompletion for mixin development, builtin NBT editor, minecraft project project type in new project window, and a bunch more small utility. Notice that for GTNH specifically you will want the fork maintained by eigenraven. We use RFG as the build tool and that one unfortunately is not compatible with the original version available on the plugin marketplace. Follow the install instructions in README of that fork.
• ASM Bytecode Viewer: Very helpful plugin for asm development. Can also be occasionally helpful for mixin development. Notice that there are multiple plugins with similiar name and near identical purpose, with one of them being a bundled one from JetBrains. The JetBrains one is slightly wonky and doesn't display ASMified code. The plugin suggested here works perfectly and can display ASMified code. If in doubt whether you got the correct plugin, here is a direct link: https://plugins.jetbrains.com/plugin/10302-asm-bytecode-viewer. To use this plugin, focus on any opened Java editor tab (either it's decompiled library class without attached source, library class with attached source, or your own source files), then click ASM Bytecode Viewer in Code menu. The action is also available via Search Everything under the same name. For your own source files, it will trigger a project build to ensure .class files are up to date.
• Single Hotswap: Allows hotswapping just a single file when using the runClient task with Hotswap & Debug mode. IntelliJ's built-in feature "Compile and Reload" always reloads every single file that is referenced by the target class, which can take a while for bigger classes. This plugin gives better control what exactly you want to hotswap, decreasing hotswap times by a factor of 50^[1]. Notice that you will need to disable the "Use Built-In Compiler" feature in the settings under "File > Settings > Build, Execution, Deployment > Debugger > Single Hotswap". To use this plugin, while running in debug mode with hotswapping enabled, open the class you want to swap and click the Hammer icon in the top right (next to the Pause, Restart, and Stop icons).

Set up launch config:

1. Select the project you want to debug
2. Click the drop-down menu next to the debug symbol -> Debug configurations...
3. Select "Remote Java Application"
4. Click "New launch configuration" (top left)
5. Change the port to 5005
6. Click "Apply"

Actually debug:

1. Launch the game with --debug-jvm (I do this from the terminal)
2. Wait until it says "Listening for transport dt_socket at address: 5005"
3. Debug with the launch config you created (you may have to go into the debug configurations menu again, if it doesnt show up in the drop-down yet)
4. Change to the "Debug" view (button in the top-right corner). There may be a window popping up asking if you want to go there
5. Done!

Not every wiki/tutorial/article/... listed here contains information about Minecraft version 1.7.10 but some topics haven't changed much and often the general methodology is the same. The newer the version, the less comparable the inner workings of Minecraft/Forge are to 1.7.10.

Use Ctrl+F if you look for something specific.

You can look at the source-code of most mods included in GTNH here.

OpenGL resources:

• [1] - a good C++ tutorial for opengl
• [2] - another step-by-step opengl c++ tutorial
• [3] - lwjgl3 tutorial book about 3d gamedev with code samples
• [4] - a short, but useful tutorial into modern opengl's rendering pipeline
• [5] - a lot of useful diagrams and linear algebra for 3d rendering with opengl
• [6] - a lot of example LWJGL3 programs showing off implementations of various rendering techniques, it's a small gold mine

Reference docs:

• [7] - nice site to search&view khronos's official docs
• [8] - a cheat sheet you can print out with the full opengl API

More advanced stuff:

• [9] - Raytracing in a Weekend series, teaches you a lot about computer graphics (beware, raytracing != rasterization which is what opengl uses, but most of the math still applies)
• [10] - a blogpost on 1 efficient method of batching drawcalls for performance
• [11] a great blog from an AMD gpu driver developer, lots of valuable info here

Search for GDC, AMD, NVIDIA and AMD talks on youtube about rendering topics too Super advanced stuff:

• [12] - a series of blogposts going really deep into how GPUs work
• [13] - the full instruction set architecture doc for AMD GCN3 GPUs, useful to understand what kind of machine code GPUs actually execute

Random non-rendering stuff: https://gameprogrammingpatterns.com/contents.html - a book (available for free online) about common patterns in game code

• Mathematics on StackExchange: Forum for everything related to Mathematics
• StackOverflow: Forum for everything related to Programming
• #mod-dev (GTNH Discord)
• modding-help (Legacy Modding Discord)
• #mod-dev (Modded Minecraft Discord)
• #mod-development (Minecraft Pack Development Discord)
• #mc-dev (CurseForge Discord)
• #help-modded-java (Blockbench Discord)

Sometimes you want to make cross-mod changes. In order to make use of code changed locally from another mod, use maven local.

• Run publishToMavenLocal for your dependency mod. Setting environment variable VERSION allows you to publish it with specified tag, like 99.99.99
• Add mavenLocal() to your repositories.gradle in your dependent mod, and change dependencies.gradle to your desired version.

Note that this doesn't work on GitHub, so in order to pass CI, you need to publish pre tag online. If you're not in the GTNH team, ask others to publish it.

Hotswap allows you to reflect code changes without relaunching the game. Use 1b. Run Client (Java 17, Hotswap) or 2b. Run Server (Java 17, Hotswap) to launch the game, and use Run > Debugging Actions > Reload Changed Classes to hotswap.

The following table shows if a source dependency - later called the Source - you included in Your Mod is visible to Your Mod and the mods that depend on Your Mod. For instance, implementation makes the Source visible to Your Mod at compile and runtime, but only at runtime to the Dependent mods, meaning that the Dependent mods are not able to use a class from Your Mod if it implements an interface from the Source. There are also test versions of some, you probably just want testImplementation.

You can also read document on ExampleMod repository for details.

These are some useful JVM flags for development purposes. A full, detailed list can be found in the table below.

• -Dmixin.debug=true Enable Mixin Debug
• -Dmixin.debug.verbose=true Verbose Debug Messages
• -Dmixin.debug.export=true Export classes after mixins have been applied. If you include fernflower in your classpath, or copy org.jetbrains.fernflower into your mixin jar the exported classes will be decompiled
• -Dmixin.debug.countInjections=true Throw an error if the injection count doesn't match expectations
• -Dlegacy.debugClassLoading=true Class Load Debugging
• -Dlegacy.debugClassLoading=true -Dlegacy.debugClassLoadingFiner=true -Dlegacy.debugClassLoadingSave=true Dump classes to ./RFB_CLASS_DUMP
• -Dfml.debugAccessTransformer=true Enable debug logging of access transformers

• Get post transform obfuscated class bytes: add -Dlegacy.debugClassLoading=true -Dlegacy.debugClassLoadingSave=true to JVM args and launch game. Be sure to enter the world and have the items you want to test to be spawned in game, or else the class you want to debug might not be loaded at all. find CLASSLOADER_TEMP in .minecraft folder. Delete every empty .class file (e.g. find . -empty -delete). Zip everything inside to a zip file and rename it to have a .jar suffix instead.
• Add the .jar you just created as a library in an empty IntelliJ project. You can do it via Maven/Gradle if you want the hassle, or you can directly add it in project settings.
• add -agentlib:jdwp=transport=dt_socket,server=y,suspend=y,address=5005 to wait for a debugger to be attached to the game before running code, put this in launcher args to debug the full pack
• In IntelliJ, use Run->Attach to process to attach the debugger to the running instance.
• Set breakpoints: line breakpoints mostly don't work as line numbers are most probably messed up. You need to rely on method breakpoints instead

If you're working on GUI features, this page could be useful: ModularUI

When fixing bugs or testing new features in-game, the right tools can save a lot of time.