Unity Netcode for GameObjects 中使用 NativeHashMap 的注意事项

概述

在 Unity Netcode for GameObjects (NGO) 1.9.1 版本中，官方宣布了对 NativeHashMap 的内置支持。然而在实际使用过程中，开发者可能会遇到一些兼容性和配置问题。本文将详细介绍如何正确使用 NGO 的 NativeHashMap 支持，以及需要注意的技术细节。

启用 NativeHashMap 支持

NGO 为了保持核心包的轻量级，避免强制依赖 Collections 包，将 NativeHashMap 的支持设计为可选功能。开发者需要手动启用：

1. 打开 Unity 编辑器
2. 进入项目设置 > Player > 其他设置
3. 在 Scripting Define Symbols 中添加 UNITY_NETCODE_NATIVE_COLLECTION_SUPPORT

这个编译符号会激活 NGO 中对 NativeCollections 的序列化支持代码。

版本兼容性问题

当前 NGO 1.x 版本仅支持 Unity.Collections v1.x 版本。如果项目中安装了 Unity.Collections v2.x（通常随 UTP v2.3+ 一起安装），会出现编译错误，例如：

error CS1955: Non-invocable member 'NativeHashSet<T>.Count' cannot be used like a method.

这是因为 v2 版本的 Collections API 发生了变更，而 NGO 1.x 的代码是基于 v1 API 编写的。

解决方案

目前有两种可行的解决方案：

1. 降级 Collections 包：将 Unity.Collections 降级到 v1.x 版本
2. 升级 NGO 版本：等待或迁移到 NGO 2.0.0 版本，该版本已针对 Collections v2 进行了适配

使用示例

正确配置后，可以这样使用 NativeHashMap 作为 NetworkVariable：

public class NetworkCacheProvider : NetworkBehaviour
{
    public NetworkVariable<NativeHashMap<int, FixedString32Bytes>> dataCache = new();
}

注意：目前建议使用 FixedString 等简单类型作为值类型，复杂类型如 NativeArray 可能仍需要额外处理。

最佳实践

1. 明确项目依赖的 Collections 版本
2. 在多人协作项目中，确保所有开发者都添加了相同的编译符号
3. 测试网络序列化性能，大数据量的 NativeHashMap 可能影响网络同步效率
4. 考虑使用 NetworkVariable 的权限设置，控制不同客户端对数据的修改权限

结论

NGO 对 NativeCollections 的支持为高性能网络游戏开发提供了更多可能性，但在使用时需要注意版本兼容性和项目配置。随着 NGO 2.0 的发布，这些兼容性问题将得到更好的解决。开发者应根据项目需求选择合适的版本组合。