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 use 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.

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 - The settings to use for generation. Any settings here will override anything set in the generator GUI.
• Starting Items - Set which items the player starts with. This will completely override the starting items in the generator GUI.
• Item Pool - Add, Remove, or Set different amounts of items for the randomizer to place.
• Dungeons - Define whether a dungeon is vanilla or master quest.
• Trials - Define whether trials are active or inactive.
• 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.