alttpr-gwaa-kiwi/alttpr-python
1
0
Fork 0
Code Issues Pull Requests Releases Activity

doc: new documentation helps

Browse Source 
fix: issue with blank shop items
This commit is contained in:
aerinon
2026-01-30 10:05:29 -07:00
parent eda03d8657
commit bf92fe91c2
13 changed files with 2111 additions and 8 deletions
Download Patch File Download Diff File Expand all files Collapse all files

257
CLAUDE.md Normal file
View 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

2
Fill.py
View File

@@ -980,7 +980,7 @@ def balance_money_progression(world):
slot = shop_to_location_table[location.parent_region.name].index(location.name)
shop = location.parent_region.shop
shop_item = shop.inventory[slot]
if location.item and interesting_item(location, location.item, world, location.item.player):
if shop_item and location.item and interesting_item(location, location.item, world, location.item.player):
if location.item.name.startswith('Rupee') and loc_player == location.item.player:
if shop_item['price'] < rupee_chart[location.item.name]:
wallet[loc_player] -= shop_item['price'] # will get picked up in the location_free block

2
Main.py
View File

@@ -38,7 +38,7 @@ from source.enemizer.DamageTables import DamageTable
from source.enemizer.Enemizer import randomize_enemies
from source.rom.DataTables import init_data_tables
version_number = '1.5.3'
version_number = '1.5.4'
version_branch = '-u'
__version__ = f'{version_number}{version_branch}'

5
PastReleaseNotes.md
View File

@@ -10,6 +10,11 @@
# Patch Notes
Changelog archive
* 1.5.3
* Logic: Key logic fix for part of a dungeon located at Skull 3 (or other similar restricted entrancs). Appropriate key logic was not being applied, causing progression issues. This mostly affect crosskey style seeds.
* Standard: Rupee balancing algorithm can no longer switch out the weapon on uncle for money.
* Dungeon Counters: Some fixes for inconsistent tracking and display of dungeon counters on the keysanity menu.
* Text: Updated main tournament winner (Thanks clearmouse!)
* 1.5.1
* Bugfix: Fixed an issue with keys not counting correctly
* 1.5.0

9
RELEASENOTES.md
View File

@@ -1,7 +1,6 @@
# Patch Notes
* 1.5.3
* Logic: Key logic fix for part of a dungeon located at Skull 3 (or other similar restricted entrancs). Appropriate key logic was not being applied, causing progression issues. This mostly affect crosskey style seeds.
* Standard: Rupee balancing algorithm can no longer switch out the weapon on uncle for money.
* Dungeon Counters: Some fixes for inconsistent tracking and display of dungeon counters on the keysanity menu.
* Text: Updated main tournament winner (Thanks clearmouse!)
* 1.5.4
* Documentation: New AI-assisted documentation [Site (I really hope this works)](https//aerinon.github.io/ALttPDoorRandomizer)
* Generation Error: Fixed Issue with Shop Code and Take Any Caves (thanks Codemann for assistance)

140
_config.yml
View File

@@ -1 +1,139 @@
theme: jekyll-theme-slate
# Site settings
title: ALttP Dungeon Randomizer
description: Advanced dungeon randomization for The Legend of Zelda - A Link to the Past
baseurl: "/ALttPDoorRandomizer"
url: "https://aerinon.github.io"
# Theme
theme: jekyll-theme-slate
remote_theme: just-the-docs/just-the-docs
# Logo and branding
# logo: "/assets/images/logo.png"
# Navigation
nav_enabled: true
nav_external_links:
- title: GitHub
url: https://github.com/aerinon/ALttPDoorRandomizer
- title: Discord
url: https://discordapp.com/invite/alttprandomizer
- title: Download
url: https://github.com/aerinon/ALttPDoorRandomizer/releases
# Search
search_enabled: true
search:
heading_level: 2
previews: 3
preview_words_before: 5
preview_words_after: 10
tokenizer_separator: /[\s/]+/
rel_url: true
button: true
# Heading anchors
heading_anchors: true
# Aux links
aux_links:
"Door Randomizer on GitHub":
- "https://github.com/aerinon/ALttPDoorRandomizer"
"ALTTP Rando Discord":
- "https://discordapp.com/invite/alttprandomizer"
aux_links_new_tab: true
# Footer
footer_content: "Copyright &copy; 2026 ALttP Door Randomizer Team. Based on ALttP Entrance Randomizer."
# Back to top link
back_to_top: true
back_to_top_text: "Back to top"
# Collections for blog posts
collections:
posts:
output: true
permalink: /blog/:year/:month/:day/:title/
# Defaults
defaults:
- scope:
path: ""
type: "posts"
values:
layout: "default"
- scope:
path: ""
values:
layout: "default"
# Build settings
markdown: kramdown
kramdown:
input: GFM
syntax_highlighter: rouge
syntax_highlighter_opts:
css_class: 'highlight'
plugins:
- jekyll-feed
- jekyll-seo-tag
- jekyll-sitemap
# Exclude from processing
exclude:
- .git/
- .github/
- .gitignore
- .gitattributes
- source/
- test/
- resources/
- data/
- debug/
- analysis/
- analysis2/
- alttp_dungeon_randomizer.egg-info/
- DR/
- "*.py"
- "*.pyc"
- "*.pyd"
- "*.pyo"
- "*.egg-info"
- "*.spec"
- requirements*.txt
- setup.py
- TestSuite.py
- DungeonRandomizer.py
- Gui.py
- MultiServer.py
- MultiClient.py
- CLAUDE.md
- LICENSE
- libbz2-dev
- tlogbfs.txt
# Include files
include:
- _posts
- blog
- docs/Customizer.md
- docs/BUILDING.md
- docs/DR_hint_reference.md
# Color scheme (for just-the-docs theme)
color_scheme: dark
# Google Analytics (optional - add your tracking ID)
# ga_tracking: UA-XXXXXXXX-X
# Compress HTML
compress_html:
clippings: all
comments: all
endings: all
startings: []
blanklines: false
profile: false

74
_posts/2026-01-30-welcome-to-door-randomizer.md Normal file
View File

@@ -0,0 +1,74 @@
---
layout: default
title: "Welcome to the ALttP Door Randomizer Blog"
date: 2026-01-26
author: Door Randomizer Team
category: development
excerpt: "Introducing the new Door Randomizer documentation site and blog. Learn about what's new, what's coming, and how to get involved."
---
# Welcome to the ALttP Door Randomizer Blog
We're excited to launch the official documentation site and development blog for ALttP Door Randomizer! This site serves as a central hub for all things Door Rando - from comprehensive feature documentation to release notes and development updates.
## What's New Here?
### Comprehensive Documentation
We've reorganized and expanded our documentation to make it easier to find what you need:
- **[Features Guide](/features)** - Complete reference for all randomizer settings and modes
- **[Installation & Usage](/installation)** - Step-by-step setup instructions for all platforms
- **[Known Issues](/known-issues)** - Tracking current bugs and limitations
- **[Roadmap](/roadmap)** - Our vision for the future of Door Randomizer
### Development Blog
This blog will be your source for:
- **Feature highlights** - Deep dives into specific features
- **Development updates** - Behind-the-scenes looks at ongoing work
- **Technical articles** - How the randomizer works under the hood
## What is Door Randomizer?
If you're new here, Door Randomizer takes the ALttP randomizer experience to the next level by shuffling the connections between rooms within dungeons. Walk through a door in Eastern Palace and you might end up in Tower of Hera, Ice Palace, or anywhere else!
Key features include:
- **Four shuffle modes** - From basic (within dungeon) to crossed (full chaos)
- **Three intensity levels** - Control how thoroughly dungeons are shuffled
- **Advanced key logic** - Multiple algorithms to prevent self-locking
- **Pottery shuffle** - Randomize items under pots with multiple modes
- **Shopsanity** - 32+ shop locations with intelligent pricing
- **Enemizer integration** - Enemy and boss randomization with logic
- **Custom seeds** - Create your own dungeons and rooms
[Learn more about features →](/features)
[Read the Customizer guide →](https://github.com/aerinon/ALttPDoorRandomizer/blob/DoorDev/docs/Customizer.md)
## What's Coming Next?
We have plans for Door Randomizer's future. Check out our [Roadmap](/roadmap) for details. (Still very much a work in progress!)
## Community
Join the Door Randomizer community:
- **Discord**: [ALTTP Randomizer Discord](https://discordapp.com/invite/alttprandomizer)
- `#door-rando` - General discussion and help
- `#bug-reports` - Report bugs and issues
- **GitHub**: [aerinon/ALttPDoorRandomizer](https://github.com/aerinon/ALttPDoorRandomizer)
## Stay Tuned
We'll be posting irregular updates here as development continues.
Thank you to everyone who has contributed to Door Randomizer through code, testing, feedback, and community support. We're excited about the future and can't wait to see what lies in store!
Happy randomizing!
---
*Have questions or feedback about the new documentation site? Let us know in Discord!*

100
blog/index.md Normal file
View File

@@ -0,0 +1,100 @@
---
layout: default
title: Blog
nav_order: 6
has_children: false
---
# Development Blog
{: .no_toc }
Latest updates, release notes, and development insights for ALttP Door Randomizer.
{: .fs-6 .fw-300 }
---
## Recent Posts
{% assign posts = site.posts | sort: 'date' | reverse %}
{% for post in posts limit:10 %}
<div class="post-entry" style="margin-bottom: 2em; padding-bottom: 1em; border-bottom: 1px solid #eeebee;">
<h3 style="margin-bottom: 0.5em;">
<a href="{{ post.url | relative_url }}">{{ post.title }}</a>
</h3>
<p style="color: #5C5962; font-size: 0.9em; margin-bottom: 0.5em;">
{{ post.date | date: "%B %d, %Y" }}
{% if post.author %} • by {{ post.author }}{% endif %}
</p>
<p>{{ post.excerpt | strip_html | truncatewords: 50 }}</p>
<p><a href="{{ post.url | relative_url }}">Read more →</a></p>
</div>
{% endfor %}
---
## Categories
Browse posts by category:
- [Release Notes](#release-notes)
- [Development Updates](#development-updates)
- [Feature Highlights](#feature-highlights)
- [Technical Deep Dives](#technical-deep-dives)
### Release Notes
{% assign release_posts = site.posts | where: "category", "release" %}
{% for post in release_posts limit:5 %}
- [{{ post.title }}]({{ post.url | relative_url }}) - {{ post.date | date: "%B %d, %Y" }}
{% endfor %}
### Development Updates
{% assign dev_posts = site.posts | where: "category", "development" %}
{% for post in dev_posts limit:5 %}
- [{{ post.title }}]({{ post.url | relative_url }}) - {{ post.date | date: "%B %d, %Y" }}
{% endfor %}
### Feature Highlights
{% assign feature_posts = site.posts | where: "category", "features" %}
{% for post in feature_posts limit:5 %}
- [{{ post.title }}]({{ post.url | relative_url }}) - {{ post.date | date: "%B %d, %Y" }}
{% endfor %}
### Technical Deep Dives
{% assign feature_posts = site.posts | where: "category", "features" %}
{% for post in feature_posts limit:5 %}
- [{{ post.title }}]({{ post.url | relative_url }}) - {{ post.date | date: "%B %d, %Y" }}
{% endfor %}
---
## Subscribe
Stay up to date with Door Randomizer development:
- **Discord**: Join [ALTTP Randomizer Discord](https://discordapp.com/invite/alttprandomizer) in `#door-rando`
---
## Archive
View all posts by year:
{% assign posts_by_year = site.posts | group_by_exp: "post", "post.date | date: '%Y'" %}
{% for year in posts_by_year %}
### {{ year.name }}
{% for post in year.items %}
- [{{ post.title }}]({{ post.url | relative_url }}) - {{ post.date | date: "%B %d, %Y" }}
{% endfor %}
{% endfor %}
---
## Contributing to the Blog
Want to write a guest post or contribute content?
Contact us on Discord to discuss your ideas!

473
features.md Normal file
View File

@@ -0,0 +1,473 @@
---
layout: default
title: Features
nav_order: 2
---
# Features Guide
{: .no_toc }
Comprehensive documentation of all Door Randomizer features and settings.
{: .fs-6 .fw-300 }
## Table of contents
{: .no_toc .text-delta }
1. TOC
{:toc}
---
## Important Differences from Other Randomizers
Most of these apply only when door shuffle is not vanilla.
### Starting Item
You start with a **Mirror Scroll** (looks like a map), a simplified mirror that only works in dungeons, not the overworld, and can't erase blocks like the Mirror.
### Navigation Changes
- Holes in Mire Torches Top and Mire Torches Bottom fall through to rooms below (you only need fire to get the chest)
- You can Hookshot from the left Mire wooden Bridge to the right one
- In the PoD Arena, you can bonk with Boots between the two blue crystal barriers against the ladder to reach the Arena Bridge chest and door (Bomb Jump also possible but not in logic - Boots are required)
- Flooded Rooms in Swamp can be traversed backward and may be required. Flippers are needed to get out of the water
### Logic Differences
- The chest in southeast Skull Woods that is traditionally a guaranteed Small Key in ER is not guaranteed here
- Fire Rod is not in logic for dark rooms (hard enough to figure out which dark room you are in)
- The hammerjump (and some other skips) are not in logic by default (see the mixed_travel setting for details). Doing so in a crossed dungeon seed can put you into another dungeon with the wrong dungeon id
### Boss Differences
- You have to find the attic floor and bomb it open and bring the maiden to the light to fight Blind. In cross dungeon door shuffle, the attic can be in any dungeon. If you bring the maiden to the boss arena, she will hint where the cracked floor can be found
- GT Bosses do not respawn after killing them in this mode
- Enemizer change: The attic/maiden sequence is now active and required when Blind is the boss of Thieves' Town even when bosses are shuffled
### Crystal Switches
- You can hit the PoD crystal switch in the Sexy Statue room with a bomb from the balcony above without jumping down
- GT Crystal Conveyor room (it has gibdos) - You can hit the crystal switch with a bomb when the blue barrier is up from the far side so you can leave the room to the left with blue barriers down
- PoD Arena Bridge - If entering from the bridge, you can circle round and hit the switch, then fall into the hole to respawn at the bridge again with the crystal barriers different
---
## Dungeon Settings
### Door Shuffle
Controls how dungeon doors are shuffled:
- **Vanilla** - Doors are not shuffled
- **Basic** - Doors are shuffled only within a single dungeon
- **Partitioned** - Dungeons are shuffled in 3 pools: Light World, Early Dark World, Late Dark World (Late Dark are the four dungeons that require Mitts in vanilla, including Ganon's Tower)
- **Crossed** - Doors are shuffled between dungeons as well
CLI: `--doorShuffle [vanilla|basic|partitioned|crossed]`
### Intensity
Controls which types of connections are shuffled:
- **Level 1** - Normal doors and spiral staircases are shuffled
- **Level 2** - Same as Level 1 plus open edges and both types of straight staircases are shuffled
- **Level 3** - Same as Level 2 plus Dungeon Lobbies are shuffled
CLI: `--intensity [1|2|3]`
### Door Type Shuffle
Controls which types of doors can be shuffled (only active if door shuffle is not vanilla):
- **Small Key Doors, Bomb Doors, Dash Doors** - Standard shuffled doors
- **Adds Big Key Doors** - Big key doors are now shuffled in addition to those above
- **Adds Trap Doors** - All trap doors that are permanently shut in vanilla are shuffled, excluding boss trap doors
- **Increases all Door Types** - Chaos mode where each door type per dungeon is randomized between 1 less and 4 more
CLI: `--door_type_mode [original|big|all|chaos]`
### Trap Door Removal
Options for making dungeon traversal more convenient:
- **No Removal** - Does not remove any trap doors
- **Removed If Blocking Path** - Dungeon generation removes annoying trap doors if necessary (boss trap doors never shuffled)
- **Remove Boss Traps** - Boss traps are removed, including the one near Mothula
- **Remove All Annoying Traps** - Removes all trap doors that are annoying, including boss traps
CLI: `--trap_door_mode [vanilla|optional|boss|oneway]`
### Dungeon Items
#### Small Keys
- **In Dungeon** - Small keys are restricted to their own dungeon
- **Randomized** - Small keys can be found anywhere
- **Universal** - Small keys work in any dungeon, can be found anywhere, and at least one shop will sell keys (like original Legend of Zelda)
CLI: `--keyshuffle [none|wild|universal]`
All other dungeon items (maps, compasses, Big Keys) can be restricted to their own dungeon or shuffled in the general pool.
### Key Logic Algorithm
Determines how small key door logic works:
- **Partial Protection** - Assumes you always have full inventory and worst case usage. Accounts for dark room and bunny revival glitches
- **Strict** - Small key doors require all small keys to be available to be in logic
- **Dangerous** - Assumes you never use keys out of logic (not recommended)
CLI: `--key_logic [partial|strict|dangerous]`
### Decouple Doors
Similar to insanity mode in ER where door entrances and exits are not paired anymore. Tends to remove more logic from dungeons as many rooms will not be required to traverse.
CLI: `--decoupledoors`
### Allow Self-Looping Spiral Stairs
If enabled, spiral stairs are allowed to lead to themselves.
CLI: `--door_self_loops`
### Experimental Features
You will start as a bunny if your spawn point is in the dark world.
CLI: `--experimental`
### Crossed Dungeon Specific Settings
#### Dungeon Chest Counters
- **Auto** - Picks an appropriate setting based on other settings
- **On** - Dungeon counters on HUD always displayed
- **Off** - Dungeon counters on HUD never displayed
- **On Compass Pickup** - Dungeons with a compass item will display the counter once the compass is found
CLI: `--dungeon_counters [auto|on|off|pickup]`
#### Mixed Travel
Controls Hammerjump, PoD Arena hovering, and Mire Big Key Chest bomb jump:
- **Prevent (default)** - Rails are added to prevent these tricks. Recommended for those learning crossed dungeon mode
- **Allow** - Rooms are left alone and it is up to player discretion whether to use these tricks
- **Force** - The two disjointed sections are forced to be in the same dungeon but the glitches are never logically required
CLI: `--mixed_travel [prevent|allow|force]`
#### Standardize Palettes
- **Standardize (default)** - Rooms in the same dungeon have their palettes changed to match
- **Original** - Rooms/supertiles keep their original palettes
CLI: `--standardize_palettes`
---
## Pool Expansions
### Pottery
Controls which pots (and large blocks) are in the locations pool:
- **None** - No pots are in the pool, like normal randomizer
- **Key Pots** - The pots that have keys are in the pool
- **Cave Pots** - The pots that are not found in dungeons are in the pool (includes Spike Cave large block)
- **Cave + Keys Pots** - Both non-dungeon pots and pots that used to have keys
- **Reduced Dungeon Pots** - Cave+Keys plus roughly 25% of dungeon pots (dynamic mode with colored pots)
- **Clustered Dungeon Pots** - Like reduced but pots grouped by logical sets, roughly 50% chosen (dynamic mode)
- **Excludes Empty Pots** - All pots that had some sort of objects under them
- **Dungeon Pots** - The pots that are in dungeons
- **Lottery** - All pots and large blocks are in the pool
CLI: `--pottery [none|keys|cave|cavekeys|reduced|clustered|nonempty|dungeon|lottery]`
#### Colorize Pots
Colors the pots that have been chosen to be part of the location pool. Forced on for dynamic modes (clustered and reduced).
CLI: `--colorizepots`
### Shuffle Enemy Drops
Controls whether enemies that drop items are randomized:
- **None** - Special enemies drop keys normally
- **Keys** - Enemies that drop keys are added to the randomization pool (includes Hyrule Castle Big Key)
- **Underworld** - Enemies in the underworld are added to the randomization pool. Blue square indicates if there are any enemies on the supertile that still have an available drop
CLI: `--dropshuffle [none|keys|underworld]`
### Shopsanity
Adds 32 shop locations (9 more in retro) to the general location pool. Multi-world supported.
Shop locations include:
- Lake Hylia Cave Shop (3 items)
- Kakariko Village Shop (3 items)
- Potion Shop (3 new items)
- Paradox Cave Shop (3 items)
- Capacity Upgrade Fairy (2 items)
- Dark Lake Hylia Shop (3 items)
- Curiosity/Red Shield Shop (3 items)
- Dark Lumberjack Shop (3 items)
- Dark Potion Shop (3 items)
- Village of Outcast Hammer Peg Shop (3 items)
- Dark Death Mountain Shop (3 items)
[See README for complete pricing guide and mechanics](/README#shopsanity)
### Take Any Caves
Three options: None, Random, and Fixed. Fixed means take any caves replace specific fairy caves:
- Desert Healer Fairy
- Swamp Healer Fairy (aka Light Hype Cave)
- Dark Death Mountain Healer Fairy
- Dark Lake Hylia Ledge Healer Fairy (aka Shopping Mall Bomb)
- Bonk Fairy (Dark)
---
## Item Randomization
### New "Items"
#### Bomb Bag
Two bomb bags are added to the item pool (look like +10 Capacity upgrades). Bombs are unable to be used until one is found.
CLI: `--bombbag`
#### Pseudo Boots
Dashing is allowed without the boots item however doors and certain rocks remain unopenable until boots are found. Specific sequence breaks like hovering and water-walking are not allowed until boots are found.
CLI: `--pseudoboots`
#### Mirror Scroll
Mirror is usable inside dungeons. Locations that require the mirror are still unattainable.
CLI: `--mirrorscroll`
#### Flute Mode
- **Normal** - Need to activate it at the village statue after finding it
- **Activated** - Can use it immediately upon finding it
CLI: `--flute_mode`
#### Bow Mode
- **Progressive** - Standard progressive bows
- **Silvers separate** - One bow in the pool and silvers are a separate item
- **Retro (progressive)** - Arrows cost rupees, need to purchase single arrow item at shop
- **Retro + Silvers** - Arrows cost rupees, one bow, silvers are separate item
CLI: `--bow_mode [progressive|silvers|retro|retro_silvers]`
### Goal Options
- **Trinity** - Find one of 3 triforces to win (pedestal, Ganon, or Murahdahla with 8 of 10 pieces)
- **Ganonhunt** - Collect the requisite triforce pieces, then defeat Ganon (Aga2 not required)
- **Completionist** - Obtain every item in the game and defeat Ganon (forces 100% accessibility)
### Item Sorting (Fill Algorithms)
Controls how items are placed in the world:
#### Balanced
Most random distribution of items (recommended).
#### Vanilla Fill
Attempts to place all items in their vanilla locations when possible. If not possible, prefers "major" locations, then heart piece locations, then the rest.
#### Major Location Restriction
Attempts to place major items in major locations. Major locations are where major items are found in the vanilla game.
#### Dungeon Restriction
Attempts to place all major items in dungeons. Overflows to overworld if necessary.
#### District Restriction
The world is divided into different regions/districts. Districts are chosen at random and filled with major items. Single green rupees indicate chosen districts.
CLI: `--algorithm [balanced|vanilla_fill|major_only|dungeon_only|district]`
### Forbidden Boss Items
Restrict items that can appear on bosses:
- **None** - Boss may have any item
- **MapCompass** - Map and compass are logically required to defeat a boss (currently bugged)
- **Dungeon** - Small keys and big keys of the dungeon are not allowed on a boss
CLI: `--restrict_boss_items [none|mapcompass|dungeon]`
---
## Entrance Randomization
### New Modes
- **Lite** - Non item entrances are vanilla, dungeons/caves grouped with restrictions
- **Lean** - Same grouping as Lite but cross-world connections allowed
- **Swapped** - Entrances are swapped with each other
### Shuffle Links House
In certain ER shuffles (not dungeonssimple or dungeonsfulls), control whether Links House is shuffled or remains vanilla.
### Skull Woods Shuffle
Options to reduce annoying Skull Woods layouts:
- **Original** - Skull woods shuffles classically amongst itself unless insanity mode
- **Restricted** - Skull woods drops are vanilla, entrances stay in skull woods and are shuffled
- **Loose** - Skull woods drops are vanilla, main ER mode's pool determines handling
- **Followlinked** - Follows Linked Drops setting
### Linked Drops Override
Controls whether drops should be linked to nearby entrances:
- **Unset** - Uses the mode's default (linked for all modes except insanity)
- **Linked** - Forces drops to be linked to their entrances
- **Independent** - Decouples drops from entrances
### Overworld Map
Option to move indicators on overworld map to reference dungeon location:
- **Default** - Showing only the prize markers on vanilla dungeon locations
- **Compass** - Compass item controls whether marker is moved to dungeon locations
- **Map** - Map item shows both prize and location of the dungeon
CLI: `--overworld_map [default|compass|map]`
---
## Enemizer
Enemizer has been incorporated into the generator. See [Enemizer in DR documentation](https://docs.google.com/document/d/1iwY7Gy50DR3SsdXVaLFIbx4xRBqo9a-e1_jAl5LMCX8/edit?usp=sharing) for extensive details.
### Enemy Shuffle
Enemies are shuffled with an enemy ban list that prevents problematic placements (blocking paths, unavoidable damage, glitches).
### Enemy Damage
The shuffled setting actually shuffles the damage table unlike the original enemizer.
### Boss Shuffle: Unique
Bosses are shuffled with some exceptions:
- Trinexx is not allowed on GT basement when DR is enabled
- Harder bosses in GT basement have logic concessions for low percentage requirements
New variant: At least one boss of each type for prize bosses will be present guarding prizes.
### Enemy Health
Health is taken into account for challenge rooms if magic or ammo is required.
### Enemy Logic
Can account for logical access to challenge rooms and item/key drops when enemies are shuffled:
- **Forbid special enemies** - Special enemies disallowed from drops and challenge rooms
- **Item drops may have special enemies** - Challenge rooms won't have special enemies, but drops may
- **Allow special enemies anywhere** - Both challenge rooms and enemy drops can have special requirements
---
## Glitched Logic
CLI: `--logic [noglitches|owglitches|hybridglitches|nologic]`
### Overworld Glitches
Includes overworld teleports, clips, superbunny, mirror to access Desert Palace East Entrance, bunny pocket access, etc.
### Hybrid Major Glitches
**Not compatible with Door Shuffle**
Includes all Overworld Glitches logic plus:
- Kikiskip to access PoD without MP or DW access
- IP Lobby clip to skip fire requirement
- Various traversals between dungeons (TT ↔ Desert, Spec rock, Paradox, Mire ↔ Hera ↔ Swamp)
- Stealing SK from Mire to open SP
- Using Mire big key to open Hera doors
---
## Game Options
### MSU Resume
Turns on MSU resume support.
CLI: `--msu_resume`
### Collection Rate
Display the collection rate unless the triforce piece counter is needed.
CLI: `--collection_rate`
### Reduce Flashing
Accessibility option to reduce some flashing animations in the game.
CLI: `--reduce_flashing`
### Shuffle Sound Effects
Shuffles a large portion of the sound effects. Can be used with the adjuster.
CLI: `--shuffle_sfx`
---
## Customizer
Create custom seeds with custom dungeons and rooms.
See [Customizer documentation](Customizer.md) for details.
---
## Generation Setup & Miscellaneous
### Create BPS Patches
Create BPS patch(es) instead of generating ROM(s) for distribution.
CLI: `--bps`
### Triforce Hunt Settings
Controls for triforce piece pool:
- `--triforce_goal_min` / `--triforce_goal_max` - Pieces to collect to win
- `--triforce_pool_min` / `--triforce_pool_max` - Pieces in item pool
- `--triforce_min_difference` / `--triforce_max_difference` - Difference between pool and goal
### Seed
Set a seed number to generate. Same seed with same settings on same version will always yield identical output.
### Count
Batch generate multiple seeds with same settings. If seed number provided, it will be used to derive subsequent seeds.

81
index.md Normal file
View File

@@ -0,0 +1,81 @@
---
layout: default
title: Home
nav_order: 1
---
# ALttP Dungeon Randomizer
**A dungeon randomizer for The Legend of Zelda: A Link to the Past**
Door Randomizer extends the standard ALttP Entrance Randomizer with advanced dungeon shuffling capabilities that can rearrange dungeon interiors at the room level, creating entirely new dungeon experiences.
[Download Latest Release](https://github.com/aerinon/ALttPDoorRandomizer/releases/latest){: .btn .btn-primary .fs-5 .mb-4 .mb-md-0 .mr-2 }
[View on GitHub](https://github.com/aerinon/ALttPDoorRandomizer){: .btn .fs-5 .mb-4 .mb-md-0 }
---
## What is Door Randomizer?
Door Randomizer takes the dungeon experience in A Link to the Past to the next level by shuffling the connections between rooms within dungeons. Instead of just shuffling dungeon entrances, Door Randomizer can:
- **Shuffle doors within dungeons** - Rooms connect in completely new ways
- **Cross dungeon boundaries** - Walk through a door in Eastern Palace and end up in Tower of Hera
- **Adjust intensity levels** - From basic door shuffling to complete dungeon lobby randomization
## Key Features
### Basic Randomizer Features
- Supports many standard ALttP Randomizer features without needing more advanced settings.
### Door Shuffle Modes
- **Vanilla** - No shuffling, classic experience
- **Basic** - Doors shuffled 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
### Advanced Features
- **Multiple key shuffle modes** - In dungeon, randomized, or universal keys
- **Pottery shuffle** - Randomize items under pots with multiple modes
- **Shopsanity** - 32 shop locations added to item pool
- **Enemy randomization** - Built-in enemizer with logic-aware placement
- **Custom seeds** - Create your own custom dungeons and rooms
- **Fill algorithms** - Multiple item placement strategies (balanced, vanilla fill, major only, district)
## Quick Start
1. [Download the latest release](https://github.com/aerinon/ALttPDoorRandomizer/releases/latest)
2. Extract the archive for your platform (Windows, Mac, or Linux)
3. Run `DungeonRandomizer.exe` (or the appropriate platform executable)
4. Configure your settings and generate a seed
5. Apply the patch to your A Link to the Past ROM (must be JP 1.0 version)
[See detailed installation instructions →](/installation)
## Community
Join the discussion and get help:
- **Discord**: [ALTTP Randomizer Discord](https://discordapp.com/invite/alttprandomizer)
- `#door-rando` - General discussion and help
- `#bug-reports` - Report bugs and issues
## Learn More
- [Features Guide](/features) - Comprehensive feature documentation
- [Installation & Usage](/installation) - Setup and running the randomizer
- [Known Issues](/known-issues) - Current bugs and limitations
- [Roadmap](/roadmap) - Future development plans
- [Blog](/blog) - Latest updates and release notes
## Credits
Based on the [ALttP Entrance Randomizer](https://github.com/KevinCathcart/ALttPEntranceRandomizer) by KevinCathcart et al.
See [alttpr.com](https://alttpr.com/) for more details on the original VT randomizer.

369
installation.md Normal file
View File

@@ -0,0 +1,369 @@
---
layout: default
title: Installation & Usage
nav_order: 3
---
# Installation & Usage
{: .no_toc }
Complete guide to installing and running ALttP Door Randomizer.
{: .fs-6 .fw-300 }
## Table of contents
{: .no_toc .text-delta }
1. TOC
{:toc}
---
## Requirements
- Python 3.10 or higher (for running from source)
- A legal copy of The Legend of Zelda: A Link to the Past (JP 1.0 version) ROM
---
## Installation Methods
### Method 1: Pre-built Releases (Recommended)
This is the easiest method for most users.
1. Visit the [Releases page](https://github.com/aerinon/ALttPDoorRandomizer/releases)
2. Download the appropriate build for your system:
- **Windows**: `ALttPDoorRandomizer-{version}-windows.zip`
- **macOS**: `ALttPDoorRandomizer-{version}-osx.tar.gz`
- **Linux**: `ALttPDoorRandomizer-{version}-linux-focal.tar.gz`
3. Extract the archive to a folder of your choice
4. Run the executable:
- **Windows**: `DungeonRandomizer.exe`
- **macOS/Linux**: `./DungeonRandomizer` or `./Gui.py`
### Method 2: Running from Source
For developers or users who want to run the latest development version.
#### Step 1: Clone the Repository
```bash
git clone https://github.com/aerinon/ALttPDoorRandomizer.git
cd ALttPDoorRandomizer
```
For the development branch:
```bash
git checkout DoorDevUnstable
```
#### Step 2: Install Python Dependencies
The project includes a script to install platform-specific dependencies:
```bash
python resources/ci/common/local_install.py
```
This will install all necessary Python packages and platform-specific dependencies.
#### Step 3: Verify Installation
Test that everything is working:
```bash
python DungeonRandomizer.py --help
```
You should see the help text with all available options.
---
## Usage
### GUI (Graphical User Interface)
The GUI provides an easy-to-use interface for generating seeds.
#### Starting the GUI
**Pre-built release:**
- **Windows**: Double-click `DungeonRandomizer.exe`
- **macOS/Linux**: Run `./DungeonRandomizer` from terminal
**From source:**
```bash
python Gui.py
```
#### Using the GUI
1. **Select your ROM**: Click "Select ROM" and choose your ALttP ROM file
2. **Configure settings**: Use the tabs to adjust:
- **Dungeon Settings**: Door shuffle mode, intensity, key logic
- **Item Settings**: Item placement, shopsanity, pottery
- **Entrance Settings**: Entrance randomization options
- **Enemy Settings**: Enemy shuffle, boss shuffle
- **Game Options**: MSU resume, collection rate, etc.
3. **Generate**: Click "Generate" to create your seed
4. **Output**: The patched ROM will be created in the same directory
### CLI (Command-Line Interface)
The CLI offers more control and is useful for batch generation or scripting.
#### Basic Usage
```bash
python DungeonRandomizer.py [options]
```
#### Common Examples
**Basic crossed dungeon shuffle:**
```bash
python DungeonRandomizer.py --doorShuffle crossed --intensity 2
```
**With key shuffle and shopsanity:**
```bash
python DungeonRandomizer.py --doorShuffle crossed --keyshuffle wild --shopsanity
```
**Pottery and enemy drops:**
```bash
python DungeonRandomizer.py --doorShuffle basic --pottery lottery --dropshuffle underworld
```
**Generate without creating ROM (testing):**
```bash
python DungeonRandomizer.py --suppress_rom --spoiler none
```
**Create BPS patch instead of ROM:**
```bash
python DungeonRandomizer.py --bps --doorShuffle crossed
```
**Batch generation:**
```bash
python DungeonRandomizer.py --doorShuffle crossed --count 10
```
#### Key CLI Arguments
**Dungeon Settings:**
- `--doorShuffle [vanilla|basic|partitioned|crossed]` - Door shuffle mode
- `--intensity [1|2|3]` - Intensity level
- `--keyshuffle [none|wild|universal]` - Key shuffle mode
- `--key_logic [partial|strict|dangerous]` - Key logic algorithm
- `--door_type_mode [original|big|all|chaos]` - Door type shuffle
- `--trap_door_mode [vanilla|optional|boss|oneway]` - Trap door removal
**Item Settings:**
- `--algorithm [balanced|vanilla_fill|major_only|dungeon_only|district]` - Item placement
- `--pottery [none|keys|cave|cavekeys|reduced|clustered|nonempty|dungeon|lottery]` - Pot shuffle
- `--dropshuffle [none|keys|underworld]` - Enemy drop shuffle
- `--shopsanity` - Enable shop randomization
- `--bombbag` - Enable bomb bag item
- `--pseudoboots` - Enable pseudo boots
**Entrance Settings:**
- `--shuffle [vanilla|simple|restricted|full|crossed|insanity|...]` - Entrance shuffle mode
- `--overworld_map [default|compass|map]` - Overworld map mode
**Enemy Settings:**
- `--enemizercli [none|basic|shuffled]` - Enemy shuffle mode
- `--enemy_damage [default|shuffled|chaos]` - Enemy damage
- `--enemy_health [default|easy|hard]` - Enemy health
- `--shufflebosses [none|basic|normal|chaos|unique]` - Boss shuffle
**Logic:**
- `--logic [noglitches|owglitches|hybridglitches|nologic]` - Logic mode
- `--mode [open|standard|inverted]` - Game mode
- `--goal [ganon|trinity|ganonhunt|completionist]` - Victory condition
**Generation:**
- `--seed SEED` - Set seed number
- `--count N` - Generate N seeds
- `--suppress_rom` - Don't create ROM (testing)
- `--bps` - Create BPS patch instead of ROM
- `--spoiler [none|spoiler|playthrough]` - Spoiler log type
**Game Options:**
- `--msu_resume` - Enable MSU resume
- `--collection_rate` - Display collection rate
- `--reduce_flashing` - Reduce flashing animations
- `--shuffle_sfx` - Shuffle sound effects
For a complete list of options:
```bash
python DungeonRandomizer.py --help
```
---
## Multiworld Setup
Door Randomizer supports multiworld seeds where multiple players play different randomized games with shared item pools.
### Installing Multiworld Dependencies
Run the same installation script to install multiworld-specific dependencies:
```bash
python resources/ci/common/local_install.py
```
### Generating Multiworld Seeds
Create YAML files for each player (see `docs/player1.yml`, `docs/player2.yml`, `docs/player3.yml` for individual examples, or `docs/multi_mystery_example.yaml` for a complete multiworld configuration).
**Example player configuration:**
```yaml
description: Player 1's World
name: Player1
doorShuffle: crossed
intensity: 2
keyshuffle: wild
shopsanity: true
```
Generate the multiworld using the multi-mystery configuration file:
```bash
python DungeonRandomizer.py --customizer docs/multi_mystery_example.yaml
```
### Running Multiworld Server
```bash
python MultiServer.py
```
It will prompt you for the multidata file created from the multiworld generation step.
### Connecting with Multiworld Client
```bash
python MultiClient.py
```
Enter the server address and your player name to connect.
---
## Testing & Verification
### Running the Test Suite
To verify your installation and test the randomizer logic:
```bash
python TestSuite.py
```
**Test with specific settings:**
```bash
python TestSuite.py --dr basic --count 10 --tense 2
```
**Run specific test modules:**
```bash
python -m pytest test/
python -m pytest test/dungeons/TestDarkPalace.py
```
---
## Troubleshooting
### Common Issues
#### "Python not found" or "python: command not found"
- **Windows**: Make sure Python is installed and added to PATH during installation
- **macOS/Linux**: Install Python 3.10+ via your package manager or from [python.org](https://www.python.org/)
#### "No module named 'yaml'" or similar import errors
Run the dependency installation script:
```bash
python resources/ci/common/local_install.py
```
#### Pre-built executable won't run on macOS
macOS may block unsigned applications. Right-click the app and select "Open" to bypass the warning.
#### Pre-built executable won't run on Linux
Ensure the file has execute permissions:
```bash
chmod +x DungeonRandomizer
```
#### GUI window is too small or cut off
Try running from the command line to see if there are any error messages. Some display scaling settings can cause issues.
#### Generated ROM doesn't work with emulator
- Ensure you're using a clean US version of ALttP ROM (Japan 1.0)
- Try a different emulator (recommended: SNES9x, RetroArch with bsnes core)
- Verify the ROM was patched successfully (check file size and modification date)
### Getting Help
If you encounter issues:
1. Check the [Known Issues](/known-issues) page
2. Search [GitHub Issues](https://github.com/aerinon/ALttPDoorRandomizer/issues)
3. Ask in the [ALTTP Randomizer Discord](https://discordapp.com/invite/alttprandomizer):
- `#door-rando` - General help and questions
- `#bug-reports` - Report bugs and issues
When reporting issues, please include:
- Operating system and version
- Python version (`python --version`)
- Door Randomizer version or commit hash
- Full error message or description of the problem
- Settings used (CLI command or screenshot of GUI)
---
## Advanced Usage
### Custom Presets
You can create custom preset files to save your favorite settings combinations.
See the [Customizer documentation](docs/Customizer.md) for details on creating custom seeds with custom dungeons and rooms.
### Build from Source (Packaging)
To create a standalone executable from source:
See [BUILDING.md](docs/BUILDING.md) for detailed build instructions.
### Development Workflow
For contributors:
1. Fork the repository
2. Create a feature branch from `DoorDevUnstable`:
```bash
git checkout DoorDevUnstable
git checkout -b my-feature
```
3. Make your changes
4. Run tests: `python TestSuite.py`
5. Submit a pull request to `DoorDevUnstable` (not main/master)
---
## Next Steps
- Read the [Features Guide](/features) for detailed information on all settings
- Check the [Known Issues](/known-issues) page for current limitations
- See the [Roadmap](/roadmap) for upcoming features
- Join the community on [Discord](https://discordapp.com/invite/alttprandomizer)

373
known-issues.md Normal file
View File

@@ -0,0 +1,373 @@
---
layout: default
title: Known Issues
nav_order: 4
---
# Known Issues & Bug Tracking
{: .no_toc }
Current known issues, bugs, and limitations in ALttP Door Randomizer.
{: .fs-6 .fw-300 }
## Table of contents
{: .no_toc .text-delta }
1. TOC
{:toc}
---
## Reporting Bugs
Before reporting a bug, please:
1. Check this page to see if the issue is already known
2. Search [existing GitHub issues](https://github.com/aerinon/ALttPDoorRandomizer/issues)
3. Verify you're using the latest version
### How to Report
Report bugs in this location:
- **Discord**: [ALTTP Randomizer Discord](https://discordapp.com/invite/alttprandomizer) in `#bug-reports` or `#door-rando` channels
### What to Include
When reporting a bug, please provide:
- **Spoiler log** if you have one
- If you don't have a spoiler log, include:
- **Seed number** and **settings used**
- **Version** of Door Randomizer (from GUI or `--version`)
- **Website or Platform** (Windows, macOS, Linux) if generator error, or which website was used
- **Description** of the issue
- **Steps to reproduce** the problem
- **Screenshots or videos** (if applicable)
- Optionally, **Save state** (if gameplay issue) (and which emulator/version)
---
## Known Issues
### Critical Issues
#### Dungeon Key HUD indicator
**Status**: Under investigation
Dungeon Key HUD indicator shows incorrect total number of keys under certain settings.
#### Links House on Death Mountain - no logical way off the mountain
**Status**: Under investigation
Some ER generations can have Link's House be on Death Mountain and no good way off the mountain.
---
### Major Issues
#### Crossed Dungeon Generation Can Be Slow
**Status**: Performance optimization needed
Generating crossed dungeon seeds, especially with high intensity and complex settings, can take a significant amount of time (30 seconds to several minutes).
**Why**: The dungeon generation algorithm uses constraint satisfaction and local search, which can require many attempts to find valid layouts.
**Workaround**: Be patient, or reduce intensity/complexity of settings.
#### Rare Impossible Seeds (Generation Failures)
**Status**: Occasional, investigating
In rare cases, the generator may fail to place all items or create a valid dungeon layout. This usually happens with very restrictive settings combinations.
**Workaround**: Try a different seed number, or slightly adjust settings.
---
### Moderate Issues
#### Some Enemy Placements Can Be Problematic
**Status**: Ongoing ban list maintenance
Despite the enemy ban list, some enemy placements can occasionally cause issues:
- Blocking required paths
- Causing unavoidable damage
- Creating glitchy behavior
- Bush enemies not working correctly
- Wallmasters can cause issues in certain locations
**Workaround**: Report specific problematic enemy locations so they can be added to the ban list.
**Note**: Thieves are always unkillable and banned from the entire underworld.
---
### Minor Issues
#### Forbidden Boss Items "MapCompass" Mode Bugged
**Status**: Under investigation
The `mapcompass` option for `--restrict_boss_items` is currently bugged and not recommended for use.
**Workaround**: Use `dungeon` option instead, or use `none`.
#### Swamp Trench 2 Keeps Draining
**Status**: Known issue
In some configurations, Swamp Trench 2 continues to drain even after the pot is obtained.
**Workaround**: None currently. This is a known behavior issue.
#### Killing Certain Red Guards Kills Music
**Status**: Known issue
Killing certain red guards in specific locations causes the music to stop playing.
**Workaround**: None currently. This is a cosmetic issue that doesn't affect gameplay.
#### Some Lobbies Exitable During Escape (Standard Mode)
**Status**: Known issue
In standard mode, some dungeon lobbies can be exited during the escape sequence when they shouldn't be.
**Workaround**: Avoid leaving during escape if you want to maintain intended flow.
---
### Logic Issues
These are cases where the logic may not perfectly match what's actually possible in-game:
#### GT Crystal Paths Room Logic
**Status**: Under investigation
Crystal switch logic for GT Crystal Paths room may not properly account for OHKO scenarios when traversing backwards.
#### OHKO (One-Hit KO) Logic Issues
**Status**: Under investigation
In some configurations, unavoidable damage logic or OHKO scenarios may not be properly accounted for.
#### Hammerjump Logic and Mixed Travel
**Status**: Configurable behavior
Hammerjump and similar tricks (PoD Arena hovering, Mire Big Key bomb jump) can unintentionally put you in another dungeon with the wrong dungeon ID.
**Setting**: Use `--mixed_travel` to control this behavior:
- `prevent`: Adds rails to prevent tricks (default, recommended for learning)
- `allow`: Up to player discretion
- `force`: Sections forced to same dungeon
---
## Mode-Specific Issues
### Glitched Logic Modes
Several issues specific to glitched logic modes (OWG, HMG):
#### Cave State Issues
**Status**: Under investigation
Cave state in GT hearts area may not work correctly in glitched modes.
#### Rain State Issues
**Status**: Under investigation
Rain state handling may have issues in glitched logic modes.
#### Key/Pot SRAM System
**Status**: Needs restoration
Old key/pot SRAM system needs to be restored for glitched modes to work properly.
### Inverted Mode Issues
#### Dark Sanctuary Inverted Insanity
**Status**: Under investigation
Dark Sanctuary with inverted mode and insanity entrance shuffle may have double entrance issues.
#### Dark Sanctuary at Tavern Error
**Status**: In progress
When Dark Sanctuary is at Tavern location, Link's body position may be incorrect.
### Entrance Randomization Issues
#### Dungeon Boss Exits in Non-ER
**Status**: Under investigation
Dungeon boss exits may not work correctly when entrance randomization is disabled.
### Decoupled Doors Issues
#### Sanctuary Palette Detection
**Status**: Known issue
In decoupled doors mode, sanctuary palette doesn't correctly identify adjacent rooms. Uses exits instead of entrances for determination.
**Workaround**: Use coupled doors or original palette mode.
### Shopsanity Issues
#### Output YAML: Shopsanity Potions Missing
**Status**: Under investigation
When outputting to YAML format, shopsanity potions may not be correctly included in the item pool representation.
**Workaround**: Check spoiler log for actual item locations.
---
## Known Limitations & Design Decisions
These items are **not planned to be fixed** as they are either fundamental limitations, intentional design choices, or affect all ALttP randomizers.
### Game Engine Limitations
#### Compass Count Stops Working After Triforce
After obtaining the Triforce, compass counts no longer function correctly. This is true in all ALttP randomizers and is a base game limitation.
**Workaround**: Complete dungeon exploration before finishing the game if you need counts.
#### GT Bosses Don't Respawn
GT bosses don't respawn after killing them. This is intentional base game behavior.
### Door Randomizer Design Decisions
#### Hybrid Major Glitches Not Compatible with Door Shuffle
Hybrid major glitches logic is not compatible with door shuffle modes. This is a fundamental limitation due to how glitch logic interacts with shuffled dungeon interiors.
**Workaround**: Use Overworld Glitches logic instead, or disable door shuffle.
#### Fire Rod Not in Logic for Dark Rooms
Fire Rod is not in logic for dark rooms in door shuffle mode, as it's too difficult to determine which dark room you're in after doors are shuffled.
**Note**: This is different from Advanced mode in the vanilla randomizer.
#### Hammerjump Requiring Mixed Travel Settings
Hammerjump and similar tricks (PoD Arena hovering, Mire Big Key bomb jump) require `--mixed_travel` settings in crossed mode to allow unintended dungeon transitions.
#### Blind Maiden/Attic Sequence Always Required
Blind maiden/attic sequence is required even when boss is shuffled. This maintains story consistency.
#### Southeast Skull Woods Chest Not Guaranteed Key
In Entrance Randomizer, the southeast Skull Woods chest is guaranteed to be a small key. In Door Randomizer, this is not guaranteed. This is an intentional change from ER.
### Technical Limitations
#### Pottery Lottery Mode: Multiworld Item Limit
In pottery lottery mode, only 256 items for other players can be placed under pots in your world due to technical constraints in how the game tracks items.
---
## Feature Limitations
See the [Roadmap](/roadmap) for planned features.
---
## Recently Fixed Issues
See RELEASENOTES.md for the latest fixes.
And PastReleaseNotes.md for older fixes.
---
## Performance Issues
### Memory Usage
**Issue**: Generator can use significant memory for complex seeds.
**Most affected by**:
- Multiworld with many players
- Pottery lottery mode
**Workaround**: Close other applications, or increase available RAM.
---
## Emulator Compatibility
### Known Issues with Emulators
#### Older SNES9x versions
Some older versions (< 1.55) may have graphical glitches with certain custom graphics.
#### ZSNES
**Not recommended**: ZSNES is outdated and has known accuracy issues.
---
## Workarounds & Tips
### If Generation Keeps Failing
1. Switch to a different door shuffle mode
4. Disable some restrictive settings (strict key logic, dungeon item restrictions)
5. Use balanced fill algorithm instead of district restriction
### If Seed Seems Impossible
1. Check spoiler log to verify it's beatable
2. Remember new logic differences (see Features guide)
3. Check for required techniques (boots bonking, crystal switch bombs, etc.)
4. Ask for help in Discord with spoiler log
### If Performance Is Poor
1. Use pre-built executable instead of running from source
2. Close other applications
3. Update to latest version
4. Use simpler settings combinations
---
## Issue Status Tracking
For real-time status of known issues, check:
- Discord `#bug-reports` and `#door-rando` channels
---
Last updated: 2026-01-30
This page is maintained as issues are discovered and fixed. If you notice an issue not listed here, please report it!

234
roadmap.md Normal file
View File

@@ -0,0 +1,234 @@
---
layout: default
title: Roadmap
nav_order: 5
---
# Development Roadmap
{: .no_toc }
Future plans and upcoming features for ALttP Door Randomizer.
{: .fs-6 .fw-300 }
## Table of contents
{: .no_toc .text-delta }
1. TOC
{:toc}
---
## Project Vision
Door Randomizer aims to provide the most comprehensive and flexible dungeon randomization experience for A Link to the Past while maintaining playability and logical consistency. Our focus is on:
1. **Robust Generation** - Ensuring seeds are always completable and logical
2. **Feature Richness** - Providing extensive customization options
3. **Community Engagement** - Responding to player feedback and needs
4. **Performance** - Improving generation speed and reliability
---
## Bug Fixes
Critical and important bugs that need to be addressed:
### Critical Bugs
- Dungeon Key HUD indicator issue (total is incorrect)
- Links House on DM pathing issues (See OWR solution)
### Minor Bugs
- Resolve Swamp Trench 2 draining issue (pot obtained but still drains)
- Fix OHKO logic issues - Crystal Path backwards in GT
- Fix MapCompass forbidden boss items mode (currently bugged)
- Killing Certain Red Guards Kills Music
---
## Logic & Generation Improvements
Improving dungeon generation algorithms and logic:
- Enhanced key logic algorithms (experimental mode in New Generation)
- Rework Uncle weapon/Escape small key
- Make Sanctuary heart the logical one (simplify sanctuary heart logic)
- Investigate rupee balancing issues causing failed generations
---
## New Features
New functionality and game modes, mostly planned for the NewGeneration branch:
- Portal placement flexibility (customizability and mixed dungeon pools)
- Smarter trap door placement (reduce forced mirroring)
- DR Keysanity menu improvements
- PitWarp feature
- Door Type pooling customizations
- OWR ER standardization (District ER, Links on Death Mountain issue)
- NewSwappedAlgorithm integration
- Bonk Item Pool from Overworld Randomizer (downstream integration)
- A better hint system
- Prize Shuffle from Overworld Randomizer (downstream integration)
- Map Screen from GK Randomizer (need to investigate)
- Other downstream integrations? (custom goals, follower shuffle, flute shuffle?)
---
## Quality of Life Enhancements
Improving user experience and usability:
- Preferred location groups (control item placement with warnings/failures/retries)
- Preset support
- Control output ROM name (customize generated ROM filename)
- Progress indicators for generations
- Better entrance tracking for trackers (investigate race legality)
- Super-tile split palettes (reduce hinting from palette colors)
- Turn off Bob by default for enemizer (fewer graphical glitches)
---
## Performance Improvements
Making generation faster and more efficient:
- Reduce memory footprint
---
## Customization & Content Creation
Tools and features for creating custom content:
- Re-design customizer file format (improved YAML structure)
- Presets for customizer (start from predefined base)
- Easier enemy customization (simpler interface for customizing specific enemies - better integration with customization system)
---
## Multiworld
Enhancements for multiplayer seeds:
- Multiworld documentation
- Ability to have similar randomizations across multiworlds (makes parts of it co-op)
---
## External Tools & Integration
Integration with external tools and platforms:
- Tracker integration features
- Web-based API
---
## Technical Debt & Refactoring
Behind-the-scenes code improvements:
- Modernize Rules.py (improve readability and maintainability)
- Python upgrade (3.10 deprecated in 2026)
---
## Research & Exploration
Experimental ideas that may or may not be implemented:
### Dungeon Randomization Ideas
- **Subroom randomization** - Randomize smaller rooms within a larger room (subtile vs. supertile doors)
- **Euclidean dungeon layouts** - Dungeon randomization that makes spatial sense (rooms connected geographically)
- **Swapped dungeon generation** - Create dungeons by swapping door destinations (requires new algorithms)
---
## Branch Strategy
### Current Branches
- **NewGeneration** - Active development branch for new generation system
- **NewSwappedAlgorithm** - Experimental branch for swapped item algorithm
- **DoorDevUnstable** - Main branch, maintenance mode - only bug fixes and patches (ready to be moved to official stable)
- **DoorDev** - Stale development branch (needs update)
- **Dev/Master** - Do NOT use for PRs. Used by upstream only.
### Planned Branch Changes
- Transition from DoorDevUnstable to DoorDev as main maintenance branch
- Transition NewGeneration to main development branch
---
## Completed Features
Recent accomplishments:
- ✅ Dynamic colored pots
- ✅ Free lamp cone
- ✅ Experimental key logic improvements
---
## How to Contribute
Want to help shape the future of Door Randomizer?
### For Players
- **Test seeds** - Play with different settings and report issues
- **Provide feedback** - Share what you like and what could be better
- **Suggest features** - Tell us what you want to see
### For Developers
- **Submit PRs to DoorDevUnstable**
- **Join Discord** - Discuss development in `#door-rando`
- **Write tests** - Improve test coverage
- **Improve documentation** - Help others understand the code
### For Creators
- **Custom rooms** - Design interesting custom rooms
- **Presets** - Create balanced preset configurations
- **Tutorials** - Teach others how to use Door Rando
- **Tools** - Build complementary tools (trackers, analyzers)
---
## Release Schedule
### Regular Releases
- **Unstable builds** - Automated on every push to DoorDevUnstable
- **Hotfixes** - As needed for critical bugs
### Upcoming Releases (Tentative)
- **v1.5.x** (Q2 2026) - DoorDevUnstable becomes DoorDev
- **v1.6** (Q3 2026) - Python upgrade
- **v2.0** (Q4 2026) - New Generation branch release
---
## Success Metrics
How we measure progress:
### Technical Metrics
- Generation success rate (target: >95%)
- Average generation time (target: <10s for crossed seeds)
- Memory usage (start measuring)
- Test coverage (start measuring)
---
## Feedback & Discussion
Have thoughts on the roadmap?
- **Discord**: Join `#door-rando` to discuss
---
*This roadmap is a living document and will be updated regularly as priorities shift and progress is made.*
Last updated: 2026-01-30