Your first mod

An item, a block, a recipe, a greeting and a command, already split into small files. You test it on a simulated server, without opening the game.

1. Create the mod

crafting new gems

gems/
├── main.craft
├── content/
│   ├── items.craft
│   ├── blocks.craft
│   └── recipes.craft
├── events/
│   └── welcome.craft
└── commands/
    └── gem.craft

main.craft only says what the mod is and which parts it has. Content goes in content/ and behaviour in events/ and commands/. Why it's laid out this way: Organizing a mod. With the VS Code extension you get errors and autocompletion as you type.

2. The files

mod "gems" { name: "gems", version: "1.0.0", author: "you" }

// What exists
import "content/items"
import "content/blocks"
import "content/recipes"

// What happens
import "events/welcome"
import "commands/gem"

item "magic_gem" { rarity: "rare", glint: true }

block "magic_block" {
    hardness: 3
    light: 10
    tool: "pickaxe"
    drops: "magic_gem"
}

recipe shaped "magic_block" {
    pattern: ["GGG", "GGG", "GGG"]
    keys: { G: "magic_gem" }
    result: "magic_block"
}

on join(e) {
    e.player.send("&aWelcome, {e.player.name}!")
}

command gem(target: player?) requires "gems.gem" {
    let p = target ?? player
    p.give(item("gems:magic_gem", 1))
    return "Gave a magic gem to {p.name}"
}

3. Check it

crafting check gems/main.craft

The checker follows imports. If something is wrong, it gives the file, the line and what it expected, for example welcome.craft:2: error: Player has no property 'helth'. Did you mean 'health'?.

4. Test it without the game

The sandbox is a simulated server with the same API as the real game. It starts in development mode: save a file and the mod reloads.

mkdir -p test/mods && cp -r gems test/mods/
crafting sandbox test

> join Steve
  [Steve] Welcome, Steve!
> op Steve
> as Steve /gem
  [Steve] Gave a magic gem to Steve
> inv Steve
  1x gems:magic_gem
> quit

5. Play it

Copy the gems folder to .minecraft/mods/ and open the Crafting 26.3 profile. The item texture goes in gems/textures/item/magic_gem.png and the block texture in gems/textures/block/magic_block.png. On a server, the mod goes on the server and on every client, because it adds blocks.

6. Grow it

Every new idea in its place: another item in content/items.craft, a new game rule in a new file under events/, a function used by several files in lib/, settings in settings.craft. The full example mod is in Organizing a mod.