258 lines
10 KiB
Markdown
258 lines
10 KiB
Markdown
# CLAUDE.md
|
|
|
|
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
|
|
|
## Project Overview
|
|
|
|
**ALttPDoorRandomizer** is a sophisticated dungeon and door randomizer for *The Legend of Zelda: A Link to the Past* (SNES). It extends the standard ALTTP Entrance Randomizer with advanced dungeon shuffling capabilities that can rearrange dungeon interiors at the door and sector level.
|
|
|
|
- **Repository**: https://github.com/aerinon/ALttPDoorRandomizer
|
|
- **Python Version**: 3.10+
|
|
- **Current Branch**: DoorDevUnstable (dev branch: NewGeneration)
|
|
- **Discord**: #door-rando and #bug-reports channels at ALTTP Randomizer discord
|
|
|
|
## Development Commands
|
|
|
|
### Running the Randomizer
|
|
```bash
|
|
# CLI interface
|
|
python DungeonRandomizer.py
|
|
|
|
# GUI interface
|
|
python Gui.py
|
|
|
|
```
|
|
|
|
### Dependencies
|
|
```bash
|
|
# Install platform-specific dependencies
|
|
python resources/ci/common/local_install.py
|
|
|
|
# For multiworld server/client
|
|
# Run the same command to install multiworld dependencies
|
|
```
|
|
|
|
### Testing
|
|
```bash
|
|
# Run test suite
|
|
python TestSuite.py
|
|
|
|
# Run test suite with specific door shuffle mode
|
|
python TestSuite.py --dr basic --count 10 --tense 2
|
|
|
|
# Individual test files (unittest-based)
|
|
python -m pytest test/
|
|
python -m pytest test/dungeons/TestDarkPalace.py
|
|
```
|
|
|
|
### ROM Generation
|
|
```bash
|
|
# Basic door shuffle seed
|
|
python DungeonRandomizer.py --doorShuffle crossed --intensity 2
|
|
|
|
# Suppress ROM output (for testing)
|
|
python DungeonRandomizer.py --suppress_rom --spoiler none
|
|
|
|
# Create BPS patch
|
|
python DungeonRandomizer.py --bps
|
|
```
|
|
|
|
## Architecture Overview
|
|
|
|
### Generation Pipeline
|
|
|
|
The randomizer follows this high-level flow (orchestrated in `Main.py`):
|
|
|
|
1. **World Setup** → Initialize World object, parse settings, set seed
|
|
2. **Region Creation** → Build game regions, locations, entrances (`Regions.py`)
|
|
3. **Dungeon Structure** → Create dungeon objects and rooms (`Dungeons.py`, `RoomData.py`)
|
|
4. **Door/Entrance Shuffling** → Shuffle dungeon interiors and/or overworld entrances
|
|
5. **Logic Rules** → Set access requirements for all locations (`Rules.py`)
|
|
6**Item Placement** → Generate item pool and place items with logic constraints (`Fill.py`)
|
|
7. **ROM Patching** → Apply changes to base ROM (`Rom.py`)
|
|
8. **Output** → Generate ROM file, spoiler log, and/or multiworld data
|
|
|
|
### Core Data Structures (BaseClasses.py)
|
|
|
|
- **World**: Container for all game state, regions, dungeons, items, and settings
|
|
- **Region**: Geographic area with locations and exits
|
|
- **Location**: Item placement spot with access rules
|
|
- **Item**: Game items with advancement/priority flags
|
|
- **Entrance**: Connections between regions with conditional access
|
|
- **CollectionState**: Tracks player's collected items for logic evaluation
|
|
|
|
### Dungeon Generation System
|
|
|
|
The dungeon shuffling system uses a three-stage algorithm:
|
|
|
|
#### 1. DungeonGenLocalSearch (source/dungeon/DungeonGenLocalSearch.py)
|
|
**Purpose**: Assigns dungeon sectors to dungeons using constraint satisfaction
|
|
|
|
**Balancing Constraints**:
|
|
- **Polarity**: North/South and East/West door balance
|
|
- **Crystal Balance**: Blue/orange barriers must have matching switches
|
|
- **Portal Balance**: Entrance distribution
|
|
- **Location Balance**: Ensures dungeons have accessible non-big-key locations
|
|
- **Branching**: Dead ends vs branches ratio (insufficient branches = unreachable areas)
|
|
- **Transitivity**: Validates that doors can actually connect
|
|
|
|
**Algorithm**: Local search with greedy constraint satisfaction, prioritizing crystal switches → portals → locations → branching → polarity → transitivity
|
|
|
|
#### 2. DungeonGenTransitivity (source/dungeon/DungeonGenTransitivity.py)
|
|
**Purpose**: Validates that door connections are possible for a given sector assignment
|
|
|
|
**Key Features**:
|
|
- Verifies all doors can be validly connected (e.g., North↔South, East↔West, Stairs↔Stairs)
|
|
- Propagates crystal switch states through connections
|
|
- Detects forced connections and impossible layouts
|
|
- Uses depth-first search with constraint propagation
|
|
- Handles special mechanics (portals, crystal barriers, special rooms)
|
|
|
|
#### 3. DungeonStitcherV2 (source/dungeon/DungeonStitcherV2.py)
|
|
**Purpose**: Realizes actual door connections from validated sector assignments
|
|
|
|
**Key Features**:
|
|
- Generates random valid door pairings
|
|
- Assigns portal connections (dungeon entrances)
|
|
- Simulates player traversal to verify connectivity
|
|
- Manages crystal barrier state propagation
|
|
|
|
### Key Logic Components
|
|
|
|
**Rules.py** (~7000 lines): Sets logical requirements for accessing locations
|
|
- Supports multiple logic modes: noglitches, owglitches, hybridglitches, nologic
|
|
- Handles multiple key logic algorithms: partial, strict, dangerous, experimental
|
|
- Manages dungeon-specific access rules and boss requirements
|
|
|
|
**Fill.py** (~2000 lines): Item placement algorithms
|
|
- **Balanced**: Random distribution
|
|
- **Vanilla Fill**: Attempts vanilla item locations when possible
|
|
- **Major Location Restriction**: Major items → major locations
|
|
- **Dungeon Restriction**: Major items → dungeons
|
|
- **District Restriction**: Items distributed by geographic region
|
|
|
|
**KeyPlacement.py** / **NewKeyLogic.py**: Advanced key door logic
|
|
- Handles small key placement with multiple satisfiability algorithms
|
|
- Prevents self-locking situations
|
|
- Manages big key placement rules
|
|
- Validates minimum key requirements for dungeon completion
|
|
|
|
### Source Module Organization
|
|
|
|
```
|
|
source/
|
|
├── dungeon/ # Dungeon generation algorithms and key logic
|
|
├── overworld/ # Entrance shuffling (EntranceShuffle2.py)
|
|
├── item/ # Item placement utilities (FillUtil.py, District.py)
|
|
├── enemizer/ # Enemy randomization system
|
|
├── gui/ # GUI components (tkinter-based)
|
|
├── rom/ # ROM patching utilities
|
|
├── classes/ # Utility classes (BabelFish, CustomSettings)
|
|
├── meta/ # Metadata and build tools
|
|
└── limited/ # Limited run coordination
|
|
```
|
|
|
|
### Important Files by Size/Complexity
|
|
|
|
- **DoorShuffle.py** (~8500 lines): Door shuffling orchestration
|
|
- **Rules.py** (~7000 lines): Location access logic
|
|
- **EnemyList.py** (~6000 lines): Enemy definitions
|
|
- **Doors.py** (~5500 lines): Door object definitions
|
|
- **Rom.py** (~5500 lines): ROM patching
|
|
- **Regions.py** (~5000 lines): World region creation
|
|
- **DungeonGenerator.py** (~5000 lines): Legacy dungeon generation
|
|
- **EntranceShuffle2.py** (~5000 lines): Entrance shuffling logic
|
|
- **BaseClasses.py** (~4000 lines): Core data structures
|
|
- **KeyDoorShuffle.py** (~3500 lines): Key door logic
|
|
- **PotShuffle.py** (~3500 lines): Pot randomization
|
|
|
|
## Key Concepts
|
|
|
|
### Door Shuffle Modes
|
|
- **Vanilla**: No shuffling
|
|
- **Basic**: Shuffle within each dungeon
|
|
- **Partitioned**: Shuffle in pools (Light World, Early Dark World, Late Dark World)
|
|
- **Crossed**: Full shuffle between all dungeons
|
|
|
|
### Intensity Levels
|
|
- **Level 1**: Normal doors and spiral staircases
|
|
- **Level 2**: + open edges and straight staircases
|
|
- **Level 3**: + dungeon lobbies
|
|
|
|
### Key Shuffle Modes
|
|
- **In Dungeon** (keyshuffle=none): Keys restricted to their dungeon
|
|
- **Randomized** (keyshuffle=wild): Keys can be anywhere
|
|
- **Universal** (keyshuffle=universal): Keys work in any dungeon
|
|
|
|
### Fill Algorithms (--algorithm)
|
|
See Fill.py for implementation details. The algorithm affect where item may be placed.
|
|
|
|
### Logic Modes
|
|
- **noglitches**: Standard logic
|
|
- **owglitches**: Overworld glitches (OOB, clips, superbunny)
|
|
- **hybridglitches**: + major underworld glitches (not compatible with door shuffle)
|
|
- **nologic**: No logical constraints
|
|
|
|
## Testing Strategy
|
|
|
|
Tests verify location accessibility with various item combinations:
|
|
- **test/dungeons/**: Per-dungeon location access tests
|
|
- **test/vanilla/**: Vanilla world logic tests
|
|
- **test/owg/**: Overworld glitch logic tests
|
|
- **test/inverted/**: Inverted mode tests
|
|
- **TestBase.py**: Base test class with utility methods
|
|
|
|
Use `TestSuite.py` for batch generation testing across modes (Open/Standard/Inverted) and settings.
|
|
|
|
## Important Development Notes
|
|
|
|
### Starting Items & Special Items
|
|
- **Mirror Scroll**: Dungeon-only mirror (starting item in door shuffle)
|
|
- **Bomb Bag**: Optional item that gates bomb usage
|
|
- **Pseudo Boots**: Allows dashing but gates certain sequence breaks
|
|
|
|
### Branch Structure
|
|
- **DoorDev**: Main development branch (use for PRs)
|
|
- **DoorDevUnstable**: Current working branch
|
|
- **Dev/Master**: Do NOT use for PRs
|
|
|
|
### Git Workflow
|
|
Recent commits show work on:
|
|
- Limited run coordination
|
|
- Custom rooms support
|
|
- Key logic improvements (transitivity, portal checks, placement rules)
|
|
- Isolated region detection fixes
|
|
- Big key placement satisfiability
|
|
|
|
### Documentation Resources
|
|
- **Algorithm.md**: Detailed dungeon generation algorithm documentation
|
|
- **docs/ai_context/**: Comprehensive architectural documentation by topic
|
|
- **docs/Customizer.md**: Custom seed configuration guide
|
|
- **docs/DR_hint_reference.md**: Hint system documentation
|
|
- **docs/BUILDING.md**: Build and installation instructions
|
|
- **README.md**: User-facing feature documentation
|
|
|
|
## Common Gotchas
|
|
|
|
1. **Transitivity Checks**: Most expensive constraint check - always run last
|
|
2. **Self-Locking Keys**: Key logic must prevent situations where players cannot access the rest of the dungeon
|
|
3. **Crystal Barriers**: Blue/orange barriers require matching switches in dungeon
|
|
4. **Portal Distribution**: Each dungeon needs at least one entrance
|
|
5. **Branching Balance**: Too many dead ends without branches = unreachable areas
|
|
6**Polarity Balance**: N/S and E/W door counts must allow valid connections
|
|
|
|
## CLI Argument Reference
|
|
|
|
Key arguments from `resources/app/cli/args.json`:
|
|
- `--doorShuffle [vanilla|basic|partitioned|crossed]`
|
|
- `--intensity [1|2|3]`
|
|
- `--keyshuffle [none|wild|universal]`
|
|
- `--key_logic [partial|strict|dangerous|experimental]`
|
|
- `--algorithm [balanced|vanilla_fill|major_only|dungeon_only|district]`
|
|
- `--logic [noglitches|owglitches|hybridglitches|nologic]`
|
|
- `--mode [open|standard|inverted]`
|
|
- `--shuffle`: Entrance randomizer options (vanilla, simple, restricted, full, crossed, insanity, etc.)
|
|
- `--pottery`: Pot shuffling modes
|
|
- `--shopsanity`: Enable shop item randomization
|
|
- `--enemizer`: Enemy randomization options
|