NeoForge 物品开发教程

neoforge源码/
├── net/neoforged/neoforge/
│   ├── registries/          ← 注册系统（最重要！）
│   │   ├── DeferredRegister.java
│   │   ├── DeferredHolder.java
│   │   ├── DeferredItem.java
│   │   └── RegisterEvent.java
│   ├── event/               ← 游戏事件
│   │   └── BuildCreativeModeTabContentsEvent.java
│   └── client/
│       └── event/           ← 客户端事件（渲染、模型等）
│           └── ModelEvent.java

/**
 * A helper class to aid in registering objects to modded and
 * {@linkplain BuiltInRegistries vanilla registries} and
 * provide deferred suppliers to access those objects.
 * ...
 */
public class DeferredRegister<T> {

// 在 DeferredRegister.java 第 142 行
public static DeferredRegister.Items createItems(String modid) {
    return new Items(modid);
}

/**
 * Fired for each registry when it is ready to have modded objects registered.
 * This event is fired for all builtin registries from vanilla and mods.
 * This event is fired on the mod-specific event bus, on both logical sides.
 */
public class RegisterEvent extends Event implements IModBusEvent {

// 第 60 行
protected DeferredItem(ResourceKey<Item> key) {
    super(key);  // 调用父类 DeferredHolder 的构造函数
}

public class DeferredItem<T extends Item> extends DeferredHolder<Item, T> implements ItemLike {

protected DeferredHolder(ResourceKey<R> key) {
    this.key = Objects.requireNonNull(key);
    this.bind(false);  // 尝试立即绑定到注册表
}

// 注册一个简单物品，使用默认属性
public DeferredItem<Item> registerSimpleItem(String name, Item.Properties props) {
    return this.registerItem(name, Item::new, props);
}

new Item.Properties()
    .stacksTo(64)          // 最大堆叠数量
    .durability(100)       // 耐久度（设置后不可堆叠）
    .fireResistant()       // 防火
    .rarity(Rarity.RARE)   // 稀有度（影响物品名颜色）

// 源码第 52-77 行的示例代码（直接从 Javadoc 提取）
private static final DeferredRegister.Items ITEMS = DeferredRegister.createItems(MODID);
private static final DeferredRegister.Blocks BLOCKS = DeferredRegister.createBlocks(MODID);

// 注册简单物品
public static final DeferredItem<BlockItem> ROCK_ITEM = 
    ITEMS.registerSimpleBlockItem(ROCK_BLOCK, new Item.Properties());

// 注册自定义物品
public static final DeferredItem<SpecialRockItem> SPECIAL_ROCK_ITEM = 
    ITEMS.register("special_rock",
        () -> new SpecialRockItem(SPECIAL_ROCK_BLOCK.get(), new Item.Properties()));

public ExampleMod(IEventBus modBus) {
    ITEMS.register(modBus);   // 必须调用！
    BLOCKS.register(modBus);
}

// 第 438-440 行
public static class Items extends DeferredRegister<Item> {
    protected Items(String namespace) {
        super(Registries.ITEM, namespace);  // 固定注册到 ITEM 注册表
    }

// DeferredRegister.java 第 209-223 行
public <I extends T> DeferredHolder<T, I> register(
        final String name, 
        final Function<ResourceLocation, ? extends I> func) {
    
    // 防止在 RegisterEvent 之后注册
    if (seenRegisterEvent)
        throw new IllegalStateException("Cannot register new entries to DeferredRegister after RegisterEvent has been fired.");
    
    // 自动拼接命名空间：modid:name
    final ResourceLocation key = ResourceLocation.fromNamespaceAndPath(namespace, name);
    
    // 创建 DeferredHolder 并存入列表
    DeferredHolder<T, I> ret = createHolder(this.registryKey, key);
    entries.putIfAbsent(ret, () -> func.apply(key));
    
    return ret;
}

src/main/java/com/yourmod/
├── YourMod.java              ← 主类（Mod 入口）
└── item/
    └── ModItems.java         ← 物品注册类

src/main/resources/
├── META-INF/
│   └── neoforge.mods.toml    ← Mod 配置文件
└── assets/yourmod/
    ├── lang/
    │   └── zh_cn.json        ← 中文翻译
    ├── models/
    │   └── item/
    │       └── my_item.json  ← 物品模型
    └── textures/
        └── item/
            └── my_item.png   ← 物品贴图

// src/main/java/com/yourmod/item/ModItems.java
package com.yourmod.item;

import net.minecraft.world.item.Item;
import net.neoforged.bus.api.IEventBus;
import net.neoforged.neoforge.registries.DeferredItem;
import net.neoforged.neoforge.registries.DeferredRegister;

public class ModItems {
    
    // 第一步：创建 DeferredRegister.Items 实例
    // 参数是你的 Mod ID（必须与 neoforge.mods.toml 中一致）
    public static final DeferredRegister.Items ITEMS = 
        DeferredRegister.createItems("yourmod");
    
    // 第二步：注册物品
    // registerSimpleItem 对应源码第 588 行
    public static final DeferredItem<Item> MY_ITEM = 
        ITEMS.registerSimpleItem("my_item", new Item.Properties());
    
    // 第三步：提供注册方法，供主类调用
    public static void register(IEventBus modEventBus) {
        ITEMS.register(modEventBus);
    }
}

// src/main/java/com/yourmod/YourMod.java
package com.yourmod;

import com.yourmod.item.ModItems;
import net.neoforged.bus.api.IEventBus;
import net.neoforged.fml.common.Mod;

@Mod("yourmod")  // Mod ID 必须与 neoforge.mods.toml 一致
public class YourMod {
    
    public YourMod(IEventBus modEventBus) {
        // 调用各个注册类的 register 方法
        ModItems.register(modEventBus);
    }
}

// 正确写法
public static final DeferredItem<Item> MY_ITEM = 
    ITEMS.registerSimpleItem("my_item", new Item.Properties());

// src/main/java/com/yourmod/item/MySword.java
package com.yourmod.item;

import net.minecraft.world.item.Item;
import net.minecraft.world.item.ItemStack;
import net.minecraft.world.InteractionResultHolder;
import net.minecraft.world.InteractionHand;
import net.minecraft.world.entity.player.Player;
import net.minecraft.world.level.Level;

public class MySword extends Item {
    
    // 构造函数必须接受 Item.Properties 参数
    // 这是 NeoForge 的约定（registerItem 方法会传入 Properties）
    public MySword(Properties properties) {
        super(properties);
    }
    
    // 重写右键使用方法
    @Override
    public InteractionResultHolder<ItemStack> use(
            Level level, Player player, InteractionHand hand) {
        // 你的逻辑
        return super.use(level, player, hand);
    }
}

// 在 ModItems.java 中
// 对应源码 DeferredRegister.java 第 544 行的 registerItem(name, func, props)
public static final DeferredItem<MySword> MY_SWORD = 
    ITEMS.registerItem(
        "my_sword",           // 物品 ID
        MySword::new,         // 构造函数引用（等价于 props -> new MySword(props)）
        new Item.Properties().durability(250)  // 属性
    );

格式：命名空间:路径
示例：yourmod:item/my_item

src/main/resources/assets/yourmod/textures/item/my_item.png
src/main/resources/assets/yourmod/models/item/my_item.json

// src/main/resources/assets/yourmod/models/item/my_item.json
{
    "parent": "minecraft:item/generated",
    "textures": {
        "layer0": "yourmod:item/my_item"
    }
}

{
    "parent": "minecraft:item/handheld",
    "textures": {
        "layer0": "yourmod:item/my_sword"
    }
}

{
    "parent": "yourmod:block/my_block"
}

// src/main/resources/assets/yourmod/lang/zh_cn.json
{
    "item.yourmod.my_item": "我的物品",
    "item.yourmod.my_sword": "我的剑"
}

// src/main/resources/assets/yourmod/lang/en_us.json
{
    "item.yourmod.my_item": "My Item",
    "item.yourmod.my_sword": "My Sword"
}

// 源码第 139-158 行
public static class RegisterAdditional extends ModelEvent implements IModBusEvent {
    /**
     * Registers a model to be loaded, along with its dependencies.
     * The ModelResourceLocation passed to this method must later be used to recover the loaded model.
     */
    public void register(ModelResourceLocation model) {
        models.add(model);
    }
}

/**
 * Fired when the contents of a specific creative mode tab are being populated.
 * This event may be fired multiple times if the operator status of the local player
 * or enabled feature flags changes.
 */
public final class BuildCreativeModeTabContentsEvent extends Event implements IModBusEvent, CreativeModeTab.Output {

// 在你的主类或专门的事件处理类中
import net.minecraft.world.item.CreativeModeTabs;
import net.neoforged.neoforge.event.BuildCreativeModeTabContentsEvent;

// 在构造函数中注册事件监听器
public YourMod(IEventBus modEventBus) {
    ModItems.register(modEventBus);
    
    // 监听创造模式物品栏填充事件
    modEventBus.addListener(this::addCreative);
}

// 事件处理方法
private void addCreative(BuildCreativeModeTabContentsEvent event) {
    // 判断是哪个物品栏
    if (event.getTabKey() == CreativeModeTabs.INGREDIENTS) {
        // 添加物品到该物品栏
        event.accept(ModItems.MY_ITEM);
    }
}

import net.minecraft.world.item.CreativeModeTab;
import net.neoforged.neoforge.registries.DeferredRegister;
import net.minecraft.core.registries.Registries;

public class ModCreativeTabs {
    
    public static final DeferredRegister<CreativeModeTab> CREATIVE_MODE_TABS =
        DeferredRegister.create(Registries.CREATIVE_MODE_TAB, "yourmod");
    
    public static final DeferredHolder<CreativeModeTab, CreativeModeTab> EXAMPLE_TAB =
        CREATIVE_MODE_TABS.register("example_tab", () -> CreativeModeTab.builder()
            .title(Component.translatable("itemGroup.yourmod.example_tab"))
            .icon(() -> ModItems.MY_ITEM.toStack())  // 标签页图标
            .displayItems((parameters, output) -> {
                output.accept(ModItems.MY_ITEM.get());
                output.accept(ModItems.MY_SWORD.get());
            })
            .build());
    
    public static void register(IEventBus modEventBus) {
        CREATIVE_MODE_TABS.register(modEventBus);
    }
}

package com.yourmod.item;

import net.minecraft.world.item.Item;
import net.neoforged.bus.api.IEventBus;
import net.neoforged.neoforge.registries.DeferredItem;
import net.neoforged.neoforge.registries.DeferredRegister;

public class ModItems {
    
    // 1. 创建注册器（使用 Items 专用子类）
    public static final DeferredRegister.Items ITEMS = 
        DeferredRegister.createItems("yourmod");
    
    // 2. 注册简单物品
    public static final DeferredItem<Item> MY_ITEM = 
        ITEMS.registerSimpleItem("my_item", new Item.Properties().stacksTo(16));
    
    // 3. 注册自定义物品类
    public static final DeferredItem<MySword> MY_SWORD = 
        ITEMS.registerItem("my_sword", MySword::new, 
            new Item.Properties().durability(250));
    
    // 4. 提供注册入口
    public static void register(IEventBus modEventBus) {
        ITEMS.register(modEventBus);
    }
}

package com.yourmod;

import com.yourmod.item.ModItems;
import net.neoforged.bus.api.IEventBus;
import net.neoforged.fml.common.Mod;
import net.neoforged.neoforge.event.BuildCreativeModeTabContentsEvent;
import net.minecraft.world.item.CreativeModeTabs;

@Mod("yourmod")
public class YourMod {
    
    public YourMod(IEventBus modEventBus) {
        // 注册物品
        ModItems.register(modEventBus);
        
        // 注册创造模式物品栏事件
        modEventBus.addListener(this::addCreative);
    }
    
    private void addCreative(BuildCreativeModeTabContentsEvent event) {
        if (event.getTabKey() == CreativeModeTabs.INGREDIENTS) {
            event.accept(ModItems.MY_ITEM);
            event.accept(ModItems.MY_SWORD);
        }
    }
}

src/main/resources/assets/yourmod/
├── lang/
│   ├── en_us.json    → {"item.yourmod.my_item": "My Item"}
│   └── zh_cn.json    → {"item.yourmod.my_item": "我的物品"}
├── models/item/
│   ├── my_item.json  → {"parent": "minecraft:item/generated", "textures": {"layer0": "yourmod:item/my_item"}}
│   └── my_sword.json → {"parent": "minecraft:item/handheld", "textures": {"layer0": "yourmod:item/my_sword"}}
└── textures/item/
    ├── my_item.png   → 16x16 PNG 贴图
    └── my_sword.png  → 16x16 PNG 贴图

// 错误：直接 new
DeferredRegister<Item> reg = new DeferredRegister<>(Registries.ITEM, "yourmod");

// 正确：使用工厂方法
DeferredRegister.Items reg = DeferredRegister.createItems("yourmod");

DeferredHolder<R, T>     ← 基础 Holder，实现 Holder<R> 和 Supplier<T>
    └── DeferredItem<T>  ← 专门用于 Item，额外实现 ItemLike
    └── DeferredBlock<T> ← 专门用于 Block

游戏启动
  → 加载 @Mod 类，调用构造函数
  → 构造函数中调用 ITEMS.register(modEventBus)
  → DeferredRegister 监听 RegisterEvent
  → RegisterEvent 触发时，遍历所有待注册条目
  → 调用每个条目的工厂函数，创建实际对象
  → 注册到 Minecraft 注册表