115 lines
5.5 KiB
Markdown
115 lines
5.5 KiB
Markdown
# 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 |