SpacetimeDB Unity 集成教程（Part 1）：搭建 Blackholio 多人游戏客户端环境

SpacetimeDB Unity 集成教程Part 1搭建 Blackholio 多人游戏客户端环境【免费下载链接】SpacetimeDBDevelopment at the speed of light项目地址: https://gitcode.com/GitHub_Trending/sp/SpacetimeDB本教程是 SpacetimeDB 官方 Unity 教程Blackhol.io 小规模 MMORPG的第一部分核心任务是在 Unity 中搭建一个可直接连接 SpacetimeDB 数据库的客户端项目骨架。读完本篇你将掌握如何创建符合要求的 Unity 2D 项目、如何通过 Package Manager 导入 SpacetimeDB Unity SDK以及如何在场景中配置GameManager与SpacetimeDBNetworkManager为后续编写服务器模块并实现客户端-服务器通信打下基础。教程背景你要构建的游戏整个系列教程的目标是用 Unity 和 SpacetimeDB 从零构建一个小型但可扩展的 MMORPG——Blackhol.io。游戏玩法受 [agar.io] 启发但改为太空主题你和数百名其他玩家在竞技场中竞争吸收比自己小的实体、不断成长最终进化为统治排行榜的黑洞。虽然游戏范围小但它在架构上足以支撑数百名玩家同时在线帮助你熟悉 SpacetimeDB 面向多人游戏的核心特性与最佳实践。本仓库中提供了教程的完整成品 demo/Blackholio包含client-unityUnity 客户端、server-rust/server-csharp/server-ts三种语言的服务器模块等完整实现可以作为教程每一步的对照参考。在开始之前请确认你具备 Unity 编辑器的基本操作能力、命令行终端使用能力和基础编程能力。Windows 用户建议使用 Git Bash 或 PowerShellmacOS 用户建议使用 Terminal后续教程会给出需要执行的 CLI 命令。支持的 Unity 版本SpacetimeDB 支持Unity2022.3.32f1或更高版本。根据教程总览index.md本教程已在以下版本上验证通过2022.3.32f1 LTS6000.0.33f1需要注意SpacetimeDB 团队无法为2022.3.32f1 LTS之前的 Unity 版本提供支持。如果你在某个特定 Unity 版本上遇到问题可以在仓库中提交 issue但请务必确认版本满足要求。Step 1创建空白 Unity 项目打开 Unity通过以下任一方式新建项目在 Unity Hub 中点击New或在 Unity 编辑器菜单中进入File - New Project。:::warning务必为你的新项目选择Universal 2D模板。:::填写项目信息时请注意Project Name使用blackholioProject Location选择一个可以通过命令行CLI导航到的目录。之所以强调这一点是因为在教程 Part 2 中我们需要通过终端进入该目录执行spacetime命令。点击Create生成空白项目。到这里Unity 端的基础项目就绪下一步导入 SpacetimeDB 客户端 SDK。Step 2通过 Package Manager 导入 SpacetimeDB Unity SDKSpacetimeDB 为 Unity 提供了官方客户端 SDK 包集成方式为标准 Unity Package打开 Package Manager 窗口菜单Window - Package Manager点击窗口左上角的按钮选择Add package from git URL输入以下 URL 并点击Addhttps://github.com/clockworklabs/com.clockworklabs.spacetimedbsdk.git导入完成后SDK 便可在项目中使用。SpacetimeDB Unity SDK 为将 SpacetimeDB 集成进 Unity 提供了实用工具其中最重要的就是网络管理器Network Manager——它会根据你的订阅查询subscription queries将 Unity 客户端的本地状态与 SpacetimeDB 数据库保持同步。这正是后续连接数据库、订阅全表数据、实时同步游戏状态能力的底层支撑。Step 3创建 GameManager 脚本GameManager脚本将承载游戏高层级的初始化与协调逻辑是客户端与 SpacetimeDB 交互的中枢。创建步骤在 UnityProject窗口中进入你想存放脚本的文件夹例如Scripts文件夹在文件夹内右键选择Create C# Script在 Unity 6 中为MonoBehavior Script将脚本命名为GameManager。在后续教程步骤中我们会在该脚本中编写连接数据库、注册事件回调、管理订阅、响应游戏内事件实体插入/更新/删除、玩家进出等的逻辑。作为参考仓库成品项目中完整的 GameManager.cs 展示了这套代码的最终形态它在Start()中通过DbConnection.Builder()注册连接/错误/断开回调并建立连接在HandleConnect中注册各表的OnInsert/OnUpdate/OnDelete事件并订阅全表数据在HandleSubscriptionApplied中读取Config表的世界尺寸来搭建竞技场边界。Step 4将 GameManager 添加到场景创建空 GameObject顶部菜单选择GameObject Create Empty或在Hierarchy窗口右键选择Create Empty。重命名 GameObject在Inspector中点击对象顶部的名称将其重命名为GameManager。附加 GameManager 脚本两种方式任选其一将Project窗口中的GameManager脚本拖拽到Hierarchy窗口中的GameManagerGameObject 上或在Inspector中点击Add Component搜索GameManager并选择它。Step 5添加 SpacetimeDBNetworkManagerSpacetimeDBNetworkManager是一个简单但关键的脚本它会挂接 Unity 的Update循环驱动客户端与 SpacetimeDB 之间消息的发送与处理。关于这个组件有三个要点你不需要也不应该直接与这个脚本交互但它必须存在于场景中的某个单一 GameObject 上才能持续处理消息当你通过 SDK 建立一个新的 SpacetimeDB 连接时该连接会被自动注册并由SpacetimeDBNetworkManager管理无需手动干预也就是说场景中保证且仅保证一个 GameObject 携带此组件即可。操作步骤点击场景中的GameManager对象点击Add Component搜索并选择SpacetimeDBNetworkManager将其添加到GameManager对象上。至此Unity 项目的基础设置全部完成。如果一切配置正确点击 Play 运行游戏会显示一个空白画面但应当正常启动且不报任何错误。这代表客户端骨架已经就绪——下一步就可以编写 SpacetimeDB 服务器模块让客户端有东西可以连了。仓库对照成品项目的结构参考如果你在搭建过程中需要对照参考本仓库的 demo/Blackholio/client-unity 提供了完整的 Unity 客户端实现其关键结构如下client-unity/Assets/ ├── Scripts/ │ ├── GameManager.cs # 连接与全局协调逻辑 │ ├── CameraController.cs # 摄像机跟随 │ ├── CircleController.cs # 玩家圆形实体控制 │ ├── PlayerController.cs # 玩家表现层 │ ├── FoodController.cs # 食物表现层 │ └── autogen/ # spacetime generate 生成的客户端绑定 │ ├── Reducers/ # 客户端可调用的 reducer 封装 │ ├── Tables/ # 表行类型Circle、Config、Entity、Food、Player… │ ├── Types/ # SpacetimeType 类型DbVector2 等 │ └── SpacetimeDBClient.g.cs # 类型感知的 DbConnection 子类 └── Scenes/Main.unity # 游戏主场景对照可见autogen/目录下的绑定文件正是spacetime generate命令的产物Part 2 会详细讲解GameManager.cs则是教程中逐步完善的客户端中枢。服务器端方面server-rust/src/lib.rs 展示了最终的模块实现其中Config、Entity、Circle、Food、Player等表的定义含#[primary_key]、#[unique]、#[auto_inc]、#[index(btree)]等属性与 Part 2 中逐步讲解的代码完全对应——你可以在 Part 1 阶段先浏览这些文件对最终目标建立直观印象。下一步预告Part 2 将做什么客户端骨架完成后教程 Part 2Connecting to SpacetimeDB将带你使用spacetime init --lang csharp|rust --server-only blackholio在blackholio目录内初始化spacetimedb服务器模块目录该命令的--lang参数在 CLI 源码 init.rs 中支持rust、csharp、typescript、cpp等语言在模块中定义 SpacetimeDB 表Config、Entity、Circle、Food、Player与SpacetimeType类型如DbVector2编写并发布 reducer用spacetime publish/spacetime call验证服务器逻辑使用spacetime generate --lang csharp生成客户端绑定代码并用DbConnection.Builder()从 Unity 连接到数据库最终在 Unity 日志中看到Connected.与Subscription applied!。Part 1 的空白项目 SDK 网络管理器正是这一切的承载环境。确认你的项目能无错误运行后就可以进入 Part 2 开始编写服务器模块了。【免费下载链接】SpacetimeDBDevelopment at the speed of light项目地址: https://gitcode.com/GitHub_Trending/sp/SpacetimeDB创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考