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 for details
• 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

# 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

# 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

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

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 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 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 - Addressables resource loading specifications, naming conventions, and performance optimization
• Commit Convention - Git commit message format and branch naming rules

---

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