aibis-dream/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).

**Unity Version:** Unity 2022.3.x LTS (Universal Render Pipeline)

## Architecture

### Core Framework (Assets/Scripts/Framework/)

The project uses a custom modular framework with these key systems:

- **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

### 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

### Web Prototypes

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)
```

## 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

### 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

## 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

### 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

### Yarn Dialogue Files

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.

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

### Asset Naming Conventions

- **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/`

## 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

### 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`

### Adding Yarn Dialogue

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

## 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#

## 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

---

*This document provides guidance for Claude Code when working with the AIBIS Dream codebase.*