CraftLang

把 C 语言编译成 Minecraft 数据包

目标平台 Minecraft Java 1.20.5+ 前端 libclang / 后端 C++17 进度 V1.0 实测通过 构建 CMake + MinGW
scoreboardstorage宏函数AST 计分板栈帧链接器extern print_intfunctionSpacetmp 临时量

0这是什么?

你写 C 语言,编译器把它翻译成游戏里的命令。
就像一台「C → Minecraft 命令」的翻译机——int a = 10; 变成 scoreboard players set, return a + b; 变成计分板运算 + 函数返回,add(x, y) 变成压栈→传参→宏调用→弹栈。 全部自动完成,你不需要在游戏里手写任何命令。

1整体流程:六步,两个工具

一份 C 源码变成能在游戏里跑的数据包,中间经过 编译器(翻译)和 链接器(组装)两个独立程序。往下看,每个阶段都标了对应的代码文件位置。

① 输入
📄 写 C 源码 + 配置 setting.json
C 源码(test.c)+ 链接配置(数据包名、pack_format、要链接哪些编译产物)
▼
② 编译器 craftlang.exe
🧠 libclang 解析 AST → 逐语句翻译成计分板命令
代码位置:src/compiler/main.cpp 入口 → lang.cpp AST 收集 → compiler.cpp 代码生成
▼
③ 中间产物
📦 符号表 JSON + 半成品命令文件
{name}_symbols.json(函数/变量清单) + {name}_o/function/*.mcfunction(每条命令已生成,但编号是局部编号)
▼
▼
⑤ 最终产物
🎁 完整 Minecraft 数据包
pack.mcmeta + data/{name}/function/*.mcfunction + start.mcfunction + load.json
▼
⑥ 运行
🕹️ 放入游戏存档的 datapacks 目录
游戏加载时自动执行 load.json → start.mcfunction → 初始化计分板 → 调用 main(),你的 C 程序跑起来了!

2代码架构:函数调用关系与分发机制

理解代码架构是接手项目的第一步。下面从调用层次、分发模式、数据流三个维度拆解整个代码结构。

2.0 全局视角:两个进程,两套代码

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 把多份中间产物合并、重编号、组装成最终数据包

2.1 编译器调用层次:一张图看清所有函数的关系

以下是从 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", ...)  // 读返回值

2.2 核心分发模式:双层 Switch 架构

编译器最核心的设计模式是双层 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:start_deal_expr 在调用 deal_expr 之前把 tmp_counter 重置为 0, 确保每次表达式求值从干净的临时量编号开始。如果直接调用 deal_expr,临时量编号会累积,导致混乱。

2.3 辅助函数层:被 deal_xxx 调用的底层工具

函数代码位置被谁调用作用
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 获取子节点列表

2.4 全局状态变量:编译器的「工作内存」

以下全局变量在 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

2.5 链接器架构:两阶段处理

链接器代码相对简单,集中在 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 还没被定义的情况就没法处理了。

2.6 数据流:变量在函数间如何传递

下面是编译器内部的数据流转图,展示了每次函数调用时参数如何跨越函数边界:

═══ 编译器内部数据流 ═══

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 调用)

3编译器 craftlang 深度剖析

编译器是项目的核心翻译引擎。它接收一份 C 源码,输出一份「半成品」——符号表 JSON + 命令文件。整个流程分为四步:

3.1 第一步:libclang 解析

入口在 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 守卫区分「前向声明」和「真正定义」。

3.2 第二步:AST 收集与遍历

代码位置:src/compiler/lang.cpp:11-28 和 :42-62。

clang_visitChildren 递归遍历 AST,collectChildrenCallback 回调把每个节点登记到全局哈希表 all_cursors。 这个表用 CursorHash 自定义哈希(基于 CXCursor 内部三个 void* 指针), CursorEqual 用 clang_equalCursors 比较——保证同一节点不重复登记。

然后 visitCursorRecursive 先序遍历整棵树,打印每个节点的类型和名称(DEBUG 模式输出完整 AST 结构)。 根节点固定为 TranslationUnit。

3.3 第三步:诊断检查

代码位置:src/compiler/main.cpp:79-93。

⚠ 零容忍策略:任何 libclang 诊断(包括警告)都导致 diagCount > 0 → throw 终止编译。 源码必须保证零警告才能通过。这是有意为之——避免悄悄生成有问题的半成品。

3.4 第四步:代码生成

入口:compile(CXCursor root_cursor) → deal_cursor(root_cursor)。

deal_cursor 是一个巨型 switch,根据 CXCursorKind 分发到不同处理逻辑。 下面 §4 和 §5 会逐一展开每种语句和表达式的翻译细节。

4语句翻译对照表(deal_cursor 全览)

每种 C 语句遇到 deal_cursor 时,会走哪个 case、生成什么 Minecraft 命令。这是项目的核心翻译规则。

4.1 TranslationUnit(根节点)

代码位置:compiler.cpp:447-484

触发条件生成逻辑
CXCursor_TranslationUnit ① 将 current_function.name 设为 "Global" —— 此时所有语句都在全局上下文
② 遍历所有子节点,逐个调用 deal_cursor(child)(函数声明、全局变量声明等)
③ 全部遍历完后,把 startFunctionContent 写入 start.mcfunction
④ 把 globalVarsToInt 和 functionMap 序列化为 JSON 写入符号表文件
💡 设计意图:startFunctionContent 收集所有全局变量的初始化指令,在 start.mcfunction 里一次性执行。 链接器之后会拼接各文件的 start 内容,加上计分板初始化,最终组装成完整的入口文件。

4.2 FunctionDecl(函数声明/定义)

代码位置: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 注入当前栈帧号。

4.3 VarDecl(变量声明)

代码位置: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. 替换函数编号。

4.4 DeclStmt(声明语句块)

代码位置:compiler.cpp:573-580

简单透传——遍历子节点(通常是 VarDecl),逐个调用 deal_cursor。本身不生成任何命令。

4.5 CompoundStmt(复合语句 / 大括号块)

代码位置:compiler.cpp:663-669

同样简单透传——遍历子节点调用 deal_cursor。这是函数体和 {} 块的通用处理。

4.6 ReturnStmt(返回语句)

代码位置: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 放在栈帧里,弹栈后就访问不到了。

4.7 表达式语句(默认分支)

代码位置:compiler.cpp:726-735

当 cursor 不是以上任何一种时,检查是否在 exprStatementKinds 列表中。 如果是,调用 start_deal_expr 求值表达式,丢弃结果(副作用已通过计分板命令生效)。 如果不是,抛出 runtime_error,打印不支持的节点类型。

exprStatementKinds = {CallExpr, BinaryOperator, CompoundAssignOperator, ParenExpr} —— 这些都是可以作为语句出现的表达式类型。

5表达式编译机制

表达式求值是整个编译器最复杂的部分。核心思想:每个表达式求值结果放在一个临时量(tmp)里, 返回临时量编号,外层表达式可以继续用这个编号做运算。

5.1 IntegerLiteral(整数常量)

代码位置:compiler.cpp:212-221

C 代码生成的 mcfunction 命令
42 scoreboard objectives remove $(functionSpace)_tmp_0
scoreboard objectives add $(functionSpace)_tmp_0 dummy
scoreboard players set {name} $(functionSpace)_tmp_0 42

用 clang_EvalResult_getAsInt 获取常量值,直接 scoreboard players set 写入临时量。

5.2 DeclRefExpr(变量引用)

代码位置:compiler.cpp:234-243

C 代码生成的 mcfunction 命令
a(局部变量) scoreboard objectives remove $(functionSpace)_tmp_0
scoreboard objectives add $(functionSpace)_tmp_0 dummy
scoreboard players operation {name} $(functionSpace)_tmp_0 = {name} $(functionSpace)_3

通过 find_var(name) 查找符号表(先局部后全局),获取变量的计分板目标名,用 operation ... = 复制到临时量。

5.3 ParenExpr / UnexposedExpr(括号/透明表达式)

代码位置:compiler.cpp:222-233

直接透传给唯一的子节点。如果子节点数量不是 1,抛异常。

5.4 BinaryOperator — 赋值类

代码位置:compiler.cpp:255-303

先判断运算符是否在 binaryOperatorNeedLValue 列表中(Assign, AddAssign, SubAssign, MulAssign, DivAssign, RemAssign)。 如果是,走左值解析路径:deal_lvalue(left) → deal_expr(right) → scoreboard operation。

运算符C 代码生成的 mcfunction
=a = bscoreboard players operation {name} $(space)_3 = {name} $(space)_tmp_1
+=a += boperation ... $(space)_3 += ... $(space)_tmp_1 → operation ... $(space)_tmp_1 = ... $(space)_3
-=a -= b同上,-= 替换 +=
*=a *= b同上,*=
/=a /= b同上,/=
%=a %= b同上,%=
💡 复合赋值返回值:复合赋值在 C 语言中是有返回值的(表达式求值结果 = 赋值后的值)。 所以在 += -= *= /= %= 后额外生成一条 operation ... tmp = ... left,把新值复制回临时量。

5.5 BinaryOperator — 算术类

代码位置:compiler.cpp:305-375

先分别求值左右子表达式(各自得到临时量),然后 tmp_counter--(复用左值的临时量), 最后用 operation ... tmp_left +=/=/*= ... tmp_right 原地运算。

运算符C 代码生成的 mcfunction
+a + boperation ... tmp_0 += ... tmp_1
-a - boperation ... tmp_0 -= ... tmp_1
*a * boperation ... tmp_0 *= ... tmp_1
/a / boperation ... tmp_0 /= ... tmp_1
%a % boperation ... tmp_0 %= ... tmp_1

5.6 BinaryOperator — 比较类(EQ/NE/LT/LE/GT/GE)

代码位置: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 同上,>=
💡 为什么用共享 tmp:execute if score 需要两个操作数,左值先复制到全局共享的 tmp 计分板, 右值直接用临时量。全局 tmp 在 start.mcfunction 中初始化,所有比较共享这一个槽位。

5.7 UnaryOperator(单目运算符)

代码位置: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 计分板没有一元取负指令的通用解决方案。

5.8 CallExpr(函数调用)— 最复杂的表达式

代码位置: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 没有原生栈帧,我们用宏参数 + 计分板模拟出来了。

5.9 deal_lvalue(左值解析)

代码位置:compiler.cpp:168-199

赋值语句需要知道「往哪里写」,deal_lvalue 从 AST 节点中提取目标计分板名。 DeclRefExpr → 查符号表拿 var.objective; ParenExpr/UnexposedExpr → 透传。 不支持的类型将返回空 LValue。

6tmp 临时变量机制深度剖析

表达式求值的核心原则: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:调用后临时量从第一个实参位置开始复用,避免浪费。
⚡ 为什么先 remove 再 add:Minecraft 计分板没有「重置」指令,scoreboard players set 只能设值,不能清空目标。 所以每次创建临时量都先移除再添加——确保干净的状态。这是 MC 计分板 API 的固有限制。

7多文件编联机制(最核心的架构设计)

这是 CraftLang 最精妙的设计——仿照传统编译器「目标文件 → 链接器」的模型,把编译和链接拆成两个独立程序。 每个 .c 文件独立编译,最后链接器统一合并。

7.1 编译阶段:每个 .c 独立产出

每个 .c 文件编译后生成两个产物:

产物内容
{name}_symbols.jsonJSON 格式的符号表:{"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 个函数可能同名,但编号独立。 链接器负责合并这些编号。

7.2 链接阶段一:收集符号(linkFile)

代码位置:src/linker/linker.cpp:84-101

读入每个 *_symbols.json,调用 collectCategory 合并到全局 functionMap 和 globalMap。

规则说明
首次出现分配全局编号 counter++,标记 defined = !isExtern
重复出现 + extern共享已有编号,不改变 defined 状态
重复出现 + 非 extern如果之前未定义则标记为已定义;如果之前已定义则 抛出 duplicate definition 错误

7.3 链接阶段二:检查 extern 引用

代码位置:src/linker/linker.cpp:241-249

遍历 functionDefined 和 globalDefined,检查所有 extern 声明是否有对应的定义。 如果某个符号 defined == false(即所有文件中都是 extern 声明,没有实际定义),抛出 undefined extern 错误。

7.4 链接阶段三:重写编号(dealFile)

代码位置: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 函数内部处理),链接器不需要处理。

7.5 链接阶段四:组装最终数据包

代码位置:src/linker/linker.cpp:232-289

产物生成逻辑
pack.mcmetainit():JSON 格式,含 pack_format 和 description
start.mcfunction拼接所有编译产物的 start 内容 + 初始化计分板(functionSpace 和 tmp)+ 调用 main(如果存在)
函数文件重写编号后的 .mcfunction 文件,复制到最终目录
other/ 资源递归复制(如内建库的 load.json),同样替换编号和 ..name..

7.6 完整示例:三个文件链接

以项目的 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 中定义,链接器检查通过后分配统一编号。

8If 语句 — 当前状态 & 未完成分析

这是项目当前正在开发中的功能。脚手架已经搭好,但关键的连接逻辑还没写。

✅ 已实现的部分 代码已有

  • deal_cursor(CXCursor_IfStmt) 在 compiler.cpp:671-722
  • 条件表达式求值:start_deal_expr(condition) 正确计算条件值
  • then 分支编译为独立文件:.f.{N}.f._{M}.mcfunction
  • else 分支编译为独立文件:.f.{N}.f._{M+1}.mcfunction
  • 分支文件内容正确生成(内部语句都被翻译了)
  • 上下文保存/恢复:oldCurrentContent、oldCurrentFile 等

⏳ 未完成的部分 需要补充

  • 没有生成条件跳转指令:条件求值结果存在临时量里但从未被使用
  • 没有生成分支调用指令:then/else 文件存在但从不被调用
  • 没有分支合并:执行完 then 或 else 后缺少汇合点
  • 没有处理 else if:当前 else if 被 clang 解析为嵌套 if,但 else 分支里的 if 也一样缺连接

8.1 当前代码做了什么

以下是 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;
}

8.2 缺少什么:需要补充的代码

在恢复上下文之前,需要生成条件跳转指令来连接父函数和分支文件:

// ═══ 需要补充的代码 ═══
// 在 ⑦ 恢复上下文之前,生成条件跳转:

// 从条件临时量中读取值到共享 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");
}
⚠ 设计挑战:then/else 分支文件需要接收父函数的 functionSpace,才能访问父函数的局部变量。 所以分支调用必须用 function ... with storage 传递当前 storage 上下文。 此外,分支文件末尾需要 return 0(mcfunction 要求),但 return 之后不能有后续指令——这可能导致分支和父函数后续代码的衔接问题。 可以考虑分支文件最后不 return,而是用 function 调用回到父函数的「续接点」——但这需要额外的函数拆分。

8.3 设计文档中的规划(V2.0)

根据 design.md,V2.0 的控制流设计:

控制流语句编译策略
if / else编译为独立函数,用 execute if/unless score 实现条件跳转
while / for编译为尾递归函数,在函数末尾根据条件决定是否继续递归
所有控制流子块接收相同的 stack 宏参数,共享父函数的局部变量

9代码风格与设计模式

9.1 命名约定

约定说明
.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

9.2 设计模式

模式代码位置说明
表驱动分发compiler.cpp:43-48exprStatementKinds 向量列出所有可作为语句的表达式类型,默认分支用 std::find 匹配
左值分类compiler.cpp:20-27binaryOperatorNeedLValue 向量列出需要左值的运算符,赋值类走左值路径
统一入口compiler.cpp:155-167addCommand 自动区分全局/函数上下文,替换 ?(space),写入对应 content
字符串替换compiler.cpp:52-63replaceAll 全局替换占位符,用于链接器重写编号
宏标记compiler.cpp:65-81addDollarPrefix:含 $ 的行自动加 $ 前缀变成宏指令
先局部后全局compiler.cpp:139-154find_var 先在 localVarsToInt 查找,找不到再查 globalVarsToInt

9.3 全局状态设计

编译器所有状态都是全局变量(compiler.cpp:29-48): current_content、current_function、localVarsToInt、globalVarsToInt、 functionMap、tmp_counter、isInFunction 等。 这是有意为之的单线程设计——编译器不需要并发,全局状态让代码更简洁。

链接器同样采用全局状态:functionMap、globalMap、functionDefined、globalDefined、startContext。

9.4 错误处理策略

策略说明
libclang 诊断零容忍任何警告/错误都导致 throw,源码必须零警告
不支持的节点响亮报错遇到未实现的 AST 节点类型,打印类型名并抛异常,绝不静默跳过
变量未找到报错find_var 找不到变量时打印变量名并抛异常
链接器重复定义报错同一符号在多个文件中有非 extern 定义时抛异常
extern 未定义报错链接器检查所有 extern 是否有对应定义

10核心数据结构一览

结构体字段用途
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 哈希表中,用自定义哈希和相等比较。

11游戏运行时:程序怎么活起来的?

11.1 四大机制的角色

Minecraft 机制在 CraftLang 中的角色通俗比喻
计分板 scoreboard程序的「内存」——所有 int 变量、临时量、函数返回值都存在这里一本「名字 → 数字」的记账本
存储 storage函数调用的「参数快递箱」——调用前把实参打包进 storage,被调用方从 storage 取出传递参数的快递盒
宏函数 /function ... with函数模板机制——同一份命令模板,每次调用时 $(N) 被替换为不同的值一张填空表,每次填不同的数
functionSpace 计分板「栈指针」——调用深度计数器。调用时 +1,返回时 -1。局部变量用它做地址前缀摞盘子,每层有自己的变量

11.2 一次函数调用的完整数据流

以 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 是唯一的「返回值通道」。

12构建系统与使用流程

12.1 依赖

依赖说明
CMake ≥ 3.15构建系统
C++17 编译器项目用 llvm-mingw 的 clang++
libclangLLVM/Clang 的 C 接口,提供 AST 解析能力
nlohmann/json已随项目内置(third_party/json/json.hpp)

12.2 CMake 构建

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 复制到可执行文件旁。

12.3 完整使用流程

# 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()

13项目文件结构

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           // 项目说明

14六阶段演进路线图

V1.0 ✅ 纯整数运算、函数调用、宏栈帧、print_int、符号表、多文件链接 —— 游戏内实测通过 已完成
V2.0 🔄 控制流(if/while/for)、受限指针(无算术)、变长数组、与手写 mcfunction 混合构建、递归验证 当前开发中
V2.5 循环展开优化(// @max_iter N 注释提示最大循环次数,小循环完全展开) 可选
V3.0 浮点数(软件模拟,两个计分板槽位 = 有效数字 + 指数)、字符串(可计算 char[] + 常量字符串) 计划中
V4.0 世界交互:mc_setblock、mc_summon、mc_fill、mc_exec 自定义命令 计划中
V5.0 数据包元数据:合成表、成就、战利品表自动生成 计划中
V6.0 源代码级调试器:「语句即函数」调试模式、断点、变量查看、调用栈回溯 计划中