AbstractWizard/DungeonSolver.Workspace/CLAUDE.md

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:

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

# Build all projects from workspace root
dotnet build DungeonSolver/DungeonSolver.sln

Source Generator Development:

# Build generators to see generated code
dotnet build DungeonSolver.Generators/
dotnet build DungeonSolver.Global.Generators/

Testing:

# 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

  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