init

DungeonSolver.Workspace/CLAUDE.md

@@ -0,0 +1,115 @@
+# 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