Unity Netcode for GameObjects 场景事件中 SceneName 不一致问题解析

问题背景

在使用 Unity Netcode for GameObjects (NGO) 进行自动场景管理时，开发者可能会遇到 SceneEvent.SceneName 属性在不同事件类型中表现不一致的情况。这个问题主要出现在分布式权威(Distributed Authority)模式下使用场景管理功能时。

问题现象

当通过 NetworkSceneManager 加载场景时，如果传入完整的场景路径（如 Assets/Scenes/GameScene_02.unity），在 NetworkSceneManager.OnSceneEvent 回调中，SceneEvent.SceneName 属性会表现出不一致的行为：

• 在 Load 事件中，SceneName 包含完整路径
• 在 LoadComplete 和 LoadEventCompleted 事件中，SceneName 仅包含场景名称

这种不一致性会导致开发者需要额外处理路径和名称的转换，增加了代码复杂度和出错可能性。

技术原理分析

场景加载机制

NGO 的场景管理系统设计允许通过两种方式加载场景：

1. 使用场景名称（如 "GameScene_02"）
2. 使用完整场景路径（如 "Assets/Scenes/GameScene_02.unity"）

当使用路径加载时，系统内部会保留原始传入的字符串，这导致了事件回调中的数据不一致。

事件传播机制

在分布式权威模式下：

• 权威实例（服务器或DA主机）会将原始传入的字符串直接传播给 Load 事件
• 其他事件类型则会使用处理后的场景名称

解决方案

在 NGO v2.4.0 版本中，官方提供了以下改进：

1. 新增了 ScenePath 属性，始终包含场景的完整路径
2. 保持 SceneName 属性的现有行为以保持向后兼容

开发者现在可以：

• 使用 ScenePath 获取一致的路径信息
• 使用 SceneName 获取场景名称（不包含路径）

最佳实践建议

1. 统一使用场景名称：如果项目不需要路径信息，建议始终使用场景名称而非完整路径来加载场景

2. 新项目使用 ScenePath：对于新项目，建议直接使用新增的 ScenePath 属性

3. 状态跟踪优化：当需要跟踪加载状态时，可以使用以下模式：

private Dictionary<string, SceneLoadingState> loadingStates = new();

private void OnSceneEvent(SceneEvent sceneEvent)
{
    // 使用ScenePath作为唯一标识
    var sceneKey = sceneEvent.ScenePath; 
    
    if(!loadingStates.ContainsKey(sceneKey))
    {
        loadingStates[sceneKey] = new SceneLoadingState();
    }
    
    // 更新状态逻辑...
}

总结

Unity Netcode for GameObjects 在 v2.4.0 中通过引入 ScenePath 属性解决了场景事件中路径信息不一致的问题。开发者现在可以根据需要选择使用场景名称或路径来管理场景加载状态，使代码更加清晰可靠。对于现有项目，建议评估是否需要进行相应的代码调整以利用这一改进。