Fabric mods: writing Minecraft mod logic in Sprig
Sprig can take care of a mod's data model, state, saving and game logic, while the parts that talk to Minecraft and Fabric stay in Java. For a new project, start from the Fabric template that ships with the SDK; it already has the official dev.sprig Gradle plugin set up.
Needs v0.6.0-beta.1 or newer
The template and the Gradle plugin ship with the SDK starting with v0.6.0-beta.1. If sprig version shows an older version, run sprig upgrade first.
Start from the template
The SDK includes the template and the libraries/sprig-gradle plugin it uses. Set SPRIG_HOME to the SDK's root, then run:
cp -R "$SPRIG_HOME/libraries/sprig-fabric/template" ./my-mod
cd my-mod
./gradlew check
./gradlew build
./gradlew runClientThe template loads the plugin from the SDK, so you don't need to clone the Sprig repository or hard-code any path on your machine.
checkruns Sprig's static checks, the Sprig tests and the usual Java checks.buildgenerates and compiles the Java for your Sprig code, the runtime and the bridge code.runClientstarts the game client from that same generated output.
The only Sprig-specific setting in build.gradle picks the source set:
plugins {
id 'net.fabricmc.fabric-loom' version "${loom_version}"
id 'dev.sprig'
}
sprig {
targetSourceSet = 'main'
}Fabric dependencies, split source sets, the mod entry point and the Java version are all ordinary Loom configuration. The Sprig plugin compiles the bridge code, supplies the real classpath, generates sources, adds the mod's own copy of the runtime and hooks all of it into Gradle's build.
Who does what
| Path | What goes there |
|---|---|
src/main.spr | State and logic written in Sprig: the tick counter and a Wand item class that extends Item |
tests/*.spr | Project tests, run by sprigTest |
src/sprigBridge/java/ | A thin Java interface for Sprig to call; a Sprig class can also implement a Java interface or extend a Java class directly with conform (see the conformance reference) |
src/main/java/ | The Fabric main entry point, which registers the Sprig wand item |
src/client/java/ | The Fabric client entry point and callback registration |
build/generated/sprig/main/java/ | The generated Java, which you can read |
Gradle and Loom handle dependencies, source sets, javac and the jar. Sprig handles type checking, code generation, lock validation and the Sprig tests. The plugin connects the two. Dependencies never update by themselves: check and build only read the current sprig.lock, and only an explicit ./gradlew sprigResolve updates it.
Renaming the project, and living next to other Sprig mods
Fabric puts every mod in one class loader, so two mods can't have a class with the same name. That's why everything Sprig adds to your jar is in a package named after your project: the generated classes in sprig.user.<project>, and the mod's own copy of the runtime in sprig.user.<project>.runtime. The template's project is called sprig-fabric-counter, so its Java entry point calls Sprig like this:
CounterActions counter = sprig.user.sprig_fabric_counter.$M_main.fn$new_counter();- Change
nameinsprig.toml, then the package in Java.javacpoints at the two calls inSprigItems.javaandSprigCounterClient.javathat still use the old package, and./gradlew sprigInfoprints the new one. - Give each mod its own project name. Two mods with the same
nameget the same package. - Mods pass values to each other as Java types. Each mod has its own runtime, so one mod's Sprig
Listisn't another's. Pass aString, a number, or a Java interface both mods know.
Needs v0.9.0-beta.1 or newer
SDK v0.8.0-beta.1 and earlier generate every mod's classes into sprig.user, with the runtime in sprig.runtime, so two Sprig mods in one game have classes with the same names.
Top-level let and var in a mod
Nothing in the game "runs main.spr". Fabric calls the Java entry point, the entry point calls $M_main.fn$new_wand(...), and later Minecraft calls the wand's use. The first time Java calls into Sprig, the top-level statements of main.spr and of the modules it imports run first, and only once. So when you write this line at the top of a module:
let cooldown_ticks = 20every function and method of the mod reads 20, just as under sprig test.
- Make the first call from the mod's initializer, as the template does. The top-level statements have then finished before the game's other threads call the mod; while they're still running, a call from another thread doesn't wait for them.
- If a top-level statement throws, the call that started it is what fails, and Fabric reports it for that entry point. The statements don't run a second time.
- Read top-level variables through a Sprig function, not as a Java field such as
$M_main.cooldown_ticks: reading a field doesn't run the statements.
Gradle integration has the full details.
This describes the main branch
With SDK v0.9.0-beta.1 and earlier, the top-level statements don't run when a Java entry point calls a function directly, and top-level variables are null or 0. With one of those versions, call $M_main.$init() once in the entry point first (it declares throws Exception).
Tested versions
The template is tested with Minecraft 26.3, Fabric Loader 0.19.5, Fabric API 0.161.0+26.3, Fabric Loom 1.18.2, Gradle 9.7.1 and OpenJDK 26.0.1 (targeting Java 25). That's one combination that has actually been tested, not a promise that every Fabric or Loom version works.
Where this template came from
An earlier comparison used a Quest Board mod built twice with the same features: once in Java only, and once in Java plus Sprig. Both versions built and ran. The Java-only version had 707 lines of production code; the mixed version had 760, about 470 of them Sprig application logic.
What kept costing effort that time was the Gradle and Loom setup: compiling the Java bridge, exporting the client classpath, generating and registering Java code, adding the runtime and wiring up check. None of that was something missing from the Sprig language, so it became the plugin and this template.
That's the experience of a single project, with no time or token measurements, so it isn't a rigorous productivity comparison. And with the manual setup it needed back then, the Java-only version was the one picked in the end. The plugin removes the setup cost seen in that project. It does not prove that Sprig is more productive than Java. It only means a future comparison has fewer distractions that have nothing to do with the language.
For more details and limitations, see libraries/sprig-fabric/README.md and libraries/sprig-gradle/README.md.
