pandas_events.txt

//===== Pandas Documentation =================================
//= 事件标签说明文档
//===== By: ==================================================
//= 熊猫模拟器开发团队
//===== Current Version: =====================================
//= 1.1
//===== Description: =========================================
//= 此文档对熊猫模拟器添加的自定义事件标签进行了说明, 包括这些
//= 事件的触发时机、关联玩家、可能的返回参数等.
//============================================================

事件名称约定:
	On[事件关联到的对象][事件名称][事件类型]

事件关联到的对象:
	是指到时候事件被触发时脚本会关联到哪个对象上执行:
	- PC		表示玩家(最常见)

事件名称:
	只事件的名字, 通常只是起到区分作用

事件类型:
	- Event		常规事件, 阻塞将进入事件队列, 不可打断
	- Filter	过滤事件, 立即执行, 可被打断
	- Express	实时事件, 立即执行, 不可打断

//============================================================
// 改进 rAthena 官方事件
//============================================================

*OnPCStatCalcEvent:

当角色能力被重新计算时触发事件, 例如: 变更角色的六维素质点, 穿戴或脱下装备,
改变角色当前所在地图, 登入游戏, 基础或职业等级变化等等.

常规用法:
	可以在这个事件的触发代码中, 编写一些装备常用的脚本.
	例如: 当基础等级被 10 整除的时候, 六维属性全部增加当前等级 / 10 的整数
	
	if (BaseLevel % 10 == 0) {
		bonus bAllStats, BaseLevel / 10;
	}

实时事件:
	此事件在熊猫模拟器中被改造成了"实时事件",
	实时事件的执行不会被放入事件队列, 只要被触发都能被立刻执行.

	部分特殊的脚本指令, 不能在实时事件的处理脚本中运行:
	mes, next, close, close2, menu, select, prompt, input,
	openstorage, guildopenstorage, produce, cooking, birthpet,
	callshop, sleep, sleep2, openmail, openauction, progressbar,
	buyingstore, makerune, opendressroom, openstorage2
	
	若您知道可能潜在的副作用且坚持需要使用上述任何一个指令,
	可以使用 'unlockcmd' 脚本指令来解锁限制.

--------------------------------------------------------------

*OnSellItem:

当某个 NPC 使用 callshop 指令打开商店, 且玩家在商店里面出售自己的道具时, 
此 NPC 的 OnSellItem 标签(存在时)将会被触发.

携带参数:
	除了 rAthena 自带的参数外, Pandas 拓展了以下数组:
	@sold_idx[]		用于保存被出售的物品在玩家身上的背包序号

注意事项:
	- 此事件为 rAthena 官方事件, 具体用法请参考 doc/script_commands.txt



//============================================================
// 常规事件 (AKA: 普通事件)
//============================================================
// 执行常规事件的时候若当前玩家正在与 NPC 对话,
// 那么本次事件将会压入事件队列暂缓执行,
// 直到玩家与 NPC 的对话完结之后才会挨个顺序触发.
//
// 整个 rAthena 官方自带的事件都属于这一类. 事件队列容量有限,
// 若队列满了那么后来的事件将被抛弃.
//============================================================

*OnPCIdentifyEvent:

当玩家成功鉴定了装备时触发事件

事件关联:
	关联到发起鉴定的玩家

中断关联:
	若玩家鉴定装备时在 OnPCIdentifyFilter 事件中使用了 processhalt
	指令打断了后续流程, 那么此事件将不会被触发.

携带参数:
	@identify_idx	已被玩家成功鉴定的道具背包序号

--------------------------------------------------------------

*OnPCInsertCardEvent:

当玩家成功插入卡片后触发事件

事件关联:
	关联到刚刚完成插卡的玩家

携带参数:
	@insert_equip_idx	刚刚成功插卡的装备背包序号
	@insert_card_idx	刚刚被插卡消耗掉的卡片背包序号 (注意: 此时的卡片已被删除)
	@insert_card_id		刚刚被插入的卡片物品编号
	@insert_card_slot	刚刚被插入卡片的卡槽编号 ( 0 - 第一个卡槽; 3 - 第四个卡槽 )

注意事项:
	此事件只有成功完成插卡后才会被触发, 插卡失败是不会触发的
	不过插卡失败的情况一般几乎不可能发生, 可以安心使用
	
	@insert_card_idx 参数指向的背包序号在极端情况下将不可信

--------------------------------------------------------------

*OnPCUseItemEvent:

当玩家成功使用非装备类道具后触发事件

事件关联:
	关联到成功使用了道具的玩家

携带参数:
	@useitem_idx	刚刚被使用的道具背包序号 (注意: 此时的道具可能已被消耗)
	@useitem_nameid	刚刚被使用的道具编号

注意事项:
	@useitem_idx 参数指向的背包序号在极端情况下将不可信
	本事件与 rAthenaCN 老版本的同名事件含义不同, 请脚本编写人员留意

--------------------------------------------------------------

*OnPCUseSkillEvent:

当玩家成功使用技能后触发事件 (技能需成功咏唱完毕)

事件关联:
	关联到成功使用了技能的玩家

携带参数:
	@useskill_id			刚刚施放的技能编号
	@useskill_lv			刚刚施放的技能等级
	@useskill_target_gid	被施法目标的 GameID, 若为 0 则表示这是个地面技能
	@useskill_pos_x			刚刚被施法的地面 X 坐标
	@useskill_pos_y			刚刚被施法的地面 Y 坐标

注意事项:
	模拟器内部的技能实现流程比较长, 手动测试无法覆盖全部分支.
	若您发现自己关心的某个技能使用后该事件没被触发的话,
	可以前往 https://github.com/PandasWS/Pandas 提交 Issue 进行反馈.

修订记录:
	v1.1.2	- 技能需要咏唱完毕才会触发此事件

--------------------------------------------------------------

*OnPCKillMvpEvent:

当玩家杀死 MVP 魔物后触发事件

事件关联:
	关联到给予 MVP 魔物最后一击的玩家

携带参数:
	killedrid			被杀魔物的类型编号 (魔物编号)
	killedgid			被杀魔物的游戏单位编号 (GameID)
	
	@mob_dead_x			魔物死亡时所处的 X 坐标
	@mob_dead_y			魔物死亡时所处的 Y 坐标
	@mob_lasthit_rid	给予魔物最后一击的角色的游戏单位编号 (GameID)
	@mob_lasthit_cid	给予魔物最后一击的角色编号
	@mob_mvp_rid		本次 MVP 角色的游戏单位编号 (GameID)
	@mob_mvp_cid		本次 MVP 角色的角色编号

修订记录:
	v1.1.1	- 增加 killedgid 携带参数

--------------------------------------------------------------

*OnPCEquipEvent:

当玩家成功穿戴一件装备时触发事件
当玩家执行"装备切换"将"待用装备"转正为"生效装备"成功后也会触发事件

事件关联:
	关联到穿戴装备的玩家

携带参数:
	@equip_idx		玩家穿戴的装备背包序号
	@equip_swapping	本次穿戴是否由于"装备切换"而触发的

装备切换:
	新的仙境传说客户端支持"装备切换"机制,
	此时如果单独将装备拖动到装备面板的"待切换装备"窗口中进行登记,
	不会触发此事件 (因为此时装备并未实际穿戴).

--------------------------------------------------------------

*OnPCUnequipEvent:

当玩家成功脱下一件装备时触发事件
用一个新装备去替换位置相同且已穿戴的"生效装备", 导致它被成功脱下时也会触发过滤器

事件关联:
	关联到脱下装备的玩家

携带参数:
	@unequip_idx		玩家成功脱下的装备背包序号
	@unequip_swapping	本次脱下是否由于"装备切换"而触发的
	@unequip_force		本次脱下是否由某个需要强制脱下的内部逻辑产生的

装备切换:
	新的仙境传说客户端支持"装备切换"机制,
	此时如果单独将装备从到装备面板的"待用装备"窗口中拖离移除,
	不会触发此过滤器 (因为此时装备并未实际脱下).

强制脱下说明:
	- 角色转职的时候, 若穿戴的装备已经不符合新职业的要求, 那么装备将被强制脱下.
	- 当精炼道具时, 已经装备就会被强制脱下, 以便进行精炼.
	- @dropall @storeall @changesex @changecharsex @fullstrip 等指令也会触发装备的强制脱下.

注意事项:
	当 @unequip_swapping 为 1 时, "生效装备"实际上只是和"待用装备"
	进行了交换, 并未直接脱下到背包中.

	替换位置相同的"生效装备"时, 参数 @unequip_swapping 的值为 0.

千万注意:
	当程序内部逻辑需要强制脱下某件装备时, @unequip_force 将为 1,
	当它为 1 的时候请不要使用 processhalt 打断后续流程, 或删除即将被操作的装备.
	因为这可能引发各种奇怪的问题.
	
	比如: 当替换装备的时候相同位置的老装备应该被强制脱下, 
	如果此时打断后续流程, 那么新穿戴的装备虽然可以成功穿戴,
	但是老的装备的"脱下脚本"就不会被触发.



//============================================================
// 熊猫模拟器 - 过滤事件 (过滤器事件)
//============================================================
// 过滤事件通常在服务器一些关键的节点触发,
// 可以用 processhalt 脚本指令打断, 打断后将影响后续工作流.
// 
// 从 v1.1.1 版本开始:
// ---------------------------------------
// 过滤事件一旦触发会被立刻执行! 哪怕玩家正在和 NPC 对话,
// 也不会被压入事件队列暂缓执行.
// 
// 过滤事件默认禁止使用[需要等待玩家进行后续动作]的指令:
// mes, next, close, close2, menu, select, prompt, input,
// openstorage, guildopenstorage, produce, cooking, birthpet,
// callshop, sleep, sleep2, openmail, openauction, progressbar,
// buyingstore, makerune, opendressroom, openstorage2
//
// 若您知道可能潜在的副作用且坚持需要使用上述任何一个指令,
// 可以使用 'unlockcmd' 脚本指令来解锁限制.
// 
// 任何过滤事件触发时都将自动携带 @interrupt_npcid 参数,
// 作者可以通过 @interrupt_npcid 参数来获取当前过滤事件触发时
// 玩家正在与哪个 NPC 对话 (游戏单位编号).
// 值为 0 表示没有打断玩家, 那你可以随意使用 mes 等指令.
//============================================================

*OnPCIdentifyFilter:

当玩家在装备鉴定列表中选择好装备, 并点击"确定"按钮时触发过滤器

事件关联:
	关联到发起鉴定的玩家

中断说明: 
	中断后会无视玩家本次鉴定道具的请求, 系统不再鉴定此装备

携带参数:
	@identify_idx	被玩家选择进行鉴定的道具背包序号

--------------------------------------------------------------

*OnPCInChatroomFilter:

当玩家双击进入 NPC 开启的聊天室时将触发过滤器

事件关联:
	关联到进入聊天室的玩家

中断关联:
	中断后客户端将不会打开聊天室窗口
	
注意事项:
	只会触发建立聊天室的 NPC 名下的过滤器事件,
	其他 NPC 使用的 OnPCInChatroomFilter 过滤器不会被触发
	
	此外需要注意的是 rAthena 自带的 waitingroom 指令有一个 "<event label>" 事件,
	当聊天室中的成员数量足够时就会被触发. 若您在本过滤器中使用 processhalt
	指令打断了后续流程, 那么 waitingroom 的事件将不会被触发.

--------------------------------------------------------------

*OnPCInsertCardFilter:

当玩家准备插入卡片时触发过滤器

事件关联:
	关联到准备插卡的玩家

中断关联:
	中断后服务端会无视玩家本次插入卡片的操作

携带参数:
	@insert_equip_idx	即将被插卡的装备背包序号
	@insert_card_idx	即将被插入的卡片背包序号
	@insert_card_id		即将被插入的卡片物品编号
	@insert_card_slot	即将被插入卡片的卡槽编号 ( 0 - 第一个卡槽; 3 - 第四个卡槽 )

--------------------------------------------------------------

*OnPCUseItemFilter:

当玩家准备使用非装备类道具时触发过滤器

事件关联:
	关联到准备使用道具的玩家

中断关联:
	中断后服务端会无视玩家本次使用道具的操作

携带参数:
	@useitem_idx	即将被使用的道具背包序号
	@useitem_nameid	即将被使用的道具编号

--------------------------------------------------------------

*OnPCUseSkillFilter:

当玩家准备使用技能时触发过滤器

事件关联:
	关联到准备使用技能的玩家

中断说明:
	中断后服务端会无视玩家本次使用技能的请求

携带参数:
	@useskill_id			即将施放的技能编号
	@useskill_lv			即将施放的技能等级
	@useskill_target_gid	被施法目标的 GameID, 若为 0 则表示这是个地面技能
	@useskill_pos_x			即将被施法的地面 X 坐标
	@useskill_pos_y			即将被施法的地面 Y 坐标

注意事项:
	为了方便利用事件实现一些技能, 本过滤器的触发时机非常早,
	就算玩家被 setpcblock 设置为禁用技能, 此过滤器也能够被触发.
	
	此过滤器触发时, 技能咏唱及施法条件判断、材料扣除等尚未发生.

--------------------------------------------------------------

*OnPCOpenRouletteFilter:

当玩家准备打开乐透大转盘的时候触发过滤器

事件关联:
	关联到准备打开乐透大转盘的玩家

中断说明:
	中断后服务端会无视本次打开乐透大转盘的请求

注意事项:
	该过滤器的触发必须依赖一些条件, 若条件不匹配则不会被触发:
	- 客户端必须是 2014-10-22 或更新的版本
	- 若当前正在与 NPC 进行对话, 那么此过滤器将不会被触发
	
	为了进一步优化体验, Pandas 对大乐透按钮的点击逻辑进行了调整:
	正在和 NPC 对话时将禁止点击大乐透按钮按钮 (与 rAthena 有所不同)

--------------------------------------------------------------

*OnPCViewEquipFilter:

当玩家准备查看某个角色的装备时触发过滤器

事件关联:
	关联到发起查看请求的玩家

中断说明:
	中断后服务端会无视本次查看他人装备的请求

携带参数:
	@view_equip_target_name$	被查看角色的角色名
	@view_equip_target_cid		被查看角色的角色编号
	@view_equip_target_aid		被查看角色的账号编号

注意事项:
	- 使用 viewequip 脚本指令也会触发此过滤器
	- 必须是对方角色公开装备且查看者也有权查看的情况下, 才会触发此过滤器

--------------------------------------------------------------

*OnPCEquipFilter:

当玩家准备穿戴装备时触发过滤器
当玩家执行"装备切换"将"待用装备"转正为"生效装备"时也会触发过滤器

事件关联:
	关联到即将穿戴装备的玩家

中断说明:
	中断后服务端会无视玩家本次穿戴操作
	若 @equip_swapping 为 1 时, 使用 processhalt 是无效的

携带参数:
	@equip_idx		玩家即将穿戴的装备背包序号
	@equip_swapping	本次穿戴是否由于"装备切换"而触发的

装备切换:
	新的仙境传说客户端支持"装备切换"机制,
	此时如果单独将装备拖动到装备面板的"待用装备"窗口中进行登记,
	不会触发此过滤器 (因为此时装备并未实际穿戴).

注意事项:
	若玩家身上已穿戴一件相同位置的装备,
	那么过滤器被触发时用 processhalt 打断了穿戴本装备的后续过程,
	角色身上的原穿戴的装备也不会被脱下.

	当玩家穿戴一件未被绑定的装备, 并在客户端中确认执行绑定后,
	在过滤器中用 processhalt 打断后续过程, 装备也将维持最初的未绑定状态.

	执行该过滤器时, 装备实际上还未穿戴上, 因此在该事件的触发脚本中使用
	getinventoryinfo(@equip_idx, 2) 尝试获取该装备的穿戴位置时获取的值永为 0

--------------------------------------------------------------

*OnPCUnequipFilter:

当玩家准备脱下装备时触发过滤器
用一个新装备去替换位置相同且已穿戴的"生效装备"时也会触发过滤器

事件关联:
	关联到即将脱下装备的玩家

中断关联:
	中断后服务端会无视玩家本次脱下操作
	若 @unequip_swapping 为 1 时, 使用 processhalt 是无效的

携带参数:
	@unequip_idx		玩家即将脱下的装备背包序号
	@unequip_swapping	本次脱下是否由于"装备切换"而触发的
	@unequip_force		本次脱下是否由某个需要强制脱下的内部逻辑产生的

装备切换:
	新的仙境传说客户端支持"装备切换"机制,
	此时如果单独将装备从到装备面板的"待用装备"窗口中拖离移除,
	不会触发此过滤器 (因为此时装备并未实际脱下).

强制脱下说明:
	- 角色转职的时候, 若穿戴的装备已经不符合新职业的要求, 那么装备将被强制脱下.
	- 当精炼道具时, 已经装备就会被强制脱下, 以便进行精炼.
	- @dropall @storeall @changesex @changecharsex @fullstrip 等指令也会触发装备的强制脱下.

注意事项:
	当 @unequip_swapping 为 1 时, "生效装备"实际上只是和"待用装备"
	进行了交换, 并未直接脱下到背包中.

	替换位置相同的"生效装备"时, 参数 @unequip_swapping 的值为 0.

	执行该过滤器时, 装备实际上还未脱下, 因此在该事件的触发脚本中使用
	getinventoryinfo(@equip_idx, 2) 尝试获取该装备的穿戴位置时获取的值通常不是 0

千万注意:
	当程序内部逻辑需要强制脱下某件装备时, @unequip_force 将为 1,
	当它为 1 的时候请不要使用 processhalt 打断后续流程, 或删除即将被操作的装备.
	因为这可能引发各种奇怪的问题.
	
	比如: 当替换装备的时候相同位置的老装备应该被强制脱下, 
	如果此时打断后续流程, 那么新穿戴的装备虽然可以成功穿戴,
	但是老的装备的"脱下脚本"就不会被触发.

--------------------------------------------------------------

*OnPCChangeTitleFilter:

事件描述: 
	当玩家即将变更称号时将触发过滤器
	
事件关联:
	关联到称号变更的玩家

中断说明:
	中断后服务端会无视玩家本次修改称号的操作,
	也不会根据 @target_title_id 变量的值来设定玩家的称号
	
	鉴于 @target_title_id 是可被修改的
	所以你可以用直接修改 @target_title_id 的方式来篡改最终的称号ID
	但是要注意, 采用这种方法的话, 后面别跟 processhalt;

携带参数:
	@trigger_mode
		0 - 通过装备面板触发
		1 - 通过 setchartitle 脚本指令触发
		2 - 通过 @title 管理员指令触发

	@target_title_id	即将变更成的目标称号ID (该值可被修改)
	@pre_title_id	之前的称号ID是多少

注意事项:
	当 @trigger_mode 为 0 时, 若 @target_title_id 参数的值也为 0,
	则表示玩家双击了 "Title Release" (或翻译成"Disable Title")

兼容提醒:
	此过滤器的一些细节与 rAthenaCN v1.8.0 版本存在差异, 可能会有不兼容情况
	请酌情修改之前的老脚本, 以便使脚本可以正常工作.

	- 取消了事件别名: OnPCChangeTitleEvent
	- @new_title_id 改名为 @target_title_id (@new_title_id 将不再被赋值)

--------------------------------------------------------------

*OnPCBuffStartFilter:

事件描述: 
	当玩家即将获得一个状态(Buff)时触发过滤器
	
事件关联:
	关联到即将获得状态的玩家

中断说明:
	中断后服务端会无视玩家本次获得状态的请求

携带参数:
	@about2start_sc_id		该状态的编号
	@about2start_sc_rate	该状态的触发概率(10000 = 100%, 该值可被修改)
	@about2start_sc_tick	该状态的持续时长(单位为毫秒, 该值可被修改)
							时长根据内部实现方式的不同, 有可能是指多长时间后剩余秒数减一
	@about2start_sc_val1	该状态的第1个参数的值 (该值可被修改)
	@about2start_sc_val2	该状态的第2个参数的值 (该值可被修改)
	@about2start_sc_val3	该状态的第3个参数的值 (该值可被修改)
	@about2start_sc_val4	该状态的第4个参数的值 (该值可被修改)

注意事项:
	若 @about2start_sc_rate 或 @about2start_sc_tick 被改写成 0 则视为执行中断
	若 @about2start_sc_tick 设为 -1 则表示无限时长

--------------------------------------------------------------

*OnPCUseOCIdentifyFilter:

当玩家使用一键鉴定道具时触发过滤器.

事件关联:
	关联到执行一键鉴定的玩家

中断说明:
	中断后服务端会无视玩家本次进行一键鉴定的请求

携带参数:
	@identify_idx	被玩家选择进行鉴定的道具背包序号

注意事项:
	此过滤器在触发的时候并未确保 @identify_idx 背包序号所指向的道具 100% 存在并且有效,
	也并未检查背包中是否存在放大镜道具 (客户端会检测一次).
	因此请在必要的时候请自己进行额外判断.

--------------------------------------------------------------

*OnPCUseReviveTokenFilter

当玩家使用菜单中的原地复活之证时触发过滤器.

事件关联:
	关联到执行原地复活的玩家

中断说明:
	中断后服务端会无视玩家本次复活操作

--------------------------------------------------------------

*OnPCGuildCreateFilter:

当玩家准备创建公会时触发过滤器 [聽風]

事件关联:
	关联到准备创建公会的玩家

中断关联:
	中断后服务端会无视玩家本次创建公会的操作

携带参数:
	@create_guild_name$	要创建的公会名称

--------------------------------------------------------------

*OnPCGuildJoinFilter:

当玩家即将加入公会时触发过滤器 [聽風]

事件关联:
	关联加入公会的玩家

中断关联:
	中断后服务端会无视玩家本次加入公会的操作

携带参数:
	@join_guild_id		公会ID
	@join_guild_aid		邀请者的AID

--------------------------------------------------------------

*OnPCGuildLeaveFilter:

当玩家准备离开公会时触发过滤器 [聽風]

事件关联:
	自愿离开公会的关联到离开公会的玩家
	会长踢出公会的关联到会长

中断说明:
	中断后玩家离开公会失败

携带参数:
	@left_guild_id		公会ID
	@left_guild_name$	公会名称
	@left_guild_kick	是否是被会长踢出 (0 - 玩家自己退出公会; 1 - 被会长从公会驱逐)
	@left_guild_aid		离开公会玩家的账号编号

--------------------------------------------------------------

*OnPCPartyCreateFilter:

当玩家准备创建队伍时触发过滤器 [聽風]

事件关联:
	关联到准备创建队伍的玩家

中断关联:
	中断后服务端会无视玩家本次创建队伍的操作

携带参数:
	@create_party_name$	要创建的队伍名称

--------------------------------------------------------------

*OnPCPartyJoinFilter:

当玩家即将加入队伍时触发过滤器 [聽風]

事件关联:
	关联到即将加入队伍的玩家

中断关联:
	中断后服务端会无视玩家本次加入队伍的操作

携带参数:
	@join_party_id		队伍编号
	@join_party_aid		队长的账号编号

注意事项:
	仅在被邀请的玩家同意加入队伍时过滤器才会触发


--------------------------------------------------------------

*OnPCPartyLeaveFilter:

当玩家准备离开队伍时触发过滤器 [聽風]

事件关联:
	若是玩家自愿离开队伍的, 则关联到离开队伍的玩家
	若是被队长踢出队伍的, 则关联到队长

中断说明:
	中断后服务端会无视玩家本次离开队伍的请求

携带参数:
	@left_party_id		队伍编号
	@left_party_name$	队伍名称
	@left_party_kick	是否是被队长踢出 (0 - 自愿退出队伍; 1 - 被队长驱逐)
	@left_party_aid		即将离开队伍的角色所对应的账号编号

--------------------------------------------------------------

*OnPCDropItemFilter:

当玩家准备丢弃或掉落道具时触发过滤器 [人鱼姬的思念]

事件关联:
	关联到即将丢弃或掉落道具的玩家

中断说明:
	中断后服务端会无视本次掉落请求

携带参数:
	@drop_idx			丢弃或掉落道具的背包序号
	@drop_itemid		丢弃或掉落道具的物品编号
	@drop_amount		丢弃或掉落道具的数量

注意事项:
	玩家在 PVP 梦魇模式被击杀导致掉落装备时, 也会触发此过滤器.
	
	哪怕不中断此过滤器, 后续也会有其他判断条件可能会导致最终无法掉落此道具,
	例如: 玩家所在地图存在 nodrop 地图标记.


//============================================================
// 熊猫模拟器 - 实时事件
//============================================================
// 实时事件一旦触发会被立刻执行! 哪怕玩家正在和 NPC 对话,
// 也不会被压入事件队列暂缓执行.
// 
// 实时事件默认禁止使用[需要等待玩家进行后续动作]的指令:
// mes, next, close, close2, menu, select, prompt, input,
// openstorage, guildopenstorage, produce, cooking, birthpet,
// callshop, sleep, sleep2, openmail, openauction, progressbar,
// buyingstore, makerune, opendressroom, openstorage2
//
// 若您知道可能潜在的副作用且坚持需要使用上述任何一个指令,
// 可以使用 'unlockcmd' 脚本指令来解锁限制.
// 
// 任何实时事件触发时都将自动携带 @interrupt_npcid 参数,
// 作者可以通过 @interrupt_npcid 参数来获取当前实时事件触发时
// 玩家正在与哪个 NPC 对话 (游戏单位编号).
// 值为 0 表示没有打断玩家, 那你可以随意使用 mes 等指令.
//============================================================

*OnPCProgressAbortExpress:

当玩家的进度条被打断后触发实时事件

事件关联:
	关联到进度条被打断的玩家

携带参数:
	@abort_npc_id		被中断的进度条是哪个 NPC 编号提供的
	@abort_timeout		若进度条不被中断时走到 100% 的具体时间戳

注意事项:
	- 该事件默认不会触发, 您需要使用 settrigger 脚本指令设置一下
	- 关于 settrigger 脚本指令的用法请查阅 doc/pandas_script_commands.txt

修订记录:
	v1.1.1	- 从 OnPCProgressAbortEvent 改成 OnPCProgressAbortExpress
			- 增加 @abort_npc_id 和 @abort_timeout 携带参数

--------------------------------------------------------------

*OnPCBuffStartExpress:

事件描述:
	当玩家成功获得一个状态(Buff)后触发实时事件

事件关联:
	关联到获得状态的玩家

携带参数:
	@started_sc_id		该状态的编号
	@started_sc_rate	该状态的触发概率(10000 = 100%)
	@started_sc_tick	该状态的持续时长(单位为毫秒)
						时长根据内部实现方式的不同, 有可能是指多长时间后剩余秒数减一
	@started_sc_val1	该状态的第1个参数的值
	@started_sc_val2	该状态的第2个参数的值
	@started_sc_val3	该状态的第3个参数的值
	@started_sc_val4	该状态的第4个参数的值

注意事项:
	若 @started_sc_tick 为 -1 则表示该状态无限时长

--------------------------------------------------------------

*OnPCBuffEndExpress:

事件描述:
	当玩家成功解除一个状态(Buff)后触发实时事件

事件关联:
	关联到解除状态的玩家

携带参数:
	@ended_sc_id		该状态的编号

--------------------------------------------------------------

*OnPCEnterMapExpress:

事件描述:
	当玩家进入或者改变地图时触发实时事件

事件关联:
	关联到进入或者改变地图的玩家

携带参数:
	@frommap_id		来源地图编号, 为 0 则表示玩家刚登录
	@frommap_name$	来源地图的名称
	@frommap_x		来源地图的起飞 x 坐标
	@frommap_y		来源地图的起飞 y 坐标
	
	@tomap_id		目标地图编号
	@tomap_name$    目标地图的名称
	@tomap_x		目标地图的落地 x 坐标
	@tomap_y		目标地图的落地 y 坐标

注意事项:
	当 @frommap_id 为 0 时, @frommap_name$ 为空字符串

--------------------------------------------------------------

*OnUnitKillExpress:

事件描述:
	当某个单位被击杀时触发实时事件
	当前支持触发的单位类型有: 玩家\魔物\生命体\佣兵\元素精灵
	
	宠物和 NPC 不会被击杀死亡, 因此不会触发此事件.
	
	生命体被安息, 元素精灵超时自动销毁或被精灵控制技能解散,
	佣兵被解雇或逃跑都不是死亡, 因此不会触发此事件.

事件关联:
	不关联到任何玩家

携带参数:
	$@killed_gid		死亡单位的游戏单位编号
	$@killed_type		死亡单位的类型
	$@killed_classid	死亡单位的种类编号 (魔物编号\生命体编号等等)
	$@killed_mapid		死亡单位所在的地图编号
	$@killed_mapname$	死亡单位所在的地图名称
	$@killed_x			死亡单位所在的 X 坐标
	$@killed_y			死亡单位所在的 Y 坐标
	
	$@killer_gid		最后一击杀手单位的游戏单位编号 (若为 0 则表示被系统击杀)
	$@killer_type		最后一击杀手单位的类型 (若为 0 则表示被系统击杀)
	$@killer_classid	最后一击杀手单位的种类编号 (魔物编号\生命体编号等等)
	$@killer_mapid		最后一击杀手单位所在的地图编号
	$@killer_mapname$	最后一击杀手单位所在的地图名称
	$@killer_x			最后一击杀手单位所在的 X 坐标
	$@killer_y			最后一击杀手单位所在的 Y 坐标
	$@killer_skillid	最后一击使用的技能编号 (若为 0 则表示普通攻击)

系统击杀:
	是指通过 @killmonster 等指令将全地图魔物击杀时,
	魔物不是被另外一个单位通过攻击杀死, 这种死亡方式称之为被系统击杀.

提示信息:
	若单位是被某个玩家击杀的话, 您可以手动关联到杀手单位.

注意事项:
	由于此事件不关联到任何玩家,
	因此携带参数的变量都变成了 $@ 开头的地图服务器临时变量,
	而不是用 @ 开头的角色临时变量, 使用时要注意区分

--------------------------------------------------------------

*OnMobDropItemExpress:

当魔物即将掉落 db/item_properties.yml 中将 ExecuteMobDropExpress 标记
设置为 true 的道具时触发实时事件.

事件关联:
	不关联到任何玩家

携带参数:
	$@mobdrop_mobid			即将掉落道具的魔物编号
	$@mobdrop_itemid		即将掉落道具的编号
	$@mobdrop_rate			即将掉落道具在应用诸多修正后的最终掉率
	$@mobdrop_mapname$		掉落道具魔物所在的地图名称
	
	$@mobdrop_from			道具的详细掉落来源, 用于帮助脚本进行更详细的判断
	
							0 - 未知的掉落来源 (通常情况下不应该存在此情况)
							1 - 配置在 mob_db 中会掉落的普通道具
							2 - 魔物死亡掉落的矿石, 矿石掉率在 finding_ore_rate 战斗配置选项中指定
							3 - 使用 bonus 指定玩家击败魔物会掉落的道具 (如: bAddMonsterDropItem)
							4 - 之前魔物拾取的道具, 这类道具 100% 掉落 (比如波利吃掉的道具)
							5 - 配置在 mob_db 中会掉落的 MVP 奖励道具 (直接掉落到玩家背包)
							
	$@mobdrop_killerrid		给魔物最后一击的玩家游戏单位编号 (为 0 表示被系统击杀)
	$@mobdrop_belongrid		道具归属玩家的游戏单位编号 (为 0 表示无归属)
	$@mobdrop_bypass		是否跳过掉落此道具 (为 0 表示正常掉落, 为 1 表示不掉落)

系统击杀:
	是指通过 @killmonster 等指令将全地图魔物击杀时,
	魔物不是被另外一个单位通过攻击杀死, 这种死亡方式称之为被系统击杀.
	
提示信息:
	若想根据最后一击玩家的某些变量来判断是否掉落道具,
	可以在确认 $@mobdrop_killerrid 非 0 的情况下使用 attachrid 指令
	与 $@mobdrop_killerrid 的玩家进行手动关联.
	
注意事项:
	由于此事件不关联到任何玩家,
	因此携带参数的变量都变成了 $@ 开头的地图服务器临时变量,
	而不是用 @ 开头的角色临时变量, 使用时要注意区分

--------------------------------------------------------------

*OnPCAttackExpress:

当玩家发起攻击并即将进行结算时触发实时事件 [聽風]

事件关联:
	关联到触发攻击行为的玩家
	如果是宠物/生命体/佣兵/元素则直接关联到其主人

携带参数:
	@attack_src_type			攻击者的类型
	@attack_src_gid				攻击者的游戏单位编号 (若是玩家则返回账号编号)

	@attack_target_type			被攻击者的类型
	@attack_target_gid			被攻击者的游戏单位编号 (若是玩家则返回账号编号)
	@attack_target_mobid		被攻击者的魔物编号 (若是不是魔物则返回 0)

	@attack_damage_flag			本次攻击的伤害类型 (位运算)
		按攻击范围:
			BF_SHORT:			近距离攻击
			BF_LONG:			远距离攻击
		按攻击类型:
			BF_WEAPON:			武器攻击
			BF_MAGIC:			魔法攻击
			BF_MISC:			混合攻击
		按技能类型:
			BF_NORMAL:			普通攻击
			BF_SKILL:			技能攻击
		
		例子:
		----------------
		if (@attack_damage_flag & BF_MAGIC == BF_MAGIC) {
			dispbottom "这是一次魔法攻击";
		}
		
		if (@attack_damage_flag & (BF_MAGIC|BF_LONG) == (BF_MAGIC|BF_LONG)) {
			dispbottom "这是一次远距离魔法攻击";
		}
		
	@attack_damage_skillid		本次攻击使用的技能编号 (若为 0 则表示普通攻击)
	@attack_damage_skilllv		本次攻击使用的技能等级
	@attack_damage_right		本次攻击右手武器造成的伤害值 (该值可被修改)
	@attack_damage_left			本次攻击左手武器造成的伤害值 (该值可被修改)

注意事项:
	只有即将发生伤害时才会触发此事件, 若为 MISS 则不触发此事件.

性能警告:
	全服建议最多只有一个 NPC 负责处理此事件.
	全服在线玩家的任意一次实际造成伤害的攻击都将触发此事件,
	因此请不要在事件中进行耗时操作.

--------------------------------------------------------------

*OnPCMerCallExpress:

当玩家成功召唤出佣兵时触发实时事件 [HongShin]

事件关联:
	关联到召唤佣兵的玩家

携带参数:
	@mer_gid					佣兵的游戏单位编号
	@mer_classid				佣兵的种类编号
	@mer_lifetime				佣兵的持续存在时间 (单位为毫秒)

	@mer_mapid					佣兵所在的地图编号
	@mer_mapname$				佣兵所在的地图名称
	@mer_x						佣兵所在的 X 坐标
	@mer_y						佣兵所在的 Y 坐标

注意事项:
	若佣兵由于各种原因没有被召唤成功, 则不会触发此事件.

--------------------------------------------------------------

*OnPCMerLeaveExpress:

当佣兵离开玩家时触发实时事件 [HongShin]

事件关联:
	关联到佣兵的主人玩家

携带参数:
	@mer_gid					佣兵的游戏单位编号
	@mer_classid				佣兵的种类编号
	@mer_leave_reason			佣兵的离开方式或原因

								0 - 因持续时间到期而离开
								1 - 因佣兵死亡而离开
								2 - 因玩家将佣兵解雇而离开
								3 - 因佣兵逃跑而离开 (玩家死亡导致)

	@mer_mapid					佣兵所在的地图编号
	@mer_mapname$				佣兵所在的地图名称
	@mer_x						佣兵所在的 X 坐标
	@mer_y						佣兵所在的 Y 坐标

--------------------------------------------------------------