Wave the code and make oneFire-Starting Magic Wand

Mission · Let’s see the final effect first

This is not a picture of a magic stick, it's about letting a player operate to really change the game world.

Imagine: you walk to the grass, holding a small orange-red wand in your hand, aim at the square at your feet and click the left button. The code first confirms "whether it is a magic wand" like a gatekeeper, and then checks whether the player has the permission to modify it. Only when all are passed, the server will replace the target block with flames and let nearby players hear the sound of fire bombs. This small effect also connects the four most important lines in the Fabric module: registry, player events, client and server, and resource files.

Version truth·Subject to template

Read the project's version statement first, and then decide which JDK to install; don't guess based on "1.20 should be...".

This tutorial is checked line by line C:\TeacherMa\Mod\maik-template-1.20. Its target game is Minecraft 1.20, using Yarn 1.20+build.1, Fabric Loader 0.18.4, Fabric API 0.83.0+1.20 and Loom 1.14.10. More notably, the template is build.gradle Set explicitly in release = 21, and fabric.mod.json Requirements java >= 21So this class uses JDK 21.

After opening IntelliJ, set the Project SDK to JDK 21 in Project Structure; in Settings → Build Tools → Gradle, point the Gradle JVM to the same set of JDK 21, and keep Distribution using Wrapper. Then execute in the project root directory:

java -version
javac -version
./gradlew.bat build

This template has actually been cleanly built, all 10 Gradle tasks have been completed, and the final display BUILD SUCCESSFUL. Let the original project succeed first, and then start changing the code. This is the most time-saving debugging method.

Flow · Understand the casting chain at a glance

The fire will not start immediately after left-clicking. The code has to go through three "levels".

Every exit in the flow chart has meaning. Ordinary items go PASS, which is equivalent to telling Fabric: "This is not my business. Please continue with the logic of Minecraft." Bystander or player without permission to change it. FAIL, indicating that the action was categorically rejected. The world is really changed only when you have a magic stick, permission to do so, and come to the server end. Such a layer would prevent the wand from taking all of its things away from the left key, as well as preventing the client from creating an instant “false flame”.

File map · Know the way first and then write the code

The project is small, but Java has its own room for each of the resources and game data.

src/main/java Put the operation logic;assets/maik Put name, model and texture;data/maik Put the synthetic formula. Here's maik is the Mod ID, which is also the resource namespace. As long as the path is accidentally written as magic,Maik or another name, the code may still compile, but the game will not be able to find the corresponding resource.

maik-template-1.20/
├─ build.gradle
├─ gradle.properties
├─ gradlew.bat
└─ src/main/
   ├─ java/com/malaoshi/maik/
   │  ├─ Maik.java
   │  ├─ item/
   │  │  └─ ModItems.java
   │  └─ event/
   │     └─ MagicWandEvents.java
   └─ resources/
      ├─ fabric.mod.json
      ├─ assets/maik/
      │  ├─ lang/
      │  │  ├─ zh_cn.json
      │  │  └─ en_us.json
      │  ├─ models/item/magic_wand.json
      │  └─ textures/item/magic_wand.png
      └─ data/maik/recipes/magic_wand.json

Entrypoint · Main switch

Maik.java It is not responsible for casting spells, it is responsible for connecting the two systems to power.

fabric.mod.json Put com.malaoshi.maik.Maik Declared as the main entrance. Fabric Loader is called when creating a module onInitialize(). Here, the items and inventory are registered first, and then the attack block event is registered. Think of the entrance class as the stage manager of a theater: it doesn't play the magician himself, but it does make sure the actors, lighting, and sound effects are in place.

package com.malaoshi.maik;

import com.malaoshi.maik.event.MagicWandEvents;
import com.malaoshi.maik.item.ModItems;
import net.fabricmc.api.ModInitializer;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;

public class Maik implements ModInitializer {
    public static final String MOD_ID = "maik";
    public static final Logger LOGGER = LoggerFactory.getLogger(MOD_ID);

    @Override
    public void onInitialize() {
        ModItems.register();
        MagicWandEvents.register();
        LOGGER.info("Maik mod initialized");
    }
}

MOD_ID Define only once, other classes pass Maik.MOD_ID Using it, spelling forks caused by handwritten strings can be reduced. Logs also use the same ID; read in the future run/logs/latest.log , it is easy to see which row comes from your module.

Registry · Issue "ID card" to the magic wand

ModItems.java Do two things: register the item, and put it into the creative mode category.

package com.malaoshi.maik.item;

import com.malaoshi.maik.Maik;
import net.fabricmc.fabric.api.itemgroup.v1.ItemGroupEvents;
import net.minecraft.item.Item;
import net.minecraft.item.ItemGroups;
import net.minecraft.registry.Registries;
import net.minecraft.registry.Registry;
import net.minecraft.util.Identifier;

public final class ModItems {
    public static final Item MAGIC_WAND = Registry.register(
            Registries.ITEM,
            new Identifier(Maik.MOD_ID, "magic_wand"),
            new Item(new Item.Settings().maxCount(1))
    );

    private ModItems() {
    }

    public static void register() {
        ItemGroupEvents.modifyEntriesEvent(ItemGroups.TOOLS)
                .register(entries -> entries.add(MAGIC_WAND));
    }
}

If the item group code is missing,/give @s maik:magic_wand Still possible to succeed; if missed Registry.register, so that the translation, model and formula are beautiful and no object can be connected. It is important to distinguish between "if there's this item in the game" and "if there's a show of it in the creation bar" when you're wrong.

Spell logic · Where the magic happens

The real mantra is not a sentence setBlockState, but a complete security check.

package com.malaoshi.maik.event;

import com.malaoshi.maik.item.ModItems;
import net.fabricmc.fabric.api.event.player.AttackBlockCallback;
import net.minecraft.block.Block;
import net.minecraft.block.Blocks;
import net.minecraft.sound.SoundCategory;
import net.minecraft.sound.SoundEvents;
import net.minecraft.util.ActionResult;

public final class MagicWandEvents {
    private MagicWandEvents() {
    }

    public static void register() {
        AttackBlockCallback.EVENT.register((player, world, hand, pos, direction) -> {
            if (!player.getStackInHand(hand).isOf(ModItems.MAGIC_WAND)) {
                return ActionResult.PASS;
            }

            if (player.isSpectator() || !world.canPlayerModifyAt(player, pos)) {
                return ActionResult.FAIL;
            }

            if (!world.isClient) {
                world.setBlockState(pos, Blocks.FIRE.getDefaultState(), Block.NOTIFY_ALL);
                world.playSound(
                        null,
                        pos,
                        SoundEvents.ITEM_FIRECHARGE_USE,
                        SoundCategory.BLOCKS,
                        1.0F,
                        1.0F
                );
            }

            return ActionResult.SUCCESS;
        });
    }
}

The first step: what is monitored is the "attack block", so the operation is the left button

AttackBlockCallback Fires when the player attempts to attack a block. The callback hands us five pieces of on-site information:player Who is operating,world Which world is it?hand Which hand is it?pos is the position of the targeted block,direction is the surface clicked on. The current template is not in use direction, because it directly replaces the blocks that are clicked on instead of generating a fire next to them.

The second step: If it is not a magic wand, then immediately PASS

player.getStackInHand(hand) Obtain the handheld stack that triggered this action,isOf(ModItems.MAGIC_WAND) Determine whether it is the registered magic wand. An exclamation point before a condition means "isn't". Return PASS After that, Fabric will allow other listeners or the original game to continue processing, and players who use pickaxes to mine or play blocks with bare hands will not be hijacked by magic logic.

The third step: bystanders and unauthorized positions cannot cast spells

player.isSpectator() Preventing bystanders from changing the world;world.canPlayerModifyAt(player, pos) Whether the player can modify the target will be determined based on game rules and location permissions. Return if any condition is not met FAIL. This is not a redundant courtesy check: server spawn protection, adventure play, or other permission systems may rely on it.

The fourth step: world modification is only performed on the server side

There are also clients and logical servers inside the single-player world of Minecraft. The client is responsible for the graphics and input, and the server has the authoritative world state.if (!world.isClient) means that only the server side performs block replacement and sound broadcasting. If both sides are changed, repeated actions may occur; if only the client is changed, the player will see the fire first, and then suddenly recover after the server synchronizes, like a failed illusion.

Step 5: Replace the target block itself with flames

world.setBlockState(pos, Blocks.FIRE.getDefaultState(), Block.NOTIFY_ALL) What is used is exactly pos, so the original square would be replaced instead of putting an extra fire on the surface.Block.NOTIFY_ALL Requires that the blocks be updated and synchronized to the client. Whether the flame will persist depends on the surrounding squares and the original fire rules; if the target position is not suitable, the fire may quickly go out.

The sixth step: the sound is broadcast by the server

playSound is null, which means there are no players that need to be excluded. A nearby player can hear you. BLOCKSThe volume and the tone. 1.0F. The picture and sound appear at the same time, and the feedback from the magic wand will have a more "magical feeling" than quietly changing blocks.

Texture pipeline · From ID to pixel

Java only tells the game "there is a magic wand"; what it looks like is completed by a three-layer resource relay.

Original texture·Original engineering map

32×32 transparent PNG, small pixels but complete information

The original image is only 32×32 pixels, and the file name is magic_wand.png. The orange-red wand unfolds diagonally, with a bright highlight at the tip, and a transparent area that allows it to naturally stack in the inventory and in the player's hand. The preview area uses nearest neighbor enlargement, so each pixel remains a clear square instead of being wiped out by the browser into a blurry block of color.

When making your own version, keep the transparent background, use PNG, and avoid saving the file as hidden magic_wand.png.png. Minecraft supports larger textures, but sizes like 16×16, 32×32, and 64×64 make it easier to maintain the original pixel style.

Model: Tell the game to draw in "handheld tool" mode

{
  "parent": "minecraft:item/handheld",
  "textures": {
    "layer0": "maik:item/magic_wand"
  }
}

minecraft:item/handheld A tool suitable for a sword, axe, wand and so on.layer0 is not written The value of assets, do not write textures, nor write .png;resource systems will maik:item/magic_wand Automatic Translation assets/maik/textures/item/magic_wand.png.

Translation: Let the registration ID become a name that readers can understand

{
  "item.maik.magic_wand": "魔法棒"
}

{
  "item.maik.magic_wand": "Magic Wand"
}

The format of the item translation key is item.命名空间.路径. If the game shows original keys item.maik.magic_wand, which indicates that the item registration has been successful. The problem is only the path to the language file, the filename, the JSON syntax or the current game language. Do not change Java 's registration code backwards.

Recipe · Give players a route to obtain

A portion of flame powder, two wooden sticks, and a staff with a flame core placed vertically.

Flame powder
B wooden stick
S wooden stick
S

→

Magic stick x 1
maik:magic_wand

{
  "type": "minecraft:crafting_shaped",
  "pattern": [
    " B ",
    " S ",
    " S "
  ],
  "key": {
    "B": { "item": "minecraft:blaze_powder" },
    "S": { "item": "minecraft:stick" }
  },
  "result": {
    "item": "maik:magic_wand"
  }
}

pattern are also counted as grids, so the three-line string must maintain three characters. First person and third person perspective inB and S It is just the internal code of the formula, letters can be changed, but it must be consistent with key Correspond. The result uses the full registration ID. This recipe belongs to data, because the server needs to know what the player puts in the material and what it produces; the sticker belongs to assetsBecause it's responsible for showing.

Run & verify · Hierarchical acceptance

Don't just look at "the game is on"; use four pieces of evidence to confirm that each layer is really connected.

./gradlew.bat build
./gradlew.bat runClient

/give @s maik:magic_wand

Real operation effect: the magic wand has ignited the blocks in the game

The following is not a conceptual diagram, nor is it a later-synthesized rendering. We use this lesson maik-template-1.20 The project started the real Fabric 1.20 development client, entered the creative mode test world, and maik:magic_wand Place it in the first space of the shortcut bar, and then press the left button on the nether rock block in the center. After the event callback passes the handheld object and permission check, the server replaces the target block with flames; the screenshot is taken by pressing the game directly while the effect is still running. F2 key to save.

Debug clinic · Find levels by symptoms

Only pursue the first root cause at a time; do not change Java, JSON, version and directory at the same time.

Creative extensions · Turn examples into gameplay

First make the mildest improvement: keep the target block and only set fire to the clicked side.

Callback has been provided direction, which indicates which side of the square is in the player's point. If you move the target position in this direction, you get a position next to the surface. For example, click on top of the ground.pos.offset(direction) It is the air grid above the ground. With the addition of air checks, magic wands will no longer eat rocks, chests, or building blocks directly.

BlockPos firePos = pos.offset(direction);

if (world.getBlockState(firePos).isAir()) {
    world.setBlockState(
            firePos,
            Blocks.FIRE.getDefaultState(),
            Block.NOTIFY_ALL
    );
    world.playSound(
            null,
            firePos,
            SoundEvents.ITEM_FIRECHARGE_USE,
            SoundCategory.BLOCKS,
            1.0F,
            1.0F
    );
}

When using this code, import net.minecraft.util.math.BlockPos. After expansion, verify again in the order of "Compile → Start → Test World → Ordinary Item Control". Don't add cooldown, durability, and particles at the same time, otherwise it will be difficult to tell which step caused an error.

Three-minute self-test

Build & deliver · Generate installable modules

After the test world passes, a clean build is performed to turn the source code into the final JAR.

./gradlew.bat clean build

After the construction has been successful, the finished product is located build/libs/maik-1.0.0.jar. in the same directory maik-1.0.0-sources.jar It is a source code package, which is convenient for reading or development. It is not a module file that ordinary players need to install. Put the finished product into a client instance that matches Minecraft 1.20, Fabric Loader, and Fabric API mods folder and start with the backed up test world first.