unity-event

**在调用本模块中的任何技能之前：**如果你打算根据技能名称或描述猜测参数后调用技能，请先停下——阅读此文件（或通过 GET /skills/recommend?includeSchema=true 获取其架构）。如果你已从 recommend/schema 获取参数定义，则可直接执行 dryRun。

触发条件

• 在 Inspector 中挂接 UnityEvents
• 连接按钮或触发器回调
• 编写持久监听器脚本
• 在 Inspector 里挂接 UnityEvent、连接按钮或触发器回调、脚本化持久监听

事件技能

检查和修改 UnityEvent 上的持久监听器（例如 Button.onClick、Toggle.onValueChanged）——也就是你在 Inspector 的事件投放槽中看到的那些监听器。

操作模式

• Approval：查询类技能（event_get_listeners / event_list_events / event_get_listener_count，源码标记为 SkillMode.SemiAuto）直接执行；其余变更/调用类技能（event_add_listener / event_set_listener / event_set_listener_state / event_invoke / event_add_listener_batch / event_copy_listeners，标记为 SkillMode.FullAuto）需要用户授权，授权后由服务端一步执行并返回结果。
• Auto / Bypass：未被禁用列表拦截的技能直接执行。
• 本模块包含 Delete 类技能：event_remove_listener、event_clear_listeners 标记为 SkillOperation.Delete，会被 IsForbiddenInSemi 静态拦截——仅在 Bypass 模式下或加入 Allowlist 后才能调用。
• event_invoke 仅在 Play mode / runtime 下有效；编辑器空跑时仅会触发 EditorAndRuntime 监听器。event_add_listener 等写入的是持久监听器（序列化到 prefab/scene），因此可在编辑器中配置。

请勿（常见幻觉）：

• event_create / event_trigger 不存在 → UnityEvents 在组件源代码中声明；本模块仅负责连接监听器
• event_subscribe 不存在 → 使用 event_add_listener
• event_remove 不存在 → 使用 event_remove_listener
• event_add_listener 要求目标上的组件类型和方法名完全匹配

路由：

• XR 交互事件 → 使用 xr 模块的 xr_add_interaction_event
• C# 事件代码 → 通过 script 模块编写

技能

event_get_listeners

获取 UnityEvent 的持久监听器。

参数	类型	必填	默认值	说明
name	string	否	null	GameObject 名称
instanceId	int	否	0	GameObject 实例 ID
path	string	否	null	GameObject 层级路径
componentName	string	是	-	组件名称
eventName	string	是	-	事件字段名称（例如 "onClick"）

返回： { success, gameObject, component, eventName, listenerCount, listeners }

event_add_listener

向 UnityEvent 添加持久监听器（编辑器时）。

参数	类型	必填	默认值	说明
name	string	否	null	GameObject 名称
instanceId	int	否	0	GameObject 实例 ID
path	string	否	null	GameObject 层级路径
componentName	string	是	-	所属事件的组件
eventName	string	是	-	事件字段名称（例如 "onClick"）
targetObjectName	string	是	-	存放要调用方法的 GameObject
targetComponentName	string	否	null	目标上的组件；或使用 GameObject 调用对象本身
methodName	string	是	-	公共方法或 set_PropertyName
mode	string	否	RuntimeOnly	Off、RuntimeOnly 或 EditorAndRuntime
argType	string	否	void	void、int、float、string 或 bool
floatArg	float	否	0	静态 float 参数
intArg	int	否	0	静态 int 参数
stringArg	string	否	null	静态 string 参数
boolArg	bool	否	false	静态 bool 参数

返回： { success, message, index, mode }

与 event_set_listener 不同，此技能没有 object 类型的 argType——它仅支持标准的 UnityEvent 重载。

event_remove_listener

按索引移除一个持久化监听器。

Parameter	Type	Required	Default	Description
name	string	No	null	GameObject 名称
instanceId	int	No	0	GameObject 实例 ID
path	string	No	null	GameObject 层级路径
componentName	string	Yes	-	组件名称
eventName	string	Yes	-	事件字段名称
index	int	No	0	监听器索引

返回： { success, remainingCount }

event_invoke

显式调用 UnityEvent（仅限运行时）。

Parameter	Type	Required	Default	Description
name	string	No	null	GameObject 名称
instanceId	int	No	0	GameObject 实例 ID
path	string	No	null	GameObject 层级路径
componentName	string	Yes	-	组件名称
eventName	string	Yes	-	事件字段名称

返回： { success, message }

event_clear_listeners

移除 UnityEvent 的所有持久化监听器。

Parameter	Type	Required	Default	Description
name	string	No	null	GameObject 名称
instanceId	int	No	0	GameObject 实例 ID
path	string	No	null	GameObject 层级路径
componentName	string	Yes	-	组件名称
eventName	string	Yes	-	事件字段名称（例如 "onClick"）

返回： { success, removed }

event_set_listener_state

设置监听器的调用状态（Off、RuntimeOnly、EditorAndRuntime）。

Parameter	Type	Required	Default	Description
name	string	No	null	GameObject 名称
instanceId	int	No	0	GameObject 实例 ID
path	string	No	null	GameObject 层级路径
componentName	string	Yes	-	组件名称
eventName	string	Yes	-	事件字段名称
index	int	No	0	监听器索引
state	string	No	null	调用状态："Off"、"RuntimeOnly" 或 "EditorAndRuntime"

返回： { success, index, state }

event_set_listener

替换指定索引处的持久化监听器。

Parameter	Type	Required	Default	Description
name	string	No	null	GameObject 名称
instanceId	int	No	0	GameObject 实例 ID
path	string	No	null	GameObject 层级路径
componentName	string	Yes	-	源组件名称
eventName	string	Yes	-	事件字段名称
index	int	No	0	要替换的监听器索引
targetName	string	Yes	-	目标 GameObject 名称
targetInstanceId	int	No	0	目标 GameObject 实例 ID
targetPath	string	No	null	目标层级路径
targetComponentName	string	No	null	目标组件名称，或 GameObject
methodName	string	Yes	-	公共方法或 set_PropertyName
mode	string	No	RuntimeOnly	Off、RuntimeOnly 或 EditorAndRuntime
argType	string	No	void	void、int、float、string、bool、object
floatArg	float	No	0	静态 float 参数
intArg	int	No	0	静态 int 参数
stringArg	string	No	null	静态 string 参数
boolArg	bool	No	false	静态 bool 参数
objectReferenceName	string	No	null	场景对象参数名称
objectReferenceInstanceId	int	No	0	场景对象参数实例 ID
objectReferencePath	string	No	null	场景对象参数路径
objectAssetPath	string	No	null	项目资源参数路径
objectType	string	No	null	对象参数的对象/组件类型

返回： { success, index, target, targetType, method, state, argType }

event_list_events

列出组件上的所有 UnityEvent 字段。

参数	类型	必填	默认值	描述
name	string	否	null	GameObject 名称
instanceId	int	否	0	GameObject 实例 ID
path	string	否	null	GameObject 层级路径
componentName	string	是	-	组件名称

返回： { success, component, count, events }

event_add_listener_batch

一次添加多个监听器。items：包含 {targetObjectName, targetComponentName, methodName} 的 JSON 数组。

参数	类型	必填	默认值	描述
name	string	否	null	GameObject 名称
instanceId	int	否	0	GameObject 实例 ID
path	string	否	null	GameObject 层级路径
componentName	string	是	-	组件名称
eventName	string	是	-	事件字段名称
items	string	是	-	包含 {targetObjectName, targetComponentName, methodName} 的 JSON 数组

返回： { success, added, total }

event_copy_listeners

将监听器从一个事件复制到另一个事件。

参数	类型	必填	默认值	描述
sourceObject	string	是	-	源 GameObject 名称
sourceComponent	string	是	-	源组件名称
sourceEvent	string	是	-	源事件字段名称
targetObject	string	是	-	目标 GameObject 名称
targetComponent	string	是	-	目标组件名称
targetEvent	string	是	-	目标事件字段名称

返回： { success, copied }

event_get_listener_count

获取 UnityEvent 上持久化监听器的数量。

参数	类型	必填	默认值	描述
name	string	否	null	GameObject 名称
instanceId	int	否	0	GameObject 实例 ID
path	string	否	null	GameObject 层级路径
componentName	string	是	-	组件名称
eventName	string	是	-	事件字段名称

返回： { success, count }

---

精确签名

准确的名称、参数、默认值和返回值由 GET /skills/schema 或 unity_skills.get_skill_schema() 定义，而非此文件。