SceneAssetWrapper¶

继承链: System.Object → SceneAssetWrapper

实现接口: System.IEquatable<SceneAssetWrapper>

声明¶

[Serializable]
public class SceneAssetWrapper : System.IEquatable<SceneAssetWrapper>

可序列化的场景引用，支持在编辑器中拖拽 SceneAsset 赋值，等价于 Eflatun.SceneReference（SceneReference 类型）+ Odin Inspector 的组合体。 设计要点： 编辑器侧以 SceneAsset 对象引用为数据源，每次访问自动同步路径、GUID、 Addressables 地址三个缓存字段；场景移动/重命名由 Unity 的对象引用机制自动重定向， 对象引用意外丢失时用序列化的 GUID 自愈路径。 运行时侧不依赖任何编辑器 API 与 Addressables 程序集，直接使用序列化的纯字符串数据。 遵循最小惊讶原则：Addressables 相关 API 在未安装 Addressables 包时依旧可见、可编译， 卸载包不会导致任何编译错误；运行期访问 Address 会抛出 AddressablesSupportDisabledException。 校验语义对位 Eflatun.SceneReference：先查 State / UnsafeReason，或直接用 TryGetScenePath 等 TryGet 家族； 未分配场景的访问器按 fail-fast 约定抛 EmptySceneAssetWrapperException。

Odin Inspector 边界：Inspector 拖拽赋值、三态着色与一键修复按钮等面板效果 依赖 Odin Inspector（经 AttributeProcessor 注入）。未安装 Odin 时仅保证 API 可用—— 用 FromScenePath 构造、SceneAsset 代码赋值（仅编辑器） 与 TryGet 家族完成全部操作，面板不支持。

构造方法¶

SceneAssetWrapper()¶

创建一个空引用（未分配任何场景）的包装器。永不抛异常。

public SceneAssetWrapper()

属性¶

LoadedScene¶

场景的 Scene 结构。场景未加载时返回的结构无效， 用 IsValid 判断（与 Eflatun.SceneReference 同语义）。

public Scene LoadedScene { get; }

SceneAsset¶

编辑器中拖拽的 SceneAsset（数据源）。赋值时自动同步路径/GUID/Addressables 地址。

public SceneAsset SceneAsset { get; set; }

State¶

引用的可用状态。安全（Regular/Addressable）只保证"有一条可行的加载途径"， 并不要求场景当前已加载——是否已加载请查 LoadedScene。

public SceneAssetWrapperState State { get; }

UnsafeReason¶

引用不安全的具体原因。Empty 优先级最高；Addressable 场景即使不在 BuildSettings 也视为安全。

public SceneAssetWrapperUnsafeReason UnsafeReason { get; }

CanAddToBuild¶

是否显示"添加到 BuildSettings"修复按钮。

public bool CanAddToBuild { get; }

CanEnableInBuild¶

是否显示"在 BuildSettings 中启用"修复按钮。

public bool CanEnableInBuild { get; }

CanMakeAddressable¶

是否显示"加入 Addressables"修复按钮（需要安装 Addressables 包且场景当前不可寻址）。

public bool CanMakeAddressable { get; }

DisabledInBuildSettings¶

场景在 BuildSettings 中存在条目但被禁用（编辑器实时检测）。

public bool DisabledInBuildSettings { get; }

IsAddressable¶

此场景是否为 Addressable 场景。 编辑器下（桥已注册）实时核验并回写缓存；运行时按序列化数据判定。

public bool IsAddressable { get; }

IsDangling¶

场景引用已悬空：SceneAsset 对象引用丢失但路径缓存仍在（场景被移动/删除或引用断链）。 Inspector 中以红色提示，可通过重新拖拽场景或右键菜单 Reset Scene 修复。

public bool IsDangling { get; }

MissingFromBuild¶

场景完全不在 BuildSettings 中（既没有启用条目，也没有禁用条目）。

public bool MissingFromBuild { get; }

NotInBuildSettings¶

场景不在 BuildSettings 中时返回 true（含"已加入但被禁用"）；空引用返回 false。

public bool NotInBuildSettings { get; }

BuildIndex¶

场景在 BuildSettings 中的序号。未加入（或被禁用）时返回 -1，不抛异常。

public int BuildIndex { get; }

Address¶

场景在 Addressables 中的地址，供 Addressables.LoadSceneAsync 使用。

public string Address { get; }

Guid¶

场景资产 GUID。

public string Guid { get; }

SceneName¶

场景名称（不包含扩展名）。

public string SceneName { get; }

ScenePath¶

场景相对路径，包含后缀名。

public string ScenePath { get; }

AddressablesSupportEnabled¶

项目是否安装了 Addressables 包。由 asmdef 的 versionDefines 宏 AESIR_MODULES_ADDRESSABLES 驱动，包缺失时相关代码不会编译，但 API 始终可见。

public static bool AddressablesSupportEnabled { get; }

方法¶

声明的方法

继承的方法

运算符方法

Equals(SceneAssetWrapper)¶

判断此引用与另一引用是否指向同一场景：优先按场景路径认定（均忽略大小写）， 任一侧路径缺失时回退到场景 GUID。 路径优先是为了与 GetHashCode 使用同一主键——哈希必然按路径取值 （Player 构建下 FromScenePath 构造的实例没有 GUID、反序列化实例带 GUID， 若哈希取 GUID 则同路径的两侧哈希不等）。判等与哈希主键不一致会违反哈希契约： 同一场景在 Dictionary{TKey,TValue} / HashSet{T} 中会出现两个条目且查找漏命中。

取舍说明：路径优先意味着"场景被移动后残留的陈旧路径"与"新路径"被视为两个不同引用 （一致的 false negative），而不是"GUID 相同即相等、哈希却不同"（不一致的 true-positive）。 需要跨改名稳定识别时，请依赖 sceneGuid 锚点自愈把路径写回后再比较。

public bool Equals(SceneAssetWrapper other)

参数

返回值

TryGetAddress(ref string)¶

尝试获取 Addressables 地址。空引用或场景不可寻址时返回 false、不抛异常； 与 Address 的差异：Address 对空引用抛 EmptySceneAssetWrapperException、对非 Addressable 场景抛 SceneNotAddressableException，本方法一律返回 false。 项目未安装 Addressables 包时两者一致，均抛 AddressablesSupportDisabledException。

public bool TryGetAddress(out ref string address)

参数

返回值

TryGetBuildIndex(ref int)¶

尝试获取 BuildSettings 序号。返回 true 时序号也可能为 -1（场景未加入 BuildSettings）。

public bool TryGetBuildIndex(out ref int buildIndex)

参数

返回值

TryGetLoadedScene(ref Scene)¶

尝试获取已加载场景的 Scene 结构。与 LoadedScene 不同， 仅当场景确实已加载且有效时返回 true。

public bool TryGetLoadedScene(out ref Scene loadedScene)

参数

返回值

TryGetSceneName(ref string)¶

尝试获取场景名称（不含扩展名）。

public bool TryGetSceneName(out ref string sceneName)

参数

返回值

TryGetScenePath(ref string)¶

尝试获取场景路径。空引用返回 false，不抛异常。

public bool TryGetScenePath(out ref string path)

参数

返回值

FromAsset(SceneAsset)¶

按 SceneAsset 构造（仅编辑器）。赋值时自动同步路径/GUID/Addressables 地址。

public static SceneAssetWrapper FromAsset(SceneAsset sceneAsset)

参数

返回值

FromScenePath(string)¶

按场景路径构造。编辑器下校验路径上确实存在场景资产并解析 GUID/Addressables 地址； 运行时（构建后）不做存在性校验，加载是否可行由 State 表达。

public static SceneAssetWrapper FromScenePath(string scenePath)

参数

返回值

Additional Notes¶

首个 ## Additional Notes 是增量生成文档标识符，请勿修改标题级别和内容！本文档由 Script Doc Generator 辅助生成。