# godot-demo1

**Repository Path**: feer/godot-demo1

## Basic Information

- **Project Name**: godot-demo1
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-10-17
- **Last Updated**: 2026-10-17

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Kotlin + Godot Android · 2D / 3D Demo

一个原生 Android 宿主与 Godot 游戏模块协作的示例：**进入独立游戏页面 → 移动角色收集 → 回传得分 → 返回原生页面 → 再次进入**。

- **2D 接星星**：保留原首页，触摸左右拖动角色，接住落下的星星。
- **3D 星岛**：在首页点击“探索 3D 星岛 Demo”进入独立原生页面，再进入独立 3D 场景。左下摇杆控制 Blender 熊猫移动、转向和步行，靠近星晶即可收集。
- 两种模式都是 30 秒一局，每颗 10 分；得分和最高分分别保存在本地。
- 游戏内“结算退出”、Android 系统返回、倒计时结束均返回各自的原生成绩页；从 3D 成绩页返回可回到 2D 首页。
- 本地运行，无账号、网络服务或付费 SDK。2D 由代码绘制；3D 使用本机 Blender 根据参考图制作的完整熊猫，已去掉铅笔和笔记本。

## 环境

| 工具 | 版本/说明 |
| --- | --- |
| Godot 编辑器 | **4.7.2 stable**，与 `org.godotengine:godot:4.7.2.stable` 匹配 |
| Gradle | **9.7.1**，Wrapper 使用本机已有的 `all` 分发缓存 |
| Android Gradle Plugin | **9.4.1**，已内置 Kotlin 支持 |
| Java | **JDK 17+**，项目字节码目标为 Java 17 |
| Android SDK | Platform **36**、Build Tools **36.0.0**、Platform Tools |
| Blender | 本机 **5.2.2 LTS**，仅修改/重新生成模型时需要；普通构建使用现成 GLB |
| 设备 | Android **7.0 / API 24+**、OpenGL ES 3.0，默认包含 arm64-v8a 和 x86_64 |

直接打开当前目录即可导入 Android Studio。`local.properties` 指向本机 SDK，该文件已忽略。引擎使用官方预编译 AAR，本 Demo 不需要自行编译 C++ 或额外安装 NDK。

macOS 会自动检测 `/Applications/Godot.app/Contents/MacOS/Godot`。其他安装位置可通过 `GODOT_BIN` 环境变量或 `-PgodotExecutable` 指定。

## 构建与安装

```bash
# 在当前项目根目录运行，自动导出游戏 PCK 并打包进 APK。
./gradlew :app:assembleDebug

# 本机依赖均已缓存，可直接离线构建和静态检查。
./gradlew --offline :app:assembleDebug :app:lintDebug

# 如有多个设备，请加 -s <设备序列号>。
adb install -r app/build/outputs/apk/debug/app-debug.apk
adb shell am start -n com.example.godotdemo/.MainActivity
```

仅构建 arm64 真机版本可以减少包体：

```bash
./gradlew :app:assembleDebug -PdemoAbis=arm64-v8a
```

自定义 Godot 路径：

```bash
./gradlew :app:assembleDebug -PgodotExecutable=/absolute/path/to/godot
```

如果终端当前默认 Java 版本过低，先将 `JAVA_HOME` 指向 JDK 17 或更新版本。Android Studio 可以在 Gradle 设置中选择随 IDE 提供的 JDK。

## 单独预览游戏

用 Godot 导入 `godot/project.godot` 后运行主场景，也可以执行：

```bash
/Applications/Godot.app/Contents/MacOS/Godot --editor --path godot
```

主场景默认预览 2D，支持鼠标拖动、键盘左右移动。预览 3D 时在 Godot 中打开 `scenes/game_3d.tscn` 并按 F6，或用桌面编辑器命令：

```bash
/Applications/Godot.app/Contents/MacOS/Godot --path godot --scene res://scenes/game_3d.tscn
```

3D 支持 WASD、方向键以及鼠标拖动摇杆。未检测到 Android 桥接插件时自动进入独立预览模式，结算面板提供重新开始和关闭。`--scene` 只用于桌面预览；官方 Android AAR 禁用了该命令行路径覆盖，因此 Android 通过包内启动页和 Bridge 选场景。

## 目录与数据流

```text
app/src/main/java/com/example/godotdemo/
  MainActivity.kt                  原有 2D 首页、3D 导航入口
  Game3DActivity.kt                独立 3D 介绍与成绩页
  GameHomeActivity.kt              公共启动门禁、Activity Result、成绩展示
  game/GameMode.kt                 模式、场景白名单及成绩命名空间
  game/GameContract.kt             Intent 参数与结果契约
  game/GameActivity.kt             引擎生命周期与结束结果
  game/AndroidBridge.kt            Kotlin / GDScript 插件接口
  score/ScoreStore.kt              仅宿主进程写入、按模式存储成绩
godot/
  scenes/bootstrap.tscn            包内场景路由
  scenes/game.tscn                 原 2D 游戏
  scenes/game_3d.tscn              独立 3D 星岛
  scenes/player_3d.tscn            CharacterBody3D、碰撞体、Blender 模型
  scenes/game_hud.tscn             两种玩法共享 HUD / 预览结算面板
  scripts/game.gd                 共享计时、结算和 Bridge
  scripts/game_field.gd           2D 绘制与玩法
  scripts/game_field_3d.gd         星岛、镜头、固定数量星晶复用
  scripts/star_character_3d.gd         角色物理移动和零件步行动作
  scripts/move_joystick_3d.gd      多点触控摇杆、释放和暂停复位
  assets/models/panda.glb          Android 运行时模型
  assets/fonts/                   中文字体及 OFL 许可
art/panda.blend                    可用 Blender 继续编辑的模型源文件
tools/create_panda.py              熊猫 Blender 模型生成脚本
tools/verify_3d.gd                  Godot 场景集成检查（无 Android 单元测试）
tools/update_game_font.py           更新中文字体子集
docs/panda-character.md             熊猫模型与本轮验收记录
```

宿主通过 `GameContract` 把模式与对局时长传给 `GameActivity`。包内 `bootstrap.gd` 通过 Bridge 读取白名单场景路径；2D 与 3D 仅替换 GameField，复用对局控制器、HUD 和桥接。游戏调用名为 `AndroidBridge` 的 GodotPlugin 获取配置、通知就绪、上报分数并请求结束，最后由 Activity Result 将完整结果交还首页。

| 桥接接口 | 方向 | 用途 |
| --- | --- | --- |
| `getGameScenePath(): String` | GDScript 调用 Kotlin | 读取当前模式的白名单场景路径 |
| `getRoundDurationSeconds(): Int` | GDScript 调用 Kotlin | 读取宿主提供的对局时长 |
| `notifyReady()` | GDScript → Kotlin | 标记信号连接和游戏初始化完成 |
| `reportScore(score: Int)` | GDScript → Kotlin | 分数变化时上报，避免逐帧跨层调用 |
| `finishGame(score: Int, completed: Boolean)` | GDScript → Kotlin | 结算并返回结果，`completed` 区分计时结束和主动退出 |
| `request_exit` 信号 | Kotlin → GDScript | Android 系统返回时请求游戏结算 |

## 生命周期和性能取舍

`GameActivity` 在 `:godot_game` 专用进程运行。引擎销毁后会结束该游戏进程；2D / 3D 原生页面保持在宿主进程，下次进入时重新创建引擎。这样可以避开同进程重复初始化引擎的状态问题，并回收 Native/GPU 资源，代价是每次进入都有引擎冷启动开销。

退出先调用 `setResult()`、`finish()`，再在 `onDestroy()` 中释放自己的游戏进程。系统返回先发送 `request_exit` 信号，未就绪或未及时响应时安全兜底退出；重复结束会被过滤。字体、语言等常见配置变化由游戏页自行处理；若系统仍要求销毁游戏 Activity，则取消本局并关闭专用进程，避免恢复已停止的引擎。游戏进程异常终止时，首页提示可重试，保留既有成绩，不保证未完成对局的分数恢复。

游戏切到后台时暂停计时与玩法更新，恢复后重置触摸状态。游戏使用 Compatibility 渲染器，固定竖屏并声明配置变化。2D 星星数量有上限，绘制点和样式复用；3D 固定复用 10 颗星晶及其网格/材质，角色在物理帧移动，圆形边界限制活动范围，一盏方向光配 1024 阴影，纯色角色材质，无大贴图或骨骼求解。数字计时仅在秒数变化时刷新。

Activity Result 可能早于引擎销毁返回。首页会短暂显示“正在释放游戏资源…”，确认 `:godot_game` 进程退出后才允许再次进入，避免快速连点时复用旧进程。启动中立刻退出时，引擎清理可能需要约 5 秒；页面离开前台后停止检查，返回时继续，不保留 Activity 回调。

Gradle 使用 Android Variant API 注册 PCK 生成目录，`mergeAssets` 自动依赖游戏打包任务。游戏源文件未变化时复用导入缓存与 PCK，不向源码目录写入 APK/PCK。

## Blender 熊猫角色资源

3D 主角已根据用户提供的熊猫形象，在本机 `/Applications/Blender.app` 制作。保留黑白毛色、大眼睛、红色眼周与红色背带裤，补齐双手、双腿、背部和尾巴，去除铅笔、笔记本及夹板。模型是完整立体网格，可以从正面、侧面和背面观察。

运行 GLB 为 **467,048 bytes、25,584 个三角面、6 个网格节点、11 个纯色材质**。网格按动画部件合并，头部、躯干与四肢各自独立，四肢由 GDScript 驱动步行。平滑网格和少量毛簇轮廓用于移动端表现。

用 Blender 打开 `art/panda.blend` 可继续修改。源文件保留独立造型部件与预览灯光、相机；手动导出时仅选择 `Panda` 及其子节点，排除预览地面和灯光。运行文件为 `godot/assets/models/panda.glb`，保留 `LeftLeg`、`RightLeg`、`LeftArm`、`RightArm` 节点名与转轴，Godot 会自动重新导入。脚底为原点，单位为米，glTF +Z 朝前、+Y 朝上。更换层级时相应修改 `star_character_3d.gd`。

重新生成模型并渲染正面、侧前及背面预览：

```bash
/Applications/Blender.app/Contents/MacOS/Blender --background --python-exit-code 1 \
  --python tools/create_panda.py -- --preview
```

此命令会覆盖本项目的 `art/panda.blend`、`panda.glb` 和预览图；请先保存自行修改的模型。模型源文件、参考图片、预览图均在 Godot 工程外，普通 Android 构建直接使用现成 GLB。

[模型预览与编辑说明](art/README.md) · [本轮验收记录](docs/panda-character.md)。原机器人源文件和生成脚本保留，旧运行资源移动至 `art/legacy-robot/`，不随当前 APK 打包。

原有 2D 玩法无需建模。将来替换成复杂 3D 角色时，可使用 glTF/GLB 模型、材质、贴图及骨骼动画，再接入 AnimationTree；Android 宿主、计分与退出契约可继续复用。

游戏已提供精简的 Noto Sans SC 字体。修改中文文案后，运行 `python3 tools/update_game_font.py` 并重建，防止新增文字缺字。正常构建直接使用仓库里的字体，不访问字体服务。

## 验证与许可

按项目约定不编写 Android 单元测试，使用 Godot 检查、Android 编译、Lint 和真机流程验收。3D 玩法也提供真实物理帧集成检查：

```bash
/Applications/Godot.app/Contents/MacOS/Godot --headless --path godot \
  --script "$PWD/tools/verify_3d.gd"
```

当前熊猫版本实测内容见 [熊猫角色验收记录](docs/panda-character.md)。此前的 [机器人 3D 记录](docs/verification-3d.md) 和 [2D 记录](docs/verification.md) 作为历史记录保留。

Godot 使用 MIT 许可；Noto Sans SC 使用 SIL OFL 1.1，字体许可附在 `godot/assets/fonts/OFL.txt`。引擎许可与第三方说明见 [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md)。

参考官方文档：[Android Library](https://docs.godotengine.org/en/stable/tutorials/platform/android/android_library.html)、[Android 插件](https://docs.godotengine.org/en/stable/tutorials/platform/android/android_plugin.html)。