Echo Ark / 《余音》

《余音》是一款关于 AI、声音、死亡、记忆、爱与告别的短篇 3D 叙事策略游戏。

英文名采用 Echo Ark，中文名保留 《余音》。仓库目录为 EchoArk。

本仓库是项目唯一事实源：企划文档、UE 源码、可版本化资产说明、脚本、harness 状态和 agent 交接都在这里维护。

当前设计骨架：3D 方舟主舱室 Hub + 多个俯视角伪 3D 塔防策略关卡。核心设计入口见 docs/design/core-design-blueprint.md。

当前工程开发方向：首个可玩叙事 Demo。目标是在已跑通的 UE 5.7 C++ 工程中，把 3D 方舟 Hub、俯视角策略关卡、WaveEvent 声波战斗、叙事 dialogue、局外成长 / 技能树、可读资产和音频反馈接成闭环。Procedural Ark Hub 仍是长期基座，但不再是唯一阶段目标。

快速开始

git lfs install
./init.sh
./scripts/harness-check.sh

Windows PowerShell 7 equivalent:

git lfs install
./init.ps1
./scripts/harness-check.ps1

当前 UE 工程已位于 game/EchoArk/EchoArk.uproject。它采用已跑通的 UE 5.7 第一人称 C++ 模板作为启动基线，后续正式开发直接在该工程下进行。

UE 工程验证命令：

./scripts/ue/generate-project-files.sh
./scripts/ue/build-editor.sh
./scripts/ue/open-editor.sh

Windows PowerShell 7 equivalent:

./scripts/ue/generate-project-files.ps1
./scripts/ue/build-editor.ps1
./scripts/ue/open-ide.ps1
./scripts/ue/open-editor.ps1

不要手写 .uproject、Target、Build.cs 或默认 C++ 模块来冒充 UE 模板；这些文件必须由 Unreal Editor 生成或由后续明确任务修改。

仓库结构

• AGENTS.md：agent 入口和事实源路由。
• docs/：权威企划、架构说明和资产登记。
• game/EchoArk/：UE app 生成的 Unreal 项目目录。
• SourceAssets/：需要版本化的原始可编辑资产，二进制文件走 Git LFS。
• ExternalAssets/：本地第三方下载包、Marketplace 包、临时导入材料，默认不提交。
• harness/：功能清单、进度、决策、交接、质量门禁。
• plans/active/、plans/archive/：任务合同和归档。
• scripts/：harness 检查和 UE 辅助脚本。

文档地位

docs/index.md

设计文档有效性入口。它说明哪些文档是当前权威，哪些只是参考层，后续 agent 应先用它判断文档职责范围。

docs/design/current-direction.md

当前权威设计方向。它记录当前明确的游戏形态、P0 可玩叙事 Demo、Hub 职责、策略关卡模型、WaveEvent 战斗、局外成长 / 技能树、资产边界、Blueprint-free gameplay 和当前非目标。

docs/design/core-design-blueprint.md

内部开发用核心设计骨架。它保存当前已对齐的世界观、澪音与亚当、余音方舟、声波净化、伪 3D 塔防策略关卡、轮回结构和三结局基点。后续正式概念设计、游戏设计、关卡设计、技术设计和资产规范都应从它派生。

正式分工文档

• docs/design/game-concept.md：游戏概念设计文档，面向评审和新协作者。
• docs/design/game-design-spec.md：游戏设计说明书，描述整体玩法、Hub、关卡、UI、成长和 Demo 骨架。
• docs/design/combat-strategy-system.md：声波战斗、建筑、敌人、资源和构筑系统。
• docs/design/level-design-spec.md：关卡设计说明书，描述章节结构、地图模板、波次方法和首个 Demo 关卡骨架。
• docs/design/narrative-content.md：剧情文案、对白、回响日志和文本数据入口。
• docs/architecture/technical-design.md：游戏技术设计说明书，描述 UE、C++、数据、UI、关卡、存档、风险和验证路线。
• docs/assets/art-asset-spec.md：美术资产规范与清单，描述风格、类型、命名、入库和首批优先级。
• docs/production/atomic-task-list.md：可给队友认领的原子任务清单。

docs/narrative_principles.md

参考层。它记录《余音》为什么成立：现实关怀、价值冲突、故事写法、方舟的大义、余音技术边界、多结局背后的哲学关系。

它不负责当前玩法规格、章节实现清单或第一阶段任务。

docs/principles.md

课程与通用文档规范摘录。它用于提醒企划文档需要回答哪些问题，不是《余音》的故事设定来源。

docs/architecture/

长期工程架构事实。当前包含 UE 工作区布局、模板基线、资产边界和 Ark Hub 架构。

docs/assets/asset-register.md

资产登记表。所有外部来源资产在进入 committed 场景前，都应记录来源、许可证、导入路径和是否入库。

docs/exports/

Markdown 文档的本地导出目录。该目录只提交 .gitignore 占位，导出文件不进入仓库。源内容仍以 docs/*.md 为准。

docs/tmp/

本地临时材料目录，例如原始讨论记录、草稿、导入导出中间文件。该目录只提交 .gitignore 占位，不作为当前权威设定来源。

资产与版本控制

• UE 导入后的项目资产放在 game/EchoArk/Content/。
• 可版本化原始资产放在 SourceAssets/。
• 本地下载包、Marketplace 原始包、Mixamo 临时导出、缓存和试验材料放在 ExternalAssets/，默认 ignore。
• .uasset、.umap、音频、模型、贴图、VRM/FBX/GLB、视频等二进制资产通过 .gitattributes 使用 Git LFS。
• Binaries/、Intermediate/、Saved/、DerivedDataCache/ 等 UE 生成目录不会进入 git。

推荐维护顺序

1. 判断文档有效性时先看 docs/index.md。
2. 讨论当前开发方向时更新 docs/design/current-direction.md。
3. 讨论 Hub 技术架构、程序化生成、交互、渲染管线时更新 docs/architecture/ark-hub.md。
4. 讨论故事哲学和主题边界时参考 docs/narrative_principles.md，但不要把它直接变成实现规格。
5. 讨论工程结构、资产规则或 agent 接手方式时，更新 docs/architecture/、harness/ 和相关脚本。

一句话：docs/index.md 管有效性，docs/design/core-design-blueprint.md 管核心设计源头，正式分工文档管可执行设计骨架，docs/production/atomic-task-list.md 管可认领任务，docs/architecture/ark-hub.md 管 Hub 落地，docs/narrative_principles.md 管哲学和叙事评估原则，harness/ 管跨会话执行状态。