Plandomizer

Plandomizer allows you to have total control over item placement. You can place a specific item on any location and locations not specified will be filled following the normal algorithm. Using a .json format text file, referred to as a distribution file when using plandomizer, you can override many different aspects of the randomizer.

This can allow you to create custom challenges you can play through yourself or share with others. The more details defined in a plandomizer the less the randomizer interferes, though the randomizer will still verify whether it is beatable based on your logic settings, and if it is logically impossible it will refuse to generate a seed.

There is a beta GUI for Plandomizer on the website that can help you with simpler plandomizer ideas, however to truly grasp the power of plandomizer you will have to modify a distribution file yourself.

Using a Plandomizer Distribution File on the Generator

Plandomizer's distribution file text box is hidden by default. To enable it all you have to do is go to ROM Options on the generator and turn on the Enable Plandomizer (Optional) setting. Then use the Browse button next to the new text box to find your Plandomizer distribution .json file.

Opening and Editing a Distribution File

Distributions are just normal text files using the .json extension instead of the .txt extension. They can be opened in any text editor that will open .txt files. Even Notepad, TextEdit, and gedit can open these files. The extension is only to help let you know that text within is expected to look a certain way.

Distribution File Format

JSON is a common format used for data that both a human and a computer are intended to read. It's a fairly picky format so it is a good idea to use a text editor that can tell you if you did something wrong through syntax highlighting. Visual Studio Code is such a text editor, and as it is cross-platform and used by many people in the community it is the one we recommend you use if you go down this path. You can also check that your file is properly formatted by using a validator such as JSONLint if you prefer to keep on using a text editor without syntax highlighting. It might also help you find an issue that you're having a hard time understanding in VSCode.

The randomizer generator on the website will also give you an error if you try to use a distribution file that is not in the proper JSON format. You may wish to use this, JSONLint, and VSCode all together to figure out how to fix any formatting problems you are having.

Understanding a Distribution File

When you generate a seed with a spoiler log, that spoiler log is actually a distribution file itself. It can be used directly to generate the exact same seed. Because of this, you can take a look at a spoiler log to help you get familiar with the types of things that can be changed, and how to format the distribution file.

Since a distribution file is in JSON format, it's somewhat rigid about how things can be written.

The Base Dictionary

First, a distribution file starts with a { opening curly brace, and ends with a } closing curly brace. Everything you define must be placed between these braces. These braces mark a Dictionary or an associative array, and while that link has a lot of useful information, you don't really have to understand it. Think of a dictionary data structure like you would a dictionary in the real world. You have a term, then you have the definition of that term. As this is the base dictionary, you don't write a term as the code that reads the JSON file creates its own term for this dictionary.

The Dictionary "Terms"

Within the base dictionary there are many terms, such as :version, file_hash, and locations. If you are viewing a spoiler log you'll notice some of these terms start with a :. These terms are ignored when Plandomizer is used and are autogenerated by the randomizer. When you are creating a distribution file yourself you can delete these terms.

Terms are followed by a : and then some spaces, then their definitions.

Definitions that start and end with " are Strings. They are just text you write, but it is important that they are between quotes.

Definitions starting with [ an open bracket and ending with a ] closing bracket are called Lists. In a distribution file lists will usually only contain strings. However, with other types of JSON files you could see them containing other data structures such as dictionaries, or other lists.

The rest of the definitions are just more dictionaries with their own terms that have definitions. These are the only data structures that you have to keep in mind, and generally they are already defined properly in the spoiler log for you so you can just modify them how you see fit. Just ensure you don't accidentally remove the symbols that go before and after the term.

The Most Common Format/Syntax Issue

You'll notice that each of these terms is followed at the very end by a , comma, except the very last one. This is probably the most common mistake someone will make when making their own distribution file. Each term needs to be separated by a comma, but the last one cannot have a comma after it. This is true for strings inside of lists, and lists, strings, and other dictionaries within a dictionary as well. If you are getting a syntax error, you probably added a comma you shouldn't have, or removed one you need. The generator will tell you that your JSON is invalid if you try to use a distribution file with one of these errors.

What Can Plandomizer Affect

Plandomizer can affect an enormous amount of the resulting seed. Everything from inconsequential things like the File Hash, to the Settings the randomizer uses to fill the world, and even specifically set items in locations that the world fill algorithm will have to work around.

File Hash

The file hash is the 5 icons that are displayed at the top of the file select screen. You can set these to any valid HASH_ICON.

You can set the file_hash definition to a list of up to 5 hash icons. If you do not want to specify an icon for a set position you can either set it to the value null, or if it is after all the ones you do want to set you can just not include it.

Hash Icons

Expand to view the full list of valid hash icons for the current version of the randomizer.

    'Deku Stick',
    'Deku Nut',
    'Bow',
    'Slingshot',
    'Fairy Ocarina',
    'Bombchu',
    'Longshot',
    'Boomerang',
    'Lens of Truth',
    'Beans',
    'Hammer',
    'Bottled Fish',
    'Bottled Milk',
    'Mask of Truth',
    'SOLD OUT',
    'Cucco',
    'Mushroom',
    'Saw',
    'Frog',
    'Master Sword',
    'Mirror Shield',
    'Kokiri Tunic',
    'Hover Boots',
    'Silver Gauntlets',
    'Gold Scale',
    'Stone of Agony',
    'Skull Token',
    'Heart Container',
    'Boss Key',
    'Compass',
    'Map',
    'Big Magic',

Examples

Set all 5 icons to Deku Nut:

"file_hash": ["Deku Nut", "Deku Nut", "Deku Nut", "Deku Nut", "Deku Nut"]

Set only the first icon to Deku Nut:

"file_hash": ["Deku Nut", null, null, null, null]

or

"file_hash": ["Deku Nut"]

Set only the last icon to Deku Nut:

"file_hash": [null, null, null, null, "Deku Nut"]

Settings

This is a dictionary defining the rules that the randomizer uses to fill the world. Any settings you set here will override the ones set in the GUI. That also means that you can leave some settings out of this dictionary and the person using your distribution file to create a seed can have a small amount of customization they can apply in case they need a little more additional help, or perhaps want to increase the difficulty a little bit.

It is not recommended to set these manually. Instead, you should go to the beta plandomizer maker on the website. You can set all the settings you want on the first tab, then create the JSON file. From here you can copy the settings dictionary from that file into this file and remove any settings you don't want to enforce. Alternatively, if you only want a few settings to be enforced, you can copy only the settings you want from the dictionary in that other JSON file into the settings dictionary in your settings file.

There are two major issues with creating the settings dictionary entirely manually:

1. If you mistype, or the name of a setting changes between versions, you will not get an error. The randomizer will just ignore this issue entirely.
2. The process of figuring out the proper name for a setting, and the various values it can hold is tedious.

If you still think you want to try this method, the file in the source code you want to look at to see all this necessary information is SettingsList.py. This is a 3000 line monstrosity that isn't very useful if you're not already pretty familiar with the settings you are looking for in the first place. Each setting has a name that you have to use for a definition inside of the settings dictionary. Then various other variables within the option's object in the settings list file are used to determine what possible definitions you want to use for that setting.

Just using the plandomizer maker on the website is highly recommended over putting yourself through this experience.

Starting Items

The starting items dictionary lets you define what items a player starts with, and how many of them. This includes both items you find in the world, and consumables you would pick up such as ammo and bombs. Any items you start with will be replaced by junk in the item pool. Songs placed here will force an item to be on one of the song locations even if shuffle_song_items is not set. This will completely override the starting items set on the randomizer generator GUI.

The term is the item you want to start with. The definition is how many of that item you want to start with. The number is not a string and should not be put in quotes.

Examples

Start with full wallet without Max Rupees setting:

"starting_items": {
    "Rupees": 99
}

Start with all shields:

"starting_items": {
    "Deku Shield": 1,
    "Hylian Shield": 1,
    "Mirror Shiled": 1
}

Item Pool

This is a dictionary defining every item possible to place in the world. It is highly recommended that you do not set every possible item to a value in this dictionary. Primarily junk items. This would make your plandomizer very rigid and can cause various issues if you try changing settings that change what, and how many items you start with, or that are available in the base pool.

You can also specify if you want to add to the base number, remove from the base number, or set the base number for the item. The default is to set the value. If you want to use the other options you'll need to set the definition to be another dictionary.

The term is the item you want to specify the number of in the pool. The definition is either:

1. The number of that item you want in the pool
2. A dictionary with a term of type set to any of the strings "add", "remove", or "set" and a term of count set to the number to modify by.

Examples

Set Mirror Shield to have 3 copies placed in the world:

"item_pool": {
    "Mirror Shield": 3
}

or

"item_pool": {
    "Mirror Shield": {
        "type": "set",
        "count": 3
}

Add 3 Deku Shields to place in the world in addition to the ones already in the base pool:

"item_pool": {
    "Deku Shield": {
        "type": "add",
        "count": 3
    }
}

Dungeons

This dictionary lets you define which dungeons are vanilla and which are mq (master quest). You will have to set the number of MQ dungeons setting to match at least whatever master quest dungeons you define here. However, you do not have to define all of the dungeons and the rest will be defined by the randomizer generator instead.

The term is the name of the dungeon. The definitions is either the string "vanilla", the string "mq", or the string "random".

Examples

Set only Deku Tree to mq:

"dungeons": {
    "Deku Tree": "mq"
}

Set only Spirit Temple to vanilla, because you don't want to learn the second version of spirit logic:

"dungeons": {
    "Spirit Temple": "vanilla"
}

Set Dodongo's Cavern to random:

"dungeons": {
    "Dodongos Cavern": "random"
}

Trials

You will define which trials are active and which ones are inactive in this dictionary. You will have to set the number of trials to match at least the trials you define here. However, you do not have to define all of the trials and the rest will be defined by the randomizer generator instead.

The term is the name of the trial. The definition is either the string "active", the string "inactive", or the string "random".

Examples

Set forest, fire, and water trials as inactive:

"trials": {
    "Forest": "inactive",
    "Fire": "inactive",
    "Water": "inactive"
}

Set light trial to active, ensuring that 3 strength upgrades are required for fighting Ganon:

"trials": {
    "Light": "active"
}

Set water trial to random:

"trials": {
    "Water": "random"
}

• Entrances - Choose how different locations are linked together when using Entrance Randomizer.
• Locations - Choose which items are placed on which locations.
• Gossip Stones - Choose what text Gossip Stones display.