OBS Trigger Volume

AInhyeongOBSTriggerVolume 是一种无代码的方式，可在游戏运行时自动控制 OBS。将其放置在关卡中，设置形状，配置触发时机、要执行的动作以及所需满足的条件，全部在 Details panel 中完成，无需 Blueprint。

放置 Trigger Volume

将一个 OBS Trigger Volume Actor 拖入关卡（或生成 AInhyeongOBSTriggerVolume）。它会在编辑器视口中绘制自身，便于定位。设置形状和范围，然后在 Details panel 中填写动作和条件。

形状

属性	类型	说明
`TriggerShape`	`EOBSTriggerShape`	`Box` 或 `Sphere`。
`BoxExtent`	`FVector`	各方向上的半尺寸（该盒体在每个轴上跨度为 2×）。当形状为 Box 时显示。
`SphereRadius`	`float`	当形状为 Sphere 时显示。

触发事件模式

TriggerEvent（EOBSTriggerEvent）控制体积的触发时机：

模式	行为
`OnEnter`	当 Actor 进入体积时触发（执行 `OnEnterActions`）。
`OnExit`	当 Actor 退出体积时触发（执行 `OnExitActions`）。
`Both`	进入和退出时均触发，分别使用两个独立的动作数组。

OnEnterActions 数组在 OnEnter/Both 时显示，OnExitActions 在 OnExit/Both 时显示。

动作

每个动作均为 FOBSTriggerAction。设置 ActionType 后，相关字段将自动显示。完整动作列表（EOBSTriggerActionType）：

动作	使用的参数	描述
`SwitchScene`	`SceneName`	切换到指定的 OBS 场景。
`StartRecording`	无	开始录制。
`StopRecording`	无	停止录制。
`ToggleRecording`	无	切换录制状态。
`PauseRecording`	无	暂停录制。
`ResumeRecording`	无	恢复录制。
`StartStreaming`	无	开始推流。
`StopStreaming`	无	停止推流。
`ToggleStreaming`	无	切换推流状态。
`StartVirtualCam`	无	启动虚拟摄像头。
`StopVirtualCam`	无	停止虚拟摄像头。
`ToggleVirtualCam`	无	切换虚拟摄像头。
`StartReplayBuffer`	无	启动 Replay Buffer。
`StopReplayBuffer`	无	停止 Replay Buffer。
`SaveReplayBuffer`	无	将 Replay Buffer 保存到文件。
`SetInputMute`	`InputName`、`bMuted`	静音或取消静音一个音频输入。
`SetInputVolume`	`InputName`、`VolumeDb`	以 dB 设置输入的音量（0 = 原始增益，负值 = 更小声，范围限制在 -100…26）。
`ToggleInputMute`	`InputName`	切换输入的静音状态。
`SetSceneItemEnabled`	`SceneName`、`SourceName`、`bEnabled`	按名称显示或隐藏场景中的来源（场景项目）。
`SetSourceFilterEnabled`	`SourceName`、`FilterName`、`bEnabled`	启用或禁用来源上指定名称的滤镜。
`TriggerHotkeyByName`	`HotkeyName`	通过已注册名称触发 OBS 热键（例如 `OBSBasic.StartRecording`）。
`TriggerMediaInputAction`	`InputName`、`MediaAction`	控制媒体源。

MediaAction 为 EOBSMediaInputAction 类型：None、Play、Pause、Stop、Restart、Next、Previous。

每个动作还有一个 DelaySeconds（单个动作的延迟时间，最小值限制为 0）。

在编辑器中，动作的目标字段在已连接时为实时 OBS 下拉菜单：场景、输入和来源选择器，以及每个来源的滤镜选择器和热键选择器（打开时按需获取）。所选名称保存在动作中，因此断开连接后仍可保留。

条件

所有条件以逻辑 AND 方式求值，即每个已启用的条件都必须通过，动作才会执行。OBS 连接始终是必要条件，并在内部进行检查。条件存放于 FOBSTriggerConditions：

录制 / 推流要求（三态）

属性	类型	取值
`RecordingRequirement`	`EOBSOutputStateRequirement`	`Any` / `Required`（必须正在录制）/ `Disallowed`（必须未在录制）
`StreamingRequirement`	`EOBSOutputStateRequirement`	`Any` / `Required` / `Disallowed`

每个输出使用单一三态值，从结构上确保了”必须开启”与”必须关闭”不会同时被设置。

场景条件

属性	类型	说明
`RequiredCurrentScene`	`FString`	仅当当前 OBS 场景与此名称匹配时触发（空值 = 任意场景）。
`ExcludedCurrentScene`	`FString`	仅当当前 OBS 场景与此名称不匹配时触发（空值 = 禁用）。

在编辑器中通过实时 OBS 场景下拉菜单进行选择。

音频阈值条件

AudioConditions 为 TArray<FOBSAudioThresholdCondition>。可添加任意数量，全部必须通过。

字段	类型	说明
`InputName`	`FString`	要检测的 OBS 输入（例如 `Mic/Aux`）。空值 = 忽略该条件。
`Mode`	`EOBSAudioConditionMode`	`Talking`（说话）或 `Idle`（静默）。
`ThresholdDb`	`float`	自动注册检测器的峰值 dB 阈值（默认 -40，范围限制在 -100…0）。

这些条件使用与麦克风 / 语音活动检测中描述的相同的防抖麦克风活动检测机制。每个输入在 BeginPlay 时自动注册检测。

来源可见性条件

SourceVisibleConditions 为 TArray<FOBSSourceVisibleCondition>。全部必须通过。

字段	类型	说明
`SceneName`	`FString`	包含来源的场景。空值 = 忽略该条件。
`SourceName`	`FString`	要检测可见性的来源（场景项目）。空值 = 忽略该条件。
`Mode`	`EOBSVisibilityConditionMode`	`Visible`（可见）或 `Hidden`（隐藏）。

读取实时 bSceneItemEnabled 缓存。未在缓存中找到的来源（名称拼写错误、场景错误或列表尚未获取）将导致条件不通过。

Details panel 会将音频和可见性条件渲染为带名称选择器的形式（在已连接时从 OBS 填充），并附有实时状态指示点，便于在编辑体积时实时查看说话/可见状态的变化。

触发过滤器与选项

属性	类型	说明
`ActorClassFilter`	`TSubclassOf<AActor>`	仅该类（或其子类）的 Actor 可触发。默认 `AActor` 允许任意 Actor。设为 `APawn` 可限制为仅玩家等。
`SpecificActorFilter`	`TSoftObjectPtr<AActor>`	仅该指定 Actor 可触发。若已设置，则忽略 `ActorClassFilter`。
`CooldownSeconds`	`float`	触发之间的冷却时间（防止在体积边缘频繁触发）。
`bTriggerOnce`	`bool`	触发一次后禁用。
`bTriggerEnabled`	`bool`	当前触发器是否已启用。

运行时辅助函数：SetTriggerEnabled(bool)、ResetTrigger()（重新启用单次触发）、ExecuteEnterActions()、ExecuteExitActions()、ExecuteActions(Actions)、AreConditionsMet()、HasValidOBSConnection()、GetActiveOBSComponent()。事件 OnTriggerEnter / OnTriggerExit 在动作即将执行时触发。

外观与可视化

该体积会在编辑器视口中（以及可选在运行时）绘制自身，便于放置和查看。属性（分类 OBS Trigger | Appearance）：

属性	类型	说明
`bShowDebugInEditor`	`bool`	在编辑器视口中绘制体积。
`bShowAtRuntime`	`bool`	在运行时也绘制（PIE / 打包的开发版本）。在 Shipping 版本中会被编译移除。
`bDrawSolid`	`bool`	在线框基础上增加半透明填充（仅限 Box，颜色的 alpha 值决定填充透明度）。
`LineThickness`	`float`	线框粗细（0 = 最细），最大限制为 10。
`DebugColor`	`FColor`	绘制颜色（也用于带样式的网格体）。
`bShowActionLabel`	`bool`	在体积上方浮动显示单行动作摘要（例如 `Enter: BRB`）。遵循相同的显示标志。
`bHideBillboard`	`bool`	隐藏编辑器选择精灵（仅限编辑器）。
`VolumeStyle`	`EOBSTriggerVolumeStyle`	可选的材质渲染外观，同样在游戏中显示：`None`、`Glow`（菲涅耳发光）、`Hologram`（全息）、`Pulse`（脉冲，由内置切换材质支持的预设），或 `Custom`（自定义）。
`StyleMaterial`	`UMaterialInterface*`	用于带样式网格体的自定义材质（仅在 `VolumeStyle = Custom` 时使用）。从体积颜色接收 `Color` 参数。

连接回退

触发器按以下顺序解析其 OBS 连接：

TargetOBSComponent：显式指定的 OBS Component（若已设置）。
关卡搜索：在关卡中找到的缓存 OBS Component（CachedOBSComponent）。
Subsystem：全局 OBS Subsystem。

若已设置 TargetOBSComponent 但无法解析，触发器将静默回退到 Subsystem。

使用示例

精彩片段回放

触发：OnEnter
条件：RecordingRequirement = Required
动作：SaveReplayBuffer

场景切换

触发：OnEnter
动作：SwitchScene → “Boss Arena”

音频区域

触发：Both
进入动作：SetInputMute “Background Music”（bMuted = true）
退出动作：SetInputMute “Background Music”（bMuted = false）

注意事项

条件为全 AND。 每个已启用的条件都必须通过，且始终额外要求 OBS 连接。

延迟动作无法取消。 设置了 DelaySeconds > 0 的动作即使在触发 Actor 已离开体积后仍会执行。

音频动作需要精确的 OBS 输入名称。 输入名称不匹配将静默失败。请使用编辑器的实时下拉菜单以避免拼写错误。

Desuq Cafe