本页目录

VR 救小猪(Piggy Rescue)——Godot XR 学习项目

piggyRescue · surreal6/piggyRescue

这是一款主题为「营救海滩边游泳的小猪」的 VR 游戏,作者将其定位为历时约两个月的 Godot 与 XR 个人学习项目,基于 Godot 4.1 stable(最终在 4.1.2 测试)与 Godot XR Tools 4.1 插件开发。仓库打包了插件,并注明部分 XR Tools 文件...

动作游戏 Godot GDScript 物理系统 游戏状态管理 音频系统 UI 系统 中级
★ Stars 16 Forks 2 License 未明确 更新 2026-08-12

国内开发环境适配

Windows
AI 推断/待核验
Linux
未知
macOS
未知
引擎 / 框架:Godot 暂无中文教程标记 未标记站长实测
仓库已内置 addons(含被修改过的 XR Tools 文件),无需额外拉取插件;但 Android 导出需自行安装 XR Loaders、Android 导出模板,并配置 Android Studio 与 JDK,国内下载这些依赖可能需要镜像或代理。在线排行榜依赖 Silentwolf 服务,需要在 Globals.gd 第 6 行填入自备 API key,网络连通性待核验。

中文项目介绍

Piggy Rescue 是一款以「营救海滩边游泳的小猪」为主题的 VR 小游戏。作者在 README 中把它明确界定为个人的 Godot 与 XR 学习项目,前后开发约两个月,并以「帮助其他人在学习中少走弯路」为目的把源码公开出来。

项目基于 Godot 4.1 stable 开发(最终在 4.1.2 上完成测试),依赖 Godot XR Tools 插件的 4.1 版本。README 中提供了 Vimeo 演示视频链接,成品游戏已在 SideQuest 与 Itch.io 上免费发布,作者同时接受捐赠。

需要先明确一点:这是一个「调得还不错的原型」,并非打磨过的商业作品。作者自己在文中反复强调代码未做优化、结构较杂乱,阅读时应把它当作可运行的 XR 学习样本,而不要当作工程规范的参考。

核心功能

功能特性一览

README 中明确列出的代码内特性包括:

  • 一个 6 通道音频混音器,并附带由代码控制音效与音乐的示例。
  • XR 中可漂浮、可抓取物体的逻辑。
  • 一个自带逻辑、可复用的倒计时节点。
  • 用于在 VR 中摆放 UI 的跟随相机逻辑。
  • 海洋 shader 与水下物体 shader,二者由同一组全局 shader 属性驱动(作者表示主要对象已接入全局属性,但不保证所有元素都用了)。
  • 一套简单的小猪生成系统。
  • 本地排行榜的实现。
  • 基于 Silentwolf 的在线排行榜实现,使用前需要把 API key 填到 Globals.gd 第 6 行。
  • 在 PCVR 与 Android 之间切换渲染质量设置的基础实现。
  • Pico4、Quest2 与 PCVR 的导出配置(仍需自行安装 XR Loaders、Android 导出模板,并配置 Android Studio、JDK 等构建环境)。
  • 一个通用的 XR 控制器场景,用控制器按钮来展示对应的输入动作。

补充说明

可以直接玩吗

可以,成品已经免费发布,无需自行编译:

  • SideQuest 页面:https://sidequestvr.com/app/19654/piggy-rescue
  • Itch.io 页面:https://asturnazari.itch.io/piggy-rescue

如果愿意支持作者,页面上也提供了捐赠入口。

XR Tools 插件与改动说明

为了让人能直接把仓库当学习素材打开,作者把 addons 一并打包进了代码库。但要注意,其中若干来自 XR Tools 的文件被作者修改过:

  • godot-xr-tools/objects/viewport_2d_in_3d.gd
  • godot-xr-tools/objects/virtual_keyboard.tscn
  • godot-xr-tools/staging/loading_screen/loading_screen_shader.tres
  • godot-xr-tools/staging/loading_screen.tscn
  • godot-xr-tools/staging/loading_screen.gd

这些改动大多是为了实现「透明菜单,并把它渲染在所有内容之上」。作者曾把该改动作为功能提案提交,而在 XR Tools v4.2 中,Malcolm Nixon 已经提供了一套更新、更好的实现方式。也就是说,如果你使用的是较新版本的 XR Tools,这些魔改大概率不再必要。

制作工具

README 列出的工具链为:Gimp、Inkscape、Penpot、Godot、Blender。其中图像与矢量素材由 Gimp / Inkscape / Penpot 处理,3D 与场景部分使用 Blender 与 Godot。

代码结构与运行逻辑

整个项目只有一个 staging 系统和一个场景,入口非常集中:

  • 主场景中存在一个 Logic 节点,游戏的主要代码都放在这里。
  • 它本质上是一个简单的状态机,通过 Globals.state 来驱动游戏各个状态。
  • 另一个函数负责根据全局状态决定当前应该显示哪一块 UI。

此外,scripts/XR_mod 文件夹里放了几个相对独立、可复用的代码片段:一个可拾取且可漂浮的物体,以及「水下摄像机音效」的实现。想快速理解项目,建议先读 Logic 节点的状态机与 UI 切换逻辑,再去看 XR_mod 中的独立模块。

关于代码质量

作者在 README 里专门加了一段「Code alert」提醒读者:代码没有经过良好优化,实现相当简单,是一个调校得还不错的原型,但写法凌乱、组织不够有序,仓库里可能还散落着一些未使用的文件。作者表示代码仍有改进空间,并欢迎提交改进。

想救更多宠物?

作者留了一个很开放的扩展点:如果想加入更多需要营救的宠物,只需要修改小猪生成器(pig spawner)对象即可。若在扩展过程中遇到问题,可以通过开 issue 的方式向作者求助。

学习建议

这个仓库比较适合已经会用 Godot、正准备迈入 XR 领域的开发者:

  1. 先跑通项目,观察状态机如何驱动场景与 UI 的切换。
  2. 再拆开 scripts/XR_mod,把漂浮抓取、倒计时、水下摄像机这类可复用模块单独抽出来理解。
  3. 最后参考它的导出配置,试着给自己手上的 Quest 或 Pico 项目打包。

需要提前有心理准备的是:在线排行榜要自行申请 Silentwolf 的 API key;仓库不包含 Android 构建环境,XR Loader、导出模板、Android Studio 与 JDK 都需要按官方文档自行补齐。

开源许可证与版权说明

许可证标识:未明确。源码、资源与依赖许可可能不同,请以官方仓库为准。本站仅做索引,不托管源码。

相似项目