minecraft-fabric-dev

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Minecraft Fabric Mod Development Skill

Minecraft Fabric模组开发指南

Overview

概述

This skill provides comprehensive guidance for Minecraft mod development with Fabric, including porting from other mod loaders (Forge, NeoForge). It integrates three MCP servers to provide complete tooling for mod development.

本指南提供了使用Fabric进行Minecraft模组开发的全面指导，包括从其他模组加载器（Forge、NeoForge）迁移的内容。它集成了三台MCP服务器，为模组开发提供完整的工具链。

Available MCP Servers

可用的MCP服务器

1. minecraft-dev-mcp

Core Minecraft development tools for source code access, decompilation, and analysis.

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

2. fabric-docs-mcp

Official Fabric documentation access with version-specific content.

可访问特定版本的官方Fabric文档。

3. baritone-docs-mcp

Baritone pathfinding library documentation (useful for AI/automation mods).

Baritone寻路库的文档（适用于AI/自动化类模组）。

Core Workflows

核心工作流程

Initial Setup Workflow

初始设置流程

When starting ANY Minecraft development task:

Sync documentation first:

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

Identify target version:

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

Decompile target version (if needed):

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

启动任何Minecraft开发任务时：

先同步文档：

sync_fabric_docs (force: false) → 获取最新Fabric文档
baritone_refresh_docs → 如有需要，获取Baritone文档

确定目标版本：

list_fabric_versions → 查看可用的Fabric版本
list_minecraft_versions → 查看可用/已缓存的Minecraft版本

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

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

Understanding Mappings

理解映射关系

Mapping Types (in priority order for Fabric):

yarn - Community-driven, human-readable names (PREFERRED for Fabric)
mojmap - Official Mojang names (good for vanilla reference)
intermediary - Stable obfuscation-independent IDs (used internally by Fabric)
official - Obfuscated names (a, b, c, etc.) - NOTE: Minecraft is transitioning to de-obfuscated releases

When to use each:

Development: Use yarn (best community support)
Reading vanilla code: Use mojmap (official names)
Mapping translation: Use intermediary as bridge
Deobfuscating: From official to yarn/mojmap

Future-Proofing Note: Starting with experimental snapshots after 1.21.11, Minecraft is releasing de-obfuscated builds. Eventually, the "official" mapping will contain human-readable names instead of obfuscated ones (a, b, c). The MCP server is already prepared for this transition. When this becomes standard:

Official releases will be immediately readable
Yarn/Mojmap will still provide value for consistent naming
Intermediary remains important for Fabric's stability guarantees
Legacy versions will still require deobfuscation

Current State (1.21.11 and earlier): Official = obfuscated, use yarn/mojmap for development Future State (experimental snapshots+): Official = de-obfuscated, still prefer yarn for Fabric consistency

映射类型（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

De-Obfuscated Minecraft Releases

Minecraft非混淆版本发布

The Transition

过渡说明

Starting with experimental snapshots after version 1.21.11, Minecraft is releasing de-obfuscated builds. This is a gradual transition that will eventually become the standard for all Minecraft releases.

What This Means:

Official Minecraft JARs will ship with human-readable class/method/field names
No more obfuscated names like
```
a
```
,
```
b
```
,
```
c
```
in official releases
Directly readable source code from vanilla JARs
Reduced need for deobfuscation tools for newer versions

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

这意味着：

官方Minecraft JAR文件将附带人类可读的类/方法/字段名称
官方版本中不再有
```
a
```
、
```
b
```
、
```
c
```
这类混淆命名
可直接从原版JAR文件读取源代码
新版本对反混淆工具的需求降低

Impact on Development Workflow

对开发流程的影响

For New Versions (De-obfuscated):

Official mappings will be immediately useful
Yarn/Mojmap still valuable for:
- Consistent naming conventions
- Better documentation
- Community-agreed terminology
- Cross-version stability
Intermediary remains critical for Fabric's version-independent mod loading

For Legacy Versions (1.21.11 and earlier):

Still require traditional deobfuscation
Use yarn/mojmap as primary mappings
Official mappings remain obfuscated (a, b, c)
All existing workflows continue unchanged

针对新版本（非混淆）：

官方映射将立即可用
Yarn/Mojmap仍有价值，原因包括：
- 一致的命名规范
- 更完善的文档
- 社区认可的术语
- 跨版本稳定性
Intermediary对Fabric的版本无关加载依然至关重要

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

仍需传统的反混淆操作
主要使用yarn/mojmap作为映射
官方映射仍为混淆状态（a、b、c等）
所有现有工作流程保持不变

MCP Server Compatibility

MCP服务器兼容性

The minecraft-dev-mcp server is already future-proof:

Handles both obfuscated and de-obfuscated official mappings
Automatically detects mapping format
Tools work identically regardless of obfuscation state
No workflow changes needed when transitioning

What You Don't Need to Worry About:

Manual detection of obfuscation state
Different tool invocations for different versions
Mapping compatibility issues
Legacy version support

minecraft-dev-mcp服务器已具备未来兼容性：

同时支持混淆和非混淆的官方映射
自动检测映射格式
无论混淆状态如何，工具的使用方式完全相同
过渡期间无需更改工作流程

无需担心的事项：

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

Recommended Practices

Still use yarn as primary for Fabric development

Fabric开发仍优先使用yarn

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

两者操作方式完全相同，服务器会自动处理差异


**When Working Across Version Boundaries:**


**跨版本开发时：**

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 )


**Why Still Use Yarn/Mojmap:**

1. **Consistency** - Names don't change between versions arbitrarily
2. **Documentation** - Community documentation references yarn names
3. **Stability** - Intermediary + yarn provides Fabric's version independence
4. **Compatibility** - Existing mods use yarn, maintain consistency
5. **Tooling** - Fabric ecosystem built around yarn conventions

compare_versions ( fromVersion: "1.21.11", # 混淆的官方版本 toVersion: "1.22", # 非混淆的官方版本 mapping: "yarn" # 跨版本保持一致命名 )


**为何仍使用Yarn/Mojmap：**

1. **一致性** - 版本间命名不会随意变更
2. **文档** - 社区文档参考的是yarn命名
3. **稳定性** - Intermediary + yarn保障Fabric的版本独立性
4. **兼容性** - 现有模组使用yarn命名，保持一致性
5. **工具链** - Fabric生态系统围绕yarn规范构建

Migration Strategy

迁移策略

No Action Required:

Continue using yarn for all Fabric development
MCP server automatically handles both formats
Existing validation tools work unchanged
Documentation remains accurate

Optional Optimizations:

For quick vanilla reference, official source becomes viable
Cross-reference official names with yarn for learning
Use official for understanding Mojang's intended naming

无需执行任何操作：

继续在所有Fabric开发中使用yarn
MCP服务器自动处理两种格式
现有验证工具工作方式不变
文档依然准确

可选优化：

快速参考原版代码时，官方源代码变得可行
交叉参考官方名称与yarn名称以学习
使用官方名称理解Mojang的命名意图

Version Detection

版本检测

The tools automatically handle version type:

undefined

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

undefined

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

- 该版本是否为非混淆状态？→ 使用直接映射转换


**You never need to specify obfuscation state manually.**

---


**您无需手动指定混淆状态。**

---

Common Development Tasks

常见开发任务

1. Understanding Minecraft Source Code

1. 理解Minecraft源代码

Workflow:

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")

Best practices:

ALWAYS use yarn mappings for Fabric development
Start broad with searches, then narrow down
Check both Fabric docs AND Minecraft source
Look for related classes using search results

工作流程：

步骤1：查找类
  → search_fabric_docs (query: "entity", mcVersion: "latest")
  → search_minecraft_code (version, query: "Entity", searchType: "class", mapping: "yarn")

步骤2：获取源代码
  → get_minecraft_source (version, className: "net.minecraft.entity.Entity", mapping: "yarn")

步骤3：获取文档上下文
  → get_documentation (className: "Entity")
  → get_fabric_doc (path: "develop/entities.md", mcVersion: "latest")

最佳实践：

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

2. Creating Mixins

2. 创建Mixin

Essential workflow:

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")

Critical rules:

Mixins MUST use yarn mappings for Fabric
Validate EVERY mixin before suggesting it's complete
Check injection points exist in target class
Verify method signatures match exactly
Consider mixin priority and conflicts

When validation fails:

Check if target class/method exists in that version
Verify mapping is correct (yarn for Fabric)
Look for renamed methods between versions
Check method signatures (return type, parameters)

核心工作流程：

步骤1：了解目标类
  → get_minecraft_source (version, className: "[target]", mapping: "yarn")
  → get_fabric_doc (path: "develop/mixins.md", mcVersion: "latest")

步骤2：编写Mixin代码
  [用户编写Mixin代码]

步骤3：验证Mixin
  → analyze_mixin (source: "[mixin code]", mcVersion: "[version]", mapping: "yarn")

步骤4：修复问题
  [查看验证结果，进行修正]
  → analyze_mixin (source: "[updated code]", mcVersion: "[version]", mapping: "yarn")

关键规则：

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

验证失败时的处理：

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

3. Using Access Wideners

3. 使用Access Wideners

Workflow:

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 syntax:

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;

工作流程：

步骤1：确定需要放宽访问权限的内容
  → get_minecraft_source (version, className: "[class]", mapping: "yarn")
  [检查字段/方法的可见性]

步骤2：创建Access Widener文件
  [编写符合语法的.accesswidener文件]

步骤3：验证
  → validate_access_widener (content: "[file content]", mcVersion: "[version]", mapping: "yarn")

步骤4：根据验证结果修复
  [根据验证结果更新文件]

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. Analyzing Existing Mods

4. 分析现有模组

For understanding/porting:

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")

Path normalization:

Tool accepts both WSL (
```
/mnt/c/...
```
) and Windows (
```
C:\...
```
) paths
Paths are automatically normalized internally

用于理解/迁移：

步骤1：提取模组元数据
  → analyze_mod_jar (jarPath: "[path]", includeAllClasses: false, includeRawMetadata: true)

步骤2：检查Mixin（如果存在）
  → analyze_mixin (source: "[jar path]", mcVersion: "[version]", mapping: "yarn")

步骤3：检查依赖和入口点
  [查看步骤1中的元数据]

步骤4：如有需要，反编译/重映射
  → remap_mod_jar (inputJar, outputJar, mcVersion, toMapping: "yarn")

路径规范化：

工具同时支持WSL（
```
/mnt/c/...
```
）和Windows（
```
C:\...
```
）路径
路径会在内部自动规范化

5. Version Migration & Porting

5. 版本迁移与移植

Comparing Minecraft versions:

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")

Breaking changes checklist:

Class renames/moves
Method signature changes
Field type changes
Registry ID changes
Removed/deprecated APIs

对比Minecraft版本：

步骤1：获取概览
  → compare_versions (fromVersion, toVersion, mapping: "yarn", category: "all")

步骤2：详细API变更
  → compare_versions_detailed (fromVersion, toVersion, mapping: "yarn", 
     packages: ["net.minecraft.entity", "net.minecraft.world"], maxClasses: 500)

步骤3：检查注册表变更
  → get_registry_data (version: "[old]", registry: "blocks")
  → get_registry_data (version: "[new]", registry: "blocks")

步骤4：搜索特定变更
  → search_fabric_docs (query: "migration [version]", mcVersion: "all")

破坏性变更检查清单：

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

6. Porting from Forge to Fabric

6. 从Forge迁移到Fabric

Comprehensive porting workflow:

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 translation patterns:

Forge Pattern	Fabric Equivalent
`@Mod` class	`ModInitializer` interface in fabric.mod.json
`MinecraftForge.EVENT_BUS.register()`	Event callbacks in respective classes
`@SubscribeEvent`	Direct method registration with event
Capabilities	Cardinal Components API (separate library)
`@ObjectHolder`	Direct `Registry.register()` calls
Config (ForgeConfig)	Cloth Config API or custom solution
`@OnlyIn(Dist.CLIENT)`	`client` entrypoint in fabric.mod.json
Network packets (SimpleChannel)	Fabric Networking API
`@Mod.EventBusSubscriber`	`ClientModInitializer` / `DedicatedServerModInitializer`

Critical Fabric-specific requirements:

```
fabric.mod.json
```
replaces
```
mods.toml
```
Mixins config file (
```
modid.mixins.json
```
)
Access widener file (if needed)
Proper entrypoint registration
Different event system architecture

完整迁移流程：

步骤1：分析Forge模组
  → analyze_mod_jar (jarPath: "[forge-mod.jar]", includeAllClasses: true, includeRawMetadata: true)

步骤2：理解Forge特定代码
  [查看：@Mod注解、事件处理器、Capability系统、 sided proxies]

步骤3：查找Fabric等效方案
  → search_fabric_docs (query: "[forge concept]", mcVersion: "latest")
  → get_fabric_doc (path: "develop/[topic].md", mcVersion: "latest")

步骤4：映射常见模式
  Forge Events → Fabric Events（注册方式不同）
  Capabilities → Cardinal Components API或自定义方案
  @Mod注解 → fabric.mod.json
  FMLJavaModLoadingContext → Fabric Mod Initializer
  DeferredRegister → 在onInitialize中调用Registry.register

步骤5：检查Minecraft版本兼容性
  → get_minecraft_source (version, className: "[needed class]", mapping: "yarn")
  → compare_versions (fromVersion: "[forge ver]", toVersion: "[fabric ver]", mapping: "yarn")

步骤6：验证转换后的Mixin
  [如果Forge模组使用CoreMods/ASM]
  → analyze_mixin (source: "[converted mixin]", mcVersion, mapping: "yarn")

Forge → Fabric转换模式：

Forge模式	Fabric等效方案
`@Mod` 类	fabric.mod.json中的 `ModInitializer` 接口
`MinecraftForge.EVENT_BUS.register()`	在对应类中注册事件回调
`@SubscribeEvent`	直接向事件注册方法
Capabilities	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文件（如有需要）
正确的入口点注册
不同的事件系统架构

Advanced Workflows

高级工作流程

Large-Scale Code Search

大规模代码搜索

When you need to find patterns across entire codebase:

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)

Search type guide:

```
"class"
```
- Class name matching
```
"method"
```
- Method definitions
```
"field"
```
- Field declarations
```
"content"
```
- Any code content
```
"all"
```
- Everything

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

步骤1：索引版本（一次性操作，启用快速搜索）
  → index_minecraft_version (version, mapping: "yarn")

步骤2：快速全文搜索
  → search_indexed (query: "entity damage", version, mapping: "yarn", 
     types: ["method", "field"], limit: 100)

替代方案：直接搜索（速度较慢，无需索引）
  → search_minecraft_code (version, query: "damage", searchType: "all", 
     mapping: "yarn", limit: 50)

搜索类型指南：

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

Finding Mappings Between Systems

不同系统间的映射转换

Use case: You have an obfuscated name and need the yarn name (legacy versions):

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")

Use case: De-obfuscated releases (1.22+ experimental):

undefined

使用场景：拥有混淆名称，需要转换为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+实验性）：

undefined

Official names are now readable, but still translate to yarn for consistency

官方名称现在可读，但为了一致性仍转换为yarn

find_mapping (symbol: "Entity", version: "1.22", sourceMapping: "official", targetMapping: "yarn") find_mapping (symbol: "LivingEntity", version: "1.22", sourceMapping: "official", targetMapping: "intermediary")


**Returns:**
- Class mappings
- Method mappings (with descriptors)
- Field mappings

**Cross-version mapping:**


**返回内容：**
- 类映射
- 方法映射（包含描述符）
- 字段映射

**跨版本映射：**

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

即使官方格式变更，yarn仍能提供一致性

undefined

undefined

Registry Data Analysis

注册表数据分析

For blocks, items, entities, etc.:

undefined

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

undefined

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")


**Use cases:**
- Finding valid registry IDs for your mod
- Checking what changed between versions
- Validating data pack references

---

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
- 检查版本间的变更
- 验证数据包引用

---

Documentation Strategy

文档策略

When to Search Documentation

何时搜索文档

Fabric Docs - Priority 1:

undefined

Fabric文档 - 优先级1：

undefined

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 Source - Priority 2:**

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 Docs - Priority 3 (AI/pathfinding specific):**

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

仅适用于寻路/AI模组

baritone_search_docs (query: "GoalBlock") baritone_read_doc (path: "baritone/api/pathing/goals/GoalBlock.md")

undefined

baritone_search_docs (query: "GoalBlock") baritone_read_doc (path: "baritone/api/pathing/goals/GoalBlock.md")

undefined

Documentation Reading Priority

文档阅读优先级

Start with Fabric docs - Official, maintained, version-specific
Reference Minecraft source - See vanilla implementation
Check related classes - Understand the full system
Validate with tools - Test mixins/access wideners

先看Fabric文档 - 官方维护，版本特定
参考Minecraft源代码 - 查看原版实现
检查相关类 - 理解完整系统
用工具验证 - 测试Mixin/Access Widener

Error Handling & Troubleshooting

错误处理与故障排除

Common Issues

常见问题

"Decompiled source not found" → Run

decompile_minecraft_version

first

"Mixin validation failed" → Check target class exists:

get_minecraft_source

→ Verify method signatures match exactly → Ensure using yarn mappings

"Documentation not found" → Run

sync_fabric_docs

(Fabric) → Run

baritone_refresh_docs

(Baritone)

"Invalid mapping type" → Fabric ALWAYS uses "yarn" (not mojmap) → Check available mappings with

find_mapping

"Path not found" (mod analysis) → Check path format (both WSL and Windows supported) → Verify file exists at specified location → Use normalized paths (auto-converted)

“Decompiled source not found” → 先运行

decompile_minecraft_version

“Mixin validation failed” → 检查目标类是否存在：

get_minecraft_source

→ 验证方法签名是否完全匹配 → 确保使用yarn映射

“Documentation not found” → 运行

sync_fabric_docs

（Fabric） → 运行

baritone_refresh_docs

（Baritone）

“Invalid mapping type” → Fabric始终使用"yarn"（而非mojmap） → 使用

find_mapping

查看可用映射

“Path not found”（模组分析） → 检查路径格式（支持WSL和Windows） → 验证文件是否存在于指定路径 → 使用规范化路径（自动转换）

Validation Best Practices

验证最佳实践

ALWAYS validate before suggesting code is complete:

Mixins:
```
analyze_mixin
```
Access wideners:
```
validate_access_widener
```
Version compatibility:
```
compare_versions
```
Registry IDs:
```
get_registry_data
```

在确认代码完成前必须验证：

Mixin：
```
analyze_mixin
```
Access Widener：
```
validate_access_widener
```
版本兼容性：
```
compare_versions
```
注册表ID：
```
get_registry_data
```

Tool Selection Decision Tree

工具选择决策树

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

用户需要...

├─ 理解Minecraft代码
│  ├─ 查找类 → search_minecraft_code (searchType: "class")
│  ├─ 查看实现 → get_minecraft_source
│  └─ 查找所有用法 → search_indexed（索引后）
│
├─ 学习Fabric概念
│  ├─ 浏览主题 → list_fabric_sections
│  ├─ 搜索功能 → search_fabric_docs
│  └─ 阅读完整指南 → get_fabric_doc
│
├─ 编写Mixin
│  ├─ 获取目标类 → get_minecraft_source
│  ├─ 查阅Fabric Mixin文档 → get_fabric_doc (path: "develop/mixins.md")
│  └─ 验证Mixin → analyze_mixin
│
├─ 访问私有成员
│  ├─ 检查存在性 → get_minecraft_source
│  ├─ 编写Access Widener → [用户编写]
│  └─ 验证 → validate_access_widener
│
├─ 迁移模组
│  ├─ 分析原版 → analyze_mod_jar
│  ├─ 查阅Forge→Fabric模式 → search_fabric_docs
│  ├─ 对比MC版本 → compare_versions_detailed
│  └─ 验证转换后的代码 → analyze_mixin
│
├─ 适配新版本
│  ├─ 概览变更 → compare_versions
│  ├─ 详细API差异 → compare_versions_detailed
│  ├─ 注册表变更 → get_registry_data（两个版本）
│  └─ 迁移指南 → search_fabric_docs (query: "migration")
│
└─ 理解映射关系
   ├─ 转换混淆名称 → find_mapping
   ├─ 查看所有映射 → 工具中列出可用项
   └─ 系统间转换 → find_mapping

Output Formatting for Users

用户输出格式

When Providing Mixin Code

提供Mixin代码时

ALWAYS include:

Full mixin class with imports
Validation command they should run
Explanation of what it does
Warning about testing

Template:

java

// Your mixin code here

Validation:

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

Important: Test this in a development environment before using in production.

必须包含：

完整的Mixin类及导入语句
用户应运行的验证命令
代码功能说明
测试警告

模板：

java

// 您的Mixin代码

验证：

analyze_mixin (source: "[上述代码]", mcVersion: "1.21.11", mapping: "yarn")

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

When Suggesting Access Wideners

建议使用Access Widener时

Template:

accessWidener v2 named
[entries here]

Validation:

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

模板：

accessWidener v2 named
[条目内容]

验证：

validate_access_widener (content: "[上述内容]", mcVersion: "1.21.11", mapping: "yarn")

When Showing Version Differences

展示版本差异时

Provide:

Summary of changes
Breaking changes highlighted
Recommended actions
Migration code examples

需提供：

变更摘要
突出显示破坏性变更
建议操作
迁移代码示例

Performance Considerations

性能考虑

Indexing Strategy

索引策略

When to index:

User will do extensive searching
Working on large-scale refactoring
Analyzing patterns across codebase

When to skip indexing:

One-off queries
Just looking up single class
Quick reference checks

Index command:

index_minecraft_version (version, mapping: "yarn")

何时索引：

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

何时跳过索引：

一次性查询
仅查看单个类
快速参考检查

索引命令：

index_minecraft_version (version, mapping: "yarn")

Caching Awareness

缓存说明

These are cached (fast after first run):

```
decompile_minecraft_version
```
```
get_minecraft_source
```
```
get_registry_data
```
Fabric/Baritone docs (after sync)

These are not cached (always fresh):

```
search_minecraft_code
```
(unless indexed)
```
analyze_mixin
```
```
validate_access_widener
```
```
compare_versions
```

以下操作会被缓存（首次运行后速度快）：

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

以下操作不会被缓存（始终获取最新内容）：

```
search_minecraft_code
```
（除非已索引）
```
analyze_mixin
```
```
validate_access_widener
```
```
compare_versions
```

Version Compatibility Matrix

版本兼容性矩阵

Minecraft Version Support

Minecraft版本支持

Check available versions:

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

Typical workflow:

User states target version
Verify version exists:
```
list_minecraft_versions
```
Check Fabric support:
```
list_fabric_versions
```
Decompile if needed:
```
decompile_minecraft_version
```

查看可用版本：

list_minecraft_versions → 查看可用版本
list_fabric_versions → 查看Fabric支持的版本

典型工作流程：

用户指定目标版本
验证版本是否存在：
```
list_minecraft_versions
```
检查Fabric支持情况：
```
list_fabric_versions
```
如有需要，反编译：
```
decompile_minecraft_version
```

Mapping Version Notes

映射版本说明

yarn: Version-specific, must match Minecraft version (works for all versions)
mojmap: Version-specific, must match Minecraft version (works for all versions)
intermediary: Version-specific, stable intermediate format (Fabric's backbone)
official:
- Legacy (≤1.21.11): Raw obfuscated (a, b, c), no version metadata
- Modern (1.22+ experimental): De-obfuscated, human-readable names

yarn：版本特定，必须与Minecraft版本匹配（支持所有版本）
mojmap：版本特定，必须与Minecraft版本匹配（支持所有版本）
intermediary：版本特定，稳定的中间格式（Fabric的核心）
official：
- 旧版（≤1.21.11）：原始混淆状态（a、b、c），无版本元数据
- 新版（1.22+实验性）：非混淆，人类可读名称

Version Categories

版本分类

Obfuscated Era (≤1.21.11):

Requires deobfuscation for development
Official mappings are obfuscated
Yarn/Mojmap essential for readability
Standard workflow applies

De-obfuscated Era (1.22+ experimental snapshots):

Official releases are human-readable
Yarn/Mojmap still recommended for consistency
Intermediary remains critical for Fabric
Tools work identically (server auto-detects)

Transition Period:

Some snapshots may be de-obfuscated (opt-in experimental)
Release versions follow official Mojang timeline
MCP server handles both formats seamlessly
No workflow changes required

混淆时代（≤1.21.11）：

开发时需要反混淆
官方映射为混淆状态
Yarn/Mojmap对可读性至关重要
标准工作流程适用

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

官方版本为人类可读
仍推荐使用Yarn/Mojmap以保持一致性
Intermediary对Fabric依然关键
工具使用方式完全相同（服务器自动检测）

过渡时期：

部分快照可能为非混淆（可选实验性）
正式版本遵循Mojang的官方时间线
MCP服务器无缝处理两种格式
无需更改工作流程

Cross-Version Development

跨版本开发

When working across obfuscated/de-obfuscated boundary:

undefined

跨混淆/非混淆版本开发时：

undefined

Use yarn for consistent names across versions

使用yarn保持跨版本命名一致

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 )


**Best Practice:** Always use yarn for Fabric development regardless of target version's obfuscation state.

---

compare_versions_detailed ( fromVersion: "1.21.11", # 混淆版本 toVersion: "1.22", # 非混淆版本 mapping: "yarn" # 跨版本保持一致 )


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

---

Critical Reminders

重要提醒

ALWAYS Remember

必须牢记

Fabric = yarn mappings (not mojmap, not intermediary for dev) - consistent across all versions
Validate before declaring complete (mixins, access wideners)
Sync docs first (prevent stale documentation)
Check version compatibility (especially for porting)
Use appropriate search scope (indexed vs direct)
Provide validation commands (so user can verify)
Normalize paths (tools handle WSL/Windows automatically)
MCP server is future-proof (handles both obfuscated and de-obfuscated releases automatically)

Fabric = yarn映射（开发时不使用mojmap或intermediary）- 所有版本保持一致
确认完成前必须验证（Mixin、Access Widener）
先同步文档（避免使用过期文档）
检查版本兼容性（尤其是迁移时）
使用合适的搜索范围（索引 vs 直接搜索）
提供验证命令（方便用户验证）
规范化路径（工具自动处理WSL/Windows路径）
MCP服务器具备未来兼容性（自动处理混淆和非混淆版本）

NEVER Do

绝对不要

Don't suggest mojmap for Fabric development
Don't skip mixin validation
Don't assume classes exist without checking
Don't provide partial validation steps
Don't ignore version differences
Don't forget to sync documentation
Don't mix mapping types in same context
Don't worry about obfuscation state - the server handles it

不要建议在Fabric开发中使用mojmap
不要跳过Mixin验证
不要假设类存在而不检查
不要提供不完整的验证步骤
不要忽略版本差异
不要忘记同步文档
不要在同一上下文中混合使用不同的映射类型
不要担心混淆状态 - 服务器会自动处理

De-Obfuscated Era Awareness

非混淆时代注意事项

When user mentions version 1.22+ or experimental snapshots:

Note that these may be de-obfuscated releases
Recommend yarn anyway for Fabric consistency
Explain official names are now readable but yarn provides stability
No workflow changes needed - tools auto-detect format

当用户提到1.22+或实验性快照时：

注意这些版本可能为非混淆版本
仍推荐使用yarn以保持Fabric开发的一致性
说明官方名称现在可读，但yarn提供更好的稳定性
无需更改工作流程 - 工具会自动检测格式

Example: Complete Mixin Creation Workflow

示例：完整的Mixin创建流程

User Request: "Create a mixin to prevent fall damage"

Response Pattern:

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

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

响应模式：

我来帮您创建一个用于Fabric的防止掉落伤害Mixin。

步骤1：理解原版实现
[获取包含掉落伤害逻辑的LivingEntity源代码]

步骤2：查阅Fabric Mixin文档
[获取Mixin指南的Fabric文档]

步骤3：创建Mixin

[完整的Mixin代码，包含导入语句和结构]

步骤4：验证（至关重要 - 请运行此命令！）

analyze_mixin (
  source: "[上述代码]",
  mcVersion: "1.21.11",
  mapping: "yarn"
)

该Mixin注入到掉落伤害方法中并取消伤害。@Inject注解定位到负责应用掉落伤害的方法，我们使用cancellable = true来允许阻止伤害。

重要提示：
- 先在创造模式世界中测试
- 可能与其他修改掉落伤害的模组冲突
- 会影响所有实体，而不仅仅是玩家

Resource URIs

资源URI

Fabric Documentation Resources

Fabric文档资源

Pattern:

fabric://docs/{path}

Example:

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

Access via:

```
get_fabric_doc
```
tool
Direct resource read
Search results include URI

格式：

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 Source Resources

Minecraft源代码资源

Pattern:

minecraft://source/{version}/{mapping}/{className}

Example:

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

Also available:

minecraft://mappings/{version}/{mapping}

minecraft://registry/{version}/{registryType}

```
minecraft://versions/list
```
```
minecraft://index/{version}/{mapping}
```

格式：

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}
```

Final Checklist for Mod Development

模组开发最终检查清单

Quick Reference Commands

快速参考命令

Initial Setup:

bash

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

Development:

bash

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

Analysis:

bash

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

Validation:

bash

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

This skill provides complete coverage of Minecraft Fabric mod development workflows using all available MCP tools.

初始设置：

bash

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

开发：

bash

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

分析：

bash

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

验证：

bash

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

本指南涵盖了使用所有可用MCP工具进行Minecraft Fabric模组开发的完整工作流程。

minecraft-fabric-dev

Original

Translation

Minecraft Fabric Mod Development Skill

Minecraft Fabric模组开发指南

Overview

概述

Available MCP Servers

可用的MCP服务器

1. minecraft-dev-mcp

1. minecraft-dev-mcp

2. fabric-docs-mcp

2. fabric-docs-mcp

3. baritone-docs-mcp

3. baritone-docs-mcp

Core Workflows

核心工作流程

Initial Setup Workflow

初始设置流程

Understanding Mappings

理解映射关系

De-Obfuscated Minecraft Releases

Minecraft非混淆版本发布

The Transition

过渡说明

Impact on Development Workflow

对开发流程的影响

MCP Server Compatibility

MCP服务器兼容性

Recommended Practices

推荐实践

Still use yarn as primary for Fabric development

Fabric开发仍优先使用yarn

Both work identically, server handles the difference

两者操作方式完全相同，服务器会自动处理差异

Comparing old (obfuscated) to new (de-obfuscated)

对比旧版（混淆）与新版（非混淆）

Migration Strategy

迁移策略

Version Detection

版本检测

Works for both obfuscated and de-obfuscated

同时支持混淆和非混淆版本

Server internally detects:

服务器内部会检测：

- Is this version obfuscated? → Apply traditional deobfuscation

- 该版本是否为混淆状态？→ 应用传统反混淆

- Is this version de-obfuscated? → Use direct mapping translation

- 该版本是否为非混淆状态？→ 使用直接映射转换

Common Development Tasks

常见开发任务

1. Understanding Minecraft Source Code

1. 理解Minecraft源代码

2. Creating Mixins

2. 创建Mixin

3. Using Access Wideners

3. 使用Access Wideners

4. Analyzing Existing Mods

4. 分析现有模组

5. Version Migration & Porting

5. 版本迁移与移植

6. Porting from Forge to Fabric

6. 从Forge迁移到Fabric

Advanced Workflows

高级工作流程

Large-Scale Code Search

大规模代码搜索

Finding Mappings Between Systems

不同系统间的映射转换

Official names are now readable, but still translate to yarn for consistency

官方名称现在可读，但为了一致性仍转换为yarn

Works across obfuscated/de-obfuscated boundary

可在混淆/非混淆版本间工作

Yarn provides consistency even as official format changes

即使官方格式变更，yarn仍能提供一致性

Registry Data Analysis

注册表数据分析

Get all registries

获取所有注册表

Get specific registry