153 lines
8.3 KiB
Markdown
153 lines
8.3 KiB
Markdown
# 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 and a modular repair/fix system.
|
|
|
|
**Unity Version:** 2022.3.7f1c1 (Universal Render Pipeline)
|
|
|
|
## Architecture
|
|
|
|
### Core Framework (Assets/Scripts/Framework/)
|
|
|
|
Modular framework with Kit-pattern utilities:
|
|
|
|
- **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
|
|
|
|
- **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`)
|
|
|
|
### Content & Localization
|
|
|
|
- **Assets/GameContent/**: Runtime assets by scope (`Common/`, `UI/`, `Scene_{Name}/`, `Feature_{Name}/`)
|
|
- **Assets/Language/**: Unity Localization tables (runtime active: `UIText/`, `Locales/`, `Sprite/`; `Dialog/`、`ActorName/`、`Params/` currently kept as migration backups)
|
|
- **Assets/Resources/Yarn/**: Current Yarn dialogue files (target migration to `Assets/Narrative/` per spec, not yet complete)
|
|
- **Assets/StreamingAssets/Config/**: CSV-driven localized gameplay data (`character.csv` for actor names, `params.csv` for `l10n.*` substitution terms)
|
|
- **Assets/Prototype/**: HTML/JS prototypes for mechanic testing
|
|
|
|
## Critical Dependencies
|
|
|
|
### 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
|
|
- **FMOD** (audio engine), **DOTween** (tweening), **Shapes** (vector graphics)
|
|
- **More Mountains Feedbacks** (game feel), **Destructible 2D**
|
|
|
|
## Development Guidelines
|
|
|
|
### Code Organization
|
|
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.
|
|
|
|
### 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
|
|
|
|
#### Yarn Line Tag Maintenance
|
|
- **Line tags** (`#line:xxxxxxx`) must be unique across the entire file. Duplicate tags break Yarn Spinner localization.
|
|
- Duplicates typically occur when copying an existing node to create a variant (e.g. `地铁ver1` → `地铁ver3`).
|
|
- **Use the dedup tool** (`Tools/dedup_yarn_tags.py`) for bulk cleanup:
|
|
```bash
|
|
# Preview duplicates from a specific node onward
|
|
python Tools/dedup_yarn_tags.py Assets/Resources/Yarn/Fiction_Day1_begin/Fiction_Day1_begin.yarn --from-node 地铁ver4
|
|
# Fix duplicates from a specific line onward
|
|
python Tools/dedup_yarn_tags.py Assets/Resources/Yarn/Fiction_Day1_begin/Fiction_Day1_begin.yarn --from-line 535 --fix
|
|
# Scan an entire directory (preview only)
|
|
python Tools/dedup_yarn_tags.py Assets/Resources/Yarn/ --scan-all
|
|
```
|
|
|
|
#### Yarn Script Generation
|
|
- **Do NOT add `#line:` tags when generating or editing Yarn dialogue.** Leave all line-tag generation to the user's localization workflow (Unity Localization + Yarn Spinner import tools).
|
|
- When creating new `.yarn` files, write plain dialogue lines without any `#line:` suffixes.
|
|
|
|
### Asset Naming
|
|
- **Scripts**: PascalCase (e.g. `DialogController.cs`)
|
|
- **Addressable Keys**: `Category/Path` — no spaces, no extensions, ≤3 levels
|
|
- **Addressable Groups**: `{Type}_{PascalCaseName}`
|
|
|
|
### 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
|
|
|
|
## Key Build Commands
|
|
|
|
```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
|
|
```
|
|
|
|
## Common Tasks
|
|
|
|
### Adding a New Mini-Game
|
|
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. Ensure YarnProject localization assets/CSV are updated (Unity `Assets/Language/Dialog/` is backup-only during migration)
|
|
3. Reference in scene's `DialogueRunner`; test with `DialogController`
|
|
|
|
## 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
|
|
- 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](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
|
|
|
|
---
|
|
|
|
*This document provides guidance for Claude Code when working with the AIBIS Dream codebase.*
|