场景与来源
本指南介绍如何切换和管理场景、配置逐场景转场覆盖，以及操作场景项目（即场景内的来源实例），涵盖变换、排序、锁定和混合模式等内容。
场景管理
| 函数 | 描述 |
|---|---|
SetCurrentScene(Name) | 切换到指定场景 |
GetSceneList() | 从 OBS 刷新场景列表 |
GetGroupList() | 获取所有场景分组 |
GetCachedScenes() | 获取本地缓存的场景列表 |
GetCachedScenesWithItems() | 获取包含来源项目的场景列表 |
SetSceneItemEnabled(Scene, ItemId, Enabled) | 显示/隐藏来源 |
场景增删改查
| 函数 | 描述 |
|---|---|
CreateScene(Name) | 创建一个新的空场景 |
RemoveScene(Name) | 删除场景（若为当前场景则失败） |
SetSceneName(Name, NewName) | 重命名场景 |
事件：
OnSceneCreated(SceneName, SceneUuid, bIsGroup)：场景已创建OnSceneRemoved(SceneName, SceneUuid, bIsGroup)：场景已删除OnSceneNameChanged(SceneUuid, OldName, NewName)：场景已重命名
注意： 无法删除当前激活的场景。请先切换到其他场景。
场景转场覆盖
逐场景转场覆盖允许你在切换到特定场景时使用不同的转场效果。
| 函数 | 描述 |
|---|---|
GetSceneTransitionOverride(SceneName) | 异步获取指定场景的转场覆盖设置 |
SetSceneTransitionOverride(SceneName, TransitionName, DurationMs) | 设置覆盖（-1 时长表示保留当前值） |
ClearSceneTransitionOverride(SceneName) | 移除覆盖，恢复使用默认转场 |
GetCachedTransitionOverride(SceneName, OutOverride) | 获取本地缓存的覆盖数据 |
FetchAllTransitionOverrides() | 获取所有已缓存场景的覆盖设置 |
事件：
OnTransitionOverrideReceived(SceneName, Override)：转场覆盖数据已获取
覆盖结构体（FOBSSceneTransitionOverride）：
| 字段 | 类型 | 描述 |
|---|---|---|
TransitionName | FString | 覆盖转场的名称（为空表示无覆盖） |
TransitionDuration | int32 | 时长（毫秒，-1 表示无覆盖） |
bHasOverride | bool | 若已设置覆盖则为 True |
场景项目变换
| 函数 | 描述 |
|---|---|
GetSceneItemTransform(Scene, ItemId) | 从 OBS 获取变换属性 |
SetSceneItemTransform(Scene, ItemId, Transform) | 设置所有变换属性 |
SetSceneItemPosition(Scene, ItemId, X, Y) | 仅设置位置 |
SetSceneItemScale(Scene, ItemId, ScaleX, ScaleY) | 仅设置缩放 |
SetSceneItemRotation(Scene, ItemId, Rotation) | 设置旋转角度（单位：度） |
SetSceneItemCrop(Scene, ItemId, L, T, R, B) | 设置裁剪量（单位：像素） |
SetSceneItemBounds(Scene, ItemId, Type, W, H, Align) | 设置边界框 |
GetSceneItemId(Scene, SourceName) | 将来源名称转换为场景项目 ID |
GetCachedSceneItemTransform(Scene, ItemId, OutTransform) | 获取缓存的变换数据 |
变换属性：
- 位置：X/Y 坐标（单位：像素）
- 缩放：X/Y 倍率（
1.0= 100%） - 旋转：角度（0 至 360）
- 裁剪：各边裁剪的像素数
- 边界框：边界框类型、尺寸和对齐方式
- 对齐：位标志（0=居中，1=左，2=右，4=上，8=下）
边界框类型：
| 类型 | 描述 |
|---|---|
None | 无边界框 |
Stretch | 拉伸填充（忽略宽高比） |
ScaleInner | 适应边界内部（添加黑边） |
ScaleOuter | 填满边界（可能裁剪） |
ScaleToWidth | 缩放以匹配宽度 |
ScaleToHeight | 缩放以匹配高度 |
MaxOnly | 仅限最大尺寸（不放大） |
重要： 场景项目通过 SceneItemId 标识，而非来源名称。同一来源可在场景中多次出现，每次对应不同的 ID。请使用
GetSceneItemId()将来源名称转换为其 ID。
场景项目管理（增删改查）
| 函数 | 描述 |
|---|---|
CreateSceneItem(Scene, SourceName, Enabled) | 将已有来源添加到场景 |
RemoveSceneItem(Scene, ItemId) | 从场景中移除项目（不删除来源） |
DuplicateSceneItem(Scene, ItemId, DestScene) | 克隆项目（目标场景为空则克隆到同一场景） |
GetSceneItemLocked(Scene, ItemId) | 查询项目是否已锁定 |
SetSceneItemLocked(Scene, ItemId, Locked) | 在 OBS 界面中锁定/解锁项目 |
GetGroupSceneItemList(GroupName) | 获取分组内的所有项目 |
GetSceneItemSource(Scene, ItemId) | 获取场景项目的来源信息 |
GetSceneItemIndex(Scene, ItemId) | 查询层级顺序位置 |
SetSceneItemIndex(Scene, ItemId, Index) | 设置层级顺序（0 = 最底层，数值越大越靠前） |
GetSceneItemBlendMode(Scene, ItemId) | 查询混合模式 |
SetSceneItemBlendMode(Scene, ItemId, Mode) | 设置合成混合模式 |
混合模式：
| 模式 | 描述 |
|---|---|
Normal | 默认混合 |
Additive | 提亮（颜色叠加） |
Subtract | 压暗（颜色相减） |
Screen | 滤色混合 |
Multiply | 正片叠底混合 |
Lighten | 保留较亮像素 |
Darken | 保留较暗像素 |
注意事项：
CreateSceneItem需要使用已有来源，无法创建新来源。DuplicateSceneItem创建的是引用而非副本。对来源的修改会同时影响两者。RemoveSceneItem仅移除引用，底层来源仍然可用。- 索引
0位于场景最底层（最先渲染），数值越大越靠前。 - 混合模式的更改不会触发 OBS 事件，如有需要请在本地跟踪。
事件
场景
OnCurrentSceneChanged(SceneName, SceneUuid)：当前激活场景已更改OnSceneListUpdated：场景列表已刷新OnSceneCreated(SceneName, SceneUuid, bIsGroup)：新场景已创建OnSceneRemoved(SceneName, SceneUuid, bIsGroup)：场景已删除OnSceneNameChanged(SceneUuid, OldSceneName, NewSceneName)：场景已重命名OnTransitionOverrideReceived(SceneName, Override)：场景转场覆盖数据已获取
场景项目
OnSceneItemTransformChanged(SceneName, SceneItemId, Transform)：场景项目变换已更改OnSceneItemCreated(SceneName, SourceName, SceneItemId, SceneItemIndex)：项目已添加到场景OnSceneItemRemoved(SceneName, SourceName, SceneItemId)：项目已从场景移除OnSceneItemEnableStateChanged(SceneName, SceneItemId, bEnabled)：项目可见性已更改OnSceneItemLockStateChanged(SceneName, SceneItemId, bLocked)：项目锁定状态已切换OnSceneItemListReindexed(SceneName)：场景内项目已重新排序（层级顺序已更改）
有关所有 OBS 领域事件的完整目录，请参阅事件参考。