Introduction: Why Does SUSY Exist?

Supersymmetry is a Minecraft modpack for 1.12.2 based around GregTech! But if you're here reading this, you probably already know that. What makes Supersymmetry any different from all those other packs?

Supersymmetry fundamentally chooses realism.

We believe that science can create engaging, interesting gameplay, and that there is a target audience of people who would be interested in playing a game based around the basic rules of the universe. The main reason why one would want to develop this modpack is because one wants to get modded Minecraft players interested not only in STEM, but the scientific method itself. No modpack strives as much to change the worldview of its audience for the better than Supersymmetry.

Supersymmetry creates an immersive industrial atmosphere for its players.

From the setting and lore of the game to the function and design of its machines, Supersymmetry attempts to create a cohesive brutalist and industrial backdrop for players to create on top of. We seek to create immersion through combat, lore, and adventure, and we seek to use Supersymmetry to combine GregTech progression with the steady conquest of outer space.

Supersymmetry is not afraid to take its time.

While releases for Supersymmetry do occur every two weeks, us developers perform large quantities of research into the scientific literature to inform our gameplay. We also take care to iteratively develop our game design in response to feedback from the community.

If you are interested in contributing to a modpack committed to realism, atmosphere, and quality, you are free to join us.

Contributing

This particular chapter introduces you to how you might begin making your first contributions to Supersymmetry. There are a few prerequisites that would be helpful for you to know, however:

• How to perform basic file operations on a personal computer
• How to install programs
• Some basic coding knowledge (especially in Java or other C-style programs)
• Collaborative Git/GitHub knowledge (commits, branches, merging, pull requests)

We unfortunately will not be able to comment on the first three in this guide, but if you don't know about GitHub, we can absolutely help with that.

If you already know how to use Git/GitHub, you can skip to Getting Started right away. Otherwise, the next section has some basic information on the essentials of Git/GitHub for contributing to the modpack.

Git for Dummies

Welcome to this short crash course on Git.

Why Git?

Git is what is known as a version control system, a piece of software that, as the name suggests, tracks "versions" of files. This is useful in that it allows many developers to coordinate development on a project without the need for extensive communication; edit your piece of the code, save it, and use Git to let everyone know about what you did. Additionally, having easy access to historical versions of a codebase streamlines bug-fixing and allows quick reversion to previous versions.

Git can be compared, in a way, to a "Wikipedia-style" editing methodology for filebases.

A particular strength of Git is its distributed nature, meaning that every person who works on a codebase using Git will have the entire codebase and its history stored locally. This further strengthens offline development and allows users to quickly make and review edits, as well as promoting greater accessibility for others to work on projects. This doesn't necessarily mean that there is no need for centralization; projects using distributed version control frequently use a central location to store data (e.g. GitHub).

Common Version Control Terminology

An example of a version control history tree. Sourced from https://commons.wikimedia.org/wiki/File:Revision_controlled_project_visualization.svg

Repository

A repository refers to a data structure storing metadata that points towards a file or directory structure.

You can think of this as a labeled list of all files along with a complete history of modifications to these files.

Branch

A branch is an independent separation of the codebase from another repository. This can also be referred to as a fork.

You can think of this as making a copy of another repository for separate development.

Commit

A commit can either be used to refer to a changeset as an object, or can be used to refer to make changes into a repository.

You can think of this as either talking about a specific change when used as a noun, or as a verb, changing something that is reflected in the repository.

Push

"Push" copies changes from one repository to another, initiated by the source repository.

Pull

"Pull" does the same as push but is initiated by the reciepient repository.

Pull request

A pull request asks a source repository to combine the revisions made in a separately developed repository. This is referred to as merging. Pull requests frequently involve discussion of the request.

Fetch

"Fetch" is identical to pull conceptually, however the git fetch command is behaviorally different from git pull as it does not automatically merge changes into your working branch.

Merge

Merge operations apply two sets of changes to file(s).

You can think of this as combining changes into a codebase.

Resolve

Resolve is a user intervention addressing change conflicts to a file.

Clone

"Clone" is creating a new repository using another repository as your base.

You can think of this as copying another repository for yourself.

Others

A more complete list can be found here.

Getting Started

Find your respective download of Git here.

Access the Git Command Line Interface (Git CLI). You should set a uniform username for your commits using a global flag, like below:

git config --global user.name "USERNAME"

GitHub (which Supersymmetry uses) prefers that you also set a commit email address to link your commits with your GitHub account.

git config --global user.email "EMAIL"

You can verify this information like so:

$ git config --global user.name
USERNAME

$ git config --global user.email
EMAIL

You may additionally authenticate with GitHub for security and ease of use reasons. You can use either GitHub CLI or Git Credential Manager (GCM).

If you would rather use a token-based authentication method, you may generate a GitHub personal access token. This can substitute your password when prompted by Git.

VSCode also supports Git integration and allows you to authenticate through the IDE.

If none of the above authentication methods are used, Git will prompt you for your GitHub password every time you do an action that requires authentication.

All of the above fall under the umbrella of HTTPS authentication. SSH can also be used for authentication.

Congratulations! You are ready to use Git.

Contributing to Supersymmetry

Download an instance of Supersymmetry from GitHub and import it into a Minecraft launcher (e.g. Prism Launcher).

Create a fork of Supersymmetry for your own development needs. This can be done through your web browser, desktop GitHub client, or the GitHub CLI.

Clone the forked repository. Point your instance path at the cloned repository. You can then run Python and packwiz to download the necessary mods for running the client.

If you would like to sync your repository with the upstream Supersymmetry repository, you can run:

git remote add upstream https://github.com/SymmetricDevs/Supersymmetry 

You can then run:

git pull upstream BRANCH

To pull the changes from the Supersymmetry repository. Running a regular git pull origin BRANCH command will pull from your forked repository. Usually this branch will be main. Usually, we try to make one branch for each PR, and it helps to avoid using the parent branch's name. You can make a new branch from your current position like so:

git switch -c <branch-name>

You can now edit files within your instance directory as you see fit.

In order to now commit your changes back to your forked repository, you must first add files to be included in the commit. This is known as staging your changes. You can do this via the command:

git add FILE

You can add the -all or -A flag to indicate you want to commit all files. After adding files, you may commit them via:

git commit -m COMMIT_MESSAGE

Then push your changes to GitHub by using the command:

git push origin BRANCH

Once pushed, you may make a pull request on the Supersymmetry repository with your commits.

Happy contributing!

Getting Started

What do I work on?

As an aspiring SUSY developer, there are a few channels of information you can look at to see what to work on:

• On the official Discord server, the #workorders channel has plenty of small tasks for you to choose from of varying difficulty.
  • #bug-discussions and #bug-reports can also be useful for getting ideas, or just lurk in #susy-general.
• If you don't want to join the Discord (fair), you can also look at the GitHub issues page for Supersymmetry (or Susy-Core). These issues may be rather difficult to fix, however.

Some easy starting tasks I would recommend are editing a quest, changing a recipe, or adding a new multiblock. Once you've selected a task, you'll need to clone a repository. You can learn more about the various repositories that we work on in Supersymmetry Projects, but the basics are:

• If you want to tweak the configurations of mods or change/add basic items and recipes, you'll want to use our main repository, SymmetricDevs/Supersymmetry. We'll comment more on how to set up this repository in the main modpack section.
• If you instead want to work with creating new multiblocks or other more complex features, you'll want to work on the core mod, which is found at SymmetricDevs/Susy-Core. More information on this is contained in the Susy-Core section.

Main Modpack Structure

In this guide, we use the term "main modpack" to refer to the repository SymmetricDevs/Supersymmetry for disambiguation.

Setting up SymmetricDevs/Supersymmetry

Most basic code-oriented text editors work fine for the main modpack, but Visual Studio Code works well enough. Once you've installed it, pick "Clone Git Repository" on the start screen, click "Clone from GitHub" in the small popup, and type in SymmetricDevs/Supersymmetry.

The Supersymmetry repository uses several Python scripts for making ZIPped instances and formatting quests. You may download Python here.

Testing Supersymmetry on PrismLauncher

You can test in-development versions of Supersymmetry by downloading an instance of Supersymmetry on PrismLauncher and then making one of the following modifications to the instance's folder:

• Replacing the groovy, resources, structures, and config/betterquesting folders manually from your main modpack repository
• Create virtual folder links to those repository folders. On Linux, the command to make such a "symlink" is: ln -s "REPOSITORY ORIGINAL FOLDER LOCATION" "INSTANCE SYMLINK LOCATION"

If you're working with a branch requiring mod versions not found in any particular release of Supersymmetry yet (e.g. you're trying to update mods), you can change those mod versions manually, or you can rebuild the main modpack through packwiz (as described below), import it into PrismLauncher, and just copy its mods folder into your favorite test instance.

You may also have to replace Susy-Core with your own compiled jar in certain cases if you want to test changes in it.

Where is everything?

Making instance ZIPs

The modpack development cycle primarily works around building the modpack through a program called packwiz. Packwiz creates the ZIP files that can be imported into modpack launchers like PrismLauncher or ATLauncher. The Supersymmetry repository wraps packwiz using Python, which you'll need if you want to use packwiz most efficiently. You may download Python here.

Once you've downloaded Python, you may now build the pack. Open any command terminal to the directory in which the Supersymmetry repository is copied, and then run the following command:

Windows: python3 build\main.py -c

Linux: python3 build/main.py -c

(You may need to modify the above command based on what your Python command is named. Common names include python, python3, and various python3.x.)

Once you've performed this command, look in the buildOut folder to see your client.zip! You may now import this into the modpack launcher of your choice. If you want a server instance, remove the -c argument in the command.

Changing mods

The mod version info itself is managed by packwiz itself in the /mods/ folder, where you'll see a lot of .toml files. You probably won't have to change them directly, except rarely to change the "side" field to "client" or "server" for client-only or server-only mods.

To work with it, use the packwiz file through the command line. It has a decent help menu, but the most important command is packwiz cf add [CURSEFORGE URL OR MOD SLUG], which allows you to add or update a mod directly. The mod slug is just the name in a CurseForge URL, like "ae2-extended-life", and using it automatically selects the latest version that works.

Questing

The questline files are all contained within /config/betterquesting, including the questline text (the English text is in /config/betterquesting/resources/supersymmetry/lang/en_us.lang). More information can be found in the dedicated quest-writing guide.

Items/Recipes

For scripting in the main modpack, we use the mod GroovyScript. It's like CraftTweaker if you've used that before. It uses the Groovy language for its scripts, but it's nearly identical to Java, so if you know Java, it's very easy to pick up.

What makes GroovyScript (GrS) so good is that you can reload certain scripts within the game itself with the command /gs reload! This only works for the scripts in /groovy/prePostInit and /groovy/postInit, as everything else is baked into the game too early to reload, but those two folders do contain almost every recipe in SUSY.

Most items and fluids are defined in /groovy/material through materials that generate many different items at once: e.g. the bronze material helps register bronze dust, bronze screws, liquid bronze, etc. Items that cannot be defined through materials are instead registered in /preInit/RegisterMetaItems.groovy, where each is given a static ID.

In order to give your materials and custom items actual names, you'll need to translate them in /resources/langfiles/lang. Other helpful locations include /groovy/globals, which contains some helper classes (such as carbon sources), while /preInit/ChangeFlags.groovy allows one to modify GTCEu-defined materials.

More information on how to make recipes is contained in the recipe guide.

IntelliJ IDEA for Susy-Core

To set up Susy-Core, we recommend installing IntelliJ IDEA Community Edition and the Java 8 JDK (which IntelliJ can help you install). Once you do this, you can create a new IDEA project by cloning one of our repositories. In fact, there is an option to directly clone a repository and set up a project on the IDEA launch page.

In order to actually clone it, you will want to select "Project from Version Control" in IDEA.

You can then navigate to the repository you want to clone in your browser and copy this URL found under the "Code" button:

Inserting that into the URL field in IDEA and then setting the main repository folder will start the process of downloading it onto your computer.

Working with SymmetricDevs/Susy-Core

Susy-Core also has a build system known as Gradle (as is used for the majority of Minecraft mods).

Once you've cloned and entered the repository in IntelliJ IDEA, look for a notification in the bottom right that tells you to "Load Gradle Project." Once you click it, it will configure a set of commands you can use to test Susy-Core in a minimal environment. You can look for some particularly common ones in the top-right corner:

Selecting any of these will override the selected top-line command "Setup Workspace," allowing you to work more efficiently. Below are some important Gradle "run configurations" for you to know.

It is also possible to interface with Gradle over the command line, either by using ./gradlew to call commands or by using a system installation. We advise using a Gradle version of 8.9 with Java 21.0.2 at the current moment. To view all tasks from the command line, use gradle tasks.

2. Run Client

This particular command starts a client instance of Minecraft including Susy-Core and a few other mods required to load it (including GregTech and JEI). If you want to debug Susy-Core, you can click the green bug icon you see here:

Careful tracing of the code in debugging mode, involving setting breakpoints, going step-by-step through each line, and looking for points before the glitch has necessarily occurred are essential for finding and fixing bugs.

6. Build Jars

This command builds a set of JAR files in the build/libs folder. After navigating there, you'll notice quite a few files:

However, the only one that can be brought into your modpack's mods folder without issue is the one that does NOT have dev at the end of the name (the first one in the picture above). The others are deobfuscated files that only work with IntelliJ IDEA, and they will crash your game if you try to use them in a real modpack instance. (Also, I recommend clearing out this folder before running the command as to not get confused about which version to pick.)

Where is everything?

Most of the useful programming in the Supersymmetry mod is located in src/main/java/supersymmetry. We'll go over the most important folders there first, before covering the rest of the project structure.

/common

The common folder covers systems that both the Minecraft client and the Minecraft server need to use. If you're unfamiliar with these concepts, you can reference this link. Anyway, the common folder contains things such as advancements, blocks, entities, items, tile entities, meta-tile entities, UI widgets, etc.

/common/items

Items in many mods for Minecraft versions 1.12.2 and earlier have to contend with the item limit: the base game has a limited number of numerical IDs (4,096) it can give to items.

GregTechCEu addresses this problem by indexing special items called metaitems using the itemDamage field, packing many "items" into one item ID. Minecraft 1.12.2 allows for up to 32,768 different values for durability, and each one can be given its own texture, behavior, and so on, making it a very flexible system. Susy-Core leverages this system for its own purposes, creating several of its own metaitems.

As such, most "items" in Susy-Core are declared and initialized in common/item/SusyMetaItems.java, and a very similar metaitem is declared in the GroovyScript files for the modpack repository (RegisterMetaitems.groovy). In SusyMetaItems.java, each metaitem is declared as a MetaValueItem and is initialized in the method initMetaItem.

Note that the IDs given to each MetaValueItem are unique and must not be changed. As Minecraft only stores the itemDamage for each item, shifting MetaValueItem IDs around would cause items with one damage value to mutate into whatever happened to be given that same damage value in the next version. That is, you get massive amounts of item transmutation!

/common/metatileentities

Tile entities are not physical entities, despite the name. Instead, they represent systems that are attached and saved alongside a block. For example, in vanilla Minecraft, signs, furnaces, crafting tables, and beds have tile entities attached to them (that is, they implement ITileEntityProvider). As such, their job is to handle rendering, saves, and client-server communication.

However, we rarely use tile entities directly: we instead use meta-tile entities.

Meta-tile entities from GTCEu implement common features that are useful to many GregTech machines, solving the same limited-ID problem for tile entities as metaitems do for items. They are implemented similarly to GregTech-based tile entities, but they inherit from MetaTileEntity. They are registered in common/metatileentities/SuSyMetaTileEntities.java with unique IDs. MetaTileEntities can be given specialized UIs, and they can even represent special multiblocks!

Project Structure

There are many, many different parts of the Supersymmetry project! These are some of the code bases that you can help contribute to:

GitHub Repositories

Supersymmetry

This is the main repository for the modpack! It contains configuration files for the modpack. This is where you'd contribute to the questbook, update recipes, add mods, etc.

Susy-Core

This repository contains the principal Java code for the modpack. It also contains all of the assets of the modpack. We use RetroFuturaGradle for the compilation.

Supercritical

This repository has our custom fission reactor implementation. It contains nuclear-relevant recipes, items, multiblocks, and textures.

Dev-Docs

This repository contains the documentation for these projects as well as tutorials and tips for how to contribute! You can also press the edit button in the top-right corner if you want to start editing a page.

RecipeViewer

This repository stores a Vite website and a few NPM scripts that allow players to view recipes without launching the game. This is mostly vibe-coded, but it does need maintenance in terms of replacing recipedump.json.gz for each game version. Contact bruberu for more information.

There are also a few projects of note from outside the SymmetricDevs organization.

GregTech

This is the mod that underpins our entire project! As of writing this (30 Jul 2026), this mod is still being ported to a new UI library, ModularUI. Help on this project makes our code more stable and efficient, and it attracts further attention to this version.

Modern Supersymmetry

In the future, it is planned to port Supersymmetry to modern versions of Minecraft, primarily for the higher level of support and attention that comes with it. However, as of writing this (30 Jul 2026), most of the developers working on this are busy with other tasks. Currently, work is planned to shift to this version more once LuV tier is reached. MCTian-mi has made quite a bit of progress with porting Supercritical and some Susy-Core multiblocks to 1.20 (version not final).

Guides

Writing Quests

Quests are provided through Better Questing Unofficial.

If you just need to edit a quest, the language files for our quests are stored in config/betterquesting/resources/supersymmetry/lang, which are easier to edit directly for fixing small errors, especially with a list of Minecraft formatting codes handy. build/questbook.py also saves your quest text here.

To create a quest, one uses /bq_admin edit to toggle editing mode, and then one can freely edit the quests from there. Anyone working with this must run /bq_admin default save to record the quest data to the files. You may also have to copy the /config/betterquesting folder back to your repository folder if it is not already linked.

There are a few other things to know when editing quests:

The mod BQuTweaker allows images and links to be embedded into quests:

• To add links, use this format: {Embed}TypeLink;<WebsiteLink>;<DisplayWidth>;<DisplayHeight>;<ButtonText>{Embed}
• As for images, use this: TypeImage;<ResourceLocation>;<DisplayWidth>;<DisplayHeight>;<ImageWidth>;<ImageHeight>{Embed}

To edit quest lines and quests, look in the lower left-hand part of the chapter-viewing interface:

Writing Recipes

Most recipes in SUSY are written using GroovyScript, a scripting mod like CraftTweaker that works off of the Groovy language. It's very similar to Java, with just a few extra nice syntax changes. Here's an example recipe:

MIXER.recipeBuilder()
        .fluidInputs(fluid('fermented_biomass') * 1000)
        .inputs(ore('nutrientPhosphorous'))
        .outputs(metaitem('fertilizer') * 5)
        .EUt(30)
        .duration(100)
        .buildAndRegister()

Clearly, this is a mixer recipe for making fertilizer, but let's break down what it does more precisely and how you would be able to make this yourself.

MIXER stands for the mixer recipe map: a group of recipes that specific machines can run broadly. Of course, like in Java, it's not defined from nowhere; it's actually an import:

import static prePostInit.Recipemaps.*

As every GroovyScript file is defined in /groovy/, one can just take a quick peek at /groovy/prePostInit/Recipemaps.groovy to see where it's defined (press Ctrl-P to navigate to a file quickly in VS Code):

MIXER = recipemap('mixer')

The "mixer" string is just an identifier defined by GregTechCEu itself. The recipemap function should strike you as being odd, however. If you look around, it's not defined in the file or imported! So where did it come from?

GroovyScript actually allows mod authors to provide special functions to give priority access to their code, such as this code in GTCEu defining recipemap to just call a function getting a recipe map. Several more such "Groovy extensions" are also used throughout the rest of the above example!

Well, anyway, now that we have our recipe map, we need to produce a recipe builder from it. The term "builder" refers to the builder pattern, the fact that we call multiple functions to help initialize a recipe (rather than use an unwieldy constructor). To get our builder, we call recipeBuilder on the recipe map.

The next line adds a fluid input to the recipe with the fluidInputs method. The fermented_biomass string passed into fluid is the name of that fluid itself. To find the correct fluid name, one can use the /gs hand command in-game as such:

Here's a quick reference to the various methods on a recipe builder:

.fluidInputs(

Conveniently, the voltage requirement of the recipe is determined by the EUt method.

Materials

Items that exist as a variant of a material are specified by the ore function with a string argument consisting of an ore prefix and a material, such as nutrientPhosphorous, foilPlastic, dustSilver, etc.

Material definitions and initializations can be found in groovy/material, and importantly, most of them contain sub-materials. SuSyMaterials.groovy defines all materials defined by the modpack and calls their initialization functions. Within FirstDegreeMaterials.groovy, the high-purity elements and materials that depend only on elements are initialized. SecondDegreeMaterials.groovy contains materials that depend on materials within FirstDegreeMaterials.groovy, and so on to avoid nasty errors. Materials of unknown or complex composition are initialized in UnknownCompositionMaterials.groovy. Sometimes, one needs to initialize materials in Susy-Core.

Metaitems

Metaitems can be thought of as individual item variants with unlocalized names and numerical IDs, meaning that one does have to be careful when merging. They are set up in SusyMetaItems.java, along with their tooltips and stack size.

Creating Multiblocks

A multiblock is implemented as a MetaTileEntity (GregTech's buffed tile entities). Therefore, all multiblocks have a controller block. However, we do not suggest that you use a MetaTileEntity superclass for most multiblocks. Usually, a RecipeMapMultiblockController or a MultiblockWithDisplayBase is what you want as the superclass.

When using a RecipeMapMultiblockController, you must create a field of SusyRecipeMaps and initialize it with a name to begin registering recipes in GroovyScript. The initialization is used to set up the GUI and the associated sounds. This is convenient, because appropriate recipe logic can be set up immediately based on the type argument.

For a MultiblockWithDisplayBase, the recipe system and GUI are customizable to a greater extent, but you will have to create them yourself.

Here is an example implementation of createStructurePattern for a launch pad.

Multiblock Parts