# Homeward

**Repository Path**: eatlesssleepmore/homeward

## Basic Information

- **Project Name**: Homeward
- **Description**: 抖音AI黑客松比赛作品《归途》
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-30
- **Last Updated**: 2026-10-22

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Homeward / 归途 项目交接说明

这是一个 Godot 4 横版 2D 无尽飞行生存游戏原型。玩家操控迁徙小鸟在草地、森林、风雨和未来的夜航/湖泊段落中调整高度、收集食物、躲避风险，并尽量飞得更远。

当前已经从“最小可玩”推进到“路线选择原型”：有正式食物贴图、风雨湿度、基础音效、天气视觉层、地面树/灌木、附着式果实/浆果，以及树干伤害和树枝减速的区别。

## 快速运行

- 引擎：Godot 4.x，`project.godot` 当前标记 `4.6`。
- 主场景：`res://scenes/main.tscn`
- 目标分辨率：`1280x720`
- 运行方式：用 Godot 编辑器打开项目根目录，运行主场景。

## 操作方式

| 输入 | 作用 |
| --- | --- |
| `W` / `Up` | 爬升 |
| `S` / `Down` | 下降 |
| `Space` / 鼠标左键按住 | 加速 |
| `R` | 重开当前局 |

## 当前已实现

- 横向循环滚动背景，并随玩家高度做轻微垂直偏移。
- 玩家小鸟使用 `assets/bird/flying/` 序列帧，当前上下移动速度为 `44m/s`。
- 高度范围 `0m~100m`，玩家横向焦点约在屏幕 43% 处。
- HUD 显示饥饿、高度、距离、时间、风、湿度、天气。
- 完整饥饿消耗骨架：基础消耗乘以风、湿度、高度、加速倍率，再加爬升/下降/加速操作额外消耗。
- 风系统：顺风降低消耗，逆风提高消耗并降低滚动速度；高空更容易遇到顺风，低空更容易遇到逆风。
- 雨系统：云影预警、细雨、中雨、暴雨阶段；羽毛湿度随雨上升，雨停后逐渐下降。
- 天气视觉层：`WeatherLayer` 使用现有雨线、暴雨雾层和压暗叠层。
- 基础音效：开局、食物、撞击、加速、风、雨前预警、Game Over。
- 正式食物贴图：地面昆虫、种子、灌木浆果、树冠幼虫/果实。
- 树和灌木固定贴地生成，不再跟随高度带漂浮。
- 灌木浆果挂在灌木上，树冠幼虫/果实挂在树上。
- 树干碰撞扣饥饿，树枝/树冠碰撞只短暂减速。
- 饥饿归零后 Game Over，按 `R` 重开。

## 暂未实现

- 捕食者系统。
- 诱饵陷阱和控制锁定。
- 夜航阶段和暖/冷光路线。
- 湖泊段落。
- 主菜单、暂停菜单、最佳距离存档。
- 正式 UI 美术替换当前程序化 HUD。
- 音频总线、混音和循环环境声管理。
- Godot 导出配置。

## 核心文件

| 路径 | 说明 |
| --- | --- |
| `project.godot` | 项目配置、主场景、输入映射、窗口设置。 |
| `scenes/main.tscn` | 主场景，包含 `World`、`Spawner`、`Player`、`HUD`、`WeatherLayer`。 |
| `scripts/main.gd` | 局内主流程：饥饿、距离、风雨、湿度、音效、Game Over、重开。 |
| `scripts/player_bird.gd` | 玩家输入、高度、屏幕位置、动画、碰撞、受击闪烁。 |
| `scripts/scrolling_world.gd` | 背景滚动和高度视觉偏移。 |
| `scripts/spawner.gd` | 食物、树、灌木生成；附着式果实/浆果；障碍事件转发。 |
| `scripts/collectible_food.gd` | 可收集食物，支持贴图和附着到父节点。 |
| `scripts/obstacle.gd` | 树/灌木障碍，支持伤害区和树枝减速区。 |
| `scripts/weather_layer.gd` | 天气视觉叠层。 |
| `scripts/hud.gd` | 程序化 HUD 和 Game Over 面板。 |
| `tests/test_minimal_playable_static.py` | 静态测试，守住关键接口和原型规则。 |

## 设计和素材文档

| 路径 | 内容 |
| --- | --- |
| `docs/homeward_game_design.md` | 英文玩法设计规格。 |
| `docs/归途_游戏设计规格.md` | 中文玩法设计规格。 |
| `docs/归途_美术风格设定.md` | 中文美术风格设定。 |
| `docs/art_asset_overview.md` | 美术资产总览、优先级和命名建议。 |
| `assets/audio/AUDIO_USAGE_MAP.md` | 音频使用建议。 |
| `assets/audio/sfx/gameplay/GAMEPLAY_SFX_MAP.md` | 游戏内音效映射。 |

## 测试

当前测试是 Python 静态测试，不依赖启动 Godot：

```powershell
python -m unittest tests/test_minimal_playable_static.py
```

Godot 命令目前不在当前终端 PATH 中，因此提交前主要依赖静态测试。运行体验仍建议在 Godot 编辑器中手动验证。

## Git 注意事项

工作区里常有大量 `.import` 文件变更，这是 Godot 编辑器导入资源产生的。提交时建议拆分：

- 代码、场景、测试、文档单独提交。
- 资源导入和 `.import` 文件单独提交。
- 不要随手回滚别人或编辑器生成的 `.import` 文件，先确认来源。

## 下一步建议

1. 在 Godot 里手测树/灌木贴地、附着食物位置、树枝减速区和树干伤害区。
2. 微调树干/树冠碰撞框，确保“穿树枝只减速”足够公平。
3. 实现诱饵陷阱，因为当前地面路线已经有食物和灌木基础。
4. 加入暂停菜单和最佳距离存档，提高可测试性。
5. 再做捕食者或夜航系统，进入 V0.3/V0.4 风险层。