doc: new documentation helps
fix: issue with blank shop items
This commit is contained in:
aerinon
257
CLAUDE.md
Normal file
257
CLAUDE.md
Normal file
@@ -0,0 +1,257 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user