自定义操作

本文档适用于 CyanTrigger 版本 0.4。如果您使用的是 0.3 或更低版本，请跳至该部分。

CyanTrigger 的自定义操作功能允许用户创建自定义操作、事件，甚至自定义变量类型，从而实现类似“子程序”的功能。这既可以简化常用操作，也可以构建复杂的自动化程序。本文将详细介绍自定义操作的创建、使用和配置。示例部分将提供更直观的理解。

自定义操作指示器

在 CyanTrigger 中，您可以通过多种方式识别自定义操作：

黄色 CyanTrigger 图标: 在逻辑中，带有黄色 CyanTrigger 图标通常表示自定义操作。

事件

对于自定义操作事件，Event Variant 选择器将显示非“VRC_Direct”的名称。此外，Event Header 下会显示“Custom Action Info”部分，包含程序资源文件和自定义操作定义。点击这些信息将直接跳转到 Assets 文件夹中的相关文件。

操作

所有自定义操作名称后都带有星号 (*)，并以与内置 Udon 操作不同的颜色显示，方便区分。

您可以在 CyanTrigger 设置 UI 中自定义此颜色（CyanTrigger Settings UI Settings -> Custom Action Name）。

当自定义操作展开以显示其输入时，您将在 Action Variant 选择器下看到“Custom Action Info”部分，其中提供了项目资产和自定义操作定义。单击其中任何一个都将选择 Assets 文件夹中的文件。

向事件添加操作时，# 图标表示内置 Udon 操作或代码定义的操作，而黄色 CyanTrigger 图标则表示自定义操作。

自定义操作实例 (变量类型)

Variables 部分中，所有自定义操作实例名称后都带有星号 (*)。鼠标悬停在截断的变量名称上会显示完整类型名称的工具提示，并提供一个按钮用于查看定义此类型的程序资源文件。

在添加全局变量时，“自定义类型”部分列出了项目中所有已定义的自定义操作实例，其名称末尾带有“(Custom)”标识。

创建自定义操作

创建自定义操作前，建议先完成 Udon 程序的开发（可以使用 CyanTrigger、UdonGraph 或 UdonSharp）。 避免在创建后频繁修改程序，以免需要更新所有已使用的自定义操作。

创建自定义操作步骤：

右键单击 Assets 文件夹，选择“Create/CyanTrigger/CyanTrigger Custom Action”。这将创建一个带有黄色 CyanTrigger 图标的自定义操作定义文件。

将 Udon 程序资源文件拖拽到“Udon Program Asset”属性中。

自定义操作定义选项

创建并添加程序后，您可以设置以下选项：

默认命名空间 (Default Namespace)

定义自定义操作集合的名称，新添加的操作将自动应用此命名空间。 虽然命名空间并非强制一致，但保持一致性有助于组织代码。 更改默认命名空间会更新所有具有相同命名空间的已定义操作。当 Custom Action Definition 设置为多实例时，默认命名空间将作为 Variables 部分中显示的自定义类型的名称。

自动添加优先级 (Auto Add Priority)

当多个自定义操作设置为自动添加到同一事件时，此选项决定添加顺序。数值越小，优先级越高。

实例类型 (Instance Type)

自定义操作有两种实例类型：单实例和多实例。

• • 单实例: 所有操作共享相同的变量数据，如同只有一个 Udon 程序实例在使用它。适用于无需在两次调用之间保存数据的操作（例如 GameObject.ToggleActive）或所有调用都应使用相同数据的操作（例如 Transform.Respawn）。

  • 多实例: 可以创建多个自定义操作实例，每个实例拥有自己的数据。多实例自定义操作被视为自定义类型，使用时需要在 Variables 部分创建实例并将其关联到操作。有关更多详细信息，请参阅 Counter 示例或 GameObjectSyncedToggle 示例。

定义操作

点击操作列表中的加号图标 (+) 可添加操作。

弹出的菜单列出了程序中的所有事件，以及一个特殊的“Variable Setter”选项，用于仅设置或获取变量值，无需其他逻辑。 注意，某些事件（例如 Start 或 OnDeserialization）可能需要手动添加（点击“自动添加非自定义事件”）。

添加操作后，系统会根据事件类型以不同的方式显示：自定义事件显示为“Action”，其他事件类型显示为“Event”。

在示例中，Start 是唯一的非自定义，将显示在 Events 列表中。

MyEvent 和 SetMyVariable 都是自定义的，将显示在 Action 列表中。

将自定义操作创建为 Event 时，它还必须定义何时应调用其操作。要定义此项，请在事件中的某个位置添加 UdonBehaviour.SendCustomEvent 操作。确保 UdonBehaviour 以自身为目标，如果使用 CyanTrigger，则为 This UdonBehaviour，并且事件为空或 null。

此示例将在启动时立即调用操作，而不执行任何其他操作。您还可以添加有关何时或是否应触发操作的逻辑。

在此示例中，它会检查本地用户是否是实例的主用户，并且只有当他们是主用户时，才会触发操作。

操作选项

添加操作后，您可以设置以下选项：

• 自动添加操作 (Auto Add): 启用后，此操作将自动添加到 CyanTrigger，并在列表中隐藏。所有变量将设置为隐藏并使用默认值。 如果多个自定义操作对同一事件设置了自动添加，请使用自动添加优先级来确定添加顺序。

• 操作命名空间 (Action Namespace): 搜索操作时显示的名称，建议与默认命名空间保持一致。

• 操作变体名称 (Action Variant Name): 此操作的名称，命名时需谨慎避免冲突。

• 描述 (Description): 对操作功能的描述（目前未在界面中显示）。

• 基本事件名称 (Base Event Name) 和活动入口 (Event Entry): 用于内部用途，显示在检查器中。 使用“Edit Base Action Data”选项谨慎修改，错误修改可能破坏操作。

定义操作输入

定义 Action 后，您还可以定义此操作的输入。这些输入将影响在 CyanTrigger 中使用此操作时显示的输入。将操作添加到自定义操作定义时，它将以无变量开始，或者如果操作有参数，则显示该操作的所有参数。在此示例中，MyCustomAction 有一个将自动添加的参数。使用参数时，某些选项将被禁用，因为该值由参数本身设置。如果程序中的参数被修改过，则需要使用顶部的 “Edit Base Action Data” 复选框手动更新此自定义操作。有关更多详细信息，请参阅更新自定义操作。

Udon 名称 (Udon Name)

程序中变量的名称，必须完全匹配。 对于 CyanTrigger 参数，格式应为 arg(VariableName)_(EventName)。

显示名称 (Display Name)

在操作检查器中显示的输入名称。

描述 (Description)

对输入用途的描述，鼠标悬停在检查器中的变量上时显示。

在检查器中隐藏 (Hidden in Inspector)

隐藏输入，始终使用默认值。启用后，“对多个对象重复”和“修改变量”选项将被禁用。

对多个对象重复 (Repeat for Multiple Objects)

允许在一次操作中对多个对象应用相同的操作。仅第一个输入可用此选项。

修改变量 (Modifies Variable)

类似于 Custom Event 参数的 Output 选项。 取消选中后，允许直接输入或使用变量输入。 选中后，预期自定义操作会修改变量值，并将修改后的值同步到检查器中使用的变量。

默认值 (Default Value)

在检查器中初始化的值。如果选中“在检查器中隐藏”，则始终使用此值。 如果选中“修改变量”，此字段将被禁用。

更新自定义操作

建议避免修改程序中使用的事件和变量。如果必须修改，请选中“Edit Base Action Data”复选框来更新自定义操作中的相关信息。这通常是未选中的，因为在不知道的情况下修改这些值会破坏自定义操作。选中此选项后，您可以编辑以下项目：

• 操作基事件名称
• 操作进入事件
• Action Input Udon Name
• Action Input Parameter 修改变量
• Remove Action 输入参数

自定义操作示例

GameObject.ToggleActive

GameObject.ToggleActive 是 CyanTrigger 提供的默认自定义操作之一。它由一个简单的 CyanTrigger 程序组成，该程序具有一个 GameObject 全局变量和一个自定义事件，该事件用于获取该全局变量的活动状态，将其翻转并设置回去。由于这是自定义事件而不是任何其他事件，因此它将被视为 Action。 查看 Custom Action Definition，只定义了一个操作。此操作位于 GameObject 命名空间中，使其与所有其他 GameObject 操作一起显示。名称为 ToggleActive，它与程序中的事件名称不同。它有一个变量输入，即程序中的 GameObject 全局变量。它设置为对多个对象重复，从而允许此操作在一个操作中应用于多个对象。这是您可以创建的最简单的自定义操作类型之一。它基本上是将几个操作压缩为一个的快捷方式。

OnPlayerTriggerEnter.LocalPlayer

OnPlayerTriggerEnter.LocalPlayer 是 CyanTrigger 提供的默认自定义操作之一。它由一个简单的 CyanTrigger 程序组成，该程序具有一个使用 OnPlayerTriggerEnter 的事件。由于这不是 Custom Event，因此在使用时将被视为 Event。查看程序本身，它会检查进入触发器的玩家是否是本地玩家。如果是本地玩家，则向自身发送一个空事件，对于 Custom Actions，该事件指示应执行 CyanTrigger Event 的 Actions。如果玩家不是本地玩家，则不会执行操作，从而阻止对远程玩家触发操作。 查看 Custom Action Definition，只定义了一个操作。此操作位于 OnPlayerTriggerEnter 命名空间中，使其与 VRChat 的 OnPlayerTriggerEnter 事件一起显示。名称为 Local Player，表示可以在 Event Header 中选择的变体。它没有变量输入。

Transform.Respawn （变换.重生）

Transform.Respawn 是一个自定义操作，用于展示 Auto Add 功能。检查程序，有两个操作：Start 和 Respawn。Start 事件将保存转换的初始位置和旋转。然后，Respawn 事件会将变换设置回原始位置和旋转。如果存在刚体，它还将移除所有速度。与前面的示例相比，这个程序的特殊之处在于它需要初始化，并且需要在两次调用之间保存数据。这需要设置为两个操作，一个用于 Start 事件以初始化自定义操作，另一个用于 Respawn 以允许用户重新生成转换。通过将 Start Custom Action（启动自定义操作）设置为 Auto Add（自动添加），只需使用 Transform.Respawn 自定义操作即可自动添加 Start（开始）操作，无需用户自行添加即可对其进行初始化。自动添加的操作不会显示在列表中供用户添加。

您只需在 CyanTrigger 中的任何位置添加此操作，一切即可正常工作。

计数器

Counter 是一个简单的示例，展示了 Custom Actions 中的多实例支持。此自定义操作定义了一个计数器，您可以向该值添加一个计数器，然后检查该值是否“很大”。

查看该程序，有一个变量来保存 counter 值，一个事件将该变量的值加 1，然后如果该值被视为 “large” ，则返回一个事件。在这种情况下，large 仅表示大于 10。

在此示例中，使用 Custom Action，在 variables 部分中定义了两个计数器：redCounter 和 blueCounter。已创建两个事件以添加到每个计数器，然后检查该计数器是否为 “Large”。如果值很大，请打印出它很大。此示例本身可能没有意义，但它显示了定义处理数据的方法的构建块。

GameObjectSyncedToggle

GameObjectSyncedToggle 是一个示例，展示了自定义操作中的多实例支持。与其他示例相比，这是一个复杂的示例。Multi-Instance 类似于创建自己的 Variable Types，是一种子程序形式，它期望为自定义操作的每个“实例”保存数据。在此示例中，Custom Action 将保存游戏对象和同步的布尔值，并允许操作切换布尔值，这将自动设置已保存游戏对象的启用状态。

查看程序，在 variables 部分中声明了两个保存的值，其中“isEnabled”是同步的布尔值，“syncedGameObject”是将切换状态的对象。

• “_SetGameObject”事件采用一个游戏对象参数，该参数将更新变量并更新“isEnabled”变量的值（在屏幕截图中省略）
• “_Toggle”事件将确保本地玩家是持有此操作的游戏对象的所有者，翻转同步的“isEnabled”变量的值，然后请求 Udon 将变量同步到房间中的每个人。
• 最后，每当值更新时，都会调用检查 “isEnabled” 布尔值的 OnVariableChanged 事件，并为保存的游戏对象设置启用状态。

查看 Custom Action Definition，这里的主要项目是 “Instance Type” 设置为 “Multi-Instance”。有了这个，你可以在 CyanTrigger 的 Variables 部分创建自定义操作的 “实例”。有 2 个定义的操作链接到具有相同名称的程序。

在这里，您可以看到使用 GameObjectSyncedToggle 自定义操作的 CyanTrigger。它在 variables 部分有两个实例：“syncedToggle1”和“syncedToggle2”。在 start 方法中，它为两个实例调用 SetGameObject，每个实例都有不同的对象。使用 “Multi-Instance” 自定义操作时，您必须选择要用于每个操作的实例。

初始化两个实例后，有两种方法可以单独切换每个实例。“Toggle1” 将切换 “syncedToggle1” 实例，“Toggle2” 将切换 “syncedToggle2” 实例。

V0.3 自定义操作

此信息仅适用于 CyanTrigger 版本 0.3 及更低版本。如果您使用的是 0.4 或更高版本，请参阅该部分。CyanTriggers 具有允许创建自定义操作的功能。目前，这仍在开发中，并且缺少一些功能。有关更多详细信息，请参阅 限制 和 注释 部分。目前，只能从现有的 Udon 程序中执行自定义操作。您可以使用 UdonGraph 或 UdonSharp，而不是 CyanTriggers。CyanTriggers 附带的所有自定义操作都是在 UdonGraph 中进行的。如果您想了解它们是如何制作的，可以在 “Assets/CyanTrigger/Resources/DefaultCustomActions” 文件夹下找到它们。

创建自定义操作

您可以为 Events （事件） 和 Actions （操作） 创建自定义操作。如果事件基于 CustomEvent，则它将显示在 Actions （操作） 列表中。如果事件基于任何其他事件，它将显示在 事件 列表中。在创建事件自定义操作时，您必须至少有一个 SendCustomEvent 节点，并且流程中没有输入。此节点将替换为 CyanTrigger 操作。

最好在创建 CyanTrigger 自定义操作定义之前创建并完成 Udon 程序。准备好后，您可以通过右键单击您的资产文件夹并选择“Create/VRChat/CyanTrigger/CyanTrigger Custom Udon Action”来创建新的自定义操作定义。这将创建一个新的基于 Udon 的自定义操作。将 Udon Program 拖到属性中，它将允许您编辑定义。

定义操作

要开始从 Udon 程序定义自定义操作，请点击 “操作” 列表中的加号。这将弹出 Udon Program 中所有事件的列表。您可以从同一事件创建多个自定义操作。当您想要使用隐藏在 CyanTrigger 界面中的默认变量选项时，这非常有用。

添加 Action 后，为您的操作选择 Namespace。命名空间将用于确定此操作在 Action （操作） 和 Event （事件） 列表中的显示位置。如果多个使用相同的命名空间，它们将一起显示。同样，还要选择操作 Variant name （变体名称）。这相当于方法名称，应描述此自定义操作的作用。

定义操作输入

定义 Action 后，您还可以编辑此自定义操作的 Inputs。Variables （变量） 列表将显示此操作的输入。变量只能使用一次。变量的选项是 Udon 程序中的 Public 变量。每个变量都有一些设置：

• Udon Name - 这是 Udon 程序中变量的名称。不要更改 udon 程序中的变量，因为它会破坏此链接。
• Display Name - 这是将显示在 CyanTrigger 界面中的名称。它可以是您想要的任何内容，但请选择描述性内容。
• 描述 - 此变量的描述。这将在 CyanTrigger 界面中输入的显示名称上显示为工具提示
• 对多个对象重复 - 此选项仅对列表中的第一个输入可用。如果启用，CyanTrigger 检查器将为输入创建一个列表。然后，将对此列表中的每个输入执行此操作。
• 在 Inspector 中隐藏 - 此选项仅适用于设置了默认值的常量值。使用此功能，您可以创建操作的不同预设变体。
• 允许常量 - 此选项将允许在 CyanTrigger 界面中使用常量值。不过，并非每种类型都有常量编辑器。
• 允许变量输入 - 此选项将允许将变量用作此自定义操作的输入。
• 修改变量 - 如果选中，则意味着 Udon 程序将修改变量。如果选中此选项，则对 Udon 程序中变量的任何更改都将被复制到界面中提供的输入变量中。如果用户提供具有 OnValueChanged 回调的变量，则将在自定义操作完全完成后进行检查。如果未检查此值并且 Udon 程序修改了变量，则对 CyanTrigger 接口中提供的变量不执行任何操作。
• 默认值 - 这是输入允许常量值时将默认的值。

局限性

自定义操作系统仍处于开发初期。您可以创建的程序类型存在限制。这些将来可能会发生变化。

• 只有一个状态 - CyanTrigger 上自定义操作的所有实例将使用相同的变量。如果未在 Inspector 中设置，它将是上次使用的任何内容。这意味着，如果您有一个递增变量的自定义操作，则该变量对于该 CyanTrigger 上使用的自定义操作都是相同的。目前还没有办法为每次使用 Custom Action （自定义操作） 提供唯一的变量。
• 一个事件 - 截至目前，自定义操作只有一个条目。如果您需要某个东西作为依赖项，则需要将其定义为另一个自定义操作并手动添加到 CyanTrigger 中。

笔记

• 虽然您可以在同一个 Udon 程序和自定义操作定义中定义多个操作，但最好为每个 Udon 程序保留一个操作。这是因为 Udon 程序的整个 Udon 程序集将被复制到 CyanTrigger 中，未使用的项目将使 CyanTrigger 程序膨胀。
• 不复制CyanTrigger 自定义操作定义文件。它们中的每个已定义操作都有一个唯一的 GUID 来表示它们。复制定义文件还不能正确生成新的 GUID。
• 定义自定义操作后，请勿更改程序源中的名称。更改自定义事件的名称、更改为另一个事件、更改公共变量的名称将无法正确更新定义，并会导致事情中断。但是，您可以更新程序中的节点。

例子

这是 GameObject.ToggleActive 的自定义操作。左侧的 UdonGraph 使用 Custom Event，并且有两个公共变量。在右侧，您可以看到 CyanTrigger 自定义操作定义。只有一个定义的操作。此操作仅使用其中一个公共变量作为输入。允许对操作的多个实例重复此变量，它可以是常量或变量类型。不会修改该变量。

这是 OnTriggerEnter.GameObject 的自定义操作。左侧的 UdonGraph 使用 OnTriggerEnter 事件，并且有一个公共变量。请注意，流链中的最后一个节点是 SendCustomEvent，没有输入。这对于 Event Custom Actions 非常重要，因为这是执行 CyanTrigger 动作的时间。如果您想在执行所有 Actions 后执行更多逻辑，则可以在此节点后添加其他节点。在右侧，您可以看到 CyanTrigger 自定义操作定义。只有一个定义的操作。此操作使用一个公共变量作为输入。允许对操作的多个实例重复此变量，它可以是常量或变量类型。不会修改该变量。