我的世界Fabric模组开发教程：基础流程与第一个物品实现

引言

Fabric作为Minecraft轻量级模组开发框架，以其快速迭代和模块化设计赢得了广大开发者的青睐。本教程将手把手带你完成Fabric开发环境搭建，并实现第一个自定义物品。

为什么选择Fabric？

轻量级架构，启动速度快

模块化设计，易于扩展

活跃的社区支持

完善的开发工具链

01｜开发环境准备

1.1 前置要求

在开始之前，请确保你的开发环境满足以下要求：

组件	最低版本	推荐版本
JDK	17	21
Gradle	7.0	8.0+
Minecraft	1.20.1	1.20.4
Fabric Loader	0.15.0	最新稳定版

1.2 环境验证

验证Java环境配置：

java -version
# 输出应显示Java 17或更高版本
 
javac -version
# 确认编译器版本

02｜项目初始化

2.1 使用Fabric模板

Fabric官方提供了项目模板，推荐新手使用：

# 克隆官方模板
git clone https://github.com/FabricMC/fabric-example-mod.git my-first-mod
cd my-first-mod
 
# 重命名包结构
./gradlew genSources

2.2 项目结构解析

标准的Fabric项目结构如下：

my-first-mod/
├── src/
│   ├── main/
│   │   ├── java/
│   │   │   └── com/example/
│   │   │       ├── MyFirstMod.java          # 主类文件
│   │   │       ├── item/                    # 物品相关类
│   │   │       ├── block/                   # 方块相关类
│   │   │       └── mixin/                   # Mixin类
│   │   └── resources/
│   │       ├── assets/
│   │       │   └── myfirstmod/
│   │       │       ├── blockstates/         # 方块状态定义
│   │       │       ├── lang/               # 语言文件
│   │       │       ├── models/             # 模型文件
│   │       │       └── textures/            # 纹理贴图
│   │       └── fabric.mod.json             # 模组主配置文件
├── build.gradle                            # Gradle构建文件
└── gradle.properties                       # 项目属性配置

03｜核心配置文件

3.1 fabric.mod.json配置

这是Fabric模组的核心配置文件：

{
  "schemaVersion": 1,
  "id": "myfirstmod",
  "version": "${version}",
  "name": "My First Mod",
  "description": "我的第一个Fabric模组",
  "authors": [
    "YourName"
  ],
  "contact": {
    "homepage": "https://example.com",
    "sources": "https://github.com/yourname/myfirstmod"
  },
  "license": "MIT",
  "environment": "*",
  "entrypoints": {
    "main": [
      "com.example.MyFirstMod"
    ],
    "client": [
      "com.example.MyFirstModClient"
    ]
  },
  "depends": {
    "fabricloader": ">=0.15.0",
    "minecraft": "~1.20.4",
    "java": ">=17",
    "fabric-api": "*"
  }
}

3.2 Gradle构建配置

gradle.properties文件配置：

# 项目属性
org.gradle.jvmargs=-Xmx4G
org.gradle.daemon=false
 
# 模组版本
mod_version=1.0.0
maven_group=com.example
archives_base_name=myfirstmod
 
# Minecraft版本
minecraft_version=1.20.4
yarn_mappings=1.20.4+build.3
loader_version=0.15.7
 
# Fabric API版本
fabric_version=0.91.2+1.20.4

04｜创建第一个物品

4.1 主类实现

创建主类MyFirstMod.java：

package com.example;
 
import net.fabricmc.api.ModInitializer;
import net.fabricmc.fabric.api.item.v1.FabricItemSettings;
import net.minecraft.item.Item;
import net.minecraft.item.ItemGroup;
import net.minecraft.registry.Registries;
import net.minecraft.registry.Registry;
import net.minecraft.util.Identifier;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
 
public class MyFirstMod implements ModInitializer {
    // 定义模组ID
    public static final String MOD_ID = "myfirstmod";
    
    // 创建日志记录器
    public static final Logger LOGGER = LoggerFactory.getLogger(MOD_ID);
    
    // 声明自定义物品
    public static final Item RUBY = new Item(new FabricItemSettings());
    
    @Override
    public void onInitialize() {
        LOGGER.info("正在初始化 {} 模组", MOD_ID);
        
        // 注册物品
        Registry.register(Registries.ITEM, new Identifier(MOD_ID, "ruby"), RUBY);
        
        LOGGER.info("{} 模组初始化完成！", MOD_ID);
    }
}

4.2 物品属性配置

让我们为红宝石添加更多属性：

public class MyFirstMod implements ModInitializer {
    // ... 前面的代码 ...
    
    // 创建具有完整属性的物品
    public static final Item RUBY = new Item(new FabricItemSettings()
        .maxCount(64)                    // 最大堆叠数
        .fireproof()                     // 防火属性
        .recipeRemainder(Items.GLASS_BOTTLE) // 合成后剩余物品
        .group(ItemGroup.MATERIALS));    // 物品分组
    
    @Override
    public void onInitialize() {
        LOGGER.info("正在初始化 {} 模组", MOD_ID);
        
        // 注册物品到游戏
        Registry.register(Registries.ITEM, new Identifier(MOD_ID, "ruby"), RUBY);
        
        LOGGER.info("红宝石物品已注册成功！");
    }
}

05｜资源文件配置

5.1 语言文件

创建语言文件src/main/resources/assets/myfirstmod/lang/zh_cn.json：

{
  "item.myfirstmod.ruby": "红宝石",
  "item.myfirstmod.ruby.tooltip": "一颗闪闪发光的红宝石",
  "itemGroup.myfirstmod.ruby_group": "我的物品"
}

5.2 物品模型

创建物品模型文件src/main/resources/assets/myfirstmod/models/item/ruby.json：

{
  "parent": "item/generated",
  "textures": {
    "layer0": "myfirstmod:item/ruby"
  }
}

5.3 纹理贴图

将红宝石的纹理图片（16x16像素，PNG格式）放置在： src/main/resources/assets/myfirstmod/textures/item/ruby.png

纹理制作建议：

使用16x16或32x32像素的基础尺寸

保持Minecraft原版风格的一致性

使用透明背景（PNG格式）

考虑不同光照条件下的显示效果

06｜高级功能实现

6.1 自定义物品类

创建自定义物品类以实现特殊功能：

package com.example.item;
 
import net.minecraft.entity.player.PlayerEntity;
import net.minecraft.item.Item;
import net.minecraft.item.ItemStack;
import net.minecraft.text.Text;
import net.minecraft.util.Hand;
import net.minecraft.util.TypedActionResult;
import net.minecraft.world.World;
 
public class RubyItem extends Item {
    
    public RubyItem(Settings settings) {
        super(settings);
    }
    
    @Override
    public TypedActionResult<ItemStack> use(World world, PlayerEntity user, Hand hand) {
        if (!world.isClient()) {
            // 服务器端逻辑
            user.sendMessage(Text.literal("你使用了红宝石！"), false);
            
            // 添加发光效果
            user.addStatusEffect(new StatusEffectInstance(
                StatusEffects.GLOWING, 
                200, // 持续时间（刻）
                1    // 等级
            ));
        }
        
        return TypedActionResult.success(user.getStackInHand(hand));
    }
    
    @Override
    public boolean hasGlint(ItemStack stack) {
        // 让物品具有附魔光效
        return true;
    }
}

6.2 更新主类

修改主类以使用自定义物品类：

public class MyFirstMod implements ModInitializer {
    // ... 其他代码 ...
    
    // 使用自定义物品类
    public static final Item RUBY = new RubyItem(new FabricItemSettings()
        .maxCount(1)
        .fireproof()
        .group(ItemGroup.TOOLS));
    
    // ... 其余代码保持不变 ...
}

07｜构建与测试

7.1 开发环境测试

使用Gradle任务运行开发环境：

# 运行客户端
./gradlew runClient
 
# 运行服务器
./gradlew runServer
 
# 生成源代码
./gradlew genSources
 
# 构建项目
./gradlew build

7.2 生产构建

构建发布版本：

# 清理并构建
./gradlew clean build
 
# 构建结果在 build/libs/ 目录下
ls -la build/libs/

08｜调试技巧

8.1 日志调试

使用SLF4J日志记录器进行调试：

public class RubyItem extends Item {
    private static final Logger LOGGER = LoggerFactory.getLogger("ruby_item");
    
    @Override
    public TypedActionResult<ItemStack> use(World world, PlayerEntity user, Hand hand) {
        LOGGER.debug("红宝石被使用了！玩家: {}", user.getName().getString());
        LOGGER.info("世界维度: {}", world.getRegistryKey().getValue());
        
        // ... 其他代码 ...
    }
}

8.2 热重载开发

Fabric支持开发时的热重载功能：

# 启用开发模式
./gradlew runClient --args="--dev"
 
# 修改代码后重新编译
./gradlew compileJava

09｜最佳实践

9.1 代码组织

推荐的包结构：

com.example.myfirstmod/
├── MyFirstMod.java           # 主类
├── item/                    # 物品包
│   ├── ModItems.java        # 物品注册器
│   └── custom/               # 自定义物品类
├── block/                   # 方块包
├── entity/                  # 实体包
├── world/                   # 世界生成包
├── client/                  # 客户端代码
├── mixin/                   # Mixin类
└── util/                    # 工具类

9.2 性能优化

物品注册优化：

public class ModItems {
    // 集中注册所有物品
    public static final Item RUBY = registerItem("ruby", 
        new RubyItem(new FabricItemSettings()
            .maxCount(64)
            .group(ItemGroup.MATERIALS)));
    
    private static Item registerItem(String name, Item item) {
        return Registry.register(Registries.ITEM, 
            new Identifier(MyFirstMod.MOD_ID, name), item);
    }
    
    public static void registerModItems() {
        MyFirstMod.LOGGER.info("正在注册模组物品...");
    }
}

9.3 兼容性考虑

版本兼容性：

明确指定支持的Minecraft版本范围
使用条件注册处理不同版本差异
提供降级兼容方案

// 版本兼容处理示例
if (FabricLoader.getInstance().getModContainer("fabric-api").isPresent()) {
    // Fabric API可用时的处理
} else {
    // 降级处理方案
}

10｜发布与分享

10.1 构建发布版本

# 构建发布版本
./gradlew build -Pversion=1.0.0-release
 
# 检查构建结果
./gradlew check

10.2 发布平台

主要发布平台：

CurseForge - 最大的模组发布平台
Modrinth - 新兴的模组平台
GitHub Releases - 代码托管和版本管理

10.3 发布清单

发布前请确认：

结语

恭喜！你已经成功创建了自己的第一个Fabric模组。这只是开始，Fabric框架提供了无限的可能性：

深入学习： 探索更复杂的方块、实体、世界生成
社区参与： 加入Fabric Discord，与其他开发者交流
开源贡献： 为Fabric生态系统贡献代码

记住，优秀的模组来自持续的迭代和用户反馈。继续编码，继续创造！

思考题：

如何为你的红宝石添加自定义的合成配方？

怎样实现右键点击方块时放置红宝石的功能？

如何让红宝石在特定条件下自动生成在世界中？

参考资料：

（此内容由 AI 辅助生成，仅供参考）