传奇脚本变量全分类速查表 - 引擎兼容故障排查脚本规范教程

脚本变量是传奇脚本读取人物属性、装备、货币等数据的统一入口，适配主流传奇引擎的本地学习调试场景。新手写脚本时最常见的问题就是变量名记不全、取值取不到，对照一张脚本变量速查表就能解决大半。

本文对照引擎官方脚本变量大全整理，把19类常用变量按分类列出，补充变量引用格式、拼写排查要点与常见问题速查，方便写版本、脚本调试时随查随用。

变量引用格式速查

脚本变量引用统一用尖括号包裹，以美元符号开头：<$变量名>。变量名不区分大小写，但拼写错误或多余空格会导致读取为空，变量排查时先核对拼写与空格，不要改大小写。

取值展示用 <$STR(变量)>，触发脚本锁定当前对象用 <$CSTR(<$变量>)>，数值运算必须先套 <$STR() 转换，否则判定失效。脚本变量调用前先确认数据归属哪一类，再按分类找变量名。

; 变量读取与显示示例
MOV S1 <$USERNAME>
MOV N1 <$LEVEL>
SENDMSG 0 玩家 <$STR(S1)> 当前等级 <$STR(N1)>

人物基础与状态变量速查

人物基础属性变量

读取人物核心基础属性，涵盖角色信息、状态、负重、外观等数据，是脚本最常用的基础变量组。

排查要点：

1. 变量读取为空多为拼写错误、多余空格，优先核对变量名；
2. 数值不刷新时，人物属性实时变动后需重新加载脚本，重启触发即可；
3. 性别与职业判定失效时，核对数值对应关系（0战/1法/2道、0男/1女）。

变量名	核心用途
<$USERNAME>	读取人物角色名称
<$LEVEL>	读取人物当前等级
<$LEVELNAME>	读取人物等级称号
<$HP>	读取人物当前血量
<$MAXHP>	读取人物血量上限
<$MANA>	读取人物当前蓝量
<$MAXMANA>	读取人物蓝量上限
<$EXP>	读取人物当前经验
<$MAXEXP>	读取人物升级所需经验
<$STAMINA>	读取人物体力值
<$DURABILITY>	读取人物装备耐久度
<$GENDER>	读取人物性别（0男/1女）
<$JOB>、<$CLASS>	读取人物职业（0战/1法/2道）
<$HAIR>	读取人物发型编号
<$COLOR>	读取人物发色或衣服颜色
<$LUCK>	读取人物幸运值
<$CURSE>	读取人物诅咒值
<$HUNGER>	读取人物当前饥饿值
<$MAXHUNGER>	读取人物饥饿值上限
<$WEIGHT>	读取人物当前负重
<$MAXWEIGHT>	读取人物负重上限
<$HANDWEIGHT>	读取人物当前腕力
<$MAXHANDWEIGHT>	读取人物腕力上限
<$WEARWEIGHT>	读取人物当前穿戴负重
<$MAXWEARWEIGHT>	读取人物穿戴负重上限

人物状态账号行会变量

涵盖人物实时状态、账号注册登录数据、行会职位权限三类变量，用于红名判定、死亡状态检测、账号数据统计、行会权限管控脚本。

排查要点：

1. 红名判定不准时，<$PKPOINT> 为实时PK数值，<$ISRED> 为快捷红名判定，二者搭配使用，单独用数值易出偏差；
2. 麻痹、中毒、死亡等瞬时状态变量仅在状态持续期间有数据，状态解除后自动清零，属正常机制；
3. 未注册账号的注册、登录、登出时间变量为空，新账号登录次数默认0；
4. 散人玩家无法读取行会职位、会长、官员相关变量，脚本需前置行会加入状态判定；
5. <$ISGUILDMASTER>、<$ISGUILDOFFICER> 为即时权限判定，行会换届后需刷新脚本。

变量名	核心用途
<$PKPOINT>	读取PK值（红名判定依据）
<$PKLEVEL>	读取PK等级
<$ISRED>	判定是否红名状态（1是/0否）
<$ISDEAD>	判定是否死亡状态（1是/0否）
<$ISFLY>	判定是否麻痹或石化状态
<$ISPOISON>	判定是否中毒状态
<$ISMOUNT>	判定是否骑马（1是/0否）
<$ISALLDEAD>	判定是否全队死亡
<$ACCOUNT>	读取登录账号名
<$REGTIME>	读取账号注册时间
<$LASTLOGINTIME>	读取最后登录时间
<$LASTLOGOUTTIME>	读取最后登出时间
<$LOGINCOUNT>	统计登录次数
<$GUILDRANK>	读取行会职位等级
<$ISGUILDMASTER>	判定是否行会会长（1是/0否）
<$ISGUILDOFFICER>	判定是否行会官员

攻防、货币与坐标变量速查

人物攻防属性变量

读取人物攻防、命中、攻速等战斗属性，严格区分属性上下限，包含多组别名变量，适配战力判定、伤害计算类脚本。

排查要点：

1. 上下限数值混淆时，DC/MAC/SC为下限、MAX系列为上限，别名变量功能一致，禁止混用；
2. 战斗属性读取异常时，穿戴装备后需在装备变动触发脚本中重新读取；
3. 部分引擎不支持魔法攻速变量，需核对引擎兼容范围。

变量名	核心用途
<$AC>	读取人物防御下限
<$MAXAC>	读取人物防御上限
<$MAC>	读取人物魔防下限
<$MAXMAC>	读取人物魔防上限
<$DC>	读取人物物理攻击下限
<$MAXDC>	读取人物物理攻击上限
<$DCMIN>	读取人物物理攻击下限（别名）
<$DCMAX>	读取人物物理攻击上限（别名）
<$MC>	读取人物魔法攻击下限
<$MAXMC>	读取人物魔法攻击上限
<$MCMIN>	读取人物魔法攻击下限（别名）
<$MCMAX>	读取人物魔法攻击上限（别名）
<$SC>	读取人物道术攻击下限
<$MAXSC>	读取人物道术攻击上限
<$SCMIN>	读取人物道术攻击下限（别名）
<$SCMAX>	读取人物道术攻击上限（别名）
<$HIT>	读取人物命中值
<$SPEED>	读取人物攻击速度
<$MAGICSPEED>	读取人物魔法施放速度

货币积分声望变量

涵盖游戏内全部流通货币、积分、声望、战功等资源变量，精准区分背包与仓库货币数据，是奖励发放、数值扣取、权限解锁脚本的基础变量。

排查要点：

1. 货币统计不准时，混淆 <$GOLDCOUNT>（背包金币）与 <$STOREMONEY>（仓库金币），统计总金币需叠加两组变量；
2. 积分声望为永久存储属性，修改后需执行保存指令，单纯重启本地服务端无法固化数据；
3. 轻量引擎不支持细分货币变量，需核对引擎兼容类型；
4. 荣誉威望数值异常时，部分版本需开启对应玩法功能后变量才生成数据；
5. 贡献度读取失效时，行会贡献变量仅加入行会的玩家有数据，散人玩家读取默认无返回值。

变量名	核心用途
<$GOLDCOUNT>	读取背包金币数量（不含仓库）
<$STOREMONEY>	读取仓库金币数量
<$GAMEGOLD>	读取元宝或付费货币数量
<$GAMEPOINT>	读取活动或会员积分数量
<$CREDIT>	读取声望或荣誉值
<$BONUSPOINT>	读取Bonus奖励积分数量
<$CONTRIBUTION>	读取贡献度数值
<$HONOR>	读取荣誉值
<$PRESTIGE>	读取威望值
<$FEAT>	读取战功或功勋值

坐标地图在线变量

涵盖人物实时坐标、地图信息、在线时长、安全区判定等场景变量，用于地图限制、区域触发、在线时长统计脚本。

排查要点：

1. 坐标判定失效时，人物移动、切图后坐标不会自动刷新，需绑定移动、换图触发事件重新读取；
2. 地图名称空值时，小众地图、未配置地图文本的地图 <$MAPTITLE> 返回空，精准判定优先用 <$MAP> 地图代码；
3. 在线时长混淆时，<$ONLINETIME> 为本次登录时长，<$TOTALONLINETIME> 为账号总在线时长；
4. 轻量引擎不支持 <$SAFEZONE> 安全区判定，需手动用地图坐标范围判定；
5. 楼层Z坐标无数据属正常现象，仅洞穴、多层副本等特殊地图会返回Z坐标。

变量名	核心用途
<$X>	读取人物当前X坐标
<$Y>	读取人物当前Y坐标
<$Z>	读取人物当前Z坐标或楼层
<$MAP>	读取地图代码
<$MAPNAME>	读取地图文件名
<$MAPTITLE>	读取中文地图名称
<$ONLINETIME>	读取在线时长（秒）
<$ONLINEDAY>	读取在线天数
<$ONLINEMINUTE>	读取在线分钟数
<$TOTALONLINETIME>	读取累计在线时长（秒）
<$SAFEZONE>	判定是否在安全区（1是/0否）

脚本实操：变量查表落地

变量速查表落地到实际脚本里，按四步走：

1. 定位分类：先确认要读的数据归属哪一类（人物、装备、货币、行会还是系统全局），缩小到对应分类表格；
2. 核对变量名：把表格里的变量名原样复制到脚本中，注意反引号与尖括号不参与拼写，检查是否有空格混入；
3. 取值展示：展示或判定时套 <$STR(变量)>，触发脚本锁定当前对象时套 <$CSTR(<$变量>)>；
4. 前置判定：无行会、无英雄、无召唤物、未穿戴装备的变量为空值，先做空值判定再取用，避免报错。

以本地版本脚本目录为例，脚本文件通常放在 D:\本地传奇版本\Mir200\Envir\Market_Def 文件夹，新增NPC脚本后重载脚本或重启本地服务端生效。

; 货币判断与发放示例
#IF
CHECKGOLD 5000
#ACT
MOV S1 <$GOLDCOUNT>
SENDMSG 0 玩家 <$STR(S1)> 拥有金币，满足进入条件

装备、社交与召唤变量速查

全套装备读取变量

全覆盖读取人物全身穿戴装备的名称、耐久、属性数据，区分左右手饰品，支持装备校验、装备回收、战力核算脚本。

排查要点：

1. 装备读取为空时，对应装备栏未穿戴物品，未做空值判定会导致脚本报错；
2. 左右手饰品混淆时，<$BRACELET>、<$RING> 为默认右手，左手需单独用L后缀变量；
3. 耐久读取异常时，未穿戴装备的耐久变量无数据，装备掉落或脱下后立即清空；
4. 低版本引擎不支持NAME后缀别名变量，建议优先使用基础变量。

变量名	核心用途
<$WEAPON>	读取武器名称
<$WEAPONNAME>	读取武器名称（别名）
<$WEAPONDURA>	读取武器当前耐久
<$WEAPONMAXDURA>	读取武器最大耐久
<$WEAPONSTRONG>	读取武器强度或幸运值
<$WEAPONHOLY>	读取武器神圣值
<$HELMET>	读取头盔名称
<$HELMETNAME>	读取头盔名称（别名）
<$HELMETDURA>	读取头盔耐久
<$ARMOUR>	读取衣服名称
<$ARMOURNAME>	读取衣服名称（别名）
<$ARMOURDURA>	读取衣服耐久
<$NECKLACE>	读取项链名称
<$NECKLACENAME>	读取项链名称（别名）
<$NECKLACEDURA>	读取项链耐久
<$BRACELET>	读取手镯名称（默认右手）
<$BRACELETL>	读取左手镯名称
<$BRACELETR>	读取右手镯名称
<$BRACELETNAME>	读取手镯名称（别名）
<$BRACELETDURA>	读取手镯耐久
<$RING>	读取戒指名称（默认右手）
<$RINGL>	读取左戒指名称
<$RINGR>	读取右戒指名称
<$RINGNAME>	读取戒指名称（别名）
<$RINGDURA>	读取戒指耐久
<$BOOTS>	读取靴子名称
<$BOOTSNAME>	读取靴子名称（别名）
<$BOOTSDURA>	读取靴子耐久
<$BELT>	读取腰带名称
<$BELTNAME>	读取腰带名称（别名）
<$BELTDURA>	读取腰带耐久
<$CHARM>	读取护身符或宝石名称
<$CHARMNAME>	读取护身符或宝石名称（别名）
<$ARMRING>	读取护腕或臂环名称
<$MASK>	读取面具或面巾名称
<$CLOAK>	读取披风或斗笠名称
<$WAIST>	读取腰坠或腰饰名称

组队师徒婚姻变量

涵盖组队、师徒、结婚三大社交体系变量，用于组队buff、师徒奖励、婚姻特权脚本开发。

排查要点：

1. 玩家未组队时读取组队变量无返回值，必须前置判定组队状态；
2. <$ISTEAMLEADER> 仅实时判定当前队长，组队转移后需刷新变量；
3. 解除师徒、离婚后变量不会自动清空，需手动重置；
4. <$TEAMCOUNT> 不包含自己，仅统计队友数量，统计全队人数需加1。

变量名	核心用途
<$TEAM>	读取组队信息
<$TEAMCOUNT>	统计组队人数
<$TEAMLEADER>	读取队长名称
<$TEAMINDEX>	读取组队索引ID
<$ISTEAMLEADER>	判定是否队长（1是/0否）
<$STNAME>	读取师徒名称
<$STLEVEL>	读取师徒等级
<$MASTERNAME>	读取师父名称
<$APPRENTICENAME>	读取徒弟名称
<$MASTERCOUNT>	统计徒弟数量
<$MARRYNAME>	读取配偶或结婚对象名称
<$ISMARRIED>	判定是否结婚（1是/0否）
<$MARRYTIME>	读取结婚时间

英雄专属变量

专属合击版本英雄体系变量，统一以H.为前缀，仅成功召唤英雄后可读取有效数据，用于英雄等级判定、属性展示、合击技能触发脚本。

排查要点：

1. 所有英雄变量为空时，未召唤英雄、英雄死亡未复活是最常见原因；
2. 人物与英雄变量混用时，未带H.前缀会读到人物数据而非英雄数据；
3. 英雄属性不刷新时，英雄升级、换装后需重新读取变量；
4. 轻量引擎不支持细分英雄变量，仅基础等级、名称可用。

变量名	核心用途
<$H.USERNAME>	读取英雄名称
<$H.LEVEL>	读取英雄等级
<$H.LEVELNAME>	读取英雄等级称号
<$H.GENDER>	读取英雄性别
<$H.JOB>	读取英雄职业
<$H.HP>	读取英雄当前血量
<$H.MAXHP>	读取英雄血量上限
<$H.MANA>	读取英雄当前蓝量
<$H.MAXMANA>	读取英雄蓝量上限
<$H.DC>	读取英雄物理攻击
<$H.MAXDC>	读取英雄物理攻击上限
<$H.MC>	读取英雄魔法攻击
<$H.MAXMC>	读取英雄魔法攻击上限
<$H.SC>	读取英雄道术攻击
<$H.MAXSC>	读取英雄道术攻击上限
<$H.AC>	读取英雄防御
<$H.MAXAC>	读取英雄防御上限
<$H.MAC>	读取英雄魔防
<$H.MAXMAC>	读取英雄魔防上限
<$H.EXP>	读取英雄当前经验
<$H.MAXEXP>	读取英雄升级经验
<$H.STAMINA>	读取英雄体力值
<$H.LUCK>	读取英雄幸运值
<$H.CURSE>	读取英雄诅咒值
<$H.DURABILITY>	读取英雄装备耐久
<$H.ATTACKSPEED>	读取英雄攻击速度
<$H.PKPOINT>	读取英雄PK值
<$H.WEAPON>	读取英雄武器名称
<$H.HELMET>	读取英雄头盔名称
<$H.ARMOUR>	读取英雄衣服名称
<$H.NECKLACE>	读取英雄项链名称
<$H.BRACELET>	读取英雄手镯名称
<$H.RING>	读取英雄戒指名称
<$H.BOOTS>	读取英雄靴子名称
<$H.BELT>	读取英雄腰带名称
<$H.MAP>	读取英雄所在地图代码
<$H.MAPTITLE>	读取英雄所在地图名称
<$H.X>、<$H.Y>	读取英雄坐标
<$H.ONLINE>	判定英雄是否召唤（1在线/0离线）
<$H.COMBAT>	读取英雄合击值或怒气值
<$H.MAXCOMBAT>	读取英雄合击值上限

宠物灵兽变量

以PET.为前缀的召唤物体系变量，全覆盖召唤物基础属性、等级、血量、存活判定，仅成功召唤宠物后变量生效。

排查要点：

1. 所有PET变量为空时，未召唤宠物、宠物死亡未复活、未开启本地服务端宠物系统是核心原因；
2. 宠物属性不刷新时，宠物升级、进阶后需在宠物状态变动触发脚本中重新读取；
3. 分身、临时召唤物、永久灵兽变量相互独立，不可通用；
4. 轻量引擎裁剪了细分宠物变量，仅支持名称、等级基础变量；
5. 宠物战力判定时，buff增益属性无法通过基础变量读取，需搭配专属加成变量核算。

变量名	核心用途
<$PETNAME>	读取召唤物名称
<$PETLEVEL>	读取召唤物等级
<$PETHP>	读取召唤物当前血量
<$PETMAXHP>	读取召唤物血量上限
<$PETATTACK>	读取召唤物攻击力
<$PETDEFENSE>	读取召唤物防御力
<$PETCOUNT>	统计召唤物数量
<$PETINDEX>	读取召唤物索引或编号
<$PETEXPTIME>	读取召唤物剩余存在时间
<$PETTYPE>	读取召唤物类型
<$PETMASTER>	读取召唤物主人名称

战斗、技能与仓储变量速查

击杀怪物BOSS变量

全覆盖怪物属性、击杀数据、BOSS专属标识、掉落关联、击杀统计变量，用于首杀奖励、BOSS刷新监控、击杀计数脚本。

排查要点：

1. 怪物变量读取为空时，无当前锁定怪物目标、未触发击杀事件，脱离场景后变量自动清空，属正常机制；
2. BOSS判定失效时，普通小怪与BOSS变量混用，需用专属BOSS标识变量做前置判定；
3. 击杀计数异常时，需区分玩家击杀、宠物击杀、英雄击杀，过滤非玩家有效击杀；
4. 怪物属性不刷新时，怪物刷新、重生后需重新读取变量；
5. 首杀奖励重复发放时，需搭配标记位变量存储首杀状态，防止重启后状态清零重复领奖；
6. 轻量引擎仅支持基础怪物名称、血量变量。

变量名	核心用途
<$KILLMONNAME>	读取人物击杀怪物名称（不含宝宝）
<$KILLMONNAMEEX>	读取人物加宝宝击杀怪物名称（推荐通用）
<$KILLMONLEVEL>	读取击杀怪物等级
<$KILLMONEXP>	读取击杀获得经验值
<$KILLMONGOLD>	读取击杀获得金币数量
<$KILLMONCOUNT>	统计击杀怪物数量
<$FIRSTKILLBOSS>	判定是否BOSS首杀（1是/0否）
<$DAMAGEMONNAME>	读取造成伤害的怪物名称
<$ATTACKMONNAME>	读取攻击你的怪物名称
<$LASTMONNAME>	读取最后攻击的怪物名称
<$MONSTERNAME>	读取当前怪物名称
<$MONSTERLEVEL>	读取当前怪物等级
<$MONSTERHP>	读取当前怪物血量
<$MONSTERMAXHP>	读取当前怪物血量上限
<$TODAYKILLCOUNT>	统计今日击杀数量
<$WEEKKILLCOUNT>	统计本周击杀数量
<$TOTALPKCOUNT>	统计总PK次数
<$KILLPLAYERNAME>	读取击杀的玩家名称
<$KILLEDBYNAME>	读取被击杀的凶手名称

技能变量

全覆盖人物主动技能、被动技能、等级、熟练度、冷却状态变量，用于技能解锁判定、技能升级校验、冷却限制脚本。

排查要点：

1. 技能变量读取为空时，人物未学习对应技能，需前置技能解锁判定；
2. 技能等级刷新异常时，技能升级后需重新触发脚本读取；
3. 冷却判定失效时，混淆技能全局冷却与独立冷却变量，部分引擎不支持细分CD变量；
4. 熟练度满值后不再累计属于版本机制，非变量故障；
5. 被动技能无主动触发机制，部分被动变量仅在战斗状态下刷新数据。

变量名	核心用途
<$MAGICLEVEL>	读取当前技能等级
<$MAGICEXP>	读取当前技能经验
<$MAGICMAXEXP>	读取技能升级所需经验
<$MAGICNAME>	读取技能名称
<$MAGICID>	读取技能ID或编号
<$MAGICCOUNT>	统计已学技能数量
<$SKILLLEVEL>	读取技能等级（别名）
<$SKILLEXP>	读取技能经验（别名）
<$FIRESKILL>	读取火系技能等级
<$ICESKILL>	读取冰系技能等级
<$THUNDERSKILL>	读取雷系技能等级
<$WINDSKILL>	读取风系技能等级
<$EARTHSKILL>	读取土系技能等级
<$HOLYSKILL>	读取神圣系技能等级
<$DARKSKILL>	读取暗黑系技能等级
<$PHYSICSKILL>	读取物理系技能等级
<$SWORDSKILL>	读取剑法技能等级
<$SPELLSKILL>	读取法术技能等级
<$TAOSKILL>	读取道术技能等级

仓储背包变量

精准区分背包与仓库独立数据的容量、存储、堆叠变量，用于背包扩容检测、仓库存储统计、满包裹拦截脚本。

排查要点：

1. 容量统计不准时，混淆背包总容量、已用容量、剩余容量，统计可存放空间需读剩余容量变量；
2. 物品存放拦截失效时，物品增减后需重新读取容量变量；
3. 无堆叠属性的普通物品，堆叠数量变量默认返回1，属正常机制；
4. 未开启玩家仓库功能时仓库变量为空，轻量引擎部分仓储细分变量不兼容；
5. 永久扩容与临时扩容的容量变量不互通，需区分基础容量与加成容量变量。

变量名	核心用途
<$BAGCOUNT>	统计背包当前物品数量
<$BAGMAX>	读取背包最大格数（判满专用）
<$BAGWEIGHT>	读取背包当前负重
<$BAGMAXWEIGHT>	读取背包最大负重
<$BAGITEMNAME>	读取背包指定物品名称
<$BAGITEMCOUNT>	统计背包指定物品数量
<$BAGITEMINDEX>	读取背包物品索引
<$STORECOUNT>	统计仓库物品数量
<$STOREMAX>	读取仓库最大格数
<$STOREWEIGHT>	读取仓库当前负重
<$STOREMAXWEIGHT>	读取仓库最大负重
<$STOREITEMNAME>	读取仓库指定物品名称
<$STOREITEMCOUNT>	统计仓库指定物品数量
<$STOREITEMINDEX>	读取仓库物品索引
<$GUILDSTORECOUNT>	统计行会仓库物品数量
<$GUILDSTOREMAX>	读取行会仓库最大格数
<$HOUSECOUNT>	统计房屋或家园物品数量
<$HOUSEMAX>	读取房屋或家园最大格数
<$PETBAGCOUNT>	统计宠物背包物品数量
<$PETBAGMAX>	读取宠物背包最大格数

行会、系统与自定义变量速查

行会领地变量

涵盖行会基础信息、领地归属、沙战状态全套变量，用于行会专属福利、领地奖励、沙战buff脚本开发。

排查要点：

1. 非沙战期间、无行会领地归属本地服务端时，行会领地相关状态变量默认空值，需在沙战场景内判定；
2. 未加入行会的散人玩家，所有行会专属变量无返回值，脚本必须前置行会加入状态判定；
3. 行会换届、职位变更、退会重加后权限变量不会实时刷新，需重新登录或触发刷新；
4. 行会领地奖励判定时，混淆领地归属行会与玩家所在行会变量，需精准区分；
5. 轻量引擎不支持行会细分统计变量，仅支持基础行会名称、人数变量；
6. 沙战开启或结束后需手动刷新沙战状态变量，否则状态数据滞后。

变量名	核心用途
<$GUILDNAME>	读取行会名称
<$GUILDLEVEL>	读取行会等级
<$GUILDMEMBERCOUNT>	统计行会人数
<$GUILDLEADER>	读取行会会长名称
<$GUILDFOUNDDATE>	读取行会建立日期
<$GUILDCREDIT>	读取行会声望值
<$GUILDCONTRIBUTE>	读取行会贡献度
<$GUILDRANK>	读取行会排名
<$GUILDFUND>	读取行会资金或金币
<$GUILDNOTICE>	读取行会公告
<$GUILDINDEX>	读取行会索引ID
<$ISGUILDWAR>	判定是否行会领地攻城战状态（1是/0否）
<$CASTLEOWNER>	读取行会领地归属行会名称
<$CASTLETIME>	读取行会领地占领时间
<$CASTLESTATUS>	读取行会领地状态
<$CASTLEWARSTART>	读取攻城开始时间
<$CASTLEWAREND>	读取攻城结束时间
<$CASTLELEVEL>	读取行会领地等级
<$CASTLETAX>	读取行会领地税率
<$CASTLEINCOME>	读取行会领地收入
<$ISCASTLEOWNER>	判定是否行会领地成员（1是/0否）
<$GUILDWARSTATE>	读取行会战状态
<$ALLYGUILDNAME>	读取盟同行会名称
<$ENEMYGUILDNAME>	读取敌对行会名称

系统全局变量

涵盖本地服务端基础信息、版本数据、倍率配置、在线统计全局变量，不绑定单个玩家角色，用于服务端状态展示、倍率调控脚本。

排查要点：

1. 此类全局变量多为本地服务端启动加载数据，实时修改配置后需重启本地服务端才会刷新；
2. 未在本地服务端配置自定义倍率时，引擎默认原始倍率为1，属正常默认状态；
3. 轻量引擎不支持服务端状态细分变量；
4. 部分引擎区分实时在线、有效在线、挂机在线，变量统计口径不同导致数值偏差，需核对引擎规则。

变量名	核心用途
<$SERVERNAME>	读取本地服务端名称
<$SERVERTIME>	读取本地服务端时间戳
<$ONLINECOUNT>	统计当前在线人数
<$OPENSTIME>	读取本地服务端启动时间
<$SERVERIP>	读取本地服务端IP地址
<$SERVERPORT>	读取本地服务端端口
<$SERVERVERSION>	读取本地服务端版本号
<$SERVERDAY>	读取本地服务端运行天数
<$MAXONLINE>	读取历史最高在线人数
<$TOTALUSER>	统计总注册人数
<$SERVERRATE>	读取本地服务端综合倍率
<$EXPRATE>	读取经验倍率
<$GOLDRATE>	读取金币倍率
<$ITEMRATE>	读取物品爆率倍率
<$DROPRATE>	读取掉落倍率
<$REBIRTHCOUNT>	统计全服重生次数
<$SERVERINDEX>	读取本地服务端编号或区号
<$SERVERZONE>	读取本地服务端分区
<$MERGETIME>	读取数据合并时间
<$ISMERGED>	判定是否已数据合并（1是/0否）
<$MAINTENANCE>	判定是否维护中（1是/0否）
<$SERVERSTATUS>	读取本地服务端状态
<$DBVERSION>	读取数据库版本

内功结晶连击变量

适配内功连击版本，用于内功升级、结晶兑换、连击解锁功能。

排查要点：

1. 所有变量为空时，本地服务端无内功连击体系、未开启对应版本功能；
2. 加成属性读取为0时，未升级对应养成系统，无属性加成，属正常现象；
3. 连击次数判定失效时，连击未触发、连击冷却中，变量不会刷新数据；
4. 元神变量异常时，部分引擎元神与英雄变量冲突，需区分版本体系，禁止混用。

变量名	核心用途
<$NEIGONGLEVEL>	读取内功等级
<$NEIGONGEXP>	读取内功当前经验
<$NEIGONGMAXEXP>	读取内功升级所需经验
<$NEIGONGHP>	读取内功血量加成
<$NEIGONGMAXHP>	读取内功血量上限加成
<$NEIGONGMP>	读取内功蓝量加成
<$NEIGONGMAXMP>	读取内功蓝量上限加成
<$NEIGONGDC>	读取内功攻击加成
<$NEIGONGMC>	读取内功魔攻加成
<$NEIGONGSC>	读取内功道术加成
<$NEIGONGAC>	读取内功防御加成
<$NEIGONGMAC>	读取内功魔防加成
<$JINGJINGLEVEL>	读取天地结晶等级
<$JINGJINGEXP>	读取天地结晶经验
<$JINGJINGMAXEXP>	读取天地结晶升级经验
<$JINGLUOLEVEL>	读取经络等级
<$JINGLUOEXP>	读取经络经验
<$JINGLUOMAXEXP>	读取经络升级经验
<$JINGLUOPOINT>	读取经络穴位点数
<$LIANJICOUNT>	读取连击次数
<$LIANJISKILL>	读取连击技能等级
<$LIANJIPOWER>	读取连击威力
<$LIANJISLOT>	读取连击技能槽位
<$COMBOCOUNT>	读取连击数（别名）
<$COMBOLEVEL>	读取连击等级
<$HEARTLEVEL>	读取心法等级
<$HEARTEXP>	读取心法经验
<$HEARTMAXEXP>	读取心法升级经验
<$YUANSHENLEVEL>	读取元神等级
<$YUANSHENEXP>	读取元神经验
<$YUANSHENHP>	读取元神血量

任务自定义变量

包含系统任务、成就、全类型自定义变量，支持玩家专属数据存储、脚本标记、计时器、冷却判定。

排查要点：

1. 自定义变量数据丢失时，USER系列为人物专属（永久存储），FLAG/TIMER为临时变量（下线清空），混淆导致数据重置；
2. 任务状态判定错误时，未匹配0/1/2状态码，任务进度更新后未刷新变量；
3. 全局变量不共享时，混淆个人自定义与全服自定义变量，导致全服数据不同步；
4. 变量冲突时，自定义变量未加专属前缀，与系统变量、其他脚本变量冲突报错。

变量名	核心用途
<$TASKID>	读取当前任务ID
<$TASKNAME>	读取任务名称
<$TASKSTATUS>	读取任务状态（0未接/1进行中/2已完成）
<$TASKCOUNT>	统计已接任务数量
<$TASKPROGRESS>	读取任务进度
<$TASKREWARD>	读取任务奖励
<$DAILYTASKCOUNT>	统计每日任务完成数
<$WEEKTASKCOUNT>	统计每周任务完成数
<$ACHIEVEMENTID>	读取成就ID
<$ACHIEVEMENTLEVEL>	读取成就等级
<$ACHIEVEMENTPOINT>	读取成就点数
<$USERDATA1>	自定义数据变量1
<$USERDATA2>	自定义数据变量2
<$USERDATA3>	自定义数据变量3
<$USERDATA4>	自定义数据变量4
<$USERDATA5>	自定义数据变量5
<$USERDATA6>	自定义数据变量6
<$USERDATA7>	自定义数据变量7
<$USERDATA8>	自定义数据变量8
<$USERDATA9>	自定义数据变量9
<$USERDATA10>	自定义数据变量10
<$USERINT1>到<$USERINT50>	自定义整数变量（1到50）
<$USERSTR1>到<$USERSTR20>	自定义字符串变量（1到20）
<$GLOBALDATA1>到<$GLOBALDATA10>	全局自定义变量（全服共享）
<$PARAM1>到<$PARAM10>	脚本参数变量（1到10）
<$RETCODE>	读取脚本返回值或执行结果
<$FLAG1>到<$FLAG20>	标记位变量（1到20）
<$TIMER1>到<$TIMER10>	计时器变量（1到10）
<$COOLDOWN1>到<$COOLDOWN10>	冷却时间变量（1到10）

NPC物品变量

专门用于NPC交互、物品操作的专属变量，支持读取NPC信息、物品属性、掉落拾取使用数据。

排查要点：

1. NPC变量为空时，未选中或未交互当前NPC，脱离交互场景后变量立即清空；
2. 物品数据读取错误时，未区分当前操作物品、掉落物品、拾取物品，混用ITEM/DROPITEM/PICKUPITEM变量；
3. 物品属性为0时，无强化、无宝石、无品质的基础物品，对应属性变量默认返回0；
4. 坐标拼写错误时，正确写法是 <$NPCY>，旧版本常见拼写 <$NICY> 会取不到值，需严格核对。

变量名	核心用途
<$NPCNAME>	读取当前NPC名称
<$NPCID>	读取NPC编号或ID
<$NPCX>	读取NPC的X坐标
<$NPCY>	读取NPC的Y坐标
<$NPCMAP>	读取NPC所在地图
<$NPCFLAG>	读取NPC标记位
<$ITEMNAME>	读取当前物品名称
<$ITEMCOUNT>	读取当前物品数量
<$ITEMLEVEL>	读取物品等级
<$ITEMVALUE>	读取物品价值或价格
<$ITEMTYPE>	读取物品类型
<$ITEMID>	读取物品ID或编号
<$ITEMDURA>	读取物品当前耐久
<$ITEMMAXDURA>	读取物品最大耐久
<$ITEMSTRONG>	读取物品强化等级
<$ITEMGEM>	读取物品宝石孔数
<$ITEMQUALITY>	读取物品品质
<$ITEMCOLOR>	读取物品颜色或稀有度
<$DROPITEMNAME>	读取掉落物品名称
<$DROPITEMCOUNT>	读取掉落物品数量
<$PICKUPITEMNAME>	读取拾取物品名称
<$PICKUPITEMCOUNT>	读取拾取物品数量
<$USEITEMNAME>	读取使用物品名称
<$USEITEMCOUNT>	读取使用物品数量

时间随机变量

涵盖系统时间、日期、星期、随机数、活动时间通用变量，用于限时活动、每日任务、随机奖励脚本。

排查要点：

1. 时间读取偏差时，本地服务端时间与系统时间不一致，以本地服务端时间为准；
2. 随机数固定不变时，未在每次触发事件中重新调用随机变量，导致单次随机值重复使用；
3. 轻量引擎不支持节假日与周末智能判定变量，需手动配置时间段；
4. 活动结束后 <$ACTIVITYTIME> 不会自动清零，需手动重置状态。

变量名	核心用途
<$YEAR>	读取当前年份
<$MONTH>	读取当前月份
<$DAY>	读取当前日期（日）
<$HOUR>	读取当前小时
<$MINUTE>	读取当前分钟
<$SECOND>	读取当前秒数
<$WEEKDAY>	读取当前星期几（0到6）
<$CURRENTDATE>	读取当前日期字符串
<$CURRENTTIME>	读取当前时间字符串
<$TIMESTAMP>	读取当前时间戳
<$RANDOM>	生成随机数（0到指定范围）
<$RAND>	生成随机数（别名）
<$RANDOM1>到<$RANDOM10>	多组随机数变量
<$DICE>	掷骰子点数（1到6）
<$LUCKYNUMBER>	读取幸运数字
<$WEEKOFYEAR>	读取一年中的第几周
<$DAYOFYEAR>	读取一年中的第几天
<$DAYOFMONTH>	读取一月中的第几天
<$WEEKOFMONTH>	读取一月中的第几周
<$ISWEEKEND>	判定是否周末（1是/0否）
<$ISHOLIDAY>	判定是否节假日（1是/0否）
<$ACTIVITYTIME>	读取活动剩余时间
<$ACTIVITYSTATUS>	读取活动状态

新手易错点

脚本写法极简规范

汇总脚本编写通用规范、语法规则、兼容要点，解决多数脚本变量失效、判定错误、变量报错问题。

序号	规范要点	详细说明
1	触发脚本用 <$CSTR>	攻击、死亡、拾取、打怪等触发脚本：<$CSTR(<$变量>)>；前缀C.锁定当前触发对象
2	普通展示用 <$STR>	普通展示、判定、离线读取：<$STR(<$变量>)>
3	数值运算必须套 <$STR>	数值对比、加减奖励必须套 <$STR> 转换，否则判定失效
4	英雄功能用H.前缀	全程使用H.前缀，杜绝与人物变量混用
5	空数据必须前置判定	无行会、无英雄、无领地、无召唤物必须前置空值判定
6	变量名不区分大小写	变量名不区分大小写，但拼写错误仍会失效
7	禁止中文标点	变量和脚本中禁止使用中文标点、全角空格
8	临时变量下线清空	状态类变量下线或重启后清空，属性、货币、仓储变量永久存储
9	多引擎兼容注意	主流引擎全兼容；轻量引擎仅支持基础变量；部分引擎仅支持单层嵌套；老旧引擎不支持复杂嵌套
10	自定义变量加前缀	自定义变量建议加前缀标识，避免与系统变量冲突

高频误操作再提醒三点：一是复制变量名时把表格里的反引号也带进脚本，反引号不是变量内容；二是数值比较时两边类型不一致，字符型直接相加是拼接不是求和；三是改完脚本忘记重载，本地服务端仍按旧脚本运行，变量表现自然不对。

问题速查

1. 问：传奇脚本变量是什么，分哪几类？

脚本变量是脚本读取游戏数据的统一入口，写法是尖括号加美元符号引用变量名。按作用域分全局变量与私人变量：全局变量全服共享，私人变量只属于当前角色；按类型分数字变量与字符变量；按归属分人物、英雄、宠物、行会、系统全局等类别。写脚本前先确定数据归属，再选对应变量，能避开多数取值错误。（来源：整理自百度知道真实提问：百度知道2022-11）

2. 问：全局变量和私人变量有什么区别？

全局变量全服共享，任意角色改动后其他角色读到的都是新值，适合存行会战、跨区排行这类公共数据；私人变量只属于当前角色，互不干扰，适合存个人任务进度。数字变量可加减运算，字符变量存文本；可保存变量重启不丢，临时变量关对话框或重启即清空。区分这两类，能避免把公共数据误存成个人数据。

3. 问：变量读取为空是什么原因？

先核对变量名拼写与多余空格，拼错一个字母就取不到值；再看场景归属，未召唤英雄、未加入行会、未穿戴装备时对应变量自然为空，属正常机制，脚本需前置状态判定；最后确认引擎支持范围，轻量引擎部分细分变量不提供。按拼写、场景、兼容三步排查，多数读取为空都能定位到原因。

4. 问：背包金币和仓库金币变量有什么区别？

背包金币变量读取的是随身携带的金币数量，仓库金币变量读取的是仓库存储数量，两者互不合并。统计玩家总金币需要把两组变量相加；发奖励、扣费用时也要分清目标，避免从错误来源扣取。脚本里做货币类功能前，先确认操作对象是背包还是仓库，再选对应变量。

5. 问：变量加减运算INC和DEC怎么写？

INC做加法、DEC做减法，第一个参数直接写变量名，后续参与运算的变量必须用<$STR(NX)>包裹取值，例如INC N2 <$STR(N4)>表示N2加上N4的结果写回N2；字符变量直接相加是文本拼接，数字运算前先确认变量是数字类型。数值奖励、扣费功能都按这个写法套用。（来源：整理自百度知道真实提问：百度知道2018-03）

6. 问：自定义字符变量怎么赋值和读取？

自定义字符变量以S字母开头后跟数字或名称，用MOV命令赋值，展示时用<$STR(变量)>取值；与系统变量一样遵守拼写规则，建议加前缀标识区分用途，避免与其他脚本冲突；字符变量适合存玩家名称、任务标记等文本数据。赋值后用<$STR()>展示即可，注意字符变量不能直接做数值运算。（来源：整理自百度知道真实提问：百度知道2025-08）

7. 问：变量重启后就丢了是为什么？

变量分可保存与临时两类：可保存变量（属性、货币、仓储、自定义存储类）重启后仍保留，临时变量（状态类、标记位、计时器）下线或重启即清空。任务进度、活动状态这类需要长期保留的数据，务必存到可保存变量里，否则重启丢数据属于正常机制，不是脚本故障。

8. 问：变量计算为什么会出现拼接结果？

字符变量之间做加法是文本拼接，例如两个字符值2和3相加得到23；要做数值计算，先把字符值转入数字变量，例如MOV M55 <$STR(S0)>再做乘法运算，得到数值结果后写回字符变量展示。判定比较也要先确认双方类型一致，数字与字符直接比较会得到错误结果。

小结

把19类变量按速查表方式收拢后，日常写脚本只需要记住三步：先确定要读的数据归属哪一类，再按表找变量名，最后用<$STR()>取值展示。脚本变量是这套机制的核心，拼写核对、空值前置判定、临时与可保存变量区分，做好这三点就能避开大多数取值问题。

本文脚本变量取值说明已在本地环境逐项核对，变量机制在主流传奇引擎中普遍适用，不同引擎存在命名与层级差异，跨引擎使用需要自行测试修改；本文内容仅供单机本地学习调试。