计算器指令

计算器是 OpenModsLib 唯一直接面向玩家的功能。通过客户端的 =* 指令可以即时求值数学表达式、定义变量与函数、切换数值后端，并从磁盘脚本批量执行。整个指令树的构建入口是 CommandCalcFactory（src/main/java/openmods/calc/command/CommandCalcFactory.java:35）。

引擎内部机制见计算器引擎，后端差异见类型后端，其余 OpenModsLib 指令见指令总览。

基本信息

功能

根组件的完整子命令表

CommandCalcFactory.root（CommandCalcFactory.java:39）是一个 MapCommandComponent，含 6 个子命令：

echo 是本条目最需要注意的一处不对称：它在根组件中已完整实现（CommandCalcFactory.java:245-250，直接 sender.addChatMessage(new ChatComponentText(args.getTail()))），但 OpenClientProxy.java:101-105 只注册了 config/eval/fun/let/execute 五条，没有为 echo 注册顶层 ICommand。因此 /echo 不可直接输入，但 /=execute <脚本> 执行脚本时每行都经由 root.execute()（CommandCalcFactory.java executeScript 方法），echo 在脚本内完全可用。

CommandCalc 构造函数 this.name = "=" + name（src/main/java/openmods/calc/command/CommandCalc.java:27）强制给所有顶层指令加 = 前缀。=eval 注册时额外传入别名 "="（OpenClientProxy.java:102），得到 /=eval + 别名 /=。

/=config — 计算器实例管理

config 是唯一的嵌套 MapCommandComponent（CommandCalcFactory.java:40-161），含 8 个终端子命令：

两个栈指令回报的栈大小分别使用 openmodslib.command.calc_after_push / calc_after_pop 语言键。

已核实缺陷：/=config push 与 /=config pop 的指令名与实际行为互换。

指令 pop（CommandCalcFactory.java:88）调用的是 state.pushCalculator()（:90）并回报 calc_after_push；指令 push（:95）调用的是 state.popCalculator()（:97）并回报 calc_after_pop。

CalcState 侧的实现本身正确且符合直觉（src/main/java/openmods/calc/command/CalcState.java）：

public int pushCalculator() {                     // :294
    calculatorStack.push(active);                 // :295  确实压栈
    return calculatorStack.size();
}

public int popCalculator() {                      // :299
    setActiveCalculator(calculatorStack.pop());    // :300  确实出栈
    return calculatorStack.size();
}

即方法名与行为正确，指令名与所调用的方法相反。玩家输入 /=config pop 实际执行压栈，输出提示 “Pushed calculator, stack size: N”；StackUnderflowException 也只会在 /=config push（真正出栈）时抛出。需按行为而非名称理解。

/=eval — 表达式求值

用法 /=eval <表达式>。行为由当前模式（ExprType.hasSingleResult）决定：

• 单值模式（PREFIX/INFIX）：state.compileExecuteAndPrint(sender, expr)，直接以文本形式回报结果
• 栈模式（POSTFIX）：state.compileAndExecute(sender, expr)，不返回值，改为回报栈大小（openmodslib.command.calc_stack_size）

表达式解析失败时抛 openmodslib.command.calc_syntax_error_path，运行失败时抛 openmodslib.command.calc_runtime_error_path。

/=let 与 /=fun — 定义符号

/=fun 的参数个数必须能解析为整数，否则抛 openmodslib.command.calc_invalid_number。

/=execute — 脚本执行

用法 /=execute <路径>，路径相对于 <游戏目录>/scripts。执行流程：

1. 目录逃逸防护：checkIsParent(scriptDir, scriptFile) 逐级上溯 getParentFile() 比对规范路径，若目标不在 scripts 目录内则抛 openmodslib.command.calc_not_child（CommandCalcFactory checkIsParent 方法）。这是明确的路径穿越防护。
2. 文件存在性检查：非文件抛 openmodslib.command.calc_not_file
3. 逐行执行：executeScript 用 BufferedReader 逐行读取，每行经 WhitespaceSplitters.fromString 拆词后交给 root.execute(sender, args)，行尾 # 起始的注释行为空串，不产生副作用
4. 回报：输出 openmodslib.command.calc_executed_count（已执行行数）

Tab 补全会扫描 scripts 下的文件与目录，目录补全时追加 /（CommandCalcFactory execute 分支的 getTabCompletions）。

计算器栈

CalcState（src/main/java/openmods/calc/command/CalcState.java:41）维护：

• 活动计算器 active（:265，初始为 CalculatorType.DOUBLE）
• 计算器栈 —— pushCalculator（:294）/ popCalculator（:299）/ restorePreviousCalculator（:284）
• 命名表 —— nameCalculator（:304）/ loadCalculator（:312）/ getCalculatorsNames（:308）
• 表达式模式 exprType（:269，默认 INFIX）

popCalculator 在栈空时抛 StackUnderflowException，由指令层转为 openmodslib.command.calc_stack_underflow。

游戏内上下文符号

所有后端都由 SenderHolder.addPrinter 注入 p（打印栈值，零返回）与 print（取值，:78,101）。数值类后端额外注入发送者方块坐标：

坐标读取经 SenderHolder.getX/getY/getZ（CalcState.java:61,66,71），对非玩家发送者会因 Preconditions.checkNotNull 抛异常。

数值

交互

CalcKey 注册的 KeyBinding 名称为 openmodslib.key.calc（显示名 “Open Calculator”），分类 openmodslib.key.category（显示名 “OpenMods”），默认键位为 Keyboard.KEY_EQUALS，可在选项视频设置中改绑。

错误处理

CommandCalc.processCommand（src/main/java/openmods/calc/command/CommandCalc.java:70）分三层处理：

1. NestedCommandException —— 推入命令名后转红色聊天消息
2. 其它 Exception —— 沿 getCause() 链收集全部消息，用 ', caused by ' 连接后抛 CommandException("openmodslib.command.calc_error", ...)
3. 参数未消费完 —— 抛 openmodslib.command.calc_extra_args 并回报剩余部分

相关条目

• 计算器引擎 — 表达式编译与执行流水线
• 类型后端 — 5 种数值实现的符号与算符差异
• 多类型值系统 — MULTI 后端的类型域
• 指令总览 — OpenModsLib 全部 9 条指令