SpacetimeDB Unreal 入门教程 Part 1搭建 Blackholio 客户端工程与 SDK 集成【免费下载链接】SpacetimeDBDevelopment at the speed of light项目地址: https://gitcode.com/GitHub_Trending/sp/SpacetimeDB本篇指南完整讲解在 Unreal Engine 5.6 中为 SpacetimeDB 多人游戏客户端搭建初始工程的全过程从创建 C 空白项目、导入 SpacetimeDbSdk 插件到建立 GameManager 单例 Actor、配置关卡光照与 GameMode。学完本部分你将得到一个可运行的 Unreal 客户端地基为下一部分编写 SpacetimeDB 服务端模块并建立连接做好准备。教程背景用 Unreal 构建一个 SpacetimeDB 多人游戏本教程来自仓库中的 Unreal 教程总览目标是带领读者从零开始用 SpacetimeDB 构建一个小规模但可扩展至数百名玩家的太空题材多人动作游戏Blackhol.io。游戏玩法参考了著名的 agar.io——玩家在培养皿中通过吞噬来积累质量、成为最大的细胞而 Blackhol.io 将其搬到太空背景黑洞主题之下是了解 SpacetimeDB 能为多人游戏开发者提供什么能力的绝佳载体。教程按四部分循序渐进展开Part 1 - Setup本文搭建 Unreal 客户端工程并接入 SpacetimeDB Unreal SDKPart 2 - Connecting to SpacetimeDB创建服务端模块可选 Rust / C# / C并打通客户端连接Part 3 - Gameplay 与 Part 4 - Moving and Colliding实现游戏玩法与移动碰撞教程刻意保持简单只有一个 Game Manager 类、最小化的错误处理、方便之处直接硬编码配置目的是让 SDK 的调用流程一目了然。在生产项目中你通常应该把这些逻辑放进 Unreal Subsystem、把密钥移出代码、遵循最佳实践并补充完善的日志与重试机制——这一点原文有明确提示。教程的完整成品工程位于仓库的 demo/Blackholio 目录其中 client-unreal 即最终的 Unreal 客户端参考实现你可以在任何一步卡住时对照它。版本与前置条件引擎版本SpacetimeDB 目前支持 Unreal Engine5.6教程仅在该版本上测试过。若在其他 Unreal 版本上遇到问题可以提交 issue但请注意 SpacetimeDB 团队无法为5.6之前的版本提供支持。语言基础教程假定你具备 Unreal Engine 的基础操作、命令行终端使用经验以及 C 编程能力。Windows 用户建议使用 Git Bash 或 PowerShellmacOS 用户建议使用 Terminal。客户端语言本教程以 C 客户端为主线编写但 SpacetimeDB Unreal 客户端 SDK 同样支持 Blueprint——教程在关键步骤中同时给出了 C 与 Blueprint 两种操作路径见下文。Step 1创建空白 Unreal 项目启动 Unreal 5.6在 Unreal Project Browser 中选择Games分类创建新项目。创建时有两个必须注意的要点:::warning 必须选择Blank模板并在Project Defaults中选择C作为项目类型。 :::项目名称统一使用blackholio点击Create生成空白项目。选择 Blank C 的原因很直接Blank 模板不会带入任何多余的示例内容保证接下来手动添加的每个 Actor、GameMode 都完全可控而 C 是使用 SpacetimeDB Unreal SDK纯 C 插件的必要条件Blueprint 项目无法直接引用插件的 C 类型。导入 SpacetimeDB Unreal SDKSpacetimeDB 的 Unreal 客户端 SDK 目前仍处于preview 阶段尚未发布到官方插件市场只能以源码方式安装。仓库中即包含该 SDK 的完整源码位于 sdks/unreal/src。SDK 本质是一个名为SpacetimeDbSdk的 Unreal 插件。从 sdks/unreal/README.md 可以看到它的能力定位与目录组织通过 WebSocket 使用BSATN 二进制格式与 SpacetimeDB 服务端通信消息与类型头文件由 SpacetimeDB CLI 生成保证与其他 SDKRust / C# / TypeScript 等结构一致提供高层 API 用于建立连接、调用 reducer、维护与服务端同步的本地表缓存client cache纯 C 实现并带有 Blueprint 包装方便游戏脚本层直接调用。插件源码按职责划分为几个核心模块均在sdks/unreal/src/SpacetimeDbSdk/Source/SpacetimeDbSdk/Public/下目录职责Connection/连接与订阅类如UDbConnectionBuilder、UDbConnectionBase、UCredentialsDBCache/客户端侧表缓存工具维护订阅结果的本地视图BSATN/BSATN 序列化器负责二进制编解码ModuleBindings/CLI 生成的消息与类型头文件QueryBuilder/订阅查询表达式构造Tables/生成表包装类的基类安装步骤安装前请先关闭 Unreal 工程与 IDE避免文件被占用导致复制失败。进入你的 Unreal 项目目录创建Plugins文件夹如果尚不存在cd blackholio mkdir Plugins将 SDK 源码中的SpacetimeDbSdk文件夹复制到新建的Plugins目录中。复制完成后目录结构应为/blackholio/Plugins/SpacetimeDbSdk。也就是说仓库中的 sdks/unreal/src/SpacetimeDbSdk 对应到你项目里的Plugins/SpacetimeDbSdk。回到 Unreal 项目根目录右键blackholio.uproject选择Generate Visual Studio project files重新生成项目文件。在 Windows 11 上可能需要先展开右键菜单的Show more options才能看到该选项这一步会重新扫描项目结构把Plugins/SpacetimeDbSdk插件模块注册进 VS/Rider 解决方案这样后面创建 C 类时才能正确解析 SDK 头文件。创建 GameManager ActorGameManager将承担游戏的高层初始化与协调逻辑是整个客户端的大脑。教程提供了 C 与 Blueprint 两种实现路径在 IDEVisual Studio 或 JetBrains Rider中打开blackholio工程并运行启动 Unreal Editor。这一步会启用Live Coding让后续的代码改动热编译生效工作流更流畅。首次启动时 Unreal 会提示构建SpacetimeDbSdk插件选择构建即可。在顶部菜单打开Tools - New C Class父类选择Actor点击Next。Class Type 选择Public。将类命名为GameManager。打开blackholio工程启动 Unreal Editor。在Content Drawer中点击Add选择Blueprint - Blueprint Class点击Actor命名为BP_GameManager。:::note 在正式的 Unreal 工程中这类逻辑通常应该放在Subsystem中实现。教程为了展示 SDK 的调用流程刻意简化为单例 Actor。 :::完成后的 GameManager 基类骨架可以参考仓库完整工程中的 demo/Blackholio/client-unreal/Source/client_unreal/Public/GameManager.h——成品工程中该类持有连接相关的ServerUri、DatabaseName、TokenFilePath属性以及IsConnected/Disconnect等蓝图友好接口这正是本教程后续步骤要填充的内容。设置关卡Level接下来配置一个空关卡把GameManager放进去并补充灯光与后处理设置。C 路径创建新关卡顶部菜单File - New Level选择Empty Level点击Create保存关卡并命名为Blackholio。创建 GameManager 蓝图在Content Drawer点击Add选择Blueprint - Blueprint Class展开All Classes搜索GameManager选中它点击Select命名为BP_GameManager。这一步将 C 的AGameManager作为父类派生蓝图从而把 C 逻辑与蓝图编辑能力结合起来。更新 Maps Modes打开Edit - Project Settings左侧选择Project - Maps Modes将Editor Startup Map设为BlackholioGame Default Map同样设为Blackholio。添加到关卡从Content Drawer把BP_GameManager蓝图拖入场景视图。添加 Directional Light点击顶部工具栏Add选择Lights - Directional Light将Rotation设置为-105.0, -31.0, -14.0。添加 Post Process Volume点击顶部工具栏Add选择Volumes - Post Process Volume然后依次配置启用并设置Exposure - Exposure Compensation为0.0启用并设置Exposure - Min EV100为1.0启用并设置Exposure - Max EV100为1.0启用Post Process Volume Settings - Infinite Extend (Unbounded)Blueprint 路径创建新关卡File - New Level选择Empty Level创建后保存为Blackholio。更新 Maps ModesEdit - Project Settings - Project - Maps Modes把Editor Startup Map与Game Default Map都设为Blackholio。添加到关卡把BP_GameManager从 Content Drawer 拖入场景。添加 Directional LightAdd - Lights - Directional LightRotation 设为-105.0, -31.0, -14.0。添加 Post Process VolumeAdd - Volumes - Post Process Volume配置项与 C 路径完全一致Exposure Compensation0.0、Min/Max EV1001.0、Infinite Extend 勾选。这套灯光与后处理参数为游戏提供了稳定、可控的太空场景基调方向光固定入射角度保证阴影一致固定 EV100 避免自动曝光导致画面亮度抖动这在后续渲染黑色圆盘黑洞时尤其重要。添加一个简单的 GameModeGameMode 负责控制关卡的启动规则。这里创建一个极简 GameMode用于微调启动设置并挂接到 World Settings。C 路径创建 C 类Tools - New C Class父类选择GameModeBase点击NextClass Type 选择Public命名为BlackholioGameMode。创建 GameMode 蓝图Content Drawer - Add - Blueprint - Blueprint Class展开All Classes搜索BlackholioGameMode选中并点击Select命名为BP_BlackholioGameMode。更新 World Settings顶部菜单Window - World Settings将GameMode Override从None改为BP_BlackholioGameMode最后保存关卡。Blueprint 路径创建 GameMode 蓝图Content Drawer - Add - Blueprint - Blueprint Class展开All Classes点击Game Mode Base命名为BP_GameMode。更新 World SettingsWindow - World Settings将GameMode Override改为BP_GameMode保存关卡。到此为止Unreal 项目的地基已经搭建完成。按 Play 运行时会看到一片空白画面但游戏应当无报错地正常启动——这正是本部分成功验收的标准。源码视角SDK 在客户端将如何工作虽然连接服务端的代码属于 Part 2但理解 SDK 的内部结构有助于你确认本部分步骤的正确性。从 sdks/unreal/src 源码可以推断出插件对外暴露的核心 API连接构建器DbConnectionBuilder.hUDbConnectionBuilderBase提供WithUriBaseWebSocket 地址、WithDatabaseNameBase数据库名、WithTokenBase认证令牌、OnConnectBase/OnConnectErrorBase/OnDisconnectBase三个回调等链式方法最终通过BuildConnection产出连接对象。这与 Part 2 中UDbConnection::Builder()-WithUri(...)-WithDatabaseName(...)-Build()的用法一一对应。连接对象DbConnectionBase.hUDbConnectionBase提供IsActive()连接是否存活、FrameTick()每帧驱动消息处理、Disconnect()以及FOnConnectBaseDelegate等动态委托订阅相关的SubscriptionBuilderBase()也在此暴露。凭证管理Credentials.hUCredentials封装了Init/LoadToken/SaveToken三个静态方法用于持久化身份令牌——这与 Part 2 中UCredentials::Init(*TokenFilePath)、UCredentials::LoadToken()、UCredentials::SaveToken(Token)的调用链吻合。这些类全部在spacetime generate生成代码、并在blackholio.Build.cs中添加SpacetimeDbSdk模块依赖之后才可被游戏代码引用属于 Part 2 的内容这里先了解其存在即可。下一步连接 SpacetimeDB至此你已经完成了 SpacetimeDB Unreal 教程的客户端环境搭建创建了 Blank C 工程、导入SpacetimeDbSdk插件、建立了GameManager单例 Actor、配置了带灯光与后处理的关卡并挂接了 GameMode。在 Part 2 - Connecting to SpacetimeDB 中你将学习用spacetime init在blackholio/spacetimedb目录初始化服务端模块可选Rust、C#或C定义config、entity、circle、food、player等 SpacetimeDB 表编写第一个 reducer用spacetime start/spacetime publish本地运行并发布模块用spacetime generate --lang unrealcpp生成客户端绑定代码最终在 Unreal 中连接到数据库。如果希望直接查看完整成品仓库中的 demo/Blackholio 包含了服务端server-rust、server-cpp、server-csharp、server-ts等多语言版本与各客户端含 client-unreal的完整实现可作为后续每一步的对照参考。【免费下载链接】SpacetimeDBDevelopment at the speed of light项目地址: https://gitcode.com/GitHub_Trending/sp/SpacetimeDB创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考