aibis-dream/CLAUDE.md

CLAUDE.md

Claude Code 与 Cursor 的项目上下文，对话开始时自动加载。

项目概览

AIBIS Dream（又名 AllOurBrokenParts）是一款基于 Unity 的叙事冒险游戏，带有调查元素。使用 Yarn Spinner 管理对话，采用自定义模块化框架，包含多个小游戏（核心之一是火山 HuoShan 的语言粒子系统）。

Unity 版本： Unity 2022.3.x LTS（Universal Render Pipeline）

架构

核心框架（Assets/Scripts/Framework/）

• ActionKit：动作序列与命令模式
• AudioKit：音频管理与音效
• Config：配置与设置
• Core：核心系统与工具
• EventSystemKit：解耦事件系统
• PoolKit：对象池
• ResourceKit：资源加载
• SingletonKit：单例基类
• StateMachineKit：状态机
• TimelineKit：Timeline 事件序列

主要游戏系统

• Dialog System（Assets/Scripts/Dialog System/）：Yarn Spinner 对话
• Clue System（Assets/Scripts/Clue/）：调查与证据收集
• MiniGame System（Assets/Scripts/MiniGame/）：小游戏框架
  • HuoShan（火山）：语言粒子系统，用于情绪表达玩法
• SceneManagement：场景与流程
• FixSystem：互动维修/解谜

Web 原型

位于 web-prototype/ 与 WebPrototype/，用于在 Unity 实现前验证玩法。

设计文档（Docs）

任何开发工作，按需阅读对应的设计文档。 文档采用单源真相，定义只维护一份。

索引	说明
Docs/HuoShan/INDEX.md	火山文档入口

常用开发命令

Unity 构建

# Windows 64-bit
"C:\Program Files\Unity\Hub\Editor\2022.3.x\Editor\Unity.exe" -batchmode -quit -projectPath . -buildWindows64Player "Build/AIBIS_Dream.exe" -logFile Build/log.txt

# WebGL
"C:\Program Files\Unity\Hub\Editor\2022.3.x\Editor\Unity.exe" -batchmode -quit -projectPath . -executeMethod BuildScript.WebGL -logFile Build/webgl_log.txt

资源与工程

# 重新生成 Visual Studio 工程
Assets\Open C# Project.regenerate-sln.bat
# 刷新资源库：菜单 Assets > Refresh 或 Ctrl+R

关键依赖

Unity 包

• Yarn Spinner、TextMesh Pro、URP、2D Animation、Cinemachine、Timeline、Localization

第三方资源

• More Mountains Feedbacks、FMOD、DOTween、Shapes、QFramework、Destructible 2D

开发规范

代码组织

1. 各系统放在 Assets/Scripts/ 下独立文件夹
2. 可复用工具以 Kit 后缀放在 Framework/
3. 全局管理类使用 Singleton
4. 组件优先于继承

场景结构

• 场景在 Assets/Scenes/
• 主场景命名：{角色}_{Day}{时间}（如 Fiction_Day1_begin）
• 小游戏场景：HuoShan*、languageTest* 等
• 需加入 EditorBuildSettings

Yarn 对话文件

• 位于 Assets/Resources/Yarn/，按角色与日期组织
• 文件命名：{角色}_{阶段}.yarn
• 使用 UTF-8

资源命名

• 脚本：PascalCase，带用途（如 DialogController.cs）
• Prefab：PascalCase 加类型后缀
• 场景：Snake_Case
• Resources：按系统/类型分组

配置要点

编辑器

• 文本编码：UTF-8（尤其中文）
• 行尾：C# 使用 Windows (CRLF)，保持一致

构建

• 平台：Windows、WebGL
• Scripting Backend：IL2CPP（Windows）、Emscripten（WebGL）
• API：.NET Standard 2.1

Git

• LFS：大文件（.unity、贴图、音频）
• 忽略：Library/、Temp/、Logs/、Build/、*.csproj.user

测试与迭代

小游戏独立测试

• 火山语言游戏：Assets/Scenes/languageTest.unity
• 火山维修：Assets/Scenes/HuoShanFixScene.unity
• 表情测试：Assets/Scenes/HuoShanExpressionTest.unity

Web 原型

1. 在 web-prototype/ 建 HTML/JS 原型
2. 逻辑与 Unity 实现保持一致
3. 浏览器快速验证

常见任务

新增小游戏

1. 建文件夹 Assets/Scripts/MiniGame/{名称}/
2. 用 Framework 实现逻辑
3. 建测试场景 {名称}Test.unity
4. 资源放 Assets/Resources/{名称}/
5. 在 README_{名称}.md 中记录

添加 Yarn 对话

1. 在 Assets/Resources/Yarn/{角色}/ 建 .yarn
2. 通过 Resources.Load 加载
3. 挂到场景的 DialogueRunner
4. 用 DialogueController 测试

调试

• LogKit 做分类日志
• ProjectSettings/LogKit 可调详细级别
• 粒子多时用 Unity Profiler 排查

性能

• 频繁创建对象用 PoolKit
• 资源加载用 ResourceKit 异步
• 粒子系统注意 overdraw
• 音效用池，复杂音频用 FMOD

重要提醒

• 以叙事为核心，对话和剧情优先
• 火山语言粒子是核心玩法，改动需保持情绪表达逻辑
• Web 原型仅供验证，正式实现用 Unity/C#
• 保持 Windows 与 WebGL 兼容
• 开发前按需读 Docs/ 下对应索引，避免与设计偏离