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

本文为传奇脚本变量完整版速查表，适配主流传奇引擎，全覆盖人物属性、攻防货币、装备社交、英雄内功、自定义任务、服务器参数等全部常用变量。文档分类清晰、附带引擎兼容规则与高频故障排查方案，搭配标准化脚本编写规范，可快速解决脚本报错、兼容失效等问题，是传奇版本开发、运维的实用工具手册。

新手GM必看：

1. 变量名不区分大小写，但禁止使用中文标点和多余空格，否则直接失效；

2. 数值运算必须套 $STR() 解析；

3. 触发脚本用 C. / $CSTR，普通展示/读取用全局变量；

4. 临时状态变量下线或重启后清空，属性、货币、仓储变量永久存储。

引擎兼容速记

GEE/GOM/翎风：全变量兼容｜HERO：仅支持基础人物和英雄变量，不支持PET、行会细分变量｜BLUE：校验最严格，仅支持单层嵌套｜LEGEND：不支持复杂嵌套变量

提示：可以使用CTRL+F快速查找所需变量。

人物基础属性变量（全版本通用）

变量简述：读取人物核心基础原生属性，涵盖角色信息、状态、负重、外观等基础数据，适配所有传奇引擎版本，是脚本最常用的基础变量组。

常见问题与故障排查：

1. 变量读取为空/无数据：多为拼写错误、多余空格，基础变量无引擎兼容问题，优先核对变量名；

2. 数值不刷新：人物属性实时变动后未重新加载脚本，重启触发即可；

3. 性别/职业判定失效：未匹配对应数值（0战/1法/2道、0男/1女），脚本判定条件写错。

人物攻防属性变量（细分上下限）

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

常见问题与故障排查：

1. 上下限数值混淆报错：DC/MAC/SC 为下限、MAX系列为上限，别名变量（DCMIN/DCMAX等）功能一致，禁止混用；

2. 战斗属性读取异常：穿戴装备后未刷新，需在装备变动触发脚本中重新读取变量；

3. 攻速/魔法速度无效：部分引擎不支持魔法攻速变量，优先核对引擎兼容列表。

货币、积分、声望变量

变量简述：涵盖游戏内全部流通货币、各类积分、声望、威望、战功等资源类变量，精准区分背包与仓库货币数据，是服务器福利回馈、道具兑换、奖励发放、数值扣取、权限解锁等各类各类功能脚本的核心基础变量。

常见问题与故障排查：

1. 货币统计数据不准：混淆$GOLDCOUNT（背包金币）与$STOREMONEY（仓库金币），统计玩家总金币需叠加两组变量；

2. 积分/声望修改不生效：此类资源变量为永久存储属性，修改后需执行保存指令，单纯重启服务器无法固化数据；

3. 货币变量为空：老旧HERO轻量引擎不支持细分货币变量，仅GEE/BLUE引擎全适配，需核对引擎兼容类型；

4. 各类荣誉/威望数值异常：部分版本需开启对应玩法功能后，变量才会生成数据，未开通玩法时变量默认空值或0；

5. 贡献度读取失效：行会贡献变量仅加入行会的玩家有数据，散人玩家读取默认无返回值，需前置行会状态判定。

坐标、地图、在线变量

变量简述：涵盖人物实时坐标、地图信息、在线时长、安全区判定等场景类变量，主要用于地图限制、区域触发、在线时长统计、场景权限管控脚本，适配各类地图专属功能、在线奖励、区域buff、安全区功能开发。

常见问题与故障排查：

1. 坐标判定失效：人物移动、切换地图后坐标不会自动刷新，需绑定移动、换图触发事件重新读取变量；

2. 地图名称空值/错乱：小众自定义地图、未配置地图文本的地图，$MapTitle 中文名称返回空值，精准判定优先使用$MAP地图代码；

3. 在线时长统计异常：混淆瞬时在线时长（当前登录会话）与累计在线时长，$ONLINETIME为本次登录时长，$TOTALONLINETIME为账号总在线时长；

4. 安全区判定无效：$SAFEZONE变量仅GEE、BLUE引擎完美兼容，HERO、LEGEND老旧引擎不支持，需手动通过地图坐标范围判定安全区；

5. 楼层Z坐标无数据：绝大多数普通地图无楼层分层，仅洞穴、多层副本、特殊地图会返回Z坐标数值，空白为正常现象。

人物状态、账号、行会变量

变量简述：涵盖人物实时状态、账号注册登录数据、行会职位权限三大类核心变量，可用于红名判定、死亡/异常状态检测、账号数据统计、行会权限管控、官职功能开发，是角色状态校验、权限区分、账号数据记录脚本的必备变量组，适配全引擎基础功能开发。

常见问题与故障排查：

1. 红名PK判定不准：$PKPOINT为实时PK数值，$ISRED为快捷红名判定，二者搭配使用，单独使用数值易出现判定偏差；不同引擎红名阈值不同，需适配服务器配置。

2. 人物状态变量失效：麻痹、中毒、死亡等瞬时状态变量仅状态持续期间有数据，状态解除后自动清零，属于正常机制，非变量故障。

3. 账号时间数据异常：未注册/未登录的空白账号，注册、登录、登出时间变量为空；新账号无历史登录记录，登录次数默认0。

4. 行会变量读取为空：非行会成员（散人）无法读取行会职位、会长、官员相关变量，脚本需前置行会加入状态判定，避免空值报错。

5. 行会权限判定错误：$ISGUILDMASTER、$ISGUILDOFFICER为即时权限判定，行会换届、职位变更后需刷新脚本，否则数据滞后。

全套装备读取变量

用途：装备检测、回收、特效触发、战力判定

变量简述：全覆盖读取人物全身穿戴装备的名称、耐久、属性等数据，区分左右手饰品，支持装备校验、专属特效、装备回收、战力核算等实操脚本。

常见问题与故障排查：

1. 装备读取为空：对应装备栏未穿戴物品，未做空值判定导致脚本报错；

2. 左右手饰品混淆：$BRACELET/$RING为默认右手，左手需单独用L后缀变量，直接混用就会导致传奇脚本变量检测失效；

3. 耐久读取异常：未穿戴装备耐久变量无数据，装备掉落/脱下后变量立即清空；

4. 别名变量失效：部分低版本引擎不支持NAME后缀别名变量，建议优先使用基础变量。

组队、师徒、婚姻变量

变量简述：涵盖玩家社交关系变量，支持组队、师徒、结婚三大社交体系，用于组队buff、师徒奖励、婚姻特权、关系判定等脚本开发。

常见问题与故障排查：

1. 组队数据为空：玩家未组队时读取组队变量无返回值，必须前置判定组队状态；

2. 队长判定错误：$ISTEAMLEADER仅实时判定当前队长，组队转移后未刷新变量导致数据滞后；

3. 师徒/配偶数据异常：解除师徒、离婚后变量不会自动清空，需手动重置；

4. 人数统计不准：$TEAMCOUNT不包含自己，仅统计队友数量，统计全队人数需+1。

英雄专属变量（H.前缀｜合击专用）

规则：仅召唤英雄后有数据，未召唤时为空

变量简述：专属合击版本英雄体系变量，统一以H.为前缀，全覆盖英雄基础属性、状态、养成、战斗相关数据，仅成功召唤英雄后可读取有效数据，主要用于英雄等级判定、属性展示、战力核算、合击技能触发、英雄养成奖励等合击专属脚本，适配主流合击引擎，老旧轻量引擎存在部分功能裁剪。

常见问题与故障排查：

1. 所有英雄变量为空：未召唤英雄、英雄死亡未复活，是最常见报错原因；

2. 人物英雄变量混用：未带H.前缀，导致读取人物数据而非英雄数据；

3. 英雄属性不刷新：英雄升级、换装后未重新读取变量，数据存在延迟；

4. 老旧引擎失效：HERO轻量引擎不支持细分英雄变量，仅基础等级、名称可用。

宠物、灵兽、召唤物变量（PET系列｜道士宝宝/神兽）

变量简述：专属宠物、灵兽、召唤兽、分身体系变量，统一以PET.为前缀，全覆盖召唤物基础属性、状态、等级、血量、技能、存活判定等核心数据，适用于宠物养成、宠物战力加成、召唤物专属buff、宠物死亡复活、分身伤害判定等脚本开发。仅成功召唤宠物/灵兽后变量生效，未召唤、宠物死亡状态下变量为空值，多数主流GEE/GOM/翎风和BLUE引擎适配，老旧HERO引擎仅支持少量基础宠物变量。

常见问题与故障排查：

1. 所有PET变量为空：未召唤宠物、宠物死亡未复活、未开启服务器宠物系统，是变量无数据的核心原因，需前置宠物存活判定；

2. 宠物属性不刷新：宠物升级、进阶、学习技能后变量不会自动更新，需在宠物状态变动触发脚本中重新读取变量；

3. 分身/灵兽变量混用：分身、临时召唤物、永久灵兽变量相互独立，不可通用，需区分对应前缀变量；

4. 老旧引擎适配失效：HERO、LEGEND轻量引擎裁剪了细分宠物变量，仅支持宠物名称、等级基础变量，高阶属性变量无法读取；

5. 宠物战力判定异常：未区分宠物基础属性与加成属性，buff增益属性无法通过基础变量读取，需搭配专属加成变量核算。

击杀、怪物、BOSS专属变量

变量简述：专属怪物、BOSS、击杀判定体系变量，全覆盖怪物属性、击杀数据、BOSS专属标识、掉落关联、击杀统计等核心数据，广泛用于怪物首杀奖励、BOSS刷新监控、击杀计数、专属掉落判定、怪物属性展示、刷怪限制等脚本开发，适配绝大多数打宝、刷怪、BOSS专属玩法功能，主流GEE/GOM/BLUE引擎全面兼容，老旧引擎部分BOSS细分变量不支持。

常见问题与故障排查：

1. 怪物变量读取为空：无当前锁定怪物目标、未触发击杀/攻击怪物事件，脱离怪物交互场景后变量自动清空，属于正常机制；

2. BOSS判定失效：普通小怪与BOSS变量混用，未使用专属BOSS标识变量做前置判定，导致小怪误触发BOSS专属功能；

3. 击杀计数统计异常：未区分玩家击杀、宠物击杀、英雄击杀，未过滤非玩家有效击杀数据，统计结果偏差；

4. 怪物属性数据不刷新：怪物刷新、重生后未重新读取变量，缓存旧数据导致属性、血量、掉落数据滞后；

5. 首杀奖励重复发放：未搭配FLAG标记位存储首杀状态，怪物重置、服务器重启后状态清零，造成重复领奖漏洞；

6. 老旧引擎变量失效：HERO/LEGEND轻量引擎仅支持基础怪物名称、血量变量，不支持BOSS等级、刷新时间、专属掉落变量。

技能变量

变量简述：全覆盖人物主动技能、被动技能、技能等级、熟练度、冷却状态、解锁状态等核心数据变量，支持技能解锁判定、技能升级校验、冷却限制、专属技能特权、技能伤害加成等脚本开发，适配全引擎技能体系功能制作，是技能相关定制脚本的核心变量组。

常见问题与故障排查：

1. 技能变量读取为空：人物未学习对应技能、技能未解锁，变量无返回数据，需前置技能解锁判定；

2. 技能等级刷新异常：技能升级后未重新触发脚本读取变量，缓存数据未更新导致数值滞后；

3. 冷却判定失效：混淆技能全局冷却与独立冷却变量，部分引擎不支持细分技能CD变量，需核对引擎兼容性；

4. 熟练度数值不变：部分版本技能熟练度满值后不再累计，属于版本机制，非变量故障；

5. 被动技能判定错误：被动技能无主动触发机制，部分被动变量仅在战斗状态下刷新数据。

仓储、背包变量

变量简述：专属人物背包、仓库容量、物品存储、堆叠数量的核心变量组，精准区分背包与仓库独立数据，支持背包扩容检测、仓库存储统计、物品堆叠判定、满包裹拦截、仓储权限管控等功能脚本，是道具存储、物品管控、容量限制类脚本的核心变量，适配全主流传奇引擎。

常见问题与故障排查：

1. 容量统计数据不准：混淆背包总容量、已用容量、剩余容量三类变量，统计可存放空间需读取剩余容量变量；

2. 物品存放拦截失效：未实时刷新背包/仓库容量变量，物品增减后未重新读取数值，导致判定滞后；

3. 堆叠数量读取异常：无堆叠属性的普通物品，堆叠数量变量默认返回1，不属于变量故障；

4. 仓库变量为空：未开启玩家仓库功能、未初始化仓库数据，老旧轻量引擎部分仓储细分变量不兼容；

5. 背包扩容判定失效：永久扩容、临时扩容的容量变量不互通，需区分基础容量与加成容量变量。

行会、行会领地变量

变量简述：涵盖行会基础信息、行会领地归属、行会权限、行会战力、沙战状态等全套行会行会领地专属变量，支持行会专属福利、行会领地奖励、行会权限判定、沙战buff、行会排名、行会领地占领统计等功能脚本开发，是传奇行会、行会领地玩法定制的核心变量组，适配主流合击、单职业、复古等各类版本引擎。

常见问题与故障排查：

1. 行会领地判定变量失效：非沙战期间、无行会领地归属服务器，行会领地相关状态变量默认空值/0，属于正常机制，需在沙战场景内判定；

2. 行会数据读取为空：未加入任何行会的散人玩家，所有行会专属变量无返回值，脚本必须前置行会加入状态判定，避免空值报错；

3. 行会职位权限错乱：行会换届、成员职位变更、退会重加后，行会权限变量不会实时刷新，需重新登录或触发脚本刷新数据；

4. 行会领地奖励判定不准：混淆$CASTLEOWNER（行会领地归属行会）与玩家所在行会变量，行会领地成员、非行会领地成员判定需精准区分；

5. 行会人数/战力统计异常：部分老旧引擎不支持行会细分统计变量，仅GEE/BLUE引擎完整适配，HERO引擎仅支持基础行会名称、人数变量；

6. 沙战状态不更新：沙战开启/结束后，需手动刷新沙战状态变量，否则会出现状态数据滞后、奖励领取异常的问题。

系统服务器全局变量

变量简述：涵盖服务器基础信息、版本数据、倍率配置、在线统计、服务器数据合并维护等全局服务器变量，属于全服通用静态/动态数据，不绑定单个玩家角色，主要用于服务器状态展示、版本活动配置、倍率调控、全区数据统计、服务器运维提示等全局脚本开发，适配全主流传奇引擎。

常见问题与故障排查：

1. 服务器变量数据固定不变：此类全局变量多为服务器启动加载数据，实时修改服务器配置后需重启服务端，变量才会刷新；

2. 倍率变量读取为1/默认值：未在服务端配置自定义倍率，引擎默认原始倍率为1，属于正常默认状态；

3. 服务器数据合并/维护变量判定失效：老旧LEGEND、HERO轻量引擎不支持服务器状态细分变量，仅GEE/BLUE引擎完整适配；

4. 在线人数统计异常：部分引擎区分实时在线、有效在线、挂机在线，变量统计口径不同导致数值偏差，需核对引擎规则；

内功、结晶、连击特殊变量

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

常见问题与故障排查：

1. 所有变量为空：服务器无内功连击体系、未开启对应版本功能，变量无数据；

2. 加成属性读取为0：未升级对应养成系统，无属性加成，属于正常现象；

3. 连击次数判定失效：连击未触发、连击冷却中，变量不会刷新数据；

4. 元神变量异常：部分引擎元神与英雄变量冲突，需区分版本体系，禁止混用。

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

任务、自定义变量

变量简述：包含系统任务、成就、全类型自定义变量，支持玩家专属数据存储、脚本标记、计时器、冷却判定，是自定义功能开发、任务系统、权限标记的核心变量组，适配所有自定义脚本。

常见问题与故障排查：

1. 自定义变量数据丢失：USER系列为人物专属（永久存储），FLAG/TIMER为临时变量（下线清空），混淆导致数据重置；

2. 任务状态判定错误：未匹配0/1/2状态码，任务进度更新后未刷新变量；

3. 全局变量不共享：混淆USERDATA（个人）和GLOBALDATA（全服），导致全服数据不同步；

4. 变量冲突：自定义变量未加专属前缀，与系统变量、其他脚本变量冲突报错。

NPC、物品变量

变量简述：专门用于NPC交互、物品操作的专属变量，支持读取NPC信息、物品属性、掉落/拾取/使用物品数据，是NPC对话、物品回收、掉落判定、道具使用脚本的基础变量。

常见问题与故障排查：

1. NPC变量为空：未选中/未交互当前NPC，脱离NPC交互场景后变量立即清空；

2. 物品数据读取错误：未区分当前操作物品、掉落物品、拾取物品，混用ITEM/DROPITEM/PICKUPITEM变量；

3. 物品属性为0：无强化、无宝石、无品质的基础物品，对应属性变量默认返回0；

4. 坐标拼写错误：$NICY为常见拼写错误，正确NPCY坐标变量无拼写错误需严格核对。

时间、随机系统变量

变量简述：涵盖系统时间、日期、星期、随机数、活动时间等通用变量，用于限时活动、每日任务、随机奖励、时间段限制、节假日专属功能脚本。

常见问题与故障排查：

1. 时间读取偏差：服务器时间与本地时间不一致，以$SERVERTIME服务器时间为准；

2. 随机数固定不变：未在每次触发事件中重新调用随机变量，导致单次随机值重复使用；

3. 节假日/周末判定失效：老旧引擎不支持智能判定变量，需手动配置时间段；

4. 活动时间显示异常：活动结束后$ACTIVITYTIME不会自动清零，需手动重置状态。

脚本写法极简规范（避坑核心）

变量简述：汇总脚本编写通用强制规范、语法规则、引擎兼容要点，解决90%以上传奇脚本变量失效、判定错误、变量报错问题，是脚本编写、排错、兼容适配的核心参考准则。

常见问题与故障排查：

1. 脚本整体失效：未使用$CSTR触发解析、存在中文标点/多余空格、数值运算未套$STR；

2. 多引擎适配报错：未区分各引擎兼容范围，复杂嵌套在HERO/LEGEND引擎中失效；

3. 空值报错频发：未做空数据前置判定，无英雄、无行会、空装备场景直接触发报错；

4. 变量混乱：英雄/人物/全局变量混用，无前缀区分，导致数据读取错误。

全文总结

本文是传奇脚本变量实用速查手册，适配GEE、GOM、HERO等多款主流传奇引擎，全覆盖收录人物属性、战斗攻防、货币资源、装备社交、英雄合击、内功连击、自定义任务、NPC物品、服务器参数等各类脚本变量。文档分类清晰、便于检索，同步配套引擎兼容规则、高频故障排查方案及脚本编写规范，可有效解决脚本变量报错、兼容失效、判定异常等问题，适配各类传奇版本自定义开发与运维修改工作，是传奇脚本制作、版本运维人员的高效必备工具。