Installation & Usage

Complete guide to installing and running ALttP Door Randomizer.

Table of contents

  1. Requirements
  2. Installation Methods
    1. Method 1: Pre-built Releases (Recommended)
    2. Method 2: Running from Source
      1. Step 1: Clone the Repository
      2. Step 2: Install Python Dependencies
      3. Step 3: Verify Installation
  3. Usage
    1. GUI (Graphical User Interface)
      1. Starting the GUI
      2. Using the GUI
    2. CLI (Command-Line Interface)
      1. Basic Usage
      2. Common Examples
      3. Key CLI Arguments
  4. Multiworld Setup
    1. Installing Multiworld Dependencies
    2. Generating Multiworld Seeds
    3. Running Multiworld Server
    4. Connecting with Multiworld Client
  5. Testing & Verification
    1. Running the Test Suite
  6. Troubleshooting
    1. Common Issues
      1. “Python not found” or “python: command not found”
      2. “No module named ‘yaml’” or similar import errors
      3. Pre-built executable won’t run on macOS
      4. Pre-built executable won’t run on Linux
      5. GUI window is too small or cut off
      6. Generated ROM doesn’t work with emulator
    2. Getting Help
  7. Advanced Usage
    1. Custom Presets
    2. Build from Source (Packaging)
    3. Development Workflow
  8. Next Steps

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

This is the easiest method for most users.

  1. Visit the Releases page
  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

git clone https://github.com/aerinon/ALttPDoorRandomizer.git
cd ALttPDoorRandomizer

For the development branch:

git checkout DoorDevUnstable

Step 2: Install Python Dependencies

The project includes a script to install platform-specific dependencies:

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:

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:

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

python DungeonRandomizer.py [options]

Common Examples

Basic crossed dungeon shuffle:

python DungeonRandomizer.py --doorShuffle crossed --intensity 2

With key shuffle and shopsanity:

python DungeonRandomizer.py --doorShuffle crossed --keyshuffle wild --shopsanity

Pottery and enemy drops:

python DungeonRandomizer.py --doorShuffle basic --pottery lottery --dropshuffle underworld

Generate without creating ROM (testing):

python DungeonRandomizer.py --suppress_rom --spoiler none

Create BPS patch instead of ROM:

python DungeonRandomizer.py --bps --doorShuffle crossed

Batch generation:

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:

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:

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:

description: Player 1's World
name: Player1
doorShuffle: crossed
intensity: 2
keyshuffle: wild
shopsanity: true

Generate the multiworld using the multi-mystery configuration file:

python DungeonRandomizer.py --customizer docs/multi_mystery_example.yaml

Running Multiworld Server

python MultiServer.py

It will prompt you for the multidata file created from the multiworld generation step.

Connecting with Multiworld Client

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:

python TestSuite.py

Test with specific settings:

python TestSuite.py --dr basic --count 10 --tense 2

Run specific test modules:

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

“No module named ‘yaml’” or similar import errors

Run the dependency installation script:

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:

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 page
  2. Search GitHub Issues
  3. Ask in the ALTTP Randomizer Discord:
    • #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 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 for detailed build instructions.

Development Workflow

For contributors:

  1. Fork the repository
  2. Create a feature branch from DoorDevUnstable:
    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

Back to top

Copyright © 2026 ALttP Door Randomizer Team. Based on ALttP Entrance Randomizer.

This site uses Just the Docs, a documentation theme for Jekyll.