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

This dictionary defines how different entrances are linked together when using entrance randomizer. Entrances must be shuffled among their respective groups so you cannot use plandomizer to force a mixed entrance pool seed. You may wish to generate a entrance randomizer seed and use its spoiler log to ensure you use the correct names for the locations.

The term is the loading zone you pass through. The definition is:

• For Dungeons and Interiors: a string with the name of the location you end up at
• For Overworld: a dictionary with a term of region set to a string of the overworld region it leads to and a term of from set to a string of the loading zone in that region that you will appear out of.

Examples

Set Deku Tree entrance to Gerudo Training Grounds:

"entrances": {
    "Outside Deku Tree -> Deku Tree Lobby": "Gerudo Training Grounds Lobby"
}

Set Hyrule Castle exit from Market to Lon Lon Ranch main entrance:

"entrances": {
    "Castle Town -> Castle Grounds": {
        "region": "Lon Lon Ranch", 
        "from": "Hyrule Field"
    }
}

Locations

This dictionary handles what is probably the main feature of plandomizer. You can assign items to any location in the game world here. Which locations are available are heavily influenced by what settings you choose, so ensure you have the proper settings set.

The term is the name of the location. The definition is either:

• A string of an item to place there
• A list containing multiple items to randomly choose from to place there
• A dictionary containing the term item containing one of the above two bullet points.
  • If making a multiworld plandomizer: the term player with the world number value of the player the item belongs to.
  • If the location is a shop: the term price with the rupee number value the item should cost. You cannot set scrub prices using plandomizer
  • If the item can be an ice trap: the term model set to a string of the item model it should appear as in the overworld.

Shop Location Numbers

Due to the odd way the shop items are stored in the game files, using shopsanity item placement is not very intuitive.

When using 1 item shopsanity, the number you use is 7 and is the bottom left item on the left side.
When using 2 items shopsanity, you also have number 5 which is the bottom right item on the left side.
When using 3 items shopsanity, you add on the number 8 which is the top left item on the left side.
When using 4 items shopsanity, you can now use all 4 numbers 5-8 for all of the left side items.

Special Item Groups

There are shortcut terms you can use for certain items when using plandomizer. They start with the # character. The ones that should work fine are:

#Bottle - Places a bottle and randomly chooses a contents for it
#Junk - Places a junk item (used by exclude locations)
#AdultTrade - Places the adult trade item without specifying which one

If you are feeling a little bit more daring, you can try:

#Song - Places a song item
#NonWarpSong - Places non warp song item
#WarpSong - Places a warp song item
#JunkSong - Places Serenade or Prelude in non-entrance randomizer.
#Spell - Places one of the three spells
#Shield - Deku or Hylian. Doesn't include Mirror.
#HealthUpgrade - Heart Container or Piece of Heart

All of these should work, but only the first list have been extensively tested.

Examples

Ready to fight Ganon after Mido's:

"locations": {
    "Mido Chest Top Left": "Bow",
    "Mido Chest Top Right": "Magic Meter",
    "Mido Chest Bottom Left": "Light Arrows",
    "Mido Chest Bottom Right": "Ice Trap"
}

Bottles in Mido's:

"locations": {
    "Mido Chest Top Left": "#Bottle",
    "Mido Chest Top Right": "#Bottle",
    "Mido Chest Bottom Left": "#Bottle",
    "Mido Chest Bottom Right": "#Bottle"
}

One step to fighting Ganon in the Kokiri Sword chest:

"locations": {
    "Kokiri Sword Chest": ["Bow", "Magic Meter", "Light Arrows"]
}

Setting shopsanity 1 item in Kokiri Shop to Ice Trap posing as Light Arrows:

"locations": {
    "Kokiri Shop Item 7": {
        "item": "Ice Trap", 
        "price": 60,
        "model": "Light Arrows"
    }
}

Place player 2's Light Arrows in player 1's Kokiri Sword chest:

"locations": {
    "World 1": {
        "Kokiri Sword Chest": {
            "item": "Light Arrows",
            "player": 2
        }
    }
}

Gossip Stones

This dictionary is just evil. It lets you replace the Gossip Stone text with any text you wish. Unlike normal randomizer, this text can lie and mislead the player. It is recommended that you use it more for inside jokes, or different types of hints than you'd normally get using the randomizer to keep the plandomizer fun for the player. Gossip stones set here will not taken into consideration for hints by logic.

The term is the name of the Gossip Stone. The definition is a dictionary with the term text.

• Any text you surround with # can also be colored. If you wish to do this add another term to the inner dictionary with the term colors and set it to a list containing strings of the colors you wish to use. You can have multiple groups of text surrounded by # and each one can be a different color.

Valid Colors

White
Red
Green
Blue
Light Blue
Pink
Yellow
Black

Examples

Just white text:

"gossip_stones": {
    "Death Mountain Crater (Bombable Wall)": {
        "text": "It's hot in here!"
    }
}

Colored text:

"gossip_stones": {
    "Death Mountain Crater (Bombable Wall)": {
        "text": "They say #Luigi# was put in this game instead of Super #Mario# 64",
        "colors": ["Green", "Red"]
    }
}