TH1/Unity/Assets/Scripts/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

This is TH1, a Unity turn-based strategy game (Touhou Project fan game) using the ET Framework architecture. The project uses a modular C# codebase with clear separation between Logic, Data, UI, and Rendering layers.

Build System

This is a Unity project. Use Unity Editor to build:

• Open project in Unity (version 2022.3 LTS recommended)
• Build via File > Build Settings
• Key scenes: MainMenu scene and Gameplay scene

The project has .csproj files generated by Unity but builds through Unity's build system, not directly via MSBuild.

Architecture Overview

Module Structure

The codebase is organized into functional modules:

Module	Purpose
TH1_Core	Core managers: EventManager, UIManager, PresentationManager
TH1_UI	UI system with View-Controller pattern
TH1_Logic	Game logic: AI, Skills, City/Unit/Player logic
TH1_Data	Data classes: PlayerData, MapData, UnitData, GridData
TH1_Renderer	Visual rendering: MapRenderer, UnitRenderer, GridRenderer
TH1_Config	Configuration and Excel-generated config classes
TH1_Instance	Instance management and base classes
TH1_Presentation	Presentation sequencing system
TH1_Anim	Animation utilities
TH1_Audio	Audio management
TH1_Resource	Resource caching (SpriteCache, AnimCache)
BTNodeCanvas	AI behavior tree nodes (NodeCanvas framework)

UI Architecture (MVC-like)

The UI follows a View-Controller pattern:

1. View Classes (TH1_UI/View/): MonoBehaviour components attached to prefabs

   • Inherit from View or ViewSub in TH1_UI/View/Base/
   • Handle visual presentation and animations (Animancer-based)
   • Example: TH1_UI/View/Base/View.cs

2. Controller Classes (TH1_UI/Controller/): Pure C# logic classes

   • Inherit from ViewController<T> in TH1_UI/Controller/Base/ViewController.cs
   • Handle data binding, event registration, and business logic
   • Example: ViewController<T> with interface IViewControllerInterface

3. Registration: All UI controllers are registered in ViewControllerManager.cs:

   • Uses ViewControllerManager.OnMatchStart() to initialize all views
   • Views are organized by domain: Top, Bottom, Info, Outside, Notify, Announce, Interaction

Data Flow

1. Runtime Data: Stored in Main.MapData (static) and data classes in TH1_Data/
2. Event System: EventManager in TH1_Core/Managers/EventManager.cs for global events
3. UI Events: UIEvents class with UIEventManagerBinder for UI-specific events

Game Logic Structure

1. Main Entry: TH1_Logic/Core/Main.cs - Game initialization and singleton management
2. Logic Modules:
   • CityLogic: City management
   • UnitLogic: Unit actions and state
   • PlayerLogic: Player resources and diplomacy
   • GameLogic: Game flow and turn management
   • InputLogic: Player input handling
   • MapInteraction: Map click/hover interactions

AI System (NodeCanvas)

AI uses NodeCanvas behavior trees with custom nodes in BTNodeCanvas/:

• Condition nodes: AIParam*.cs files (e.g., AIParamHealth.cs)
• Action nodes: AIAction*.cs files (e.g., AIExcuteAction.cs)
• All nodes inherit from NodeCanvas base classes

Key Managers (Singleton Pattern)

Manager	Location	Purpose
UIManager	TH1_Core/Managers/UIManager.cs	UI root management
EventManager	TH1_Core/Managers/EventManager.cs	Global event dispatch
PresentationManager	TH1_Core/Managers/PresentationManager.cs	Presentation sequencing
ConfigManager	TH1_Logic/Config/	Configuration loading
AudioManager	TH1_Logic/Core/	Audio playback
ResourceCache	TH1_Resource/	Sprite/animation caching
PrefabPoolManager	TH1_Logic/PrefabPool/	Object pooling

Configuration System

Configs are Excel-generated C# classes:

• Source configs: Config/ folder (outside Unity)
• Generated code: TH1_Config/GenerateCS/
• Partial classes: TH1_Config/ExcelPartial/

Serialization

Uses MemoryPack for network and save data serialization:

• Data classes marked with [MemoryPackable]
• Fields use [MemoryPackIgnore] for non-serialized data

Common Development Patterns

Creating a New UI Panel

1. Create View class in TH1_UI/View/{Category}/ inheriting from View
2. Create Controller class in TH1_UI/Controller/{Category}/ inheriting from ViewController<T>
3. Add to ViewControllerManager.cs:
   • Add static field
   • Add property getter
   • Create in _CreateAllViewControllers()
4. Create prefab in Unity with View component attached

Adding an AI Behavior Node

1. Create class in BTNodeCanvas/ inheriting from ConditionTask or ActionTask
2. Implement required methods (OnCheck() for conditions, OnExecute() for actions)
3. Node will auto-register with NodeCanvas

Event Usage

// Subscribe to event
EventManager.Instance.AddListener<EventType>(callback);

// UI Events via UIEvents class
UIEvents.OnCitySelected += HandleCitySelected;

Data Access

// Access game data
var mapData = Main.MapData;
var playerData = PlayerData.SelfPlayerData;

Important Conventions

1. File Organization: Each major class has its own .cs file with matching name
2. Namespaces: Follow folder structure (e.g., TH1_UI.Controller.Base)
3. Meta Files: Unity .meta files are committed to version control
4. Chinese Comments: Many files contain Chinese comments for team communication
5. Partial Classes: Configuration classes use partial classes for generated + custom code

Dependencies

Key third-party libraries:

• NodeCanvas: Behavior tree/AI framework (in ThirdParty/)
• Animancer: Animation system (replaces Unity Animation)
• MemoryPack: High-performance serialization
• Steamworks.NET: Steam integration

Testing

The project includes editor windows for testing:

• TH1_Logic/Editor/ contains various editor tools
• AI debugging via MainEditor.Instance (F10/F11 editor controls)
• Debug UI in TH1_UI/DebugUI.cs