把 C 语言编译成 Minecraft 数据包
你写 C 语言,编译器把它翻译成游戏里的命令。
就像一台「C → Minecraft 命令」的翻译机——int a = 10; 变成 scoreboard players set,
return a + b; 变成计分板运算 + 函数返回,add(x, y) 变成压栈→传参→宏调用→弹栈。
全部自动完成,你不需要在游戏里手写任何命令。
一份 C 源码变成能在游戏里跑的数据包,中间经过 编译器(翻译)和 链接器(组装)两个独立程序。往下看,每个阶段都标了对应的代码文件位置。
test.c)+ 链接配置(数据包名、pack_format、要链接哪些编译产物)src/compiler/main.cpp 入口 → lang.cpp AST 收集 → compiler.cpp 代码生成{name}_symbols.json(函数/变量清单) + {name}_o/function/*.mcfunction(每条命令已生成,但编号是局部编号)src/linker/linker.cpp — linkFile() 收集 → dealFile() 重写 → link() 组装pack.mcmeta + data/{name}/function/*.mcfunction + start.mcfunction + load.jsondatapacks 目录load.json → start.mcfunction → 初始化计分板 → 调用 main(),你的 C 程序跑起来了!理解代码架构是接手项目的第一步。下面从调用层次、分发模式、数据流三个维度拆解整个代码结构。
CraftLang 产出两个独立的可执行程序,各自有独立的 main 入口和代码路径:
| 程序 | 入口文件 | 核心文件 | 职责 |
|---|---|---|---|
craftlang.exe |
src/compiler/main.cpp |
src/compiler/compiler.cpp + src/compiler/lang.cpp |
把一份 C 源码翻译成中间产物(符号表 JSON + 命令文件) |
craftlinker.exe |
src/linker/main.cpp |
src/linker/linker.cpp |
把多份中间产物合并、重编号、组装成最终数据包 |
以下是从 main() 到最终代码生成的完整调用链。箭头表示「调用」,缩进表示「被调用」。
═══ main.cpp ═══
main()
├─ clang_createIndex() // libclang:创建索引
├─ clang_parseTranslationUnit() // libclang:解析 C 源码 → AST
├─ clang_visitChildren(root, collectChildrenCallback) // libclang:遍历 AST 收集节点
│ └─ collectChildrenCallback() // lang.cpp:11 — 回调函数,每个 AST 节点触发一次
│ ├─ all_cursors[cursor] = Cursor{...} // 登记节点到全局哈希表
│ └─ all_cursors[parent].children.push_back(cursor) // 建立父子关系
├─ visitCursorRecursive(rootCursor, 0) // lang.cpp:42 — 先序遍历 AST,打印结构
│ ├─ printSpelling(cursor) // lang.cpp:34 — 打印节点名称
│ └─ getChildCursors(cursor) // lang.cpp:30 — 从哈希表取子节点
└─ compile(rootCursor) // compiler.cpp:739 — 代码生成入口
├─ fs::remove_all / create_directories // 清理 + 创建输出目录
└─ deal_cursor(rootCursor) // compiler.cpp:441 — ★ 核心分发函数 ★
═══ compiler.cpp — 核心代码生成 ═══
deal_cursor(cursor) // ★ 语句级分发:一个巨型 switch(CXCursorKind)
├─ case CXCursor_TranslationUnit: // 根节点 — 遍历子节点 + 写入 start.mcfunction + 符号表
│ └─ deal_cursor(child) 【递归】 // 遍历所有子节点
├─ case CXCursor_FunctionDecl: // 函数声明/定义 — 登记符号表 + 编译函数体
│ ├─ functionMap[inside_name] = Function{...} // 登记函数
│ ├─ initVar / setConstToVar // 参数绑定
│ ├─ deal_cursor(child) 【递归】 // 遍历函数体内每条语句
│ └─ 写入 .f.{N}.f..mcfunction // 输出函数文件
├─ case CXCursor_DeclStmt: // 声明语句块 — 透传子节点
│ └─ deal_cursor(child) 【递归】
├─ case CXCursor_VarDecl: // 变量声明 — 登记符号表 + 初始化
│ ├─ globalVarsToInt[name] = Var{...} // 全局变量登记
│ ├─ localVarsToInt[name] = Var{...} // 局部变量登记
│ ├─ start_deal_expr(initializer) // 求值初始值表达式
│ │ └─ deal_expr(expr) 【递归】 // ★ 表达式级分发
│ ├─ initVar(...) // 创建计分板目标
│ └─ setVarToVar(...) / setConstToVar(...) // 赋值
├─ case CXCursor_CompoundStmt: // 复合语句 {} — 透传子节点
│ └─ deal_cursor(child) 【递归】
├─ case CXCursor_ReturnStmt: // return 语句
│ ├─ start_deal_expr(returnValue) // 求值返回值
│ │ └─ deal_expr(expr) 【递归】
│ ├─ initVar("return", ...) // 初始化返回值计分板
│ └─ setVarToVar("return", tmp, ...) // 写入返回值
├─ case CXCursor_IfStmt: // if 语句(开发中)
│ ├─ start_deal_expr(condition) // 求值条件
│ │ └─ deal_expr(expr) 【递归】
│ ├─ deal_cursor(then) 【递归】 // 编译 then 分支到独立文件
│ └─ deal_cursor(else) 【递归】 // 编译 else 分支到独立文件
└─ case default: // 表达式语句(CallExpr / BinaryOperator 等)
└─ start_deal_expr(cursor) // 表达式语句:求值并丢弃结果
└─ deal_expr(expr) 【递归】 // ★ 表达式级分发
═══ deal_expr — 表达式级分发 ═══
start_deal_expr(expr) // compiler.cpp:200 — 表达式求值入口(重置 tmp_counter)
└─ deal_expr(expr) // compiler.cpp:206 — ★ 表达式级分发:又一个巨型 switch
├─ case CXCursor_IntegerLiteral: // 整数常量 42
│ ├─ initVar(tmp) // 创建临时量
│ └─ setConstToVar(tmp, "42") // 写入常量值
├─ case CXCursor_DeclRefExpr: // 变量引用 a
│ ├─ find_var(name) // 查符号表(先局部后全局)
│ ├─ initVar(tmp) // 创建临时量
│ └─ setVarToVar(tmp, var.objective) // 复制变量值到临时量
├─ case CXCursor_ParenExpr: // 括号表达式 (a+b)
│ └─ deal_expr(child) 【递归】 // 透传子节点
├─ case CXCursor_UnexposedExpr: // 透明表达式
│ └─ deal_expr(child) 【递归】 // 透传子节点
├─ case CXCursor_BinaryOperator: // 二元运算符(赋值 / 算术 / 比较)
│ ├─ IF 是赋值类运算符: // 走左值路径
│ │ ├─ deal_lvalue(left) // compiler.cpp:168 — 解析左值,获取目标计分板名
│ │ │ ├─ case CXCursor_DeclRefExpr → 查符号表
│ │ │ └─ case CXCursor_ParenExpr → 透传
│ │ ├─ deal_expr(right) 【递归】 // 求值右值
│ │ └─ scoreboard operation left = right_tmp // 赋值命令
│ ├─ ELSE IF 是算术类运算符: // + - * / %
│ │ ├─ deal_expr(left) 【递归】 // 求值左值
│ │ ├─ deal_expr(right) 【递归】 // 求值右值
│ │ └─ scoreboard operation left_tmp += right_tmp // 原地运算
│ └─ ELSE IF 是比较类运算符: // == != < <= > >=
│ ├─ deal_expr(left) 【递归】
│ ├─ deal_expr(right) 【递归】
│ ├─ set tmp 0 / if score ... run set tmp 1 // 条件执行
│ └─ 返回 bool(0/1)
├─ case CXCursor_UnaryOperator: // 单目运算符
│ ├─ if +x → deal_expr(child) 【递归】 // 恒等透传
│ └─ if -x → deal_expr(child) → tmp *= const-1 // 取负绕道
└─ case CXCursor_CallExpr: // 函数调用 f(a, b)
├─ FOR 每个实参: deal_expr(arg) 【递归】 // 逐个求值
│ └─ execute store result storage {N} // 写入 storage 槽位
├─ scoreboard add functionSpace 1 // 压栈
├─ execute store result storage functionSpace // 同步栈帧号
├─ function {name}:.f.{N}.f. with storage // 宏调用
├─ scoreboard remove functionSpace 1 // 弹栈
└─ IF 有返回值: initVar + setVarToVar("return", ...) // 读返回值
编译器最核心的设计模式是双层 switch 分发:
| 层级 | 函数 | Switch 对象 | 处理粒度 |
|---|---|---|---|
| 第一层:语句级 | deal_cursor(cursor) |
CXCursorKind(AST 节点类型) |
整条语句 / 整个声明 / 整个函数 |
| 第二层:表达式级 | deal_expr(expr) |
CXCursorKind(AST 节点类型) |
单个表达式 / 运算符 / 字面量 |
设计思路:deal_cursor 处理「大块」——函数定义、变量声明、return 语句、if 语句等。
当遇到表达式时(如 a + b、foo(x, y)),它不自行处理,而是调用 deal_expr(或 start_deal_expr)。
这样「语句结构」和「表达式求值」两个关注点被清晰分离。
start_deal_expr 在调用 deal_expr 之前把 tmp_counter 重置为 0,
确保每次表达式求值从干净的临时量编号开始。如果直接调用 deal_expr,临时量编号会累积,导致混乱。
| 函数 | 代码位置 | 被谁调用 | 作用 |
|---|---|---|---|
addCommand(cmd) |
compiler.cpp:155 |
deal_cursor / deal_expr 中几乎所有生成命令的地方 | 统一命令写入入口:自动区分全局/函数上下文,替换 ?(space),写入对应的 current_content 或 startFunctionContent |
initVar(name, type) |
compiler.cpp:83 |
deal_cursor / deal_expr | 创建计分板目标:scoreboard objectives remove + add。目前只支持 Int 类型 |
setVarToVar(dst, src, type) |
compiler.cpp:103 |
deal_cursor / deal_expr | 生成 scoreboard players operation ... = ... 命令 |
setConstToVar(dst, value, type) |
compiler.cpp:121 |
deal_cursor / deal_expr | 生成 scoreboard players set ... {value} 命令 |
find_var(name) |
compiler.cpp:139 |
deal_expr / deal_lvalue | 先查 localVarsToInt,再查 globalVarsToInt。找不到抛异常 |
deal_lvalue(cursor) |
compiler.cpp:168 |
deal_expr(赋值类运算符) | 从 AST 节点提取左值(计分板目标名)。目前只处理 DeclRefExpr 和 ParenExpr |
replaceAll(str, from, to) |
compiler.cpp:52 |
addCommand / linker | 字符串全局替换。链接器用此函数做编号重写 |
addDollarPrefix(text) |
compiler.cpp:65 |
deal_cursor(输出文件时) | 逐行扫描:含 $ 的行自动加 $ 前缀变成宏指令 |
getChildCursors(cursor) |
lang.cpp:30 |
几乎所有地方 | 从全局哈希表 all_cursors 获取子节点列表 |
以下全局变量在 compiler.cpp:29-48 定义,是整个编译器的共享状态。所有函数都通过读写这些变量来协作。
| 变量 | 类型 | 作用 |
|---|---|---|
functionMap |
unordered_map<string, Function> |
函数符号表:函数名 → 函数信息(编号、返回类型、参数、是否 extern) |
functionCounter |
int |
函数编号计数器,每遇到一个 FunctionDecl 递增 |
current_content |
string |
当前正在编译的函数体的命令内容。写完一个函数后清空 |
startFunctionContent |
string |
全局初始化命令。所有全局变量的 init 指令收集到这里,最终写入 start.mcfunction |
isInFunction |
bool |
是否在函数体内?用于 if 语句分支编译时判断上下文 |
current_function |
Function |
当前正在编译的函数信息。全局上下文时 name = "Global" |
current_file |
filesystem::path |
当前正在写入的文件名(如 .f.3.f.) |
localVarsToInt |
unordered_map<string, Var> |
当前函数的局部变量表。进入新函数时清空 + 重新登记 |
globalVarsToInt |
unordered_map<string, Var> |
全局变量表。整个编译过程累积,不清空 |
localVarCounter |
int |
局部变量编号计数器,进入新函数时重置为 0 |
globalVarCounter |
int |
全局变量编号计数器,整个编译过程累积 |
tmp_counter |
int |
临时量编号计数器,start_deal_expr 时重置 |
childrenFunctionCounter |
int |
if 语句子函数编号计数器,用于给 then/else 分支文件命名 |
symbols |
nlohmann::json |
符号表 JSON,最终输出到 *_symbols.json |
链接器代码相对简单,集中在 src/linker/linker.cpp。核心是两个函数:
| 函数 | 代码位置 | 作用 |
|---|---|---|
linkFile(file) |
linker.cpp:84 |
读入一个 *_symbols.json,调用 collectCategory 把符号合并到全局 functionMap/globalMap。处理 extern 去重和重复定义检查 |
dealFile(file) |
linker.cpp:102 |
读入一个编译产物目录,逐一替换 .f.N.f. → 全局编号、.g.N.g. → 全局编号、..name.. → 真实数据包名,复制到最终输出目录 |
link() |
linker.cpp:232 |
主流程:① 初始化目录 + pack.mcmeta ② 遍历所有 linkFile 调用 linkFile 收集符号 ③ 检查 extern 完整性 ④ 遍历所有 linkFile 调用 dealFile 重写 ⑤ 生成 start.mcfunction |
init() |
linker.cpp:70 |
创建输出目录 + 生成 pack.mcmeta |
collectCategory(...) |
linker.cpp:36 |
通用符号收集:按名字合并,分配全局编号,处理 extern 语义 |
为什么分两阶段:linkFile 先跑完所有文件收集符号,得到全局唯一编号后,
dealFile 再跑一遍做替换。如果边收集边替换,遇到 extern 还没被定义的情况就没法处理了。
下面是编译器内部的数据流转图,展示了每次函数调用时参数如何跨越函数边界:
═══ 编译器内部数据流 ═══
main.cpp lang.cpp compiler.cpp
───────── ──────── ────────────
main()
│
├─ clang_parseTranslationUnit() ──→ 生成 CXTranslationUnit
│
├─ clang_visitChildren() ──→ collectChildrenCallback() ──→ all_cursors 哈希表
│ (每个 AST 节点触发一次) (Cursor → 父子关系)
│
├─ visitCursorRecursive() ──→ getChildCursors() ──→ 从 all_cursors 读取
│ printSpelling() 打印 AST 结构
│
└─ compile(rootCursor) ──────────────────────────────────────→ deal_cursor(rootCursor)
│
┌────────────────────────────────────────────────────────────┘
│
▼
deal_cursor(cursor) ──→ 读/写 functionMap, localVarsToInt, globalVarsToInt
│ 读/写 current_content, startFunctionContent
│ 读/写 tmp_counter, current_function, current_file
│
├── 遇到表达式时 ──→ start_deal_expr(expr) ──→ tmp_counter = 0
│ │
│ └──→ deal_expr(expr) ──→ 返回 ExprResult{tmp_number}
│ │
│ └──→ addCommand(cmd) ──→ 写入 current_content
│ 或 startFunctionContent
│
├── 遇到变量声明时 ──→ localVarsToInt[name] = Var{...}
│ 或 globalVarsToInt[name] = Var{...}
│
└── 遇到函数调用时 ──→ deal_expr(CallExpr) ──→ 生成压栈/传参/宏调用/弹栈 命令
│
└──→ functionMap[name] 查找目标函数编号
═══ 链接器内部数据流 ═══
linker.cpp
──────────
link()
│
├── FOR EACH linkFile:
│ linkFile(json) ──→ 读入 *_symbols.json
│ └── collectCategory("function", ...) ──→ functionMap[name] = globalNumber
│ └── collectCategory("global", ...) ──→ globalMap[name] = globalNumber
│
├── 检查 extern 完整性 ──→ functionDefined / globalDefined
│
└── FOR EACH linkFile:
dealFile(json) ──→ 读入 *_symbols.json + *_o/ 目录
├── 建立 local→global 映射表 (functionDealMap / globalDealMap)
├── FOR EACH .mcfunction in *_o/function/:
│ replaceAll(content, ".f.{local}.f.", to_string(global)) ──→ 重写函数编号
│ replaceAll(content, ".g.{local}.g.", to_string(global)) ──→ 重写全局编号
│ replaceAll(content, "..name..", config.name) ──→ 替换数据包名
│ 写入 output/{name}/data/{name}/function/{重写后文件名}.mcfunction
└── start 文件合并到 startContext
└── 最后写入 start.mcfunction(含计分板初始化 + main 调用)
编译器是项目的核心翻译引擎。它接收一份 C 源码,输出一份「半成品」——符号表 JSON + 命令文件。整个流程分为四步:
入口在 src/compiler/main.cpp:65-71:
// 创建 libclang 索引
CXIndex index = clang_createIndex(0, 0);
// 解析 C 源码 → TranslationUnit(语法树根节点)
// -I 参数让 clang 能找到 #include <mcstd.h> 中声明的头文件
CXTranslationUnit unit = clang_parseTranslationUnit(
index, filePath.c_str(),
clangArgs.data(), // 含 -I include/ 路径
clangArgs.size(), nullptr, 0, CXTranslationUnit_None
);
关键设计:libclang 解析时同时处理 #include,所以 mcstd.h 里的 print_int 声明和 #define bool int 宏会一并进入 AST。
编译器内部通过 functionMap 的 find 守卫区分「前向声明」和「真正定义」。
代码位置:src/compiler/lang.cpp:11-28 和 :42-62。
clang_visitChildren 递归遍历 AST,collectChildrenCallback 回调把每个节点登记到全局哈希表 all_cursors。
这个表用 CursorHash 自定义哈希(基于 CXCursor 内部三个 void* 指针),
CursorEqual 用 clang_equalCursors 比较——保证同一节点不重复登记。
然后 visitCursorRecursive 先序遍历整棵树,打印每个节点的类型和名称(DEBUG 模式输出完整 AST 结构)。
根节点固定为 TranslationUnit。
代码位置:src/compiler/main.cpp:79-93。
diagCount > 0 → throw 终止编译。
源码必须保证零警告才能通过。这是有意为之——避免悄悄生成有问题的半成品。
入口:compile(CXCursor root_cursor) → deal_cursor(root_cursor)。
deal_cursor 是一个巨型 switch,根据 CXCursorKind 分发到不同处理逻辑。
下面 §4 和 §5 会逐一展开每种语句和表达式的翻译细节。
每种 C 语句遇到 deal_cursor 时,会走哪个 case、生成什么 Minecraft 命令。这是项目的核心翻译规则。
代码位置:compiler.cpp:447-484
| 触发条件 | 生成逻辑 |
|---|---|
CXCursor_TranslationUnit |
① 将 current_function.name 设为 "Global" —— 此时所有语句都在全局上下文② 遍历所有子节点,逐个调用 deal_cursor(child)(函数声明、全局变量声明等)③ 全部遍历完后,把 startFunctionContent 写入 start.mcfunction④ 把 globalVarsToInt 和 functionMap 序列化为 JSON 写入符号表文件
|
startFunctionContent 收集所有全局变量的初始化指令,在 start.mcfunction 里一次性执行。
链接器之后会拼接各文件的 start 内容,加上计分板初始化,最终组装成完整的入口文件。
代码位置:compiler.cpp:486-571
| 步骤 | 详细操作 |
|---|---|
| ① 登记函数 | 检查 functionMap 是否已有同名函数。没有则新增:Function{name, return_type, parms, functionCounter++, cursor, true}。有则跳过(前向声明的合法情况)。 |
| ② 无函数体 | 如果子节点中没有 CompoundStmt(即只有声明没有定义),直接 return——不生成代码。 |
| ③ 参数绑定 | 遍历子节点中的 ParmDecl,登记到 localVarsToInt,命名格式 $(functionSpace)_N。生成初始化命令: initVar 创建计分板目标 + setConstToVar 从宏参数 $(N) 取值。 |
| ④ 编译函数体 | 遍历 CompoundStmt 的子节点,逐个调用 deal_cursor(child)。所有命令收集到 current_content。 |
| ⑤ 输出文件 | 写入 .f.{number}.f..mcfunction,文件名含内部编号,链接器会替换为全局编号。 |
关键:每个函数编译到独立文件,参数通过宏 $(0) $(1) 传入。
局部变量用 $(functionSpace)_N 寻址,运行时由宏调用 with storage 注入当前栈帧号。
代码位置:compiler.cpp:582-631
| 场景 | 生成逻辑 |
|---|---|
全局变量int g = 10; |
① 登记到 globalVarsToInt,计分板目标名 0_.g.{N}.g.(全局在第 0 层)② 如果是 extern:只登记,不生成初始化代码③ 如果有初始值: initVar 创建计分板 + setVarToVar 从临时量复制④ 所有命令写入 startFunctionContent(而非 current_content)
|
局部变量int a = 10; |
① 登记到 localVarsToInt,计分板目标名 $(functionSpace)_N② 如果有初始值:求值表达式 → initVar 创建 + setVarToVar 复制③ 所有命令写入 current_content(当前函数体内)
|
0_.g.N.g. 用 .g. 包裹编号,局部变量 $(functionSpace)_N 无包裹。
链接器通过正则匹配 .g.N.g. 来替换全局编号,.f.N.f. 替换函数编号。
代码位置:compiler.cpp:573-580
简单透传——遍历子节点(通常是 VarDecl),逐个调用 deal_cursor。本身不生成任何命令。
代码位置:compiler.cpp:663-669
同样简单透传——遍历子节点调用 deal_cursor。这是函数体和 {} 块的通用处理。
代码位置:compiler.cpp:633-661
| 返回类型 | 生成命令 |
|---|---|
void 函数 |
直接 return 0(mcfunction 必须用 return 结束) |
int 函数 |
① 求值 return 后的表达式 → 临时量 ② initVar("return", CXType_Int) 创建全局 return 计分板③ setVarToVar("return", "$(functionSpace)_tmp_N", ...) 复制到 return 槽④ return 0 结束函数
|
return 是一个全局共享的计分板(不是 $(functionSpace)_return),
因为调用方在弹栈后需要读取返回值——如果 return 放在栈帧里,弹栈后就访问不到了。
代码位置:compiler.cpp:726-735
当 cursor 不是以上任何一种时,检查是否在 exprStatementKinds 列表中。
如果是,调用 start_deal_expr 求值表达式,丢弃结果(副作用已通过计分板命令生效)。
如果不是,抛出 runtime_error,打印不支持的节点类型。
exprStatementKinds = {CallExpr, BinaryOperator, CompoundAssignOperator, ParenExpr}
—— 这些都是可以作为语句出现的表达式类型。
表达式求值是整个编译器最复杂的部分。核心思想:每个表达式求值结果放在一个临时量(tmp)里, 返回临时量编号,外层表达式可以继续用这个编号做运算。
代码位置:compiler.cpp:212-221
| C 代码 | 生成的 mcfunction 命令 |
|---|---|
42 |
scoreboard objectives remove $(functionSpace)_tmp_0scoreboard objectives add $(functionSpace)_tmp_0 dummyscoreboard players set {name} $(functionSpace)_tmp_0 42
|
用 clang_EvalResult_getAsInt 获取常量值,直接 scoreboard players set 写入临时量。
代码位置:compiler.cpp:234-243
| C 代码 | 生成的 mcfunction 命令 |
|---|---|
a(局部变量) |
scoreboard objectives remove $(functionSpace)_tmp_0scoreboard objectives add $(functionSpace)_tmp_0 dummyscoreboard players operation {name} $(functionSpace)_tmp_0 = {name} $(functionSpace)_3
|
通过 find_var(name) 查找符号表(先局部后全局),获取变量的计分板目标名,用 operation ... = 复制到临时量。
代码位置:compiler.cpp:222-233
直接透传给唯一的子节点。如果子节点数量不是 1,抛异常。
代码位置:compiler.cpp:255-303
先判断运算符是否在 binaryOperatorNeedLValue 列表中(Assign, AddAssign, SubAssign, MulAssign, DivAssign, RemAssign)。
如果是,走左值解析路径:deal_lvalue(left) → deal_expr(right) → scoreboard operation。
| 运算符 | C 代码 | 生成的 mcfunction |
|---|---|---|
= | a = b | scoreboard players operation {name} $(space)_3 = {name} $(space)_tmp_1 |
+= | a += b | operation ... $(space)_3 += ... $(space)_tmp_1 → operation ... $(space)_tmp_1 = ... $(space)_3 |
-= | a -= b | 同上,-= 替换 += |
*= | a *= b | 同上,*= |
/= | a /= b | 同上,/= |
%= | a %= b | 同上,%= |
+= -= *= /= %= 后额外生成一条 operation ... tmp = ... left,把新值复制回临时量。
代码位置:compiler.cpp:305-375
先分别求值左右子表达式(各自得到临时量),然后 tmp_counter--(复用左值的临时量),
最后用 operation ... tmp_left +=/=/*= ... tmp_right 原地运算。
| 运算符 | C 代码 | 生成的 mcfunction |
|---|---|---|
+ | a + b | operation ... tmp_0 += ... tmp_1 |
- | a - b | operation ... tmp_0 -= ... tmp_1 |
* | a * b | operation ... tmp_0 *= ... tmp_1 |
/ | a / b | operation ... tmp_0 /= ... tmp_1 |
% | a % b | operation ... tmp_0 %= ... tmp_1 |
代码位置:compiler.cpp:336-369
比较运算的关键设计:MC 没有直接返回 bool 的运算,所以用 execute if/unless score 条件执行来模拟。
| 运算符 | C 代码 | 生成的三条命令 |
|---|---|---|
== |
a == b |
① operation ... tmp = ... tmp_0(复制左值到共享 tmp)② set ... tmp_0 0(先清零)③ execute if score ... tmp = ... tmp_1 run set ... tmp_0 1(条件成立则置 1)
|
!= |
a != b |
同上,但用 execute unless score ... tmp = ... |
< |
a < b |
同上,但用 execute if score ... tmp < ... |
<= |
a <= b |
同上,<= |
> |
a > b |
同上,> |
>= |
a >= b |
同上,>= |
execute if score 需要两个操作数,左值先复制到全局共享的 tmp 计分板,
右值直接用临时量。全局 tmp 在 start.mcfunction 中初始化,所有比较共享这一个槽位。
代码位置:compiler.cpp:377-395
| 运算符 | C 代码 | 生成的 mcfunction |
|---|---|---|
+ |
+x |
直接透传子表达式结果(恒等) |
- |
-x |
MC 没有一元取负,用 0 - x 绕道:① 创建 const-1 计分板,set const-1 -1② operation ... tmp *= ... const-1③ 返回临时量编号 |
const-1 是全局常量计分板,值为 -1。用乘法实现取负——这是 Minecraft 计分板没有一元取负指令的通用解决方案。
代码位置:compiler.cpp:397-432
函数调用是整个编译器最复杂的翻译,涉及压栈、传参、宏调用、弹栈、读返回值五个步骤。
| 步骤 | 生成的 mcfunction |
|---|---|
| ① 求值实参 | 逐个 deal_expr(arg),每个实参得到一个临时量。然后 execute store result storage {name} {N} int 1 run scoreboard players get {name} $(space)_tmp_{M} 把临时量写入 storage 槽位。 |
| ② 压栈 | scoreboard players add {name} functionSpace 1 |
| ③ 同步栈帧号 | execute store result storage {name} functionSpace int 1 run scoreboard players get {name} functionSpace —— 把 functionSpace 值同步到 storage,这样被调用函数的宏 $(functionSpace) 能拿到正确的栈帧号。 |
| ④ 宏调用 | function {name}:.f.{N}.f. with storage {name} —— 调用目标函数,storage 携带所有参数槽和栈帧号。 |
| ⑤ 弹栈 | scoreboard players remove {name} functionSpace 1 |
| ⑥ 读返回值 | 如果函数返回类型不是 void:initVar + setVarToVar 把 return 计分板复制到新临时量。 |
functionSpace 是全局计分板,记录当前调用深度。每次调用 +1,返回 -1。
被调用函数的局部变量全部用 $(functionSpace)_N 寻址,不同层的变量自然隔离。
这就是宏栈帧机制——Minecraft 没有原生栈帧,我们用宏参数 + 计分板模拟出来了。
代码位置:compiler.cpp:168-199
赋值语句需要知道「往哪里写」,deal_lvalue 从 AST 节点中提取目标计分板名。
DeclRefExpr → 查符号表拿 var.objective;
ParenExpr/UnexposedExpr → 透传。
不支持的类型将返回空 LValue。
表达式求值的核心原则:MC 计分板 operation 不能直接操作字面量,必须通过计分板目标。
所以每个表达式中间结果都放在一个「临时变量」里——这就是 tmp 机制。
| 机制 | 说明 |
|---|---|
| 计数器 | tmp_counter:每次 start_deal_expr 重置为 0。每次需要新临时量时 tmp_counter++。 |
| 命名 | 函数内:$(functionSpace)_tmp_N;全局上下文:0_tmp_N(?(space) 替换为 0)。 |
| 生命周期 | 每次 start_deal_expr 清空计数器,同一表达式内顺序分配。不同表达式之间不共享临时量。 |
| 创建方式 | initVar(name, CXType_Int):先 scoreboard objectives remove 清理旧值,再 scoreboard objectives add 创建。 |
| 复用优化 | 二元运算时 tmp_counter--:左值临时量被右值运算结果覆盖,减少临时量占用。 |
| 函数调用特殊处理 | CallExpr 中 tmp_counter = tmp - num + 1:调用后临时量从第一个实参位置开始复用,避免浪费。 |
scoreboard players set 只能设值,不能清空目标。
所以每次创建临时量都先移除再添加——确保干净的状态。这是 MC 计分板 API 的固有限制。
这是 CraftLang 最精妙的设计——仿照传统编译器「目标文件 → 链接器」的模型,把编译和链接拆成两个独立程序。
每个 .c 文件独立编译,最后链接器统一合并。
每个 .c 文件编译后生成两个产物:
| 产物 | 内容 |
|---|---|
{name}_symbols.json | JSON 格式的符号表:{"Global": [{name, number, isExtern}, ...], "function": [{name, number, isExtern}, ...]} |
{name}_o/function/ | 命令文件目录:start.mcfunction + .f.{N}.f..mcfunction 等。文件名含局部编号,内容含占位符。 |
{name}_o/other/ | 其他资源文件(如内建库的 minecraft/tags/function/load.json) |
关键:每个文件独立编译时,函数和变量用的是「局部编号」——文件 A 的第 0 个函数和文件 B 的第 0 个函数可能同名,但编号独立。 链接器负责合并这些编号。
代码位置:src/linker/linker.cpp:84-101
读入每个 *_symbols.json,调用 collectCategory 合并到全局 functionMap 和 globalMap。
| 规则 | 说明 |
|---|---|
| 首次出现 | 分配全局编号 counter++,标记 defined = !isExtern |
| 重复出现 + extern | 共享已有编号,不改变 defined 状态 |
| 重复出现 + 非 extern | 如果之前未定义则标记为已定义;如果之前已定义则 抛出 duplicate definition 错误 |
代码位置:src/linker/linker.cpp:241-249
遍历 functionDefined 和 globalDefined,检查所有 extern 声明是否有对应的定义。
如果某个符号 defined == false(即所有文件中都是 extern 声明,没有实际定义),抛出 undefined extern 错误。
代码位置:src/linker/linker.cpp:102-231
对每个编译产物,做三件事:
| 替换目标 | 替换方式 |
|---|---|
.f.{N}.f. → 全局编号 | replaceAll(content, ".f." + to_string(local) + ".f.", to_string(global)) |
.g.{N}.g. → 全局编号 | replaceAll(content, ".g." + to_string(local) + ".g.", to_string(global)) |
..name.. → 真实数据包名 | replaceAll(content, "..name..", config.name) |
注意:?(space) 占位符在编译器阶段已经替换完毕(addCommand 函数内部处理),链接器不需要处理。
代码位置:src/linker/linker.cpp:232-289
| 产物 | 生成逻辑 |
|---|---|
pack.mcmeta | init():JSON 格式,含 pack_format 和 description |
start.mcfunction | 拼接所有编译产物的 start 内容 + 初始化计分板(functionSpace 和 tmp)+ 调用 main(如果存在) |
| 函数文件 | 重写编号后的 .mcfunction 文件,复制到最终目录 |
other/ 资源 | 递归复制(如内建库的 load.json),同样替换编号和 ..name.. |
以项目的 example/setting.json 为例:
{
"name": "craftlang",
"pack_format": 101,
"description": "test",
"linkFile": [
"build\\test_symbols.json", // test.c 编译产物
"build\\test2_symbols.json", // test2.c 编译产物
"build\\if_test_symbols.json", // if_test.c 编译产物
"mcstd\\mcstd_symbols.json" // 内建库预编译产物
],
"outputPath": "build\\craftlang"
}
test.c 定义了 add/sub/mul/divi/mod/main 等函数 + 全局变量 g1 + extern g2。
test2.c 定义了 judge 函数 + 全局变量 g2(满足 test.c 的 extern 引用)。
mcstd 提供了 print_int 内建函数。
链接器把三份符号表合并,g2 在 test.c 中 extern、test2.c 中定义,链接器检查通过后分配统一编号。
这是项目当前正在开发中的功能。脚手架已经搭好,但关键的连接逻辑还没写。
deal_cursor(CXCursor_IfStmt) 在 compiler.cpp:671-722start_deal_expr(condition) 正确计算条件值.f.{N}.f._{M}.mcfunction.f.{N}.f._{M+1}.mcfunctionoldCurrentContent、oldCurrentFile 等以下是 compiler.cpp:671-722 的逐行分析:
case CXCursor_IfStmt:
{
// ① 解析 if 的三个子节点:condition, then, [else]
std::vector<CXCursor> children = getChildCursors(cursor);
CXCursor condition = children[0]; // 条件表达式
CXCursor then = children[1]; // then 分支
bool has_else = children.size() == 3; // 是否有 else
// ② 求值条件表达式(得到临时量,但从未使用!)
ExprResult tmp = start_deal_expr(condition);
// ③ 保存当前上下文
std::string oldCurrentContent = current_content;
auto name = ".f." + std::to_string(current_function.number)
+ ".f._" + std::to_string(childrenFunctionCounter++);
fs::path oldCurrentFile = current_file;
bool oldIsInFunction = isInFunction;
// ④ 编译 then 分支到独立文件
current_content = "";
current_file = name;
isInFunction = false;
deal_cursor(then); // 生成 then 内部的所有命令
// ⑤ 输出 then 文件
std::ofstream outputFile(function_path / (current_file.string() + ".mcfunction"), ...);
outputFile << addDollarPrefix(current_content);
outputFile.close();
// ⑥ 如果有 else,同样编译到独立文件
if (has_else) {
current_content = "";
name = ".f." + ... + ".f._" + std::to_string(childrenFunctionCounter++);
current_file = name;
isInFunction = false;
auto then = children[2]; // 注意:这里变量名是 then 但实际是 else
deal_cursor(then);
// 输出 else 文件
}
// ⑦ 恢复上下文
current_content = oldCurrentContent; // 恢复父函数内容
current_file = oldCurrentFile;
isInFunction = oldIsInFunction;
break;
}
在恢复上下文之前,需要生成条件跳转指令来连接父函数和分支文件:
// ═══ 需要补充的代码 ═══
// 在 ⑦ 恢复上下文之前,生成条件跳转:
// 从条件临时量中读取值到共享 tmp
addCommand("scoreboard players operation " + config.name + " tmp = "
+ config.name + " ?(space)_tmp_" + std::to_string(tmp.tmp_number) + "\n");
// 条件为真 → 跳转到 then 分支
addCommand("execute if score " + config.name + " tmp matches 1 run function "
+ config.name + ":.f." + std::to_string(current_function.number)
+ ".f._" + std::to_string(then_number) + ".f. with storage " + config.name + "\n");
if (has_else) {
// 条件为假 → 跳转到 else 分支
addCommand("execute unless score " + config.name + " tmp matches 1 run function "
+ config.name + ":.f." + std::to_string(current_function.number)
+ ".f._" + std::to_string(else_number) + ".f. with storage " + config.name + "\n");
}
functionSpace,才能访问父函数的局部变量。
所以分支调用必须用 function ... with storage 传递当前 storage 上下文。
此外,分支文件末尾需要 return 0(mcfunction 要求),但 return 之后不能有后续指令——这可能导致分支和父函数后续代码的衔接问题。
可以考虑分支文件最后不 return,而是用 function 调用回到父函数的「续接点」——但这需要额外的函数拆分。
根据 design.md,V2.0 的控制流设计:
| 控制流语句 | 编译策略 |
|---|---|
if / else | 编译为独立函数,用 execute if/unless score 实现条件跳转 |
while / for | 编译为尾递归函数,在函数末尾根据条件决定是否继续递归 |
| 所有控制流子块 | 接收相同的 stack 宏参数,共享父函数的局部变量 |
| 约定 | 说明 |
|---|---|
.f.{N}.f. | 函数中间产物文件名,链接时替换为全局编号 |
.g.{N}.g. | 全局变量计分板目标名,链接时替换为全局编号 |
..name.. | 数据包名占位符,链接时替换为真实名字 |
?(space) | 栈帧占位符:全局上下文→0,函数内→$(functionSpace) |
$(functionSpace)_N | 局部变量/参数,运行时宏展开为当前栈帧层 |
$(functionSpace)_tmp_N | 临时量,LIFO 复用 |
deal_xxx 函数 | 分发处理函数:deal_cursor(语句)、deal_expr(表达式)、deal_lvalue(左值) |
start_deal_expr | 表达式求值入口,重置 tmp_counter |
| 模式 | 代码位置 | 说明 |
|---|---|---|
| 表驱动分发 | compiler.cpp:43-48 | exprStatementKinds 向量列出所有可作为语句的表达式类型,默认分支用 std::find 匹配 |
| 左值分类 | compiler.cpp:20-27 | binaryOperatorNeedLValue 向量列出需要左值的运算符,赋值类走左值路径 |
| 统一入口 | compiler.cpp:155-167 | addCommand 自动区分全局/函数上下文,替换 ?(space),写入对应 content |
| 字符串替换 | compiler.cpp:52-63 | replaceAll 全局替换占位符,用于链接器重写编号 |
| 宏标记 | compiler.cpp:65-81 | addDollarPrefix:含 $ 的行自动加 $ 前缀变成宏指令 |
| 先局部后全局 | compiler.cpp:139-154 | find_var 先在 localVarsToInt 查找,找不到再查 globalVarsToInt |
编译器所有状态都是全局变量(compiler.cpp:29-48):
current_content、current_function、localVarsToInt、globalVarsToInt、
functionMap、tmp_counter、isInFunction 等。
这是有意为之的单线程设计——编译器不需要并发,全局状态让代码更简洁。
链接器同样采用全局状态:functionMap、globalMap、functionDefined、globalDefined、startContext。
| 策略 | 说明 |
|---|---|
| libclang 诊断零容忍 | 任何警告/错误都导致 throw,源码必须零警告 |
| 不支持的节点响亮报错 | 遇到未实现的 AST 节点类型,打印类型名并抛异常,绝不静默跳过 |
| 变量未找到报错 | find_var 找不到变量时打印变量名并抛异常 |
| 链接器重复定义报错 | 同一符号在多个文件中有非 extern 定义时抛异常 |
| extern 未定义报错 | 链接器检查所有 extern 是否有对应定义 |
| 结构体 | 字段 | 用途 |
|---|---|---|
Function |
name, return_type, parms, number, cursor, isExtern |
函数符号表条目。编译器登记,链接器合并重编号。 |
Var |
name, objective, type, number, isExtern |
变量符号表条目。objective 是计分板目标名(如 $(functionSpace)_3 或 0_.g.5.g.)。 |
Parm |
kind, name, number |
函数参数。number 是参数在函数内的编号(0, 1, 2...),对应宏参数 $(0) $(1)。 |
ExprResult |
tmp_number |
表达式求值结果——只包含临时量编号。调用方用这个编号去拼 $(space)_tmp_N。 |
LValue |
objective |
左值——计分板目标名。赋值时直接对其操作。 |
Cursor |
cursor, parent, children |
AST 节点包装。存储在 all_cursors 哈希表中,用自定义哈希和相等比较。 |
| Minecraft 机制 | 在 CraftLang 中的角色 | 通俗比喻 |
|---|---|---|
计分板 scoreboard | 程序的「内存」——所有 int 变量、临时量、函数返回值都存在这里 | 一本「名字 → 数字」的记账本 |
存储 storage | 函数调用的「参数快递箱」——调用前把实参打包进 storage,被调用方从 storage 取出 | 传递参数的快递盒 |
宏函数 /function ... with | 函数模板机制——同一份命令模板,每次调用时 $(N) 被替换为不同的值 | 一张填空表,每次填不同的数 |
functionSpace 计分板 | 「栈指针」——调用深度计数器。调用时 +1,返回时 -1。局部变量用它做地址前缀 | 摞盘子,每层有自己的变量 |
以 add(10, 20) 为例,以下是在游戏里实际执行的命令序列:
# ═══ 调用方 main ═══
# ① 求值实参:10 → tmp_0, 20 → tmp_1
scoreboard objectives remove $(functionSpace)_tmp_0
scoreboard objectives add $(functionSpace)_tmp_0 dummy
scoreboard players set craftlang $(functionSpace)_tmp_0 10
scoreboard objectives remove $(functionSpace)_tmp_1
scoreboard objectives add $(functionSpace)_tmp_1 dummy
scoreboard players set craftlang $(functionSpace)_tmp_1 20
# ② 传参:把实参写入 storage 的 0 号和 1 号槽
$execute store result storage craftlang 0 int 1 run scoreboard players get craftlang $(functionSpace)_tmp_0
$execute store result storage craftlang 1 int 1 run scoreboard players get craftlang $(functionSpace)_tmp_1
# ③ 压栈:functionSpace +1
scoreboard players add craftlang functionSpace 1
# ④ 同步栈帧号到 storage
execute store result storage craftlang functionSpace int 1 run scoreboard players get craftlang functionSpace
# ⑤ 宏调用:进入 add 函数
function craftlang:3 with storage craftlang
# ═══ 被调用方 add(文件 3.mcfunction)═══
# ⑥ 参数绑定:从 storage 宏参数取值写入本层局部变量
$scoreboard objectives remove $(functionSpace)_0 dummy
$scoreboard objectives add $(functionSpace)_0 dummy
$scoreboard players set craftlang $(functionSpace)_0 $(0) # $(0) = 10
$scoreboard objectives remove $(functionSpace)_1 dummy
$scoreboard objectives add $(functionSpace)_1 dummy
$scoreboard players set craftlang $(functionSpace)_1 $(1) # $(1) = 20
# ⑦ 执行加法:a + b
$scoreboard objectives remove $(functionSpace)_tmp_0
$scoreboard objectives add $(functionSpace)_tmp_0 dummy
$scoreboard players operation craftlang $(functionSpace)_tmp_0 = craftlang $(functionSpace)_0
$scoreboard players operation craftlang $(functionSpace)_tmp_0 += craftlang $(functionSpace)_1
# ⑧ 返回:把结果写入全局 return 计分板
scoreboard objectives add return dummy
scoreboard players operation craftlang return = craftlang $(functionSpace)_tmp_0
return 0
# ═══ 回到调用方 main ═══
# ⑨ 弹栈:functionSpace -1
scoreboard players remove craftlang functionSpace 1
# ⑩ 读返回值:从 return 复制到临时量
scoreboard objectives remove $(functionSpace)_tmp_2
scoreboard objectives add $(functionSpace)_tmp_2 dummy
scoreboard players operation craftlang $(functionSpace)_tmp_2 = craftlang return
return 是全局计分板(不是 $(functionSpace)_return),因为弹栈后调用方的 functionSpace 已经变了,
如果 return 放在栈帧里就访问不到了。全局 return 是唯一的「返回值通道」。
| 依赖 | 说明 |
|---|---|
| CMake ≥ 3.15 | 构建系统 |
| C++17 编译器 | 项目用 llvm-mingw 的 clang++ |
| libclang | LLVM/Clang 的 C 接口,提供 AST 解析能力 |
| nlohmann/json | 已随项目内置(third_party/json/json.hpp) |
CMakeLists.txt 产出两个目标:craftlang.exe(编译器)和 craftlinker.exe(链接器)。
# 设置 libclang 路径
$env:LIBCLANG_PATH = "C:\Program Files\LLVM"
# 配置(MinGW Makefiles)
cmake -G "MinGW Makefiles" -B build
# 构建
cmake --build build
# DEBUG 模式构建(输出更多日志)
cmake -G "MinGW Makefiles" -B build -DCMAKE_CXX_FLAGS="-D_DEBUG"
cmake --build build
CMake 用 file(GLOB_RECURSE) 收集源文件,新增/删除 src 下的 .cpp 后需重新运行配置命令。
构建后会自动把 libclang.dll 复制到可执行文件旁。
# 1. 编译每个 C 源文件(生成中间产物)
build\craftlang.exe example\test.c
build\craftlang.exe example\test2.c
build\craftlang.exe example\if_test.c
# 2. 链接成完整数据包
build\craftlinker.exe example\setting.json
# 3. 把 build\craftlang\craftlang\ 复制到游戏存档的 datapacks 目录
# 游戏加载时自动执行 start → 初始化 → 调用 main()
CraftLang/ ├─ include/ │ ├─ craftlang/ │ │ ├─ config.h // 编译器配置结构体 │ │ ├─ lang.h // AST 遍历接口(Cursor, CursorHash, all_cursors) │ │ └─ compiler.h // 代码生成接口(Function, Var, ExprResult, deal_xxx) │ ├─ linker/ │ │ ├─ config.h // 链接器配置结构体 │ │ └─ linker.h // 链接器接口(linkFile, dealFile, link) │ └─ mcstd.h // 内建函数声明(print_int)+ bool 宏定义 ├─ src/ │ ├─ compiler/ │ │ ├─ main.cpp // 编译器入口:libclang 解析 + AST 遍历 │ │ ├─ lang.cpp // AST 收集(collectChildrenCallback)与打印 │ │ └─ compiler.cpp // 代码生成核心(deal_cursor / deal_expr / 符号表) │ └─ linker/ │ ├─ main.cpp // 链接器入口:读取配置 │ └─ linker.cpp // 链接器核心:符号合并 / 编号重写 / 数据包组装 ├─ mcstd/ │ ├─ mcstd_symbols.json // 内建库符号表 │ └─ mcstd_o/ │ ├─ function/ │ │ ├─ .f.0.f..mcfunction // print_int 实现(say $(0)) │ │ └─ start.mcfunction // 空(内建库无全局变量) │ └─ other/minecraft/tags/function/ │ └─ load.json // 数据包加载入口标签 ├─ third_party/json/ │ └─ json.hpp // nlohmann/json 单头文件 ├─ example/ │ ├─ test.c // 主测试文件(四则运算 + 函数调用 + 全局变量) │ ├─ test2.c // 补充测试(比较运算 + 全局变量 g2 定义) │ ├─ if_test.c // if 语句测试(classify 函数) │ └─ setting.json // 链接配置(数据包名 + 链接文件列表) ├─ CMakeLists.txt // 构建脚本 ├─ design.md // 六阶段架构演进设计文档 └─ README.md // 项目说明
print_int、符号表、多文件链接 —— 游戏内实测通过
已完成
if/while/for)、受限指针(无算术)、变长数组、与手写 mcfunction 混合构建、递归验证
当前开发中
// @max_iter N 注释提示最大循环次数,小循环完全展开)
可选
mc_setblock、mc_summon、mc_fill、mc_exec 自定义命令
计划中