Explain build script structure

buildSrc/build.gradle

@@ -2,19 +2,16 @@ plugins {
     id "groovy-gradle-plugin"
 }
 
+// Counterpart of settings.gradle file, sadly conventions can't use those defined repositories for some reason...
 repositories {
     gradlePluginPortal()
-    maven {
-        url = "https://repo.spongepowered.org/repository/maven-public/"
-    }
-    maven {
-        url = "https://jitpack.io/"
-    }
-    maven {
-        url = "https://files.minecraftforge.net/maven"
-    }
+
+    maven { url = "https://repo.spongepowered.org/repository/maven-public/" }
+    maven { url = "https://jitpack.io/" }
+    maven { url = "https://files.minecraftforge.net/maven" }
 }
 
+// Counterpart of settings.gradle file, sadly conventions can't use those defined plugins for some reason...
 dependencies {
     implementation "com.github.johnrengelman:shadow:7.1.2"
     implementation "net.minecraftforge.gradle:ForgeGradle:5.+"

buildSrc/src/main/groovy/viaforge.base-conventions.gradle

@@ -2,11 +2,14 @@ plugins {
     id "java-library"
 }
 
+// We define the configuration here so we can use it across all conventions and platforms
+// To define which projects/source files should be included in the jar
 configurations {
     include
     implementation.extendsFrom(include)
 }
 
+// Repositories for the ViaVersion dependencies defined below
 repositories {
     maven {
         url = "https://repo.spongepowered.org/repository/maven-public"
@@ -16,6 +19,7 @@ repositories {
     }
 }
 
+// Including all required libraries for ViaVersion {for version numbers see gradle.properties}
 dependencies {
     include "com.viaversion:viaversion:${project.viaversion_version}"
     include "com.viaversion:viabackwards:${project.viabackwards_version}"

buildSrc/src/main/groovy/viaforge.conflicting-conventions.gradle

@@ -2,6 +2,8 @@ plugins {
     id "viaforge.shadow-conventions"
 }
 
+// Get rid of the services folder, since Forge 1.16+ would conflict with some of the ForgeDev Environment's services
+// And since we don't need them for Mixins anyway, we can just exclude them from the shadowJar
 shadowJar {
-    exclude("META-INF/services/**")
+    exclude "META-INF/services/**"
 }

buildSrc/src/main/groovy/viaforge.forge-conventions.gradle

@@ -1,6 +1,7 @@
 plugins {
     id "net.minecraftforge.gradle"
     id "org.spongepowered.mixin"
+
     id "viaforge.shadow-conventions"
 }
 
@@ -15,8 +16,8 @@ minecraft {
             // mixin
             property "mixin.debug.export", "true"
             property "mixin.hotSwap", "true"
-            property "fml.coreMods.load", "de.florianmichael.viaforge.mixin.MixinLoader"
-            args '-mixin.config=' + 'mixins.' + project.getProperty('maven_name') + ".json"
+            property "fml.coreMods.load", "de.florianmichael.viaforge.mixin.MixinLoader" // Only required for MC 1.12, but modern Forges skips this anyway
+            args "-mixin.config=" + "mixins." + project.getProperty('maven_name') + ".json"
 
             // source set
             mods {
@@ -33,12 +34,12 @@ sourceSets.main.resources {
 }
 
 dependencies {
-    include "org.spongepowered:mixin:0.8.3"
-    include "org.slf4j:slf4j-api:${project.slf4j_version}"
+    include "org.spongepowered:mixin:${mixin_version}"
+    include "org.slf4j:slf4j-api:${slf4j_version}"
 
-    annotationProcessor "org.spongepowered:mixin:0.8.3:processor"
+    annotationProcessor "org.spongepowered:mixin:${mixin_version}:processor"
 
-    include project(":")
+    include project(":") // Include the base project, to get Common-ViaForge
 }
 
 mixin {
@@ -56,8 +57,8 @@ jar {
             "Implementation-Timestamp": new Date().format("yyyy-MM-dd"-"HH:mm:ssZ"),
             "TweakClass": "org.spongepowered.asm.launch.MixinTweaker",
             "TweakOrder": "0",
-            "FMLCorePluginContainsFMLMod": "true",
-            "FMLCorePlugin": "de.florianmichael.viaforge.mixin.MixinLoader",
+            "FMLCorePluginContainsFMLMod": "true", // Only required for MC 1.12, but modern Forges skips this anyway
+            "FMLCorePlugin": "de.florianmichael.viaforge.mixin.MixinLoader", // Counterpart to the above
             "MixinConfigs": "mixins.${maven_name}.json",
             "ForceLoadAsMod": "true"
     )
@@ -66,9 +67,10 @@ jar {
 
 shadowJar {
     archiveFileName = jar.archiveFileName
-    configurations = [project.configurations.include]
+    configurations = [project.configurations.include] // Include the dependencies from the include configuration
     duplicatesStrategy DuplicatesStrategy.EXCLUDE
 
+    // Prevent conflicts with Forge's weird service loading
     exclude("META-INF/maven/**")
     exclude("META-INF/versions/**")
 }

buildSrc/src/main/groovy/viaforge.modern-conventions.gradle

@@ -3,4 +3,5 @@ plugins {
     id "viaforge.conflicting-conventions"
 }
 
+// Minecraft 1.17+ required Java 16/17 to compile
 java.toolchain.languageVersion = JavaLanguageVersion.of(17)

buildSrc/src/main/groovy/viaforge.shadow-conventions.gradle

@@ -1,14 +1,18 @@
 plugins {
+    id "viaforge.base-conventions" // Include the base conventions, to get the dependencies
+
     id "com.github.johnrengelman.shadow"
-    id "viaforge.base-conventions"
 }
 
+// Define the jar output attributes for all platforms
 archivesBaseName = project.maven_name
 version = maven_version + "-" + project.mc_version
 group = maven_group
 
 compileJava.options.encoding = "UTF-8"
 
+// Replace the version in the mcmod.info and mods.toml files with the project version
+// Since this depends on the platform version, we can't define it in the global scope :(
 processResources {
     inputs.property "version", project.version
 

settings.gradle

@@ -9,6 +9,7 @@ pluginManagement {
         maven { url = "https://files.minecraftforge.net/maven" }
     }
 
+    // If you update these versions, also update the versions in buildSrc/build.gradle
     plugins {
         id "com.github.johnrengelman.shadow" version "7.1.2"
         id "net.minecraftforge.gradle" version "5.+"