<!-- skill: Minecraft Mod | version: 1.0.0 | description: Build Minecraft Java mods with NeoForge — items, blocks, events | category: Games -->

## Instructions
- Use NeoForge (modern Forge) with its MDK (mod dev kit) + Gradle. Target a specific Minecraft version and don't mix versions.
- Java 17+ (MC 1.20+) — match the Java version to the MC version or nothing compiles.
- Register everything through `DeferredRegister` (items, blocks, entities) in the mod event bus — never static-init game objects.
- One class per item/block + a `ModItems`/`ModBlocks` registry class; datagen for models/lang/loot tables where possible.
- Test in the dev client (`./gradlew runClient`) before touching servers; check `logs/latest.log` on crash.
- Client-only code (screens, keybinds) goes behind `Dist.CLIENT` checks or a client package — servers crash on it.

## Examples
- Ruby item: `ModItems` registers `ruby` + `ruby_sword`, English lang entry, generated item model.
- Chorus! block: block + blockitem + loot table dropping itself.

## Workflows
1. Download MDK for the target MC version, rename packages, `./gradlew build` to verify the toolchain.
2. Add item/block classes + registry entries + lang + models.
3. `runClient`, verify in creative inventory, fix crashes from the log.
4. Datagen run for models/lang/loot (`runData`), commit generated files.
5. Build jar (`./gradlew build`) → `build/libs/` → test in a real instance.

## Templates
```java
// ModItems.java — deferred registration pattern
public class ModItems {
    public static final DeferredRegister.Items ITEMS =
        DeferredRegister.createItems(MyMod.MODID);
    public static final DeferredItem<Item> RUBY =
        ITEMS.register("ruby", () -> new Item(new Item.Properties()));
}
```

## Tools
- Needs JDK 17+ and Gradle (MDK wrapper included).
- SARAH `shell_run` for `./gradlew` builds; read `logs/latest.log` via file tools on crash.

## Advanced
- Data that sticks around: capabilities/attachments for per-player/per-item state (never static Maps — they leak across worlds and break on servers).
- Networking: custom packets via the built-in payload system for client↔server sync (cooldowns, GUIs); mark `flow` correctly (clientbound/serverbound), keep packets tiny.
- Content data: tags (`data/.../tags/`) for cross-mod compatibility, recipes + loot tables via datagen, advancements for progression hooks.
- Creative tabs, tooltips (`appendHoverText`), and item properties (food, durability, cooldowns) make content feel vanilla.
- Debug like a pro: runClient + runServer both, read `latest.log`/`debug.log` (the `Caused by` line is the truth), `--refresh-dependencies` when Gradle acts haunted.
- Ship it: jar in `build/libs`, test on a DEDICATED server (singleplayer hides sided bugs), publish on Modrinth + CurseForge with dependency list and MC version matrix.

## Documentation
- NeoForge docs: https://docs.neoforged.net
- MDK: https://github.com/neoforged/MDK