跳转至

Ballance 脚本 Mod 编写指南

五分钟快速开始

不确定从哪里开始时，先完成这一段；不需要先理解句柄、Timer、IMC 或 Virtools 对象。准备配套版本的 BMLPlus-<version>.zip 运行时和 BMLPlus-SDK-<version>-Release.zip SDK。如果尚未安装运行时，先阅读 使用 BML+。

  1. 在 <Ballance>/ModLoader/Mods 中打开 PowerShell，让 SDK 生成并填写模板：
& "<BML-SDK>/scripts/New-BMLScriptMod.ps1" `
  -Id "yourname.my-mod" -Name "My Mod" -Author "Your Name"

也可以继续手动复制 templates/script-mod-template。 2. 确认 <Ballance>/BuildingBlocks/AngelScript.dll 存在。 3. 不再修改生成的源码，直接启动 Bin/Player.exe，确认游戏内出现问候语，并在 ModLoader/ModLoader.log 中找到 My Mod loaded。 4. 保持生成的 id 稳定；以后修改 id 会成为另一个 Mod，并且需要重启一次。 5. 保持 Player 运行，修改问候语并保存。已加载的目录 Mod 会自动热重载。

新增 Mod、修改 id 或修改依赖时需要重启 Player；普通源码修改不需要。加载失败时 依次使用：

script status
script diag yourname.my-mod
script logs error

把诊断命令中的 yourname.my-mod 换成你的实际 id。

完成这条最短路径后，再按下面的课程系统学习。课程会从环境和语言基础重新讲起， 不要求预先理解模板中的全部内容。

SDK 的 examples/script-mod 还提供三个完整的后续示例，分别演示命令与配置、 输入与界面、游戏状态访问。一次只复制一个示例到 ModLoader/Mods；实际项目仍 从模板开始，不要把示例当作通用骨架。

系统教程

从第 01 节开始。每节结束时都能看到明确结果；第 01～07 节是基础开发，第 08 节以后逐步进入 Ballance 数据、行为图和物理系统。

# 标题 你会得到
01 环境搭建 VS Code 能补全 AngelScript
02 第一个 Mod 日志里出现 "Hello"
03 输出与输入 游戏内提示 + 按键响应
04 ImGui 窗口 浮动调试窗口
05 命令系统 /hello 可执行
06 回调模型 理解 BML 何时调用脚本
07 配置与 Timer 配置文件 + 定时器
08 查找对象 日志打印对象名列表
09 坐标显示器 第一个实用 mod
10 Ballance 运行结构 能说出 Level01 里有什么
11 读 DataArray ImGui 显示 CurrentLevel 表
12 状态面板 第二个实用 mod
13 Levelinit 占位符 能解释 PC_Checkpoints 如何进入运行时
14 Gameplay 状态机 ImGui 显示 IngameParameter 表
15 行为图阅读法 能读懂 activate next Checkpoint 流程
16 物理观察 日志显示物理对象状态
17 生成物理对象 游戏里凭空出现一个球
18 控制物理对象 按键推动自己创建的球
19 修改前检查清单 能判断操作的风险等级
20 完整 Mod 完整 mod 骨架
21 发布 zip 打包可分发
22 排错 按症状快速定位问题

参考

教程中遇到不认识的 API 或概念时来这里查。