Spindle Loader

Spindle is a forward-only Java 25 mod loader project with Minecraft treated as a target layer, not as the loader's foundation. The broader Spindle Ecosystem keeps the loader boundary distinct from Minecraft-specific target work.

Today the repository contains a stable runtime-facing loader API, a target-neutral loader core, CLI wiring, and a partial Minecraft Target Layer for baseline Minecraft 26.2.

Status

• Loader runtime: stable for the current Runtime API-0 / Runtime-1 scope.
• Minecraft Target Layer: partial and intentionally narrow.
• SteelHook: internal only, with bounded proofs completed through SteelHook 1.0 and a narrow client title-screen branding transform.
• Public Minecraft modding API: not implemented yet.

Spindle is not currently a Fabric/Forge/NeoForge/Quilt compatibility layer, a gameplay API, a general client modding platform, a remapping stack, or a Java sandbox.

Repository Layout

Spindle repo
├─ spindle-loader-api/
│  └─ Stable runtime-facing public loader API
│
├─ spindle-loader-core/
│  └─ Target-neutral loader planning, diagnostics, security, classloading, lifecycle
│
├─ spindle-loader-cli/
│  └─ CLI entrypoint and provider wiring
│
├─ target-minecraft/
│  └─ Minecraft Target Layer, planning, bootstrap, SteelHook internals
│
├─ sample-game/
│  └─ Fake game provider fixture
│
├─ sample-mod/
│  └─ Basic sample mod
│
├─ sample-runtime-mod/
│  └─ Runtime API sample
│
├─ sample-server-fixture/
│  └─ Fake Minecraft server fixture
│
├─ sample-minecraft-mod/
│  └─ Guarded Minecraft bootstrap fixture mod
│
├─ docs/
│  └─ Architecture and mod-facing documentation
│
└─ backlog/
   └─ Longer-term notes

What Works Today

The loader side currently supports:

• loader.mod.json parsing for schema 1 and 2
• deterministic discovery, dependency resolution, frozen graphs, and lockfiles
• runtime contract validation and fail-closed gates before mod classloading
• deterministic diagnostics, trust, and quality reports
• loader-owned config, data, cache, and generated storage
• runtime config and deterministic service registry support
• stable public runtime-facing APIs in com.spindle.api.*

The Minecraft Target Layer currently supports:

• Minecraft artifact planning, cache/verification, and runtime boundary reporting
• deterministic runtime, integration, preflight, and reproducibility planning
• guarded fake-server bootstrap and offline replay flows
• a Prism-backed local server workflow through ./gradlew runSpindleMinecraftServer
• a Prism-backed local client workflow through ./gradlew runSpindleMinecraftClient
• a deterministic fake-server one-command proof through ./gradlew runSpindleMinecraftServerFixture
• concept-grounding architecture work for lifecycle, commands, resources/reload, and registry bootstrap
• internal SteelHook proof arcs through Target-40 / SteelHook 0.5
• first guarded SteelHook 1.0 runtime installation for server_tick_before
• first visible client branding proof: runSpindleMinecraftClient launches through a Spindle bootstrap classloader and rewrites the vanilla title-screen version text to include Spindle v0.1.0

SteelHook remains internal machinery. SteelHook 1.0 supports the first guarded server runtime transform for server_tick_before, and the client branding path uses the same bounded posture for one version-grounded TitleScreen string recipe. This does not expose public mod APIs, make SteelHook a public freeform bytecode editor, broadly transform Minecraft at runtime, or sandbox Java mod execution.

What Is Still Intentionally Missing

• public Minecraft gameplay APIs
• registry, command, networking, resource, world, entity, or client modding APIs
• general-purpose Minecraft runtime transformation
• compatibility shims for other loader ecosystems
• Java sandboxing for mods

com.spindle.api.minecraft.* remains a deferred placeholder area used by guarded bootstrap fixtures. It is not part of the stabilized loader API.

Build And Verification

Use Java 25 and the Gradle wrapper:

./gradlew spotlessApply
./gradlew spotlessCheck
./gradlew :spindle-loader-core:test

For changes touching Minecraft runtime planning, boundary reports, bootstrap execution, reproducibility, integration planning, or SteelHook/bootstrap behavior, also run:

./gradlew minecraftMegaMilestone7Check
./gradlew minecraftMilestone8Check

For a quick smoke check:

./gradlew validateMilestone0

For the current long-lived dedicated-server workflow:

./gradlew runSpindleMinecraftServer

By default this validates the Prism instance Spindle 26.2 under the normal Prism launcher root, prompts for EULA acceptance when needed, streams server output, and keeps the server attached until you type stop. Override with -PspindlePrismRoot=..., -PspindlePrismInstance=..., or -PspindleMinecraftVersion=....

For the current attached client workflow:

./gradlew runSpindleMinecraftClient

By default this validates the same Prism instance, launches the verified vanilla client through Spindle, applies the guarded title-screen branding transform, writes spindle.minecraft-client-launch-result.json and spindle.minecraft-client-branding-transform-result.json, and waits until Minecraft exits normally. Client mod execution and general client hooks are still future work.

On Windows, use gradlew.bat.

Do not run the real Mojang download or real server smoke tasks unless you explicitly want those networked/EULA-sensitive flows.

Key Docs

• Architecture Overview
• Minecraft Target Layer Architecture
• Minecraft Target Concept Roadmap
• SteelHook Strategy
• Loader API Docs
• Security And Trust Boundaries

Current Direction

Near-term work is still about strengthening deterministic runtime foundations and carefully grounding Minecraft-facing concepts before any public Minecraft modding API is exposed.

That means:

• keep loader-core target-neutral
• keep Minecraft-specific work in target-minecraft
• treat SteelHook as internal machinery, not a public API
• preserve deterministic reports, lockfiles, and fail-closed validation

License

Spindle is licensed under the Mozilla Public License 2.0. See LICENSE and NOTICE.