Cursor
@@ -1,185 +1,174 @@
|
||||
# CLAUDE.md
|
||||
|
||||
Shared project context for **Claude Code** and **Cursor**. Both tools auto-load this file at conversation start.
|
||||
Claude Code 与 Cursor 的项目上下文，对话开始时自动加载。
|
||||
|
||||
## Project Overview
|
||||
## 项目概览
|
||||
|
||||
AIBIS Dream (also known as "AllOurBrokenParts") is a Unity-based narrative adventure game with investigative elements. The project uses Yarn Spinner for dialogue, features a custom framework with modular systems, and includes multiple mini-games (notably the HuoShan/Volcano language particle system).
|
||||
AIBIS Dream（又名 AllOurBrokenParts）是一款基于 Unity 的叙事冒险游戏，带有调查元素。使用 Yarn Spinner 管理对话，采用自定义模块化框架，包含多个小游戏（核心之一是火山 HuoShan 的语言粒子系统）。
|
||||
|
||||
**Unity Version:** Unity 2022.3.x LTS (Universal Render Pipeline)
|
||||
**Unity 版本：** Unity 2022.3.x LTS（Universal Render Pipeline）
|
||||
|
||||
## Architecture
|
||||
## 架构
|
||||
|
||||
### Core Framework (Assets/Scripts/Framework/)
|
||||
### 核心框架（Assets/Scripts/Framework/）
|
||||
|
||||
The project uses a custom modular framework with these key systems:
|
||||
- **ActionKit**：动作序列与命令模式
|
||||
- **AudioKit**：音频管理与音效
|
||||
- **Config**：配置与设置
|
||||
- **Core**：核心系统与工具
|
||||
- **EventSystemKit**：解耦事件系统
|
||||
- **PoolKit**：对象池
|
||||
- **ResourceKit**：资源加载
|
||||
- **SingletonKit**：单例基类
|
||||
- **StateMachineKit**：状态机
|
||||
- **TimelineKit**：Timeline 事件序列
|
||||
|
||||
- **ActionKit**: Action sequencing and command pattern implementation
|
||||
- **AudioKit**: Audio management and sound effect system
|
||||
- **Config**: Game configuration and settings management
|
||||
- **Core**: Core game systems and utilities
|
||||
- **EventSystemKit**: Decoupled event system for inter-system communication
|
||||
- **PoolKit**: Object pooling for performance optimization
|
||||
- **ResourceKit**: Asset loading and resource management
|
||||
- **SingletonKit**: Singleton base classes for managers
|
||||
- **StateMachineKit**: Game state management
|
||||
- **TimelineKit**: Timeline-based event sequencing
|
||||
### 主要游戏系统
|
||||
|
||||
### Key Game Systems
|
||||
- **Dialog System**（Assets/Scripts/Dialog System/）：Yarn Spinner 对话
|
||||
- **Clue System**（Assets/Scripts/Clue/）：调查与证据收集
|
||||
- **MiniGame System**（Assets/Scripts/MiniGame/）：小游戏框架
|
||||
- **HuoShan（火山）**：语言粒子系统，用于情绪表达玩法
|
||||
- **SceneManagement**：场景与流程
|
||||
- **FixSystem**：互动维修/解谜
|
||||
|
||||
- **Dialog System** (Assets/Scripts/Dialog System/): Yarn Spinner integration for narrative flow
|
||||
- **Clue System** (Assets/Scripts/Clue/): Investigation and evidence collection mechanics
|
||||
- **MiniGame System** (Assets/Scripts/MiniGame/): Modular mini-game framework
|
||||
- **HuoShan** (Volcano): Language particle system for emotional expression gameplay
|
||||
- **SceneManagement**: Scene flow control and transitions
|
||||
- **FixSystem**: Interactive repair/puzzle mechanics
|
||||
### Web 原型
|
||||
|
||||
### Web Prototypes
|
||||
位于 `web-prototype/` 与 `WebPrototype/`，用于在 Unity 实现前验证玩法。
|
||||
|
||||
Located in `web-prototype/` and `WebPrototype/` directories, these contain HTML/JavaScript prototypes for testing game mechanics before Unity implementation.
|
||||
### 设计文档（Docs）
|
||||
|
||||
### Design Documentation
|
||||
**任何开发工作，按需阅读对应的设计文档。** 文档采用单源真相，定义只维护一份。
|
||||
|
||||
Located in `Docs/`, scenario design documents for character repair flows:
|
||||
- `Docs/HuoShan/` - 火山维修场景，单源索引见 `INDEX.md`，核心在 `core/`，探索在 `_branches/`
|
||||
| 索引 | 说明 |
|
||||
|------|------|
|
||||
| `Docs/HuoShan/INDEX.md` | 火山文档入口 |
|
||||
|
||||
## Key Development Commands
|
||||
## 常用开发命令
|
||||
|
||||
### Unity Build Process
|
||||
### Unity 构建
|
||||
|
||||
```bash
|
||||
# Build for Windows (64-bit)
|
||||
# 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
|
||||
|
||||
# Build for WebGL
|
||||
# WebGL
|
||||
"C:\Program Files\Unity\Hub\Editor\2022.3.x\Editor\Unity.exe" -batchmode -quit -projectPath . -executeMethod BuildScript.WebGL -logFile Build/webgl_log.txt
|
||||
```
|
||||
|
||||
### Asset Import and Generation
|
||||
### 资源与工程
|
||||
|
||||
```bash
|
||||
# Regenerate solution files (Visual Studio)
|
||||
# 重新生成 Visual Studio 工程
|
||||
Assets\Open C# Project.regenerate-sln.bat
|
||||
|
||||
# Refresh asset database
|
||||
# (Use Unity Editor menu: Assets > Refresh or Ctrl+R)
|
||||
# 刷新资源库：菜单 Assets > Refresh 或 Ctrl+R
|
||||
```
|
||||
|
||||
## Critical Dependencies
|
||||
## 关键依赖
|
||||
|
||||
### Unity Packages (via Package Manager)
|
||||
- **Yarn Spinner**: Dialogue system (dev.yarnspinner.unity)
|
||||
- **TextMesh Pro**: Text rendering and typography
|
||||
- **Universal Render Pipeline**: Graphics rendering
|
||||
- **2D Animation**: Sprite-based animation tools
|
||||
- **Cinemachine**: Camera system
|
||||
- **Timeline**: Cinematic sequencing
|
||||
- **Localization**: Multi-language support
|
||||
### Unity 包
|
||||
|
||||
### Third-Party Assets
|
||||
- **More Mountains Feedbacks**: Game feel and feedback system
|
||||
- **FMOD**: Advanced audio engine
|
||||
- **DOTween**: Tweening and animation
|
||||
- **Shapes**: Vector graphics and shapes rendering
|
||||
- **QFramework**: Additional utility framework
|
||||
- **Destructible 2D**: 2D destruction mechanics
|
||||
- Yarn Spinner、TextMesh Pro、URP、2D Animation、Cinemachine、Timeline、Localization
|
||||
|
||||
## Development Guidelines
|
||||
### 第三方资源
|
||||
|
||||
### Code Organization
|
||||
- More Mountains Feedbacks、FMOD、DOTween、Shapes、QFramework、Destructible 2D
|
||||
|
||||
1. **Modular Systems**: Each major system should be self-contained in its own folder under `Assets/Scripts/`
|
||||
2. **Kit Pattern**: Reusable utilities go in `Framework/` with "Kit" suffix
|
||||
3. **Manager Classes**: Use Singleton pattern for global managers (derived from `SingletonKit`)
|
||||
4. **Component Design**: Favor composition over inheritance for game objects
|
||||
## 开发规范
|
||||
|
||||
### Scene Structure
|
||||
### 代码组织
|
||||
|
||||
- Scenes are located in `Assets/Scenes/`
|
||||
- Main scenes use naming convention: `{Character}_{Day}{Time}` (e.g., `Fiction_Day1_begin`)
|
||||
- Mini-game scenes start with prefix: `HuoShan*`, `languageTest*`, etc.
|
||||
- Always configure scenes in `EditorBuildSettings` for proper loading
|
||||
1. 各系统放在 `Assets/Scripts/` 下独立文件夹
|
||||
2. 可复用工具以 Kit 后缀放在 `Framework/`
|
||||
3. 全局管理类使用 Singleton
|
||||
4. 组件优先于继承
|
||||
|
||||
### Yarn Dialogue Files
|
||||
### 场景结构
|
||||
|
||||
Located in `Assets/Resources/Yarn/`, organized by character and day:
|
||||
- Each character has their own folder
|
||||
- Files follow pattern: `{Character}_{Stage}.yarn`
|
||||
- Use UTF-8 encoding for Chinese text support
|
||||
- 场景在 `Assets/Scenes/`
|
||||
- 主场景命名：`{角色}_{Day}{时间}`（如 `Fiction_Day1_begin`）
|
||||
- 小游戏场景：`HuoShan*`、`languageTest*` 等
|
||||
- 需加入 EditorBuildSettings
|
||||
|
||||
### Asset Naming Conventions
|
||||
### Yarn 对话文件
|
||||
|
||||
- **Scripts**: PascalCase with component purpose (e.g., `DialogController.cs`)
|
||||
- **Prefabs**: PascalCase with type suffix (e.g., `ClueItem.prefab`)
|
||||
- **Scenes**: Snake_Case with descriptive names
|
||||
- **Resources**: Organize by system/type in `Assets/Resources/`
|
||||
- 位于 `Assets/Resources/Yarn/`，按角色与日期组织
|
||||
- 文件命名：`{角色}_{阶段}.yarn`
|
||||
- 使用 UTF-8
|
||||
|
||||
## Important Configuration
|
||||
### 资源命名
|
||||
|
||||
### Editor Settings
|
||||
- **Text Encoding**: All text files must use UTF-8 (especially for Chinese)
|
||||
- **Line Endings**: Windows (CRLF) for C# files, but be consistent
|
||||
- **Visual Studio**: Use provided `.sln` and `.csproj` files
|
||||
- **脚本**：PascalCase，带用途（如 `DialogController.cs`）
|
||||
- **Prefab**：PascalCase 加类型后缀
|
||||
- **场景**：Snake_Case
|
||||
- **Resources**：按系统/类型分组
|
||||
|
||||
### Build Settings
|
||||
- **Target Platform**: Primarily Windows and WebGL
|
||||
- **Scripting Backend**: IL2CPP for Windows, Emscripten for WebGL
|
||||
- **API Compatibility**: .NET Standard 2.1
|
||||
## 配置要点
|
||||
|
||||
### Git Configuration
|
||||
- **LFS**: Used for large binary assets (.unity, textures, audio)
|
||||
- **Ignored**: Library/, Temp/, Logs/, Build/, *.csproj.user
|
||||
### 编辑器
|
||||
|
||||
## Testing and Iteration
|
||||
- 文本编码：UTF-8（尤其中文）
|
||||
- 行尾：C# 使用 Windows (CRLF)，保持一致
|
||||
|
||||
### Running Individual Mini-Games
|
||||
### 构建
|
||||
|
||||
Most mini-genes can be tested independently by opening their specific scene:
|
||||
- HuoShan Language Game: `Assets/Scenes/languageTest.unity`
|
||||
- HuoShan Fix Scene: `Assets/Scenes/HuoShanFixScene.unity`
|
||||
- Expression Test: `Assets/Scenes/HuoShanExpressionTest.unity`
|
||||
- 平台：Windows、WebGL
|
||||
- Scripting Backend：IL2CPP（Windows）、Emscripten（WebGL）
|
||||
- API：.NET Standard 2.1
|
||||
|
||||
### Web Prototyping
|
||||
### Git
|
||||
|
||||
For testing mechanics before Unity implementation:
|
||||
1. Create HTML/JS prototype in `web-prototype/`
|
||||
2. Use similar logic to planned Unity implementation
|
||||
3. Test in browser for rapid iteration
|
||||
- LFS：大文件（.unity、贴图、音频）
|
||||
- 忽略：Library/、Temp/、Logs/、Build/、*.csproj.user
|
||||
|
||||
## Common Development Tasks
|
||||
## 测试与迭代
|
||||
|
||||
### Adding a New Mini-Game
|
||||
### 小游戏独立测试
|
||||
|
||||
1. Create folder in `Assets/Scripts/MiniGame/{GameName}/`
|
||||
2. Implement game logic using Framework kits
|
||||
3. Create test scene in `Assets/Scenes/{GameName}Test.unity`
|
||||
4. Add required assets to `Assets/Resources/{GameName}/`
|
||||
5. Document in `README_{GameName}.md`
|
||||
- 火山语言游戏：`Assets/Scenes/languageTest.unity`
|
||||
- 火山维修：`Assets/Scenes/HuoShanFixScene.unity`
|
||||
- 表情测试：`Assets/Scenes/HuoShanExpressionTest.unity`
|
||||
|
||||
### Adding Yarn Dialogue
|
||||
### Web 原型
|
||||
|
||||
1. Create `.yarn` file in appropriate `Assets/Resources/Yarn/{Character}/` folder
|
||||
2. Add file to Resources using Unity's `Resources.Load` system
|
||||
3. Reference in scene's `DialogueRunner` component
|
||||
4. Test with `DialogueController`
|
||||
1. 在 `web-prototype/` 建 HTML/JS 原型
|
||||
2. 逻辑与 Unity 实现保持一致
|
||||
3. 浏览器快速验证
|
||||
|
||||
### Debugging Tips
|
||||
## 常见任务
|
||||
|
||||
- Use `LogKit` for consistent logging with categories
|
||||
- Enable verbose logging in `ProjectSettings/LogKit`
|
||||
- Use Unity's frame debugger for rendering issues
|
||||
- Profile with Unity Profiler, especially for mini-games with many particles
|
||||
### 新增小游戏
|
||||
|
||||
## Performance Considerations
|
||||
1. 建文件夹 `Assets/Scripts/MiniGame/{名称}/`
|
||||
2. 用 Framework 实现逻辑
|
||||
3. 建测试场景 `{名称}Test.unity`
|
||||
4. 资源放 `Assets/Resources/{名称}/`
|
||||
5. 在 `README_{名称}.md` 中记录
|
||||
|
||||
- **Pooling**: Always use PoolKit for frequently instantiated objects (particles, UI elements)
|
||||
- **Asset Loading**: Use ResourceKit for async loading to avoid frame drops
|
||||
- **Particle Systems**: Pool particle systems, limit overdraw in language particle game
|
||||
- **Audio**: Use object pooling for frequent SFX, FMOD for advanced audio
|
||||
### 添加 Yarn 对话
|
||||
|
||||
## Important Notes
|
||||
1. 在 `Assets/Resources/Yarn/{角色}/` 建 `.yarn`
|
||||
2. 通过 Resources.Load 加载
|
||||
3. 挂到场景的 DialogueRunner
|
||||
4. 用 DialogueController 测试
|
||||
|
||||
- This is a narrative-focused game - ensure dialogue and story take precedence
|
||||
- The HuoShan language particle system is a core feature - changes should maintain the emotional expression mechanics
|
||||
- Web prototypes are for testing only - production code must be in Unity/C#
|
||||
- Maintain compatibility with both Windows and WebGL builds
|
||||
### 调试
|
||||
|
||||
- LogKit 做分类日志
|
||||
- ProjectSettings/LogKit 可调详细级别
|
||||
- 粒子多时用 Unity Profiler 排查
|
||||
|
||||
## 性能
|
||||
|
||||
- 频繁创建对象用 PoolKit
|
||||
- 资源加载用 ResourceKit 异步
|
||||
- 粒子系统注意 overdraw
|
||||
- 音效用池，复杂音频用 FMOD
|
||||
|
||||
## 重要提醒
|
||||
|
||||
- 以叙事为核心，对话和剧情优先
|
||||
- 火山语言粒子是核心玩法，改动需保持情绪表达逻辑
|
||||
- Web 原型仅供验证，正式实现用 Unity/C#
|
||||
- 保持 Windows 与 WebGL 兼容
|
||||
- **开发前按需读 `Docs/` 下对应索引，避免与设计偏离**
|
||||
|
||||
Reference in New Issue
Block a user