# CLAUDE.md

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

## Workspace Architecture

**DungeonSolver.Workspace** is a multi-project C# solution (.NET 8.0) organized as a modular game development workspace. Each project serves a specific purpose and can be built independently.

### Project Structure

- **DungeonSolver/**: Main Godot 4.5 game project with Python integration (see `DungeonSolver/CLAUDE.md` for detailed game-specific guidance)
- **DungeonSolver.Global/**: Core game systems and global providers, outputs to `DungeonSolver/Data/` for game consumption
- **DungeonSolver.PythonBridge/**: Python integration layer using IronPython/pythonnet
- **DungeonSolver.Game/**: Game-specific logic and systems
- **DungeonSolver.Generators/**: Roslyn source generators for automated code generation
- **DungeonSolver.Global.Generators/**: Source generators specifically for the Global project
- **DungeonSolver.Tasks/**: Build tasks and utilities

### Key Architectural Patterns

**Modular Project Design**: Each component is isolated in its own project with specific responsibilities:
- Global project compiles to `DungeonSolver/Data/` for runtime access
- Source generators use `OutputItemType="Analyzer" ReferenceOutputAssembly="false"` pattern
- Python bridge allows C# game systems to be accessed from Python via `clr.AddReference()`

**Source Generator Integration**: Projects use Roslyn source generators for code generation:
- Generators project contains sample incremental source generators
- Target classes use `[Generators.ReportAttribute]` for report generation
- Build generators to see generated code in IDE

**Python-C# Interop**:
- **Python Package Generator**: Automatically generates Python wrapper classes for C# types marked with `[PythonSharedType]` attributes
  - Generates type-safe Python interfaces from C# classes, interfaces, and enums
  - Handles complex generic types and nested class hierarchies
  - Supports inheritance, member access, and method calls with proper type hints
  - Generated Python packages are output to `user://dungeon_solver/types/`
- **Type Registration System**: Uses `PythonSharedTypeRegister` to map C# types to Python equivalents
- **Shared Memory Communication**: Advanced IPC system for real-time C#-Python communication (see `Documents/SharedMemoryCommunicationProtocol.md`)
- **Runtime Access**: Python scripts access C# via `DungeonSolver.Global.dll` using IronPython/pythonnet
- **Bridge Pattern**: Example implementation in `DungeonSolver/Data/Solver.py`

## Build and Development Commands

**Building Individual Projects**:
```bash
# Build specific project
dotnet build DungeonSolver.Global/
dotnet build DungeonSolver.Generators/
dotnet build DungeonSolver.PythonBridge/

# Build main game project (includes all dependencies)
cd DungeonSolver && dotnet build
```

**Building the Entire Workspace**:
```bash
# Build all projects from workspace root
dotnet build DungeonSolver/DungeonSolver.sln
```

**Source Generator Development**:
```bash
# Build generators to see generated code
dotnet build DungeonSolver.Generators/
dotnet build DungeonSolver.Global.Generators/
```

**Testing**:
```bash
# Run generator unit tests
cd DungeonSolver.Generators && dotnet test
cd DungeonSolver.Global.Generators && dotnet test
```

## Code Style Guidelines

**C# Coding Standards**:
- **No `var` keyword**: Always use explicit types instead of `var`
  ```csharp
  string name = "example";           // Correct
  List<int> numbers = new List<int>(); // Correct
  // var name = "example";            // Wrong
  ```
- **No comments**: Do not write any comments in code (XML documentation, inline comments, or block comments)
- Write self-documenting code with clear variable and method names

## Development Workflow Notes

**Project Dependencies**: The main solution (`DungeonSolver/DungeonSolver.sln`) references all other projects, creating a unified build process while maintaining modular development.

**Global System Access**: Python scripts can access the Global project's compiled output via the established bridge pattern in `Data/Solver.py`.

**Source Generator Workflow**: 
1. Modify generator code in `*.Generators` projects
2. Build generator project to compile changes
3. Target projects automatically regenerate code during their build
4. Use Rossynt plugin for syntax tree analysis during development

**Cross-Project Development**: Each project can be developed and tested independently, with the main game project serving as the integration point.

**Python Type System Development**:
1. Mark C# types with appropriate `[PythonSharedType]` attributes (`[PythonSharedClass]`, `[PythonSharedInterface]`, `[PythonSharedEnum]`)
2. Add `[PythonSharedMember]` and `[PythonSharedMethod]` attributes to expose specific members
3. Build `DungeonSolver.Global` project to register types in `PythonSharedTypeRegister`
4. Generated Python types automatically handle complex scenarios like:
   - Generic type parameters and constraints
   - Nested class inheritance hierarchies
   - Interface implementation and multiple inheritance
   - Enum value mapping and type safety

**Important Development Notes**:
- Always build `DungeonSolver.Global` before the main game project to ensure Python bindings are up-to-date
- When modifying Python-shared types, rebuild is required to regenerate Python wrapper classes
- Use `PythonPackageGenerator.Generate()` to manually trigger Python code generation during development
- Nested classes inherit sharing attributes from parent classes automatically via `NestedClassWrapper` pattern