传奇引擎字符型变量键值对全套操作脚本教程

admin6小时前2

在传奇版本制作、NPC脚本编写、榜单统计、CSV数据联动等开发场景中，字符型变量键值对是核心的数据存储与交互方式。相较于普通变量，键值对结构支持一键多值、批量存储、条件排序，能够高效实现玩家数据存档、捐献榜单、外部数据导入等常用功能。本文整合传奇引擎全部字符型变量键值对操作命令，详解语法参数、实战案…

在传奇版本制作、NPC脚本编写、榜单统计、CSV数据联动等开发场景中，字符型变量键值对是核心的数据存储与交互方式。相较于普通变量，键值对结构支持一键多值、批量存储、条件排序，能够高效实现玩家数据存档、捐献榜单、外部数据导入等常用功能。本文整合传奇引擎全部字符型变量键值对操作命令，详解语法参数、实战案例，帮助版本开发者快速落地脚本功能。

一、字符型变量基础说明

传奇引擎中字符型变量是键值对操作的载体，分为系统内置变量与自定义变量两大类，所有键值对命令均基于该类变量执行，核心规范如下：

1. 内置字符型变量：包含A变量、T变量、S变量，为引擎原生支持，无需额外声明即可直接使用；

2. 自定义字符型变量：固定格式为HUMAN(XXX)，支持搭配GLOBAL、GUILD属性，分别代表玩家个人全局变量、行会全局变量；

3. 书写规范：变量调用禁止添加<$>修饰符，自定义变量必须携带HUMAN/GLOBAL/GUILD标识，涉及全局存储的自定义变量需配置数据保存规则，否则重启后数据丢失。

二、键值对写入操作：ADDSTRVALUE命令

2.1 命令语法格式

ADDSTRVALUE 参数1 参数2 参数3

2.2 参数详细解析

参数1：目标字符型变量，支持A/T/S内置变量、HUMAN(XXX)自定义变量（带GLOBAL/GUILD标识）；

参数2：自定义主键值，为键值对的唯一标识，支持数字、字母、组合字符；

参数3：主键对应的存储值，可存储文本、数字、域名等任意字符内容。

2.3 实战脚本案例

基础赋值（初始定义键值对数据）

[@main]

#IF

#ACT

MOV T10 1=999,2=888,3=777

新增键值对（向已有变量追加新主键数据）

[@main]

#IF

#ACT

ADDSTRVALUE T10 4 996M2

修改已有主键值（覆盖更新指定主键的对应数据）

[@main]

#IF

#ACT

ADDSTRVALUE T10 1 996M2.COM

三、键值对读取操作：GETSTRVALUE命令

3.1 命令语法格式

GETSTRVALUE 参数1 参数2 参数3

3.2 参数详细解析

参数1：源字符型变量，规则同ADDSTRVALUE命令，自定义变量需标注存储属性；

参数2：需要读取的目标主键值；

参数3：用于存放读取结果的字符型变量。

重要提示：使用HUMAN、GLOBAL、GUILD自定义变量读取时，必须提前开启变量持久化保存，否则无法读取历史数据。

3.3 实战脚本案例

[@获取主键值对应值]

#IF

#ACT

GETSTRVALUE T10 1 S10

SENDMSG 6 获取出来的为：<$STR(S10)>

四、键值对删除操作：DELSTRVALUE命令

4.1 命令语法格式

DELSTRVALUE 参数1 参数2

4.2 参数详细解析

参数1：待操作的字符型变量（内置/自定义均可）；

参数2：需要删除的目标主键值，删除后该主键及对应值将从变量中清除。

4.3 实战脚本案例

[@删除主键值]

#IF

#ACT

DELSTRVALUE T10 1

五、全量主键获取：GETSTRKEY命令

5.1 命令功能与语法

功能：提取指定键值对变量中的全部主键，以英文逗号分割形式输出

语法：GETSTRKEY 参数1 参数2

参数1：键值对源变量名称；参数2：存储全部主键的目标变量

5.2 实战脚本案例（搭配字符分割使用）

#if

#ACT

mov T11=2,2=1,996=2,引擎=3

GETSTRKEY T1 S1

;取出主键值为逗号分割(1,2,996,引擎)

sendmsg 7 <$str(S1)>

;搭配分割指令遍历所有主键

MOV N11 0

GETVALIDSTRSUPER <$str(S1)> , S$获取主键值 N$总主键数量

while N11 < <$str(N$总主键数量)>

INC N11 1

sendmsg 7 <$str(S$获取主键值<$str(N11)>)>

endwhile

六、常量式读取键值对数据

传奇引擎支持直接通过常量指令在弹窗、提示信息中读取键值对数据，无需单独赋值中转，简化脚本代码结构，适合简易数据展示场景。

6.1 实战脚本案例

[@main]

#IF

#ACT

mov T1 1=996M2,2=996M2.COM

sendmsg 7 <$GETSTRVALUE(T1,1)>，<$GETSTRVALUE(T1,2)>.

七、键值对主键修改：SETSTRVALUEKEY命令

7.1 命令功能与语法

功能：替换键值对中已存在的主键名称，保留原主键对应的存储数值

语法：SETSTRVALUEKEY 变量名称原主键新主键

7.2 实战脚本案例

[@main]

#if

#ACT

mov T11=2,2=1,996=2,引擎=3

#if

#ACT

;修改主键“引擎”为“M2”

SETSTRVALUEKEY T1 引擎 M2

SENDMSG 6 <$STR(T1)>

;打印输出值：1=2,2=1,996=2,M2=3

八、CSV外部数据导入：NEWREADCSVSAVEVAR命令

8.1 命令功能与语法

功能：读取本地CSV文件指定行列数据，自动以键值对形式写入字符型变量，实现外部数据与传奇脚本联动

语法：NEWREADCSVSAVEVAR 参数1 参数2 参数3 参数4 参数5

8.2 参数详细解析

参数1：CSV文件本地路径，支持相对路径（QuestDiary目录为常用路径）；

参数2：数据读取起始行，跳过表头可设置为10及以上行数；

参数3：作为主键的CSV列序号；参数4：作为存储值的CSV列序号；

参数5：存储数据的目标字符型变量（仅支持A/T/S类字符变量）。

8.3 核心注意事项

1. CSV中主键、值同时为空的行，判定为数据末尾，引擎终止读取；

2. 主键为空、值不为空时，忽略该行数据；主键不为空、值为空时，正常写入空值键值对。

8.4 实战脚本案例

[@main]

#IF

#ACT

MOV T10

NEWREADCSVSAVEVAR ..\QuestDiary\test.csv 10 1 2 T10

sendmsg 6 <$STR(T10)>

sendmsg 7 <$GETSTRVALUE(T10,10)>，<$GETSTRVALUE(T10,11)>.

九、键值对智能排序：SORTVARSTR命令

9.1 命令功能与语法

功能：对带时间戳的键值对数据进行升降序排序，常用于玩家捐献、战力榜单、积分排名等场景

语法：SORTVARSTR 参数1 参数2 参数3 参数4

9.2 参数详细解析

参数1：待排序的键值对变量名称；

参数2：排序数量，范围1-100，仅对指定条数数据排序；

参数3：排序方式，0=升序排列，1=降序排列；

参数4：时间戳优先级，0=小于时间戳优先（先上榜者靠前），1=大于时间戳优先（后上榜者靠前）。

9.3 专属常量说明

排序主键读取：<$GETSTRKEY(变量名,第几个)>，用于获取排名对应玩家/主键名称；

排序值读取：<$GETSORTSTRVALUE(变量名,第几个)>，用于获取排名对应数值；

标准数据格式：玩家名字=捐献数量#时间戳，为榜单排序专用格式。

9.4 实战脚本案例（捐献排名系统）

[@main]

#if

#ACT

;赋值本次捐献的数量

MOV N$捐献数量 10000

;在原始数据中取出该玩家历史捐献数量

MOV N$捐献数量取出 <$GETSTRVALUE(A10,<$username>)>

;累加本次捐献数量

INC N$捐献数量取出 <$str(N$捐献数量)>

;更新原始数据变量

ADDSTRVALUE A10 <$username> <$str(N$捐献数量取出)>

;写入带时间戳的排序专用变量

ADDSTRVALUE A11 <$username> <$str(N$捐献数量取出)>#<$UTCNOW>

;降序排序前6名，同数值下后捐献者靠前

SORTVARSTR A11 6 1 1

;前端展示排名数据

sendmsg 6 <$Str(A11)>

sendmsg 6 排名第一名玩家名字：<$GETSTRKEY(A11,1)>。捐献数量：<$GETSORTSTRVALUE(A11,1)>

sendmsg 6 排名第二名玩家名字：<$GETSTRKEY(A11,2)>。捐献数量：<$GETSORTSTRVALUE(A11,2)>

sendmsg 6 排名第三名玩家名字：<$GETSTRKEY(A11,3)>。捐献数量：<$GETSORTSTRVALUE(A11,3)>

sendmsg 6 排名第四名玩家名字：<$GETSTRKEY(A11,4)>。捐献数量：<$GETSORTSTRVALUE(A11,4)>

sendmsg 6 排名第五名玩家名字：<$GETSTRKEY(A11,5)>。捐献数量：<$GETSORTSTRVALUE(A11,5)>

sendmsg 6 排名第六名玩家名字：<$GETSTRKEY(A11,6)>。捐献数量：<$GETSORTSTRVALUE(A11,6)>

9.5 开发核心避坑要点

1. 数据分层存储：用A10存储原始永久数据，A11单独用于排序，避免全量变量排序造成服务器卡顿；

2. 数量限制：排序指令最大仅支持100组键值对，超出数量会触发引擎性能预警；

3. 时间戳作用：同数值数据依靠时间戳区分排名，是榜单公平性的核心配置项。

十、总结

本文全覆盖讲解了传奇引擎字符型变量键值对的写入、读取、删除、主键管理、CSV导入、数据排序六大核心功能，所有命令均适配主流传奇M2引擎。合理运用键值对脚本，可以高效实现玩家数据存档、行会统计、外部数据对接、排行榜系统等高频开发需求，分层的数据处理逻辑还能有效优化服务器运行性能，是传奇版本开发必备的核心脚本技能。