Introduction to Grimmix Workspace Setup

You probably have already noticed links for workspace setup examples in the README of this project, but in case you didn't - here they are:

• For 1.7.10: https://github.com/Aizistral-Studios/ForgeWorkspaceSetup/tree/1.7.10-grimmix
• For 1.12.2: https://github.com/Aizistral-Studios/ForgeWorkspaceSetup/tree/1.12.2-grimmix

As we all know, an example is worth a thousand words and everything. However, if you want to integrate Grimoire in your pre-existing workspace without starting with a blank template, and somehow have trouble understanding what does what in the example setup - the rest of this article is for you.

In the Beginning, There Were Shenanigans

To make things as nice and clean as possible and to save you from having to erect and abomination alike this in your buildscript, we have designed a special Gradle plugin that takes care of almost everything that needs to be done in order to get Mixin and Grimoire itself properly working in your workspace. Bearing the proud name of Grimoire Shenanigans, it serves as both a tool in our toolchain and symbol of our supremacy. Should you find yourself interested to learn more about its capabilities, you can head over and check its repository, but you don't have to if you don't feel like.

The steps for adding it to your build are quite simple:

1. Add https://github.com/juanmuscaria/maven/raw/master repository to repositories in your buildscript block (if it's not there yet);
2. Add Grimoire Shenanigans dependency in dependencies block still within the buildscript, for instance like this:

classpath 'com.integral.grimoire:GrimoireShenanigans:[1.5.3,)'

3. Apply grimoire-shenanigans plugin somewhere after forge;
4. Head over to your gradle.properties, or create some if you don't have yet. Here you want to define one property in particular: mixinRefmapName, which will reflect the name of your refmap. For instance: mixinRefmapName=supermod.refmap.json, or mixinRefmapName=mixinstuff/supermod.refmap.json if you don't feel like placing it in the root of your jar. Be sure to check out that you use this same refmap in your mixin configuration, and proceed;
5. Run IDE-specific task to set up a project for it, either eclipse or idea;
6. You're done! Now the Grimoire itself is placed in the list of your libraries, and everything it requires is configured and ready to be used.

Yes, now you can go and open your IDE, and have fun making your mixins go brrrrr... as soon as you check out another article explaining how to make them go brrrr properly: Introduction to Mixin Configuration Management

Phew. That was almost easy, right? Right?... Alright, I sure enough am aware that not all of you have got it. And since I have spent many more hours of my life than I really should have trying to make this Grimoire thing as accessible for everyone as realistically possible, might as well spend a couple more.

Step-by-Step Guide

So, suppose you start with a build.gradle file that looks something like this:

buildscript {
    repositories {
        mavenCentral()
        maven {
            name = "forge"
            url = "http://files.minecraftforge.net/maven"
        }
        maven {
            name = "sonatype"
            url = "https://oss.sonatype.org/content/repositories/snapshots/"
        }
    }
    dependencies {
        classpath 'net.minecraftforge.gradle:ForgeGradle:1.2-SNAPSHOT'
    }
}

apply plugin: 'forge'

version = "1.0"
group= "com.yourname.modid"
archivesBaseName = "modid"

minecraft {
    version = "1.7.10-10.13.4.1614-1.7.10"
    runDir = "eclipse"
}

dependencies {
	// NO-OP
}

processResources {
    inputs.property "version", project.version
    inputs.property "mcversion", project.minecraft.version

    from(sourceSets.main.resources.srcDirs) {
        include 'mcmod.info'
        expand 'version':project.version, 'mcversion':project.minecraft.version
    }
        
    from(sourceSets.main.resources.srcDirs) {
        exclude 'mcmod.info'
    }
}

It might be different depending on whether or not you are using my particular fork of ForgeGradle (which you really should be), but in that case things will only be simpler for you. Here we assume the default case of more or less pristine buildscript shipped with latest 1.7.10 versions of Forge. If you're on the 1.12.2, and/or have some extra business going on in that little file of yours - don't worry, steps will be exactly the same, what we do here is really just for the purpose of demonstration.

1. Adding repository

For now we only care about the buildscript block, which is this one:

buildscript {
    repositories {
        mavenCentral()
        maven {
            name = "forge"
            url = "http://files.minecraftforge.net/maven"
        }
        maven {
            name = "sonatype"
            url = "https://oss.sonatype.org/content/repositories/snapshots/"
        }
    }
    dependencies {
        classpath 'net.minecraftforge.gradle:ForgeGradle:1.2-SNAPSHOT'
    }
}

Let's go ahead and add our previously mentioned https://github.com/juanmuscaria/maven/raw/master repository to this block. All we really do is just stick it among other repositories declared in there, like forge or sonatype:

buildscript {
    repositories {
        mavenCentral()
        maven {
            name = "forge"
            url = "http://files.minecraftforge.net/maven"
        }
        maven {
            name = "sonatype"
            url = "https://oss.sonatype.org/content/repositories/snapshots/"
        }
        maven {
            name = "github"
            url = "https://github.com/juanmuscaria/maven/raw/master"
        }
    }
    dependencies {
        classpath 'net.minecraftforge.gradle:ForgeGradle:1.2-SNAPSHOT'
    }
}

Easy does it! If anything the github thing is completely arbitrary, you can name that repository however you want. Try fantabulouspony or covidneverends if you want to increase the fun without affecting utility.

2. Adding plugin dependency

Now it's time to actually declare the dependency for Grimoire Shenanigans plugin. Not gonna keep you too busy on this, for all you really need to do is stick a single line of code into dependecies block within the buildscript block:

buildscript {
    repositories {
        mavenCentral()
        maven {
            name = "forge"
            url = "http://files.minecraftforge.net/maven"
        }
        maven {
            name = "sonatype"
            url = "https://oss.sonatype.org/content/repositories/snapshots/"
        }
        maven {
            name = "github"
            url = "https://github.com/juanmuscaria/maven/raw/master"
        }
    }
    dependencies {
        classpath 'net.minecraftforge.gradle:ForgeGradle:1.2-SNAPSHOT'
	classpath 'com.integral.grimoire:GrimoireShenanigans:[1.5.3,)'
    }
}

It's not quite neccesary to have exactly [1.5.3,) after last colon, you can put just 1.5.3 or really any valid version of Grimoire Shenanigans if you know what you're doing. The [,) part however ensures that if a plugin version more modern than 1.5.3 is available, it will automatically be used without you having to go and edit your build.gradle once again.

3. Applying the plugin

Even simpler than previous step. Take a look at this part of our example build.gradle:

...
}

apply plugin: 'forge'

version = "1.0"
...

We want to apply Grimoire Shenanigans just after applying the forge plugin. And thus we do:

...
}

apply plugin: 'forge'
apply plugin: 'grimoire-shenanigans'

version = "1.0"
...

4. Defining Mixin refmap name

Ooooh, here comes the tough part. If you're modding on 1.7.10 or 1.12.2 with one of the default MDK distributions, the most likely case is that there is no such thing as gradle.properties anywhere to be seen within your project. However, this is easily rectified - you just create it yourself! Of course, I am not going to show you how to create files; consider increasing your computer literacy before trying to make mods in case you don't know how that's done.

The only things you need to keep in mind is to name your newborn file exactly gradle.properties, and place it in the exact same directory as build.gradle file. Then open it using text editor of your choice, and witness perfect, pristine, untainted canvas that no human or machine have had a chance to tamper with yet. I recommend admiring it within two to three hours, but you might want to adjust that time depending on your tastes.

Unfortunately, soon as your time elapses you shall have to singlehandedly murder sheer beauty and innocence in front of you, by spilling unholy machine-parsable writings upon it, ones that may read something like this:

mixinRefmapName=supermod.refmap.json

...it might appear like a single tiny line, but the havoc is sown, and damage is already beyond repair. From this moment on there is no way back, and no penance shall cleanse your soul of horrendous sin you have unsuspectingly committed. You shall live on knowing that the day of reckoning shall come - as inexorably as the Sun shall rise upon the sky in an early hour.

In an instance if you already have gradle.properties file in your project, things are quite a bit simpler - just append that mixinRefmapName=supermod.refmap.json line at the end of your existing file. Once again, the supermod.refmap part is completely arbitrary, and you can name your refmap however you feel like. Just don't forget to actually specify it right in your mixin configuration .json, and you'll be good.

5. Executing IDE-specific setup task

This final step is about as simple as it gets. Depending on your OS you will want to open either a Windows-command-line or Linux-terminal, but in the end you will be doing the exact same thing regradless of the case. Type in either gradlew idea, in case you follow the path of the many, or gradlew eclipse if you embraced the path of the few. Wait for it... and it's done!

Probably. Unless you encountered some error during command execution, or screwed something in the buildscript during your previous steps. Worst case - you can always jump over to our Discord server, and we will send you some help.