传奇清除宝石升级装备属性完整脚本教程 ClearStoneUpgrade命令用法与位置编码及转生还

清除宝石升级属性的核心命令是ClearStoneUpgrade，按装备位置参数指定要清除哪件装备，执行后该装备通过宝石升级获得的所有附加属性全部消失，装备的基础属性不受影响。与之容易混淆的是DELATTLIST和UPGRADEITEMEX参数5=2，三条命令的适用场景和清除范围完全不同，写脚本时混用会导致清除结果不符合预期。

## ClearStoneUpgrade命令格式与参数

命令格式为ClearStoneUpgrade 位置(0-14)。只有一个参数，即装备位置编号，取值0到14，对应人物身上各个装备栏位。

最基础的写法：

```
[@main]
#IF
#ACT
ClearStoneUpgrade 0
```

位置0代表盔甲，执行后身上穿的盔甲上所有通过宝石升级获得的星星和附加属性全部消失，装备恢复为未升级状态。命令没有返回值，执行后不会自动弹出提示，需要在脚本中手动用SENDMSG或SAY段落反馈结果。

这条命令的一个重要特性是不区分极品和普通装备，清除时所有属性都将消失。这意味着如果装备同时拥有宝石升级属性和鉴定属性，执行ClearStoneUpgrade后宝石升级相关的属性会被移除，鉴定属性的处理取决于引擎版本。部分引擎中两条属性是独立存储的，清除宝石升级属性不影响鉴定属性；另一些引擎中两者存在同一属性组里，清除操作会一并移除。实际部署前先在测试环境验证当前引擎的具体行为。

## 装备位置编码对照

位置参数0到14的对应关系如下：0盔甲，1武器，2照明物，3项链，4头盔，5右手镯，6左手镯，7右戒指，8左戒指，9护身符位置，10腰带，11鞋子，12宝石，13斗笠，14面巾或马牌。

写错位置是脚本报错的高频原因。比如要清除武器的宝石升级属性却写了位置0，实际清除的是盔甲栏。玩家反馈武器属性没变但盔甲属性被清空，排查时优先检查ClearStoneUpgrade后面的位置参数。

位置参数不支持变量。不能写成ClearStoneUpgrade <$STR(N1)>这样的形式，参数必须是固定数字。需要让玩家选择清除哪件装备时，在NPC脚本中为每个位置单独写一个选项按钮，每个按钮跳转到独立的标识段落，段落中执行对应位置的清除命令。

## 清除宝石升级属性与清除全部附加属性的区别

ClearStoneUpgrade只清除通过宝石升级系统获得的属性，即装备上用星星表示的那些升级次数对应的附加属性。装备的鉴定属性、元素属性、自定义属性组不受影响。

DELATTLIST清除的是通过ADDATTLIST命令添加的自定义属性组。格式为DELATTLIST 属性组名称，参数为空时清除所有自定义属性组。这条命令针对的是属性组系统，与宝石升级的星星是两套独立的机制。

UPGRADEITEMEX的参数5设置为2时执行还原操作，格式为UPGRADEITEMEX 物品位置 属性位置 0 0 2。参数5=2代表还原，会把装备恢复到DB数据库中的初始属性状态，清空所有升级加成。区别在于UPGRADEITEMEX需要同时指定物品位置和属性位置，只能还原指定属性的升级值，而ClearStoneUpgrade是一次性清除整件装备的全部宝石升级属性。

三条命令的选择逻辑：只需清除宝石升级的星星和加成用ClearStoneUpgrade，需要清除通过脚本添加的自定义属性用DELATTLIST，需要把装备完全还原到初始状态用UPGRADEITEMEX参数5=2。

## 带条件限制的清除脚本

直接让玩家无条件清除宝石升级属性，在多数版本中不合适。通常需要配合金币消耗、道具消耗或等级限制来使用。

以下是消耗金币清除武器宝石升级属性的完整NPC脚本：

```
[@武器清除]
#IF
CHECKGAMEGOLD > 49999
#ACT
GAMEGOLD - 50000
ClearStoneUpgrade 1
SENDMSG 6 武器宝石升级属性已清除，消耗50000元宝。
#ELSESAY
元宝不足50000，无法执行清除操作。
```

配合清零石道具使用的写法：

```
[@清除武器]
#IF
CHECKITEM 属性清零石 1
#ACT
TAKE 属性清零石 1
ClearStoneUpgrade 1
SENDMSG 6 武器宝石升级属性已清除，消耗属性清零石1枚。
#ELSESAY
你没有属性清零石，无法执行清除操作。
```

CHECKITEM检测背包中是否有指定道具，TAKE扣除道具后再执行清除。两个命令之间没有先后顺序限制，但先扣道具再清除更安全，防止清除执行后扣道具失败导致玩家白嫖。

## 清除前检测升级次数

部分版本需要先检测装备是否已经通过宝石升级过，没有升级次数的装备执行清除没有意义，还会浪费玩家消耗的道具。用CheckItemupgradeCount命令检测升级次数。

格式为CheckItemupgradeCount 方式(0,1) 位置(0-12) 操作符(> = <) 次数(0-255)。方式=0时检测正在升级的装备，方式=1时检测人物身上的装备。位置参数与装备栏位对应。

完整写法：

```
[@清除检测]
#IF
CHECKITEM 属性清零石 1
CheckItemupgradeCount 1 1 > 0
#ACT
TAKE 属性清零石 1
ClearStoneUpgrade 1
SENDMSG 6 武器宝石升级属性已清除。
#ELSESAY
你没有清零石，或者武器没有宝石升级属性。
```

CheckItemupgradeCount 1 1 > 0 检测人物身上武器栏的装备升级次数是否大于0，只有在升级过的情况下才执行清除，避免玩家对未升级装备浪费道具。

## 检测指定装备名称后再清除

CheckUpgradeItemName命令用于检测正在通过宝石升级界面操作的装备名称，该命令只能在QFunction.txt的@ItemUpgrade触发段中执行。位置0检测升级装备的名字，位置1检测宝石格物品的名字。

结合清除操作的写法：

```
[@ItemUpgrade]
#IF
CheckUpgradeItemName 0 裁决之杖
#ACT
ClearStoneUpgrade 1
SENDMSG 6 裁决之杖的宝石升级属性已清除。
#ELSESAY
只能清除裁决之杖的宝石升级属性。
```

这个写法与直接在NPC对话中调用ClearStoneUpgrade的区别在于触发时机。@ItemUpgrade在玩家打开宝石升级界面并放入装备时触发，此时已经指定了要操作的装备。而NPC对话中的清除操作需要玩家先选择清除哪件装备，再执行命令。

两种场景可以并存。宝石升级界面中通过CheckUpgradeItemName限制可升级装备名称，NPC处通过位置参数直接指定清除哪件装备。两者使用的是同一个ClearStoneUpgrade命令，只是触发入口不同。

## 装备升级失败后属性清零的机制

宝石升级本身就有失败后清零属性的机制，与手动调用ClearStoneUpgrade是两个层面的操作。这个机制由宝石DB中的Need字段控制。

打开StdItems.DB找到升级宝石的记录，Need字段的取值决定升级失败后的结果。Need等于1到100时，升级失败后把装备副加属性全部清零。Need等于101到200时，升级失败后装备消失。Need等于201到300时，升级失败后装备当前属性不变。

如果版本中设置了Need=1到100，玩家使用该宝石升级失败后，装备上的宝石升级属性会自动清零，效果等同于执行了一次ClearStoneUpgrade。这个机制是自动的，不需要脚本触发。手动清除与自动清零的区别在于：手动清除是玩家主动操作，可选择保留或清除；自动清零是升级失败的惩罚，玩家无法控制。

宝石的NeedLevel字段控制升级范围限制，等于0时不限制，设定为低限乘以65535加上限时可以限制该宝石只能用于升级特定强化等级的装备。例如NeedLevel=5*65535+10表示该宝石只允许升级+5到+10之间的装备。

## 多命令联动的装备还原脚本

需要同时清除宝石升级属性和其他附加属性时，把多条命令组合使用。以下脚本把装备的宝石升级属性、自定义属性组和鉴定属性一并清除：

```
[@完全还原]
#IF
CHECKITEM 还原石 1
#ACT
TAKE 还原石 1
ClearStoneUpgrade 1
DELATTLIST
UPGRADEITEMEX 1 0 0 0 2
SENDMSG 6 武器已完全还原到初始状态。
#ELSESAY
你没有还原石，无法执行还原操作。
```

执行顺序影响最终结果。ClearStoneUpgrade先清除宝石升级的星星和属性，DELATTLIST清除通过ADDATTLIST添加的自定义属性组，UPGRADEITEMEX参数5=2最后把装备属性强制还原到DB数据库中的初始值。先清自定义属性和宝石升级属性，再做完全还原，可以确保所有升级痕迹都被清除。

如果只需要还原宝石升级属性，保留鉴定属性和元素属性，脚本中只写ClearStoneUpgrade和UPGRADEITEMEX两条即可，去掉DELATTLIST。

## 引擎兼容性与报错排查

ClearStoneUpgrade在GOM引擎、996引擎、LegendM2、BLUE引擎等主流引擎中均有支持，命令名称和格式一致。996引擎官方论坛中有用户反馈脚本写法与引擎手册一致但M2仍然报错，这类情况通常与脚本文件编码或命令加载顺序有关。

排查步骤如下。先确认脚本文件保存为ANSI编码，UTF-8编码下虽然英文命令本身不受影响，但如果脚本中夹杂了中文字符串，乱码可能导致整段脚本解析失败。检查ClearStoneUpgrade所在脚本是否在正确的文件中，NPC对话脚本放在Market_Def目录下，QFunction触发脚本放在Envir根目录下。确认M2Server中是否开启了宝石升级相关功能，部分引擎需要在M2选项的功能设置中启用宝石升级系统才能让清除命令生效。修改脚本后重启M2Server，或在控制台执行@ReloadManage重新加载QManage.txt。

如果执行清除命令后装备没有任何变化，先确认该装备是否确实通过宝石升级系统升级过。从未使用过升级宝石的装备执行ClearStoneUpgrade不会有任何反应，这是正常行为。通过CheckItemupgradeCount 1 位置 > 0检测升级次数是否大于0，可以判断装备是否具有可清除的宝石升级属性。

ClearStoneUpgrade只对通过宝石升级系统（StdMode=55、56、57、58、59的升级宝石）产生的属性有效。通过UPGRADEITEMEX直接升级出来的属性不被ClearStoneUpgrade清除，需要用UPGRADEITEMEX参数5=2来还原。排查时打开StdItems.DB确认升级时使用的宝石类型，判断应该使用哪条命令来清除属性。