Repository navigation
workflow
Use this flow for normal code, build, and template changes.
Before editing, answer these questions from the repository:
- Which Minecraft versions are affected?
- Which loaders are affected: Fabric, LexForge, NeoForge, or all?
- Is the change shared across all versions, one Minecraft version, or one loader project?
- Does it touch only runtime code, or also config, metadata, build logic, CI, or release behavior?
Check settings.gradle.kts for the project list in the repository you are
editing. Directory names that are not included there are not build participants.
Use the narrowest correct location:
- Put cross-version shared Java in
common/src/main. - Put cross-version shared config declarations in
common/src/config. - Put one-version shared Java in
<mc>/common/src/main. - Put one-version shared config helpers in
<mc>/common/src/config. - Put loader startup code in
<mc>/fabric,<mc>/forge, or<mc>/neo. - Put Fabric client-only code in
<mc>/fabric/src/client. - Put loader client config UI code in
src/configClientwhere that project has the source set. - Put generated metadata shape in
src/main/templates. - Put build behavior in
buildSrc/src/main/kotlinunless it is truly unique to one subproject.
Search before changing:
rg "symbol_or_property_name"
rg --files '<mc>/fabric' '<mc>/forge' '<mc>/neo' '<mc>/common' commonFor repeated version/loader files, inspect at least one older Forge project, one Fabric project, and one NeoForge project when applicable. Keep names, packages, and source set layout consistent with nearby examples.
Keep edits small and paired:
- If code references a shared API, update every version-specific implementation that must compile against it.
- If metadata values change, prefer
gradle.propertiesover template rewrites. - If metadata structure changes, update the relevant template and convention plugin inputs together.
- If adding dependencies, update the relevant subproject
build.gradle.ktsand version property orlibs.versions.tomlentry. Use the dependency table indocs/README.mdto choose between compile, local runtime, CI runtime staging, and production metadata changes. - If adding a project, update
settings.gradle.ktsand make sure the project name follows<mc>-<loader>or<mc>-common, with its directory under<mc>/<loader>or<mc>/common.
Do not edit generated build outputs.
Run the narrowest build first:
./gradlew :<project>:buildExamples:
./gradlew :1.20.1-fabric:build
./gradlew :1.20.1-forge:build
./gradlew :26.1-neo:buildFor shared changes, build representative downstream projects:
./gradlew :1.18.2-forge:build :1.20.1-fabric:build :26.1-neo:buildFor CI matrix or project inclusion changes:
./gradlew --configuration-cache --no-daemon writeCiBuildMatrix
cat build/ci/build-matrix.jsonFor Forge or NeoForge game test server support:
./gradlew :<forge-or-neo-project>:runGameTestServerFor older projects that do not support runGameTestServer, use a server smoke
test:
mkdir -p <project>/run
printf 'eula=true\n' > <project>/run/eula.txt
printf 'stop\n' | ./gradlew :<project>:runServer 2>&1 | tee runServer.log
grep -E '\[Server thread/INFO\].*Stopping server$' runServer.logThe GitHub Build workflow derives platform projects from that repository's
settings.gradle.kts, excluding common and *-common. A platform project
must have:
- a valid
minecraftVersion; - a loader suffix of
fabric,forge, orneo; - a matching
<minecraftVersion>-commonproject; - a numeric
javaVersionwhen set; - buildable jars under the configured project directory's
build/libs; - optional runtime jars staged by
collectCiRuntimeMods.
Run writeCiBuildMatrix whenever those assumptions might have changed.
Before handing off:
- Run
git status --short. - Confirm only intended files changed.
- State which verification commands passed or could not be run.
- Mention any project/version/loader combinations that were not verified.