minecraft-fabric-dev

Minecraft Fabric 模组开发技能

概述

此技能提供 Minecraft Fabric 模组开发的全面指南，包括从其他模组加载器（Forge、NeoForge）移植模组。它集成了三个 MCP 服务，为模组开发提供完整的工具支持。

可用的 MCP 服务

1. minecraft-dev-mcp

用于访问源代码、反编译和分析的 Minecraft 核心开发工具。

2. fabric-docs-mcp

提供按版本分类内容的 Fabric 官方文档。

3. baritone-docs-mcp

Baritone 寻路库文档（对 AI/自动化模组很有用）。

---

核心工作流

初始设置工作流

开始任何 Minecraft 开发任务时：

1. 先同步文档：

   sync_fabric_docs (force: false) → Get latest Fabric docs
   baritone_refresh_docs → Get Baritone docs if needed
   

2. 确定目标版本：

   list_fabric_versions → See available Fabric versions
   list_minecraft_versions → See available/cached Minecraft versions
   

3. 反编译目标版本（如有需要）：

   decompile_minecraft_version (version, mapping: "yarn", force: false)
   

了解映射

映射类型（按 Fabric 的优先级排序）：

• yarn - 社区驱动、便于阅读的名称（Fabric 首选）
• mojmap - Mojang 官方名称（适合参考原版）
• intermediary - 稳定、不受混淆影响的 ID（Fabric 内部使用）
• official - 混淆后的名称（a、b、c 等）——注意：Minecraft 正在逐步转向发布去混淆版本

各类型的用途：

• 开发：使用 yarn（社区支持最佳）
• 阅读原版代码：使用 mojmap（官方名称）
• 映射转换：使用 intermediary 作为桥接
• 去混淆：从 official 转换为 yarn/mojmap

面向未来的说明： 从 1.21.11 之后的实验性快照开始，Minecraft 正在发布去混淆版本。最终，“official”映射将包含便于阅读的名称，而不是混淆名称（a、b、c）。MCP 服务已为此转变做好准备。当这一做法成为标准后：

• 官方版本将可立即阅读
• Yarn/Mojmap 仍能为命名一致性提供价值
• Intermediary 对 Fabric 的稳定性保证仍然很重要
• 旧版本仍需要去混淆

当前状态（1.21.11 及更早版本）： Official = 混淆名称，开发时使用 yarn/mojmap
未来状态（实验性快照及之后）： Official = 去混淆名称，但为保持 Fabric 一致性，仍建议优先使用 yarn

---

Minecraft 去混淆版本

转变过程

从 1.21.11 之后的实验性快照开始，Minecraft 正在发布去混淆版本。这是一个渐进的转变，最终将成为所有 Minecraft 版本的标准。

这意味着：

• Minecraft 官方 JAR 将使用便于阅读的类、方法和字段名称
• 官方版本中不再出现 a、b、c 等混淆名称
• 可直接阅读原版 JAR 中的源代码
• 新版本对去混淆工具的需求将减少

对开发工作流的影响

对于新版本（已去混淆）：

• 官方映射将立即可用
• Yarn/Mojmap 仍有价值，可用于：
  • 保持命名规范一致
  • 提供更完善的文档
  • 使用社区认可的术语
  • 保持跨版本稳定性
• Intermediary 对 Fabric 的版本无关模组加载仍然至关重要

对于旧版本（1.21.11 及更早版本）：

• 仍需传统的去混淆处理
• 以 yarn/mojmap 作为主要映射
• 官方映射仍是混淆名称（a、b、c）
• 所有现有工作流保持不变

MCP 服务兼容性

minecraft-dev-mcp 服务已具备面向未来的兼容性：

• 可处理混淆和去混淆的官方映射
• 自动检测映射格式
• 无论混淆状态如何，工具的使用方式都相同
• 转变期间无需更改工作流

你无需担心：

• 手动检测混淆状态
• 针对不同版本使用不同的工具调用方式
• 映射兼容性问题
• 对旧版本的支持

推荐实践

为了获得最佳兼容性：

# Still use yarn as primary for Fabric development
decompile_minecraft_version (version: "1.21.11", mapping: "yarn")
decompile_minecraft_version (version: "1.22-experimental", mapping: "yarn")

# Both work identically, server handles the difference

跨版本工作时：

# Comparing old (obfuscated) to new (de-obfuscated)
compare_versions (
  fromVersion: "1.21.11",  # Obfuscated official
  toVersion: "1.22",        # De-obfuscated official
  mapping: "yarn"           # Consistent naming across both
)

为什么仍然使用 Yarn/Mojmap：

1. 一致性 - 名称不会在不同版本间随意变化
2. 文档 - 社区文档引用的是 yarn 名称
3. 稳定性 - Intermediary + yarn 提供了 Fabric 的版本独立性
4. 兼容性 - 现有模组使用 yarn，保持一致性
5. 工具链 - Fabric 生态系统围绕 yarn 约定构建

迁移策略

无需采取行动：

• 继续在所有 Fabric 开发中使用 yarn
• MCP 服务会自动处理这两种格式
• 现有验证工具无需更改即可继续使用
• 文档仍然准确

可选优化：

• 快速查阅原版内容时，官方映射已可行
• 学习时将官方名称与 yarn 名称交叉对照
• 使用官方映射来了解 Mojang 预期的命名方式

版本检测

工具会自动处理版本类型：

# Works for both obfuscated and de-obfuscated
get_minecraft_source (version, className, mapping: "yarn")

# Server internally detects:
# - Is this version obfuscated? → Apply traditional deobfuscation
# - Is this version de-obfuscated? → Use direct mapping translation

你无需手动指定混淆状态。

---

常见开发任务

1. 理解 Minecraft 源代码

工作流：

Step 1: Find the class
  → search_fabric_docs (query: "entity", mcVersion: "latest")
  → search_minecraft_code (version, query: "Entity", searchType: "class", mapping: "yarn")

Step 2: Get source code
  → get_minecraft_source (version, className: "net.minecraft.entity.Entity", mapping: "yarn")

Step 3: Get documentation context
  → get_documentation (className: "Entity")
  → get_fabric_doc (path: "develop/entities.md", mcVersion: "latest")

最佳实践：

• Fabric 开发中始终使用 yarn 映射
• 先进行广泛搜索，再逐步缩小范围
• 同时查阅 Fabric 文档和 Minecraft 源代码
• 根据搜索结果查找相关类

2. 创建 Mixin

基本工作流：

Step 1: Understand the target
  → get_minecraft_source (version, className: "[target]", mapping: "yarn")
  → get_fabric_doc (path: "develop/mixins.md", mcVersion: "latest")

Step 2: Write mixin code
  [User writes mixin based on source + docs]

Step 3: Validate mixin
  → analyze_mixin (source: "[mixin code]", mcVersion: "[version]", mapping: "yarn")

Step 4: Fix issues
  [Review validation results, make corrections]
  → analyze_mixin (source: "[updated code]", mcVersion: "[version]", mapping: "yarn")

关键规则：

• Fabric 必须使用 yarn 映射编写 Mixin
• 在建议完成之前，验证每一个 Mixin
• 检查目标类中是否存在注入点
• 确认方法签名完全匹配
• 考虑 Mixin 优先级和冲突

验证失败时：

• 检查目标类/方法在该版本中是否存在
• 确认映射正确（Fabric 使用 yarn）
• 查找不同版本间重命名的方法
• 检查方法签名（返回类型、参数）

3. 使用 Access Widener

工作流：

Step 1: Identify what needs widening
  → get_minecraft_source (version, className: "[class]", mapping: "yarn")
  [Check field/method visibility]

Step 2: Create access widener file
  [Write .accesswidener with proper syntax]

Step 3: Validate
  → validate_access_widener (content: "[file content]", mcVersion: "[version]", mapping: "yarn")

Step 4: Apply fixes from validation
  [Update based on validation results]

Access Widener 语法：

accessWidener v2 named
accessible class net/minecraft/class/Name
accessible method net/minecraft/class/Name methodName (Lparams;)Lreturn;
accessible field net/minecraft/class/Name fieldName Ltype;
extendable class net/minecraft/class/Name
mutable field net/minecraft/class/Name fieldName Ltype;

4. 分析现有模组

用于理解/移植：

Step 1: Extract mod metadata
  → analyze_mod_jar (jarPath: "[path]", includeAllClasses: false, includeRawMetadata: true)

Step 2: Examine mixins (if present)
  → analyze_mixin (source: "[jar path]", mcVersion: "[version]", mapping: "yarn")

Step 3: Check dependencies and entry points
  [Review metadata from Step 1]

Step 4: Decompile/remap if needed
  → remap_mod_jar (inputJar, outputJar, mcVersion, toMapping: "yarn")

路径规范化：

• 工具接受 WSL（/mnt/c/...）和 Windows（C:\...）路径
• 路径会在内部自动规范化

5. 版本迁移与移植

比较 Minecraft 版本：

Step 1: Get high-level overview
  → compare_versions (fromVersion, toVersion, mapping: "yarn", category: "all")

Step 2: Detailed API changes
  → compare_versions_detailed (fromVersion, toVersion, mapping: "yarn", 
     packages: ["net.minecraft.entity", "net.minecraft.world"], maxClasses: 500)

Step 3: Check registry changes
  → get_registry_data (version: "[old]", registry: "blocks")
  → get_registry_data (version: "[new]", registry: "blocks")

Step 4: Search for specific changes
  → search_fabric_docs (query: "migration [version]", mcVersion: "all")

破坏性更改检查清单：

• 类重命名/移动
• 方法签名更改
• 字段类型更改
• 注册表 ID 更改
• API 移除/弃用

6. 从 Forge 移植到 Fabric

完整的移植工作流：

Step 1: Analyze Forge mod
  → analyze_mod_jar (jarPath: "[forge-mod.jar]", includeAllClasses: true, includeRawMetadata: true)

Step 2: Understand Forge-specific code
  [Review: @Mod annotations, event handlers, capability system, sided proxies]

Step 3: Find Fabric equivalents
  → search_fabric_docs (query: "[forge concept]", mcVersion: "latest")
  → get_fabric_doc (path: "develop/[topic].md", mcVersion: "latest")

Step 4: Map common patterns
  Forge Events → Fabric Events (different registration)
  Capabilities → Cardinal Components API or custom solution
  @Mod annotation → fabric.mod.json
  FMLJavaModLoadingContext → Fabric Mod Initializer
  DeferredRegister → Registry.register in onInitialize

Step 5: Check Minecraft version compatibility
  → get_minecraft_source (version, className: "[needed class]", mapping: "yarn")
  → compare_versions (fromVersion: "[forge ver]", toVersion: "[fabric ver]", mapping: "yarn")

Step 6: Validate converted mixins
  [If Forge mod uses CoreMods/ASM]
  → analyze_mixin (source: "[converted mixin]", mcVersion, mapping: "yarn")

Forge → Fabric 转换模式：

Forge 模式	Fabric 对应项
@Mod 类	fabric.mod.json 中的 ModInitializer 接口
MinecraftForge.EVENT_BUS.register()	相应类中的事件回调
@SubscribeEvent	直接注册事件处理方法
能力	Cardinal Components API（独立库）
@ObjectHolder	直接调用 Registry.register()
配置（ForgeConfig）	Cloth Config API 或自定义方案
@OnlyIn(Dist.CLIENT)	fabric.mod.json 中的 client 入口点
网络数据包（SimpleChannel）	Fabric Networking API
@Mod.EventBusSubscriber	ClientModInitializer / DedicatedServerModInitializer

Fabric 特定的关键要求：

• fabric.mod.json 替代 mods.toml
• Mixin 配置文件（modid.mixins.json）
• Access Widener 文件（如需要）
• 正确注册入口点
• 不同的事件系统架构

---

高级工作流

大规模代码搜索

需要在整个代码库中查找模式时：

Step 1: Index the version (one-time, enables fast search)
  → index_minecraft_version (version, mapping: "yarn")

Step 2: Fast full-text search
  → search_indexed (query: "entity damage", version, mapping: "yarn", 
     types: ["method", "field"], limit: 100)

Alternative: Direct search (slower, no index needed)
  → search_minecraft_code (version, query: "damage", searchType: "all", 
     mapping: "yarn", limit: 50)

搜索类型指南：

• "class" - 类名匹配
• "method" - 方法定义
• "field" - 字段声明
• "content" - 任意代码内容
• "all" - 所有内容

查找系统间的映射

用例：你有一个混淆后的名称，需要查找对应的 yarn 名称（旧版本）：

find_mapping (symbol: "a", version: "1.21.11", sourceMapping: "official", targetMapping: "yarn")
find_mapping (symbol: "Entity", version: "1.21.11", sourceMapping: "mojmap", targetMapping: "yarn")
find_mapping (symbol: "class_1234", version: "1.21.11", sourceMapping: "intermediary", targetMapping: "yarn")

用例：反混淆版本（1.22+ 实验性）：

# Official names are now readable, but still translate to yarn for consistency
find_mapping (symbol: "Entity", version: "1.22", sourceMapping: "official", targetMapping: "yarn")
find_mapping (symbol: "LivingEntity", version: "1.22", sourceMapping: "official", targetMapping: "intermediary")

返回：

• 类映射
• 方法映射（含描述符）
• 字段映射

跨版本映射：

# Works across obfuscated/de-obfuscated boundary
find_mapping (symbol: "Entity", version: "1.21.11", sourceMapping: "yarn", targetMapping: "yarn")
find_mapping (symbol: "Entity", version: "1.22", sourceMapping: "yarn", targetMapping: "yarn")
# Yarn provides consistency even as official format changes

注册表数据分析

针对方块、物品、实体等：

# Get all registries
get_registry_data (version, registry: undefined)

# Get specific registry
get_registry_data (version, registry: "blocks")
get_registry_data (version, registry: "items")
get_registry_data (version, registry: "entities")
get_registry_data (version, registry: "biomes")

用例：

• 查找模组的有效注册表 ID
• 检查版本间的变更
• 验证数据包引用

---

文档策略

何时搜索文档

Fabric 文档 - 优先级 1：

# Feature implementation
search_fabric_docs (query: "custom blocks", mcVersion: "latest", limit: 15)
get_fabric_doc (path: "develop/blocks.md", mcVersion: "latest")

# Concept learning
list_fabric_sections (mcVersion: "latest")
get_fabric_doc_headings (path: "develop/mixins.md", mcVersion: "latest")

Minecraft 源码 - 优先级 2：

# When you need to see how vanilla does it
get_minecraft_source (version, className: "BlockItem", mapping: "yarn")
search_minecraft_code (version, query: "registerBlock", searchType: "method", mapping: "yarn")

Baritone 文档 - 优先级 3（AI/寻路相关）：

# Only for pathfinding/AI mods
baritone_search_docs (query: "GoalBlock")
baritone_read_doc (path: "baritone/api/pathing/goals/GoalBlock.md")

文档阅读优先级

1. 从 Fabric 文档开始 - 官方维护且针对特定版本
2. 参考 Minecraft 源码 - 查看原版实现
3. 检查相关类 - 理解完整系统
4. 使用工具验证 - 测试 mixin/access widener

---

错误处理与故障排除

常见问题

“未找到反编译源码” → 先运行 decompile_minecraft_version

“Mixin 验证失败” → 检查目标类是否存在：get_minecraft_source → 确认方法签名完全一致 → 确保使用 yarn 映射

“未找到文档” → 运行 sync_fabric_docs（Fabric） → 运行 baritone_refresh_docs（Baritone）

“无效的映射类型” → Fabric 始终使用“yarn”（而非 mojmap） → 使用 find_mapping 检查可用映射

“未找到路径”（模组分析） → 检查路径格式（支持 WSL 和 Windows） → 确认指定位置存在该文件 → 使用规范化路径（会自动转换）

验证最佳实践

建议代码前务必进行验证：

• Mixins：analyze_mixin
• Access widener：validate_access_widener
• 版本兼容性：compare_versions
• 注册表 ID：get_registry_data

---

工具选择决策树

User wants to...

├─ Understand Minecraft code
│  ├─ Find a class → search_minecraft_code (searchType: "class")
│  ├─ See implementation → get_minecraft_source
│  └─ Find all usages → search_indexed (after indexing)
│
├─ Learn Fabric concepts
│  ├─ Browse topics → list_fabric_sections
│  ├─ Search for feature → search_fabric_docs
│  └─ Read full guide → get_fabric_doc
│
├─ Write a mixin
│  ├─ Get target class → get_minecraft_source
│  ├─ Check Fabric mixin docs → get_fabric_doc (path: "develop/mixins.md")
│  └─ Validate mixin → analyze_mixin
│
├─ Access private members
│  ├─ Check what exists → get_minecraft_source
│  ├─ Write access widener → [user writes]
│  └─ Validate → validate_access_widener
│
├─ Port a mod
│  ├─ Analyze original → analyze_mod_jar
│  ├─ Check Forge→Fabric patterns → search_fabric_docs
│  ├─ Compare MC versions → compare_versions_detailed
│  └─ Validate converted code → analyze_mixin
│
├─ Update for new version
│  ├─ High-level changes → compare_versions
│  ├─ Detailed API diff → compare_versions_detailed
│  ├─ Registry changes → get_registry_data (both versions)
│  └─ Migration guide → search_fabric_docs (query: "migration")
│
└─ Understand mappings
   ├─ Translate obfuscated → find_mapping
   ├─ See all mappings → List available in tool
   └─ Convert between systems → find_mapping

---

面向用户的输出格式

提供 Mixin 代码时

务必包含：

1. 包含导入语句的完整 mixin 类
2. 用户应运行的验证命令
3. 功能说明
4. 测试警告

模板：

// Your mixin code here

验证：

analyze_mixin (source: "[above code]", mcVersion: "1.21.11", mapping: "yarn")

重要： 在生产环境中使用前，请先在开发环境中测试。

建议使用 Access widener 时

模板：

accessWidener v2 named
[entries here]

验证：

validate_access_widener (content: "[above content]", mcVersion: "1.21.11", mapping: "yarn")

展示版本差异时

提供：

1. 变更摘要
2. 突出显示破坏性变更
3. 建议采取的操作
4. 迁移代码示例

---

性能考量

索引策略

何时建立索引：

• 用户将进行大量搜索
• 进行大规模重构
• 分析代码库中的模式

何时跳过索引：

• 一次性查询
• 只查找单个类
• 快速参考查询

索引命令：

index_minecraft_version (version, mapping: "yarn")

缓存说明

以下内容会缓存（首次运行后速度较快）：

• decompile_minecraft_version
• get_minecraft_source
• get_registry_data
• Fabric/Baritone 文档（同步后）

以下内容不会缓存（始终获取最新结果）：

• search_minecraft_code（除非已建立索引）
• analyze_mixin
• validate_access_widener
• compare_versions

---

版本兼容性矩阵

Minecraft 版本支持

检查可用版本：

list_minecraft_versions → See what's available
list_fabric_versions → See what Fabric supports

典型工作流：

1. 用户说明目标版本
2. 验证该版本是否存在：list_minecraft_versions
3. 检查 Fabric 支持情况：list_fabric_versions
4. 如有需要则反编译：decompile_minecraft_version

映射版本说明

• yarn：特定于版本，必须与 Minecraft 版本匹配（适用于所有版本）
• mojmap：特定于版本，必须与 Minecraft 版本匹配（适用于所有版本）
• intermediary：特定于版本的稳定中间格式（Fabric 的基础）
• official：
  • 旧版（≤1.21.11）：原始混淆名称（a、b、c），没有版本元数据
  • 新版（1.22+ 实验版）：已反混淆，名称易于阅读

版本类别

混淆时代（≤1.21.11）：

• 开发时需要反混淆
• 官方映射已混淆
• yarn/mojmap 对提高可读性至关重要
• 适用标准工作流

已反混淆时代（1.22+ 实验性快照）：

• 官方版本的名称易于阅读
• 仍建议使用 yarn/mojmap 以保持一致性
• intermediary 对 Fabric 仍然至关重要
• 工具的工作方式完全相同（服务会自动检测）

过渡期：

• 部分快照可能已反混淆（需选择启用实验功能）
• 正式版本遵循 Mojang 的官方时间表
• MCP 服务可无缝处理两种格式
• 无需更改工作流

跨版本开发

跨越混淆／已反混淆边界进行开发时：

# Use yarn for consistent names across versions
decompile_minecraft_version (version: "1.21.11", mapping: "yarn")
decompile_minecraft_version (version: "1.22-experimental", mapping: "yarn")

# Compare versions safely
compare_versions_detailed (
  fromVersion: "1.21.11",    # Obfuscated
  toVersion: "1.22",          # De-obfuscated
  mapping: "yarn"             # Consistent across both
)

**最佳实践：**无论目标版本的混淆状态如何，Fabric 开发始终使用 yarn。

---

重要提醒

务必牢记

1. Fabric = yarn 映射（开发时不用 mojmap，也不用 intermediary）——所有版本均保持一致
2. 在声明完成前进行验证（mixins、访问扩展器）
3. 先同步文档（避免文档过时）
4. 检查版本兼容性（尤其是移植时）
5. 使用适当的搜索范围（已索引或直接搜索）
6. 提供验证命令（以便用户验证）
7. 规范化路径（工具会自动处理 WSL/Windows）
8. MCP 服务面向未来（可自动处理已混淆和已反混淆版本）

切勿

1. 不要建议在 Fabric 开发中使用 mojmap
2. 不要跳过 mixin 验证
3. 不要未经检查就假定类存在
4. 不要只提供部分验证步骤
5. 不要忽视版本差异
6. 不要忘记同步文档
7. 不要在同一上下文中混用映射类型
8. 不必担心混淆状态——服务会处理

了解已反混淆时代

用户提及 1.22+ 版本或实验性快照时：

• 提醒用户这些版本可能已反混淆
• 仍建议使用 yarn，以保持 Fabric 开发的一致性
• 说明官方名称现在易于阅读，但 yarn 更稳定
• 无需更改工作流——工具会自动检测格式

---

示例：完整的 Mixin 创建工作流

用户请求：“创建一个防止坠落伤害的 mixin”

响应模式：

Let me help you create a fall damage prevention mixin for Fabric.

Step 1: Understanding the vanilla implementation
[get_minecraft_source for LivingEntity with fall damage logic]

Step 2: Checking Fabric mixin documentation
[get_fabric_doc for mixins guide]

Step 3: Creating the mixin

[Full mixin code with proper imports and structure]

Step 4: Validation (CRITICAL - run this!)

analyze_mixin (
  source: "[mixin code above]",
  mcVersion: "1.21.11",
  mapping: "yarn"
)

This mixin injects into the fall damage method and cancels it. The @Inject annotation targets the method responsible for applying fall damage, and we use cancellable = true to allow preventing the damage.

Important notes:
- Test in creative world first
- May conflict with other fall damage mods
- Affects all entities, not just players

---

资源 URI

Fabric 文档资源

模式： fabric://docs/{path}

示例：

fabric://docs/develop/getting-started.md
fabric://docs/develop/mixins.md
fabric://docs/items/custom-item.md

访问方式：

• get_fabric_doc 工具
• 直接读取资源
• 搜索结果中包含 URI

Minecraft 源码资源

模式： minecraft://source/{version}/{mapping}/{className}

示例：

minecraft://source/1.21.1/yarn/net.minecraft.entity.Entity
minecraft://source/1.21.1/mojmap/net.minecraft.world.level.Level

还可使用：

• minecraft://mappings/{version}/{mapping}
• minecraft://registry/{version}/{registryType}
• minecraft://versions/list
• minecraft://index/{version}/{mapping}

---

Mod 开发最终检查清单

在建议解决方案已完成之前，请验证：

• 已搜索并参考文档
• 已确认目标 Minecraft 版本
• 使用了正确的映射类型（Fabric 使用 yarn）
• 已检查原版实现的源代码
• 已使用 analyze_mixin 验证 Mixin
• 已验证访问扩展器（如果使用）
• 已检查版本兼容性
• 已确定依赖项
• 已提供测试说明
• 已指出潜在冲突

---

快速参考命令

初始设置：

sync_fabric_docs
list_minecraft_versions
decompile_minecraft_version (version: "1.21.11", mapping: "yarn")

开发：

get_fabric_doc (path: "develop/[topic].md")
get_minecraft_source (version, className, mapping: "yarn")
analyze_mixin (source, mcVersion, mapping: "yarn")

分析：

analyze_mod_jar (jarPath)
compare_versions (fromVersion, toVersion, mapping: "yarn")
search_minecraft_code (version, query, searchType: "all", mapping: "yarn")

验证：

analyze_mixin (source, mcVersion, mapping: "yarn")
validate_access_widener (content, mcVersion, mapping: "yarn")

此技能涵盖 Minecraft Fabric 模组开发工作流，并使用所有可用的 MCP 工具。