3K传奇引擎变量参数完整合集 私人全局字符数字变量命令与脚本引用变量大全

3K引擎的变量体系按存储周期和作用域分为三大类，私人变量仅当前角色有效且下线或小退后重置，全局变量全服玩家共享且部分可保存到服务器重启后依然存在，字符型变量用于存储文本内容。所有变量都不要用P、G、M、I、D、N、S、A开头来命名自定义变量，否则会与引擎内置变量冲突。下面按变量类型、操作命令、脚本引用变量、常见错误四个方面拆解。

## 数字型私人变量

P0到P9是私人数字变量，关闭NPC对话框后自动重置为0，适合用作对话过程中的临时计数或选择标记，不能保存任何需要持久化的数据。M0到M99同样是私人数字变量，下线不保存、小退归0，作用域比P变量更广但依然不持久化，适合脚本执行过程中的中间计算、临时循环计数等场景。D0到D9是私人数字变量，不可保存，常用于装备升级、强化次数记录等短周期数据。N0到N99是私人数字变量，不可保存，@@InPutInteger输入框接收的数字会自动存入对应的N变量中，后缀0到99代表变量槽位编号。

P、M、D、N这四组私人数字变量的共同特性是下线后数据消失，区别在于P变量在关闭对话框时就会重置，M变量和N变量在角色小退时归零，D变量的重置时机与M、N基本一致。选择哪组变量取决于数据的生命周期需求，对话内的临时数据用P变量最安全，跨对话但单次登录内的数据用M或N变量，装备升级相关的短期记录用D变量。

## 全局数字变量

G0到G99是全局数字变量，可保存，服务器重启后数值依然保留，适合记录全服活动进度、限时领取名额剩余数量、行会战积分等需要跨重启持久化的数据。G变量存放在GlobalVals.XML文件中，不属于任何单个角色，所有玩家的运算操作都会直接影响同一个数值，一个玩家减少G11的值，其他玩家看到的G11也会同步变化。

G变量的典型用法是控制限量活动的名额。脚本中写 `small G11 10` 检测G11的值是否小于10，小于则允许领取，领取后执行 `INC G11 1` 将名额消耗加1。这个逻辑保证全服总共只有10个领取名额，无论哪个玩家先到先得，名额耗尽后所有玩家都检测不通过。

I0到I99是全局数字变量，不可保存，服务器重启后自动重置为0。与G变量的区别仅在于持久化能力，I变量适合记录本次服务器运行周期内的全服状态，比如当前在线人数缓存、本轮活动已开启的标记等，重启后归零符合预期。

## 字符型变量

S0到S99是私人字符变量，下线不保存、小退归0，用于存储文本内容。@@InPutString输入框接收的文本会自动存入对应的S变量中，玩家在NPC对话框中输入的任意文字都会按后缀编号存入S槽位。

A0到A99是全局字符变量，可保存，服务器重启后依然存在，适合记录全服公告文本、跨角色的文本配置等数据。字符变量在脚本中引用时需要加 `<$STR(...)>` 格式化，例如 `<$STR(S0)>` 或 `<$STR(A0)>`，直接把变量名写在对话文本中不会解析出实际值。

## 变量操作命令

MOV命令用于变量赋值和变量之间的值传递。最常见用法是 `MOV D1 1` 把数值1赋给D1变量。变量之间传值写 `MOV S0 S1` 把S1的值传给S0，字符变量和数字变量之间不能直接互传，需要经过格式化处理。自定义变量与系统变量之间的传值使用 `MOV HUMAN 变量名 S0` 的格式，HUMAN关键字指定操作对象为当前人物的自定义变量。

INC命令使变量值自增。`INC D0 1` 等价于 `D0 = D0 + 1`，是计数器场景中最常用的写法。INC也支持两个变量之间的操作，`INC HUMAN TEST D0` 表示自定义数字变量TEST的值增加D0的数值。DEC命令与INC相反，`DEC D0 1` 等价于 `D0 = D0 - 1`，用于递减计数。

MOVR命令生成随机数并存入变量。格式为 `MOVR N2 10000000`，在0到9999999之间生成随机整数存入N2。生成范围由第二个参数决定，数值越大随机空间越大，验证码类场景建议范围不低于10000000，避免玩家猜测。

SET命令用于设置标识位的状态。`SET [700] 1` 把标识700设为1，`SET [700] 0` 把标识700重置为0。标识位只有0和1两种状态，保存在hum.db中，下线后不会丢失，是任务接取状态、会员权限标记等二值场景的首选存储方式。

DIV命令在3K引擎中的格式与Legend引擎不同。3K引擎写 `DIV M10 <$STR(M10)> 5` 表示 `M10 = M10 / 5`，必须用 `<$STR()>` 包裹变量名；Legend引擎的格式是 `DIV M10 5`，不需要包裹。这是引擎之间最容易写错的差异之一。

## 脚本引用变量

3K引擎内置了大量以 `<$...>` 格式直接引用的系统变量，不需要声明即可在脚本中使用。人物基础信息类包括 `<$USERNAME>` 人物名称、`<$LEVEL>` 等级、`<$HP>` 当前生命值、`<$MAXHP>` 生命值上限、`<$MP>` 当前魔法值、`<$MAXMP>` 魔法值上限、`<$EXP>` 当前经验值、`<$MAXEXP>` 升级所需经验值。

属性类变量包括 `<$AC>` 防御力、`<$MAXAC>` 最高防御力、`<$MAC>` 魔法防御力、`<$DC>` 物理攻击力、`<$MC>` 魔法力、`<$SC>` 道术，每项都有对应的MAX前缀版本返回最大值。装备栏引用变量包括 `<$DRESS>` 衣服、`<$WEAPON>` 武器、`<$HELMET>` 头盔、`<$NECKLACE>` 项链、`<$RING_R>` 右戒指、`<$ARMRING_R>` 右手镯、`<$BELT>` 腰带、`<$BOOTS>` 鞋子、`<$CHARM>` 宝石。

位置与状态类变量包括 `<$X>` 人物X坐标、`<$Y>` 人物Y坐标、`<$MAPNAME>` 所在地图名称、`<$SIT>` 是否坐下（1为坐下0为站立）。货币与点数类包括 `<$GOLDCOUNT>` 金币数量、`<$GAMEGOLD>` 游戏币数、`<$GAMEPOINT>` 游戏点数、`<$PKPOINT>` PK点数、`<$CREDITPOINT>` 声望点数。

地图与标记类变量用于记录路标数据，`<$TAGMAPNAME1>` 返回记路标识1的地图名，`<$TAGX1>` 和 `<$TAGY1>` 返回对应坐标。行会相关变量包括 `<$GUILDNAME>` 行会名称、`<$RANKNAME>` 行会职位名称。英雄相关变量包括 `<$HERONAME>` 英雄名称。

## 全局变量与个人变量的声明方式

在脚本中引用自定义变量时，全局变量用 `<$GLOBAL(变量名)>` 格式，个人变量用 `<$HUMAN(变量名)>` 格式。个人变量可以在登录脚本中直接声明和初始化，全局变量的声明需要在服务端的全局脚本中单独设置，不能通过玩家登录脚本动态创建。

查看自定义全局变量可以通过M2控制台执行 `@ViewGVar` 命令，或者在脚本中使用 `<$GLOBAL(变量名)>` 打印当前值。

## 变量类型速查

P0-P9私人数字，关对话框归零。M0-M99私人数字，小退归零。D0-D9私人数字，小退归零。N0-N99私人数字，小退归零。S0-S99私人字符，小退归零。G0-G99全局数字，可保存。I0-I99全局数字，重启归零。A0-A99全局字符，可保存。

## 常见错误与排查

变量名以P、G、M、I、D、N、S、A开头是最常见的冲突来源。自定义变量命名时避开这些字母，比如用TEST、Name、Count等不以这些字母开头的名称。

DIV命令的写法在3K引擎和Legend引擎之间不兼容。从其他引擎移植脚本到3K引擎时，所有DIV语句都要加上 `<$STR()>` 包裹，否则计算结果错误或脚本直接报错。

字符变量在对话文本中直接写变量名不会被解析。`<$STR(S0)>` 才能输出S0的实际内容，单独写S0只会显示字母S和数字0。数字变量同样需要格式化，`<$STR(N2)>` 才能正确显示数字值。

@@InPutInteger和@@InPutString的编号必须与脚本中处理的变量编号一致。@@InPutInteger1接收的输入存入N1，@@InPutInteger10存入N10，如果脚本中检查的是N2但输入框用的是@@InPutInteger1，比对永远失败。

变量操作命令执行后没有生效，检查命令结尾是否遗漏了英文分号。3K引擎的ACT段落中每一行执行命令都必须以分号结尾，MOV、INC、DEC、SET、MOVR这些命令全部不例外。

所有脚本文件保存为ANSI编码，UTF-8编码下中文字符串乱码，虽然英文命令本身不受影响，但脚本中的文本提示和变量名称如果包含中文会出现解析错误。修改脚本后重启M2Server，或在控制台执行 `@ReloadManage` 重新加载脚本文件。