tinbird/aibis-dream
5
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: 更新 CLAUDE.md 项目指南

Browse Source
This commit is contained in:
dingyuntian
2026-04-15 22:23:40 +08:00
parent 0c7d4952a6
commit 3918fbce98
1 changed files with 86 additions and 145 deletions
Download Patch File Download Diff File Expand all files Collapse all files
CLAUDE.md
+86 -145
View File
@@ -1,192 +1,133 @@
# CLAUDE.md
# CLAUDE.md
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
## 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 (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 and a modular repair/fix system.
**Unity Version:** Unity 2022.3.x LTS (Universal Render Pipeline)
**Unity Version:** 2022.3.7f1c1 (Universal Render Pipeline)
## Architecture
### Core Framework (Assets/Scripts/Framework/)
The project uses a custom modular framework with these key systems:
Modular framework with Kit-pattern utilities:
- **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
- **Note**: New code should use `ResourceSystem` (via Addressables), see [Resource Loading Best Practices Guide](Docs/ResourceLoadingBestPractices.md) for details. **Where assets live on disk** (e.g. `GameContent/`, `Narrative/`) is defined in [Resource Management Spec](Docs/ResourceManagementSpec.md).
- **SingletonKit**: Singleton base classes for managers
- **StateMachineKit**: Game state management
- **TimelineKit**: Timeline-based event sequencing
- **ActionKit**: Action sequencing and command pattern
- **AudioKit**: Audio management (includes FMOD integration)
- **Config / Core**: Configuration and core utilities
- **EventSystemKit**: Decoupled event system
- **LogKit**: Structured logging with categories
- **PoolKit**: Object pooling
- **ResourceKit**: Asset loading via `ResourceSystem` (Addressables-based)
- **Note**: New code must use `ResourceSystem`, never `Resources.Load`. See [Resource Loading Best Practices](Docs/ResourceLoadingBestPractices.md). Asset placement rules in [Resource Management Spec](Docs/ResourceManagementSpec.md).
- **SelectorKit**: Weighted/batch/non-repeat random selection
- **SingletonKit**: Singleton base classes
- **StateMachineKit**: State management
- **OtherKit**: Miscellaneous utilities (`CameraKit`, `AnimatorKit`, `FadeKit`, `LocalizationKit`, etc.)
- **Attribute**: Custom editor attributes
### Key Game Systems
- **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
- **Game Loop** (Scripts/Game Loop/): `GameManager` (Singleton entry), `StorageSystem` (save + Yarn variables), `SceneLoader`, `ChapterController`, `TalkSceneSO`
- **Dialog System** (Scripts/Dialog System/): Yarn Spinner integration — `DialogController`, `LineRunner`, `LocalisedLineProvider`, `BaseYarnCommand`
- **SceneManagement** (Scripts/SceneManagement/): `ActorKit/`, `AnimatorKit/`, `EnvironmentKit/`, `SpawnerKit/`, `TimelineKit/`, `SceneCenter/`, `DreamDoorSystem`
- **UI** (Scripts/UI/): `DialogUI/`, `Panel/`, `Form/`, `Components/`, `Cursor/`, `UIManager`
- **MiniGame** (Scripts/MiniGame/): `HuoShan/` (language particles, EmotionWave), `BlockPuzzle/`, `Peipei/` (Eye, CutLine, Memory)
- **FixSystem** (Scripts/FixSystem/): Legacy — HeatMap, PunchTape, Memory, screen effects
- **FixSystemNew** (Scripts/FixSystemNew/): Active repair system — `FixSystemCenter`, `BodyModule/`, `Cable/`, `WhackMole/`, `Screen System/`, `Open/`, `Clinic/`
- **AssetRefs** (Scripts/AssetRefs/): Addressable key constants (`ConstRef`, `FixAssetRef`, `TimelineAssetRef`)
### Web Prototypes
### Content & Localization
Located in `web-prototype/` and `WebPrototype/` directories, these contain HTML/JavaScript prototypes for testing game mechanics before Unity implementation.
## Key Development Commands
### Unity Build Process
```bash
# Build for 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
"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)
Assets\Open C# Project.regenerate-sln.bat
# Refresh asset database
# (Use Unity Editor menu: Assets > Refresh or Ctrl+R)
```
- **Assets/GameContent/**: Runtime assets by scope (`Common/`, `UI/`, `Scene_{Name}/`, `Feature_{Name}/`)
- **Assets/Language/**: Unity Localization tables (`Dialog/`, `ActorName/`, `UIText/`, `Locales/`, `Sprite/`)
- **Assets/Resources/Yarn/**: Current Yarn dialogue files (target migration to `Assets/Narrative/` per spec, not yet complete)
- **Assets/Prototype/**: HTML/JS prototypes for mechanic testing
## 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 Packages
- **Yarn Spinner** 2.4.2 (OpenUPM), **Addressables** 1.21.21, **Cinemachine** 2.9.7
- **URP** 14.0.8, **TextMesh Pro** 3.0.6, **Timeline** 1.7.5, **Localization** 1.4.5
- **Visual Effect Graph** 14.0.8, **Visual Scripting** 1.8.0
### 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
- **Destructible 2D**: 2D destruction mechanics
### Third-Party
- **FMOD** (audio engine), **DOTween** (tweening), **Shapes** (vector graphics)
- **More Mountains Feedbacks** (game feel), **Destructible 2D**
## Development Guidelines
### Code Organization
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
1. Each major system self-contained in its own folder under `Assets/Scripts/`
2. Kit-pattern utilities in `Framework/` — reusable across systems
3. Singleton pattern for global managers (derived from `SingletonKit`)
4. Favor composition over inheritance
5. All runtime asset loading via `ResourceSystem` — never `Resources.Load`
### Scene Structure
- Scenes in `Assets/Scenes/`; `Persistence` scene hosts global managers and Persistent Loader
- Fix scenes: `{Character}FixScene` (e.g. `HuoShanFixScene`, `PeipeiFixScene`, `ExpressFixScene`)
- Test scenes: `languageTest`, `HuoShanExpressionTest`, `wavetest`, etc.
- 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
### Addressables
- Config in `Assets/AddressableAssetsData/`; Groups: `Core`, `Scene_*`, `Feature_*`, `Shared_*`, `Localization-*`
- Key format: `Category/Path` (e.g. `Animation/Peipei`, `Timeline/BlockPuzzle/PanelOpen`)
- Scene keys use bare PascalCase names (e.g. `ClinicOut`)
- Details in [Resource Loading Best Practices](Docs/ResourceLoadingBestPractices.md)
### Yarn Dialogue Files
- Current path: `Assets/Resources/Yarn/` (migration to `Assets/Narrative/Yarn/` planned)
- Pattern: `{Character}_{Stage}.yarn`; UTF-8 encoding required for Chinese
Target layout and co-location with Dialog localization tables: [Resource Management Spec](Docs/ResourceManagementSpec.md) (`Assets/Narrative/Yarn/`, `Assets/Narrative/Localization/`). Legacy paths may still include `Assets/Resources/Yarn/` during migration.
### Asset Naming
- **Scripts**: PascalCase (e.g. `DialogController.cs`)
- **Addressable Keys**: `Category/Path` — no spaces, no extensions, ≤3 levels
- **Addressable Groups**: `{Type}_{PascalCaseName}`
Convention for file naming and UTF-8:
- Organize by narrative module / character and day as the project requires
- Files often follow pattern: `{Character}_{Stage}.yarn`
- Use UTF-8 encoding for Chinese text support
### Git & Commits
- LFS for large binaries; ignored: Library/, Temp/, Build/, *.csproj, *.sln
- **Commit format**: `<type>(<scope>): <subject>` — subject in Chinese, type/scope in English
- Extended types: `feat`, `fix`, `art`, `audio`, `scene`, `yarn`, `perf`, `refactor`, `style`, `docs`, `build`, `chore`, `test`
- See [COMMIT_CONVENTION.md](COMMIT_CONVENTION.md) for full details
### Asset Naming Conventions
## Key Build Commands
- **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/`
```bash
# Windows build
"C:\Program Files\Unity\Hub\Editor\2022.3.7f1c1\Editor\Unity.exe" -batchmode -quit -projectPath . -buildWindows64Player "Build/AIBIS_Dream.exe" -logFile Build/log.txt
```
## 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
### 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
- **Commit Convention**: See [COMMIT_CONVENTION.md](COMMIT_CONVENTION.md) for commit message format and branch naming rules. All commits must follow `<type>(<scope>): <subject>` format.
## Testing and Iteration
### 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`
### Web Prototyping
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
## Common Development Tasks
## Common 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`
1. Create `Assets/Scripts/MiniGame/{GameName}/`
2. Add assets to `Assets/GameContent/Feature_{GameName}/`
3. Create Addressable Group `Feature_{GameName}`
4. Create test scene in `Assets/Scenes/`
### Adding Yarn Dialogue
1. Create `.yarn` in `Assets/Resources/Yarn/{Module}/`
2. Add Dialog string tables in `Assets/Language/Dialog/`
3. Reference in scene's `DialogueRunner`; test with `DialogController`
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`
### 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
- **Pooling**: Always use PoolKit for frequently instantiated objects (particles, UI elements)
- **Asset Loading**: Use ResourceKit for async loading to avoid frame drops.
See [Resource Loading Best Practices Guide](Docs/ResourceLoadingBestPractices.md) for detailed specifications including Group/Key/Label naming and preloading strategies.
- **Particle Systems**: Pool particle systems, limit overdraw in language particle game
- **Audio**: Use object pooling for frequent SFX, FMOD for advanced audio
## Debugging & Performance
- `LogKit` for structured logging; Addressables Event Viewer for resource debugging
- Monitor `SceneResourceLoader.TotalHandleCount` for leak detection
- Always use PoolKit for frequent instantiation; `LoadUncachedAsync` + `EarlyRelease` for large Timeline assets
- Use `LoadAsync<GameObject>` + `Instantiate` for prefabs, never `InstantiateAsync`
## Important Notes
- 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#
- Narrative-focused game — dialogue and story take precedence
- `FixSystemNew` is the active repair architecture; `FixSystem` is legacy
- `StorageSystem` serves as both save system and Yarn variable storage
## Reference Documents
- [Resource Loading Best Practices Guide](Docs/ResourceLoadingBestPractices.md) - How to load assets: `ResourceSystem`, Addressables Key/Group/Label, lifecycle and performance
- [Resource Management Spec](Docs/ResourceManagementSpec.md) - Where to place assets: `GameContent/`, `Narrative/` (Yarn + Dialog tables), `_Archive/`, and exceptions (distinct from loading mechanics above)
- [Commit Convention](COMMIT_CONVENTION.md) - Git commit message format and branch naming rules
- [Resource Loading Best Practices](Docs/ResourceLoadingBestPractices.md) — `ResourceSystem` API, Key/Group/Label naming, lifecycle
- [Resource Management Spec](Docs/ResourceManagementSpec.md) — Asset placement: `GameContent/`, `Narrative/`, `_Archive/`
- [Commit Convention](COMMIT_CONVENTION.md) — Commit message format and branch naming
- [HuoShan Docs](Docs/HuoShan/) — Narrative flow, resources, test flowcharts
---