Home › Minecraft mods (Fabric) › Minecraft Fabric mod CLAUDE.md

Minecraft Fabric mod CLAUDE.md

CLAUDE.md for Minecraft Java mods on Fabric: Gradle tasks, client/server separation, registries, minimal mixins, data generation, and version-pinned mappings.

Claude Code (CLAUDE.md)Minecraft mods (Fabric)

Copy CLAUDE.md

How to use

Save this as CLAUDE.md in your repository root, commit it, and your agent will pick it up automatically. Edit the commands to match your project.

Note: Review and test before use. Provided as is, without warranty. See Terms.

# CLAUDE.md: Minecraft Fabric mod

## Commands
- `./gradlew build` (jar in `build/libs/`) · `./gradlew runClient` / `./gradlew runServer` (dev environments) · `./gradlew runDatagen` if data generation is set up.
- Minecraft, Fabric Loader, Fabric API, Loom and mappings versions live in `gradle.properties`. Never bump them as a side effect; a version change is its own task.

## Structure
- Common entrypoint (`ModInitializer`) registers blocks, items, entities, sounds and networking payloads. Client-only code (renderers, screens, keybinds, HUD) goes in the `ClientModInitializer` and the client source set.
- Never reference client classes (`MinecraftClient`, rendering, screens) from common code; it crashes dedicated servers. Run `runServer` after touching shared code.
- Register through `Registry.register(Registries.X, Identifier.of(MOD_ID, "name"), obj)` (or the helper the repo already uses) in one place per content type. IDs are lowercase snake_case.
- Assets and data follow vanilla layout: `assets/<modid>/` (models, textures, lang) and `data/<modid>/` (recipes, loot tables, tags). Prefer data generators over handwritten JSON when the repo has datagen.
- All user-visible text goes through translation keys in `en_us.json`.

## Mixins
- Use Fabric API events and hooks first. A mixin is a last resort: target the narrowest method, prefer `@Inject` at a specific point over `@Overwrite` or `@Redirect`, and give each mixin class a comment explaining why no API covers it.
- Accessor/invoker mixins for private fields instead of reflection. Keep mixins in the `mixins.json` matching their side (client vs common).

## Networking and logic
- Server is authoritative: validate every client-to-server payload (player can reach the block, has the item, values in range).
- Don't do heavy work on the main thread every tick; cache, throttle, or move IO off-thread and hand results back via the server task queue.

## Done when
`./gradlew build` succeeds and you state whether `runClient`/`runServer` were launched (they need a display or may not run here).