脚本进阶
INI 读写
帮助你了解 Blue 引擎脚本中的 INI 读写、维护和排序读取，包括常用命令、排序标识和文件重载。
说明
这一页整理脚本里直接操作 INI 文件的常用命令。
如果你的需求是读取配置项、写回状态值、维护节和键，或者把某个节按键值排序后再循环读取，可以从这里开始。
INI 适合处理什么
INI 更适合处理下面这类数据：
- 节、键、值结构清晰的配置文件
- 需要直接落盘保存的简单文本或数值配置
- 需要按节批量读取并排序的列表数据
- 需要被脚本和外部文件共同维护的数据
如果当前数据本身已经是多层对象或数组，通常更适合优先看 JSON。
INI 命令一览
如果你只是来速查命令，直接看下面各组总览表；如果你还不确定具体参数怎么写，再继续往下看重点命令说明。
读取 INI
这组命令适合直接从现有 INI 文件里拿配置值。是否选字符串版还是整数版，核心只看结果应该写进哪类变量。
| 命令 | 最小格式 | 一句话用途 |
|---|---|---|
INI_READ_STRING | <文件路径> <节名> <键名> <变量> | 读取一个字符串值 |
INI_READ_INTEGER | <文件路径> <节名> <键名> <变量> | 读取一个整数值 |
INI_SECTION_COUNT | <文件路径> <节名> <变量> | 获取指定节中的键数量 |
什么时候用字符串读取，什么时候用整数读取
| 情况 | 优先命令 | 原因 |
|---|---|---|
| 结果是名称、路径、标记、说明文本 | INI_READ_STRING | 这类结果应进入 S 或 A 变量 |
| 结果是数量、等级、开关、计数 | INI_READ_INTEGER | 这类结果应进入 P/G/D/M/H 变量 |
读取字符串值
什么时候用
当某个键保存的是文本内容，而且后续要继续用于消息显示、拼接字符串或条件判断时，用 INI_READ_STRING 更合适。
调用格式
INI_READ_STRING <文件路径> <节名> <键名> <变量>
参数要点
| 参数 | 必填 | 说明 |
|---|---|---|
| 文件路径 | 是 | 目标 INI 文件路径 |
| 节名 | 是 | 要读取的节 |
| 键名 | 是 | 要读取的键 |
| 变量 | 是 | 用于接收结果的字符串变量，应使用 S 或 A 变量 |
示例
INI_READ_STRING .\Activity.ini Reward RewardName S10
注意事项
- 目标值是文本时，优先用
INI_READ_STRING，不要把它读进整数变量。 - 如果文件内容刚被外部程序改过，而脚本里还是旧值，先检查是否需要执行
INI_RELOAD。
写入与维护
这组命令负责写值、改值、删键、删节、重命名和文件保存。这里最容易混淆的不是命令名，而是“改的是键、节，还是整个文件当前缓存”。
| 命令 | 最小格式 | 一句话用途 |
|---|---|---|
INI_WRITE_STRING | <文件路径> <节名> <键名> <变量或字符串> | 写入一个字符串值 |
INI_WRITE_INTEGER | <文件路径> <节名> <键名> <整数值> | 写入一个整数值 |
INI_WRITE_INTEGER_EX | <文件路径> <节名> <键名> <运算符> <整数值> | 按 +、-、= 更新整数值 |
INI_DELETE_KEY | <文件路径> <节名> <键名> | 删除指定键 |
INI_CLEAR_SECTION | <文件路径> <节名> | 清空节里的键值内容 |
INI_ERASE_SECTION | <文件路径> <节名> | 删除整个节 |
INI_RENAME_SECTION | <文件路径> <节名> <新节名> | 重命名节 |
INI_SAVE | <文件路径> | 把当前改动保存到文件 |
INI_RELOAD | <文件路径> | 重新加载文件内容 |
写入与重载的关系
INI_WRITE_STRING、INI_WRITE_INTEGER、INI_WRITE_INTEGER_EX负责改当前文件内容。INI_SAVE用于把当前改动保存到文件。INI_RELOAD用于把文件重新加载进来，适合外部程序或手动编辑后同步脚本里的内容。
INI_WRITE_INTEGER_EX 的运算符
| 运算符 | 作用 |
|---|---|
+ | 在原值基础上增加 |
- | 在原值基础上减少 |
= | 直接改成指定值 |
按操作符更新整数值
什么时候用
当键值本来就是整数，而且你要表达“增加多少”“扣掉多少”或“重新赋值”时，用 INI_WRITE_INTEGER_EX 比先读再写更直接。
调用格式
INI_WRITE_INTEGER_EX <文件路径> <节名> <键名> <运算符> <整数值>
参数要点
| 参数 | 必填 | 说明 |
|---|---|---|
| 文件路径 | 是 | 目标 INI 文件路径 |
| 节名 | 是 | 要修改的节 |
| 键名 | 是 | 要修改的键 |
| 运算符 | 是 | + 增加，- 减少，= 赋值 |
| 整数值 | 是 | 本次更新使用的整数值 |
示例
INI_WRITE_INTEGER_EX .\PlayerState.ini UserData KillCount + 1
INI_WRITE_INTEGER_EX .\PlayerState.ini UserData KillCount = 0
注意事项
- 这个命令适合整数键值，不适合字符串键值。
- 如果你要表达的是“覆盖写入一个固定整数”，
INI_WRITE_INTEGER会更直观。 - 如果脚本流程依赖最终落盘结果，记得确认是否需要显式执行
INI_SAVE。
排序读取
这组命令不是直接读单个键值，而是先把一个节按指定规则排序到内存标识里，再从这个标识中逐项读取结果。
| 命令 | 最小格式 | 一句话用途 |
|---|---|---|
INI_SORT_READ_SECTION_VALUES | <文件路径> <节名> <排序字段> <排序类型> <排序方式> <标识名> <是否保存到文件> | 读取某个节并排序到内存标识 |
INI_SORT_SECTION_VALUES_COUNT | <标识名> <变量> | 获取排序结果数量 |
INI_SORT_GET_SECTION_STRING | <标识名> <变量> | 读取排序结果对应的节名 |
INI_SORT_GET_VALUE_STRING | <标识名> <索引> <变量> | 读取指定排序项的字符串值 |
INI_SORT_GET_IDENT_STRING | <标识名> <索引> <变量> | 读取指定排序项的键名 |
INI_SORT_GET_IDENT_VALUE_STRING | <标识名> <索引> <变量> | 读取指定排序项的键值组合文本 |
INI_SORT_GET_VALUE_INTEGER | <标识名> <索引> <变量> | 读取指定排序项的整数值 |
INI_SORT_DELETE | <标识名|ALL> | 删除排序结果对应的内存标识 |
排序参数怎么选
| 参数 | 可选值 | 说明 |
|---|---|---|
排序字段 | 0 / 1 | 0 按键排序，1 按值排序 |
排序类型 | 0 / 1 | 0 按字符串排序，1 按整数排序 |
排序方式 | 0 / 1 | 0 升序，1 降序 |
是否保存到文件 | 0 / 1 | 0 不保存文件，1 保存文件 |
排序读取调用顺序
- 先用
INI_SORT_READ_SECTION_VALUES生成排序结果标识。 - 再用
INI_SORT_SECTION_VALUES_COUNT拿数量。 - 按需要读取节名、键名、值或键值组合。
- 用完后执行
INI_SORT_DELETE清理对应标识。
生成排序结果标识
什么时候用
当你不是只想拿单个键值，而是要把整个节里的内容按键或值排序后，再逐项循环读取时，先从 INI_SORT_READ_SECTION_VALUES 开始。
调用格式
INI_SORT_READ_SECTION_VALUES <文件路径> <节名> <排序字段> <排序类型> <排序方式> <标识名> <是否保存到文件>
参数要点
| 参数 | 必填 | 说明 |
|---|---|---|
| 文件路径 | 是 | 目标 INI 文件路径 |
| 节名 | 是 | 要排序读取的节 |
| 排序字段 | 是 | 0 按键，1 按值 |
| 排序类型 | 是 | 0 字符串，1 整数 |
| 排序方式 | 是 | 0 升序，1 降序 |
| 标识名 | 是 | 用于后续读取排序结果的内存标识 |
| 是否保存到文件 | 是 | 0 不保存，1 保存 |
示例
INI_SORT_READ_SECTION_VALUES .\Rank.ini Warrior 1 1 1 排行结果 0
INI_SORT_SECTION_VALUES_COUNT 排行结果 M10
注意事项
- 这一步只是生成排序结果标识，后面还要继续用各类
GET命令读取。 - 如果排序类型和实际值类型不匹配，排序结果很容易和预期不一致。
- 排序结果属于内存标识，用完后应及时清理。
读取排序项的值
什么时候用
当你已经拿到排序标识，并且要按索引读取某一项对应的值时，可以按值类型选择 INI_SORT_GET_VALUE_STRING 或 INI_SORT_GET_VALUE_INTEGER。
调用格式
INI_SORT_GET_VALUE_STRING <标识名> <索引> <变量>
参数要点
| 参数 | 必填 | 说明 |
|---|---|---|
| 标识名 | 是 | 前一步生成的排序结果标识 |
| 索引 | 是 | 要读取的排序项索引 |
| 变量 | 是 | 用于接收字符串值的变量，应使用 S 或 A 变量 |
示例
INI_SORT_GET_VALUE_STRING 排行结果 0 S10
INI_SORT_GET_IDENT_STRING 排行结果 0 S11
注意事项
- 字符串值读进
S/A变量，整数值读进P/G/D/M/H变量。 - 如果你还需要键名或键值组合，可以改用
INI_SORT_GET_IDENT_STRING或INI_SORT_GET_IDENT_VALUE_STRING。
清理排序结果标识
什么时候用
当排序读取已经完成，不再需要继续访问该结果时，立即执行 INI_SORT_DELETE 收尾。
调用格式
INI_SORT_DELETE <标识名|ALL>
参数要点
| 参数 | 必填 | 说明 |
|---|---|---|
| 标识名或 ALL | 是 | 删除单个排序标识，或删除全部排序标识 |
示例
INI_SORT_DELETE 排行结果
INI_SORT_DELETE ALL
注意事项
- 排序结果是内存中的临时标识，不建议长期放着不清理。
- 如果你后面还要继续读取同一批排序结果，不要过早删除对应标识。
相关主题
如果当前需求已经不只是节、键、值这类平面结构，而是开始需要多层对象、数组或路径读取，通常更适合改看 JSON 专题。