QFunction-0.txt

文件作用

QFunction-0.txt 是常规功能回调脚本文件。

当前项目中，这个文件位于：

Mir200\Envir\Market_Def\QFunction-0.txt

它和 MerChant.txt、QManage.txt、QMapEvent-0.txt 不同，不是单一来源的脚本页，而是很多系统功能回调最终会落到这里执行。

如果某个功能已经触发，但后续脚本没有继续执行，或者某个系统入口本来就应该走功能回调，通常都要优先检查这里。

常见回调判定

使用这一节时，不需要先把所有回调参数都记下来。

写脚本或排查问题时，先看每类回调里最常用于分支判断的几个字段即可。

`[@DroppingItem]`

常见返回数据：

<$PARAM(0)>：类型，=1000 表示死亡掉落背包物品、0~16 为死亡掉落身上装备位置、=2000 表示手动丢掉
<$PARAM(1)>：物品名称
<$PARAM(4)>：掉落地图
<$PARAM(5)>、<$PARAM(6)>：掉落坐标

优先看：<$PARAM(0)>

它最常用于区分“死亡掉落”和“主动丢物”。

`[@PickupItem]`

常见返回数据：

<$PARAM(0)>：类型，=0 表示背包掉落，!=0 表示非背包掉落，=2 表示挖取
<$PARAM(1)>：物品名称
<$PARAM(4)>：拾取地图
<$PARAM(5)>、<$PARAM(6)>：拾取坐标

优先看：<$PARAM(0)>

它最常用于区分“捡回自己掉的物品”和“拾取地图掉落物”。

`[@MonDropItemDown]`

怪物掉落提示物品时触发。

这里的“提示物品”指 HintItemList.txt 中已存在的物品（该名单与物品表 RareItem=1 字段配合生效）；相关效果通常还要求客户端同时更新到支持该提示的版本。

常见返回数据：

<$PARAM(0)>：是否手动丢弃，0/1
<$PARAM(1)>：物品名
<$PARAM(2)>：物品 Looks
<$PARAM(3)>：掉落者名称
<$PARAM(4)>：地图名
<$PARAM(5)>、<$PARAM(6)>：掉落坐标
<$PARAM(7)>：物品 ID
<$PARAM(8)>：掉落者 Race，常见值为 1 人物、60 英雄

优先看：<$PARAM(1)>、<$PARAM(3)>、<$PARAM(4)>

这类回调最常见的用途，是在地图里广播“谁掉了什么物品”，或者按物品名进一步分流到不同提示逻辑。

最小示例：

[@MonDropItemDown]
#ACT
SendScrollMsg <$PARAM(4)>的<$PARAM(3)>掉落：<$PARAM(1)> 151 16

`[@DealingGoods]`

常见返回数据：

<$PARAM(0)>：类型，0 表示购买物品，1 表示出售物品
<$PARAM(1)>：物品名
<$PARAM(8)>：价格
<$PARAM(9)>：NPC 商店名称

优先看：<$PARAM(0)>

它最常用于区分买入和卖出。

`[@StorageItem]`

常见返回数据：

<$PARAM(0)>：类型，0 表示存入，1 表示取出
<$PARAM(1)>：物品名
<$PARAM(4)>：地图名
<$PARAM(7)>：物品 ID

优先看：<$PARAM(0)>

它最常用于区分存仓和取仓。

`[@MagSelfFunc数字]`

这是释放魔法专用回调的一部分，常与 [@MagTagFunc数字] 成对出现。

这组回调默认不会生效。使用前需要先在 !Setup.txt 中开启 CanUseMagSelfFunc=1。它和 [@Attack]、[@UnderAttack] 不是同一类入口。即使这里能触发，也不等于已经开启了常规攻击触发。

常见返回数据：

<$PARAM(0)>：0 表示触发的是玩家，1 表示触发的是英雄
<$PARAM(1)>：目标 X 坐标
<$PARAM(2)>：目标 Y 坐标
<$PARAM(3)>：施法者角色名

优先看：<$PARAM(0)>

这类回调常见用于按玩家或英雄主体分支处理技能逻辑。

补充理解：

[@MagSelfFunc数字] 通常在施法者侧触发。
[@MagTagFunc数字] 通常在目标侧触发。
[@MagTagFunc数字] 中，<$PARAM(1)> 和 <$PARAM(2)> 同样常用于读取目标坐标，<$PARAM(3)> 通常表示被攻击角色名。
这组编号里的“数字”通常对应技能 ID，例如技能 ID 为 13 时，常见写法是 [@MagSelfFunc13] 或 [@MagTagFunc13]。
MagicFire 这类主动释放魔法命令，虽然不走常规技能触发和攻击触发流程，但在开启 CanUseMagSelfFunc=1 的前提下，仍可能进入这组专用回调。

战斗相关回调

常见入口包括 [@Attack] 与 [@UnderAttack]。

使用这组回调前，需要先在 !setup.txt 中开启 AttackTrigger=1；如果总开关没有开启，即使 QFunction-0.txt 中已经写了 [@Attack] 或 [@UnderAttack]，相关逻辑通常也不会触发。

常见返回数据：

<$TARINFO_RACE>：目标 Race
<$TARINFO_ISHERO>：目标是否是英雄
<$TARINFO_NAME>：目标名称
<$ATTINFO_SKILLID>：这次攻击使用的技能 ID
<$ATTINFO_RACE>：攻击者 Race
<$ATTINFO_ISHERO>：攻击者是否是英雄
<$ATTINFO_NAME>：攻击者名称

优先看：<$ATTINFO_SKILLID>、<$ATTINFO_NAME>、<$TARINFO_NAME>

这两类回调不主要依赖 <$PARAM(0)>，而是更常用 TARINFO、ATTINFO 这一组上下文数据来判断攻击双方身份、种族和技能来源。

最小示例：

[@Attack]
#IF
COMPVAL <$TARINFO_FNAME> = 蜈蚣
#ACT
SENDMSG 7 你正在攻击<$TARINFO_NAME>

这段写法用于说明：[@Attack] 中更适合先看 TARINFO，因为这里最常判断的是“当前打到的目标是谁”。

[@UnderAttack]
#IF
COMPVAL <$ATTINFO_FNAME> = 蜈蚣
#ACT
SENDMSG 7 <$ATTINFO_NAME>正在攻击你

这段写法用于说明：[@UnderAttack] 中更适合先看 ATTINFO，因为这里最常判断的是“是谁正在打你或打你的随从”。

补充理解：

FNAME 更适合按基础怪物名或基础对象名判断，常用于区分同类对象
NAME 更适合按当前实际显示名称判断，常用于提示文本或区分改名后的具体对象

两个入口的完整变量表（攻击者、目标、通用目标变量）与脚本示例见攻击触发 @Attack / @UnderAttack。

聚灵珠相关回调

常见入口包括 [@OnUseExpBall] 与 [@OnHeroUseExpBall]。

常见返回数据：

<$PARAM(0)>：物品名
<$PARAM(1)>：价格
<$PARAM(2)>：价格类型，常见值为 0-4

优先看：<$PARAM(0)>

这类回调最常见的写法，是先按 <$PARAM(0)> 判断用了哪个聚灵珠，再按 <$PARAM(1)>、<$PARAM(2)> 处理价格或货币类型。

行会相关回调

常见入口包括：

[@BuildGuild]
[@JoinGuild]
[@LeaveGuild]
[@KickOutOfGuild]
[@DismissGuild]

这组回调最常见的返回数据非常统一：

<$PARAM(0)>：行会名

优先看：<$PARAM(0)>

如果脚本里需要区分当前处理的是哪个行会，通常直接看 <$PARAM(0)> 就够了。

组队与上下线相关回调

常见入口包括：

[@JoinGroup]
[@LeaveGroup]
[@HeroLogin]
[@KickDoubleConnect]
[@OnLogout_SoftClosing]
[@OnLogout_OffLinePlaying]
[@PlayDie]

这组回调在当前已整理资料里，大多没有像商店、仓库那样固定的一组 <$PARAM(n)> 说明。

这类脚本更常见的写法，是直接根据当前触发场景去处理，例如：

玩家是否是被顶号下线
当前是小退还是大退
当前是否是英雄上线
当前是否发生了死亡或离队

优先看：当前触发场景本身

如果后续项目里需要对这组入口做更细的条件判断，再按具体玩法补充即可。

`[@HeroDie]`

英雄死亡触发。

常见返回数据：

<$PARAM(0)>：主人角色名
<$PARAM(1)>：英雄角色名
<$PARAM(2)>：地图名
<$PARAM(3)>、<$PARAM(4)>：坐标

优先看：<$PARAM(0)>、<$PARAM(2)>

这类回调最常见的用途，是在英雄死亡时按主人、地图和坐标做联动处理。

属性回调

常见入口包括 [@SETABILITY_数字] 与 [@RESETABILITY_数字]。

常见返回数据：

<$PARAM(0)>：0 表示触发的是玩家，1 表示触发的是英雄

优先看：<$PARAM(0)>

这类回调最常见的分支点，就是判断这次属性变化对应的是人物还是英雄。

`[@OnItemDamageRevive]`

常见返回数据：

<$PARAM(0)>：装备位置
<$PARAM(1)>：装备名称
<$PARAM(3)>：角色名
<$PARAM(4)>：地图名
<$PARAM(5)>、<$PARAM(6)>：坐标
<$PARAM(8)>：1/60，1 表示人物，60 表示英雄
<$PARAM(9)>：剩余持久，0 表示装备失效或被销毁

优先看：<$PARAM(8)>、<$PARAM(9)>

如果脚本里要区分“人物复活”还是“英雄复活”，或者要判断装备是否已经损坏，通常优先看这两个值。

`[@RELEASECOLLECTEXP]`

释放天地结晶里的经验触发。玩家在天地结晶界面点击提取时进入本段，常见写法是用 QUERYVALUE 提交一次确认，再由确认标签扣费并发放经验。

[@RELEASECOLLECTEXP]
#ACT
QUERYVALUE 2 2 10 @EXPNOW
你的天地结晶已经储存了<$COLLECTEXP>经验和<$COLLECTIPEXP>内功经验，你可以支付<$GCEPAYMENT>元宝\
提取其中的<$GAINCOLLECTEXP>经验和<$GAINCOLLECTIPEXP>内功经验

[@EXPNOW]
#IF
CHECKGAMEGOLD ? $GCEPAYMENT
#ACT
GAMEGOLD - $GCEPAYMENT
CHANGEEXP + $GAINCOLLECTEXP
CHANGEIPEXP + $GAINCOLLECTIPEXP
ResetCollectExpState

关键点：

<$GCEPAYMENT> 是提取需要支付的元宝数，<$COLLECTEXP>、<$COLLECTIPEXP> 是结晶中已储存的经验。
<$GAINCOLLECTEXP>、<$GAINCOLLECTIPEXP> 是本次能提取的经验。
发放经验后必须接恢复天地结晶初始状态，否则同一批经验会被重复提取。
地图侧参数见天地结晶地图参数。

物品双击回调

对应标签为 [@StdModeFunc<AniCount>]。

[@StdModeFunc<AniCount>] 是物品专用双击触发入口。

这里的 AniCount，就是物品数据库 Items 表中的 AniCount 字段值。

常见理解方式可以直接写成下面这样：

物品配置为专用双击类型后
玩家双击这个物品时
引擎会到 QFunction-0.txt 中查找对应的 [@StdModeFunc数字]

最常见的基础写法是：

物品表里把 StdMode 设为 31
物品表里把 AniCount 设为某个编号，例如 123
在 QFunction-0.txt 中编写 [@StdModeFunc123]

例如：

Name=记忆石
StdMode=31
AniCount=123

[@StdModeFunc123]
#ACT
SendMsg 5 "你双击使用了记忆石。"

这类触发最适合放下面几种功能：

记忆石、宝箱、烟花之类的双击道具
捆装物品、卷类道具的专用使用逻辑
双击后扣费、发奖、开箱或切换状态的功能道具

宝石镶嵌回调

宝石镶嵌系统在 !Setup.txt 中开启回调开关后，会在打孔、镶嵌、拆卸三个阶段触发 QFunction 回调。三个开关与三个标签的对应关系如下：

开关参数（!Setup.txt）	回调标签	说明
`CreateEquipSocketScriptCallback`	`[@ONCREATINGEQUIPSOCKET]`	打孔时触发，`<$PARAM(1)>` 为装备名
`InlayGemStoneScriptCallback`	`[@ONINLAYINGGEMSTONE]`	镶嵌时触发，`<$PARAM(1)>` 装备名、`<$PARAM(2)>` 宝石名、`<$PARAM(3)>` 宝石类型、`<$PARAM(4)>` 宝石等级
`DisassembleGemStoneScriptCallback`	`[@ONDISASSEMBLINGGEMSTONE]`	拆卸时触发，参数同镶嵌

打孔成功后另有 [@CREATEEQUIPSOCKETOK]，<$PARAM(0)> 为第几孔、<$PARAM(1)> 为装备名。

回调脚本中的写法要点：

使用 APPROVE 设置执行结果；判定失败时需在 $CALCRESULT 中写入失败原因。
回调脚本中禁用任何带 HARDDISK 的 NPC 命令。
全身宝石等级可用 <$GEMSTONELEVEL>、<$H.GEMSTONELEVEL> 读取，见常用变量与变量标签。
界面入口见打开宝石镶嵌界面，开关默认值与说明见 !setup.txt。

[@ONINLAYINGGEMSTONE]
#IF
#ACT
SENDMSG 5 正在为 <$PARAM(1)> 镶嵌 <$PARAM(2)>（类型 <$PARAM(3)>，等级 <$PARAM(4)>）
APPROVE

双击编号扩展规则

这里讨论的仍然是 [@StdModeFunc<AniCount>] 这组标签的扩展编号写法。

StdMode=31 的双击物品不只支持 AniCount 直接映射。

当配置需要超过 255 的编号时，常见扩展写法是：

XX = Reserved * 256 + AniCount

注意：`AniCount` 必须大于 3；`Reserved>0` 时才会计算以上公式（`AniCount` 必须是 4~255 之间）。

也就是说，实际触发的标签编号可以大于 255。

例如：

AniCount=140
Reserved=255
实际触发 [@StdModeFunc65420]

这一层更适合用于扩展双击道具或做更细的分类控制。

常见排查思路

如果 QFunction-0.txt 相关逻辑不生效，可优先按下面顺序检查：

触发来源是否真的成立，例如 QMapEvent-0.txt、物品双击、技能触发或商店触发
QFunction-0.txt 中是否真的存在对应标签
标签编号是否和配置一致，例如 AniCount=123 对应 [@StdModeFunc123]
脚本是否被前面的条件判断、BREAK 或其他分支提前截断
如果是双击物品，是否把 StdMode、AniCount、Reserved 写对