The Logic file structure has been unchanged since the very first release of the randomizer in 2019 and we believe it is for the best to revamp it with some more functionality.

Decouple Items from Locations:

Previously: All the Locations were read and they all offered an item, these items were taken and then added to the item pool, this pool could then only be modified by replacing items that already existed in that pool.

Now we define the Item Pool separate to the Locations. Can specify the amount of this item that should be added to the pool, the Location Type it should be placed into and also given a Dungeon ID so that they are only placed into locations that match that ID.

Items that wish to be unshuffled (or forced to a specific location) can still be offered by a location in exactly the same manner as previously.

New Item/Location Types:

New Item/Location types have been added to provide layers to the randomization stages, this helps make sure seeds are beatable the vast majority of the time by placing important items before less important items.

Location Types:

Music: New, Shuffled completely independently from the rest of randomization which allows music to be a purely cosmetic choice.
Helper: Unchanged from before, does not write to game memory, helps make logic neater and more readable.
Unshuffled: Unchanged, writes the offered item to game memory, considered by logic.
DungeonEntrance: New, Shuffles fake items to represent the dungeon entrances. Only allows items of type DungeonEntrance to be shuffled here. If there are any unfilled locations after all items have been placed or any items left over after all locations have been filled then randomization fails.
DungeonConstraint: New, Shuffles fake items to allow dungeons to have special item placements not previously possible in logic. Mainly used for key placements in Droplets. Only allows items of type DungeonConstraint to be shuffled here.If there are any unfilled locations after all items have been placed or any items left over after all locations have been filled then randomization fails.
OverworldConstraint: New, Shuffles fake items to allow overworld to have special item placements not previously possible in logic. Not currently used but will be useful for future fusion settings. Only allows items of type OverworldConstraint to be shuffled here.If there are any unfilled locations after all items have been placed or any items left over after all locations have been filled then randomization fails.
DungeonPrize: New, Shuffles elements. Having this helps fix the “Non-Element Dungeons” setting to make the majority of seeds succeed in randomization. Any unfilled locations after all items have been placed will get added to the Dungeon Pool.
Major: New, Shuffles Major items to this location first before other locations. Useful for choosing certain locations you always want to be required. Any locations unfilled after all Majors are placed will be added to the Any Pool.
Dungeon: Shuffles DungeonMajor items to this location, only shuffles items from one of the listed dungeon IDs to this location. Any locations unfilled after all DungeonMajors are placed will be added to the Any Pool.
Any: Standard location type, any item can get shuffled here. Any locations unfilled after all items have been placed will be added to the Minor Pool.
Minor: New, only allows items of type Minor to be placed here. Not currently used but will allow us to force a location to not be required. Any unfilled locations get filled with Filler.
Inaccessible: New, Items are not randomized to this location, not shown in spoiler log, filler items are placed onto this location to remove its vanilla item.

Item Types:

Music: New, Shuffled completely independently from the rest of randomization which allows music to be a purely cosmetic choice.
DungeonEntrance: New, Specifies this item can only be placed on Location Type: DungeonEntrance.
DungeonConstraint: New, Specifies this item can only be placed on Location Type: DungeonConstraint.
OverworldConstraint: New, Specifies this item can only be placed on Location Type: OverworldConstraint.
DungeonPrize: New, Specifies this item can only be placed on Location Type: DungeonPrize. Any items unplaced after all locations have been filled will cause randomization to fail.
DungeonMajor: New, Shuffles this item to Dungeon locations, shuffles to any location with a matching Dungeon ID. Any items unplaced after all locations have been filled will cause randomization to fail.
Major: Shuffles this item to Major, Dungeon, or Any locations.
Minor: Shuffles this item to Any or Minor locations.
Filler: Specifies this item should be used to fill any unfilled locations after all other items have been placed. Filler items are randomly selected for each location and the amount parameter is used to change the odds that item is selected.

Location Dungeons:

Locations now can have any number of Dungeon IDs. This allows for things such as small keys being placed inside their own dungeon but big keys to be placed in their own region, since these two items will have different Dungeon IDs they shuffle to.

‘No Spoiler’ Tag

A special dungeon ID has been added called NoSpoiler, this prevents this location and its contents from being added to the spoiler log. Useful for unshuffled locations like rupee spots that would clog up the spoiler log while keeping that location defined. Unnecessary when the location type is Inaccessible.

Logical ‘Not’ Statement

~Items.SmithSword prevents this item from being placed at this location but only if that logic dependency is what is required to place this location in logic. This statement can NEVER be used for Helpers.

Eg: (|Items.A,(&Items.B,~Items.C)) means that this location is in logic if Item B is obtained but Item C cannot be located here in that case, however if Item A is obtained then Item C can be placed here.

Import Statement

You can now import functions into the logic file! These functions are written in C# in the LogicImports file in the Randomizer Core. Imports are meant to simplify implementation of certain features that would be extremely cumbersome or even impossible in the logic file. You can import a function by putting !import - function_name in the logic file. The following function names can currently be imported:

NON_ELEMENT_DUNGEONS_BARREN - Asserts that if a dungeon is one of the main 6 dungeons and does not have an element, then no major items can be placed in it.

NON_ELEMENT_DUNGEONS_NOT_REQUIRED - Asserts that if a dungeon is one of the main 6 dungeons and does not have an element, then no major items can be placed in it until Vaati is beatable.

VERIFY_LOCATION_IS_ACCESSIBLE - Asserts that a location is accessible before placing a major or dungeon major item on it. This should always be imported unless you want no logic, in which case not importing this function will give you no logic.

Shuffle Options:

Due to the improvements made to the Logic File structure, this update is mainly a refinement of existing settings to resolve bugs and to make use of this improved functionality. Some new settings were added however, and we hope to not have many major bugs with these additions.

Main Settings:

Key Settings: reworked `Regional Items` and `Inter-Dungeon Items`, adding them to each dungeon item as an option. Each Dungeon Item (Small Key, Big Key, Map/Compass) now has the following settings:

Removed (Keasy), [For Small Keys and Big Keys Only]
Start With [For Maps/Compasses Only]
Vanilla
Own Dungeon
Own Region
Any Dungeon
Any Region
Anywhere (Keysanity)

Figurine Hunt is temporarily unavailable until we resolve an issue with item replacement.
Dojo Swordmasters: Dojo swordmasters now have the following options for what items are randomized to them

Vanilla Scrolls: They always offer their vanilla scroll.
Randomized Scrolls: Scrolls are randomized between the dojos.
Any Item: They can have any item, scrolls are shuffled into the wider pool.

World Settings:

Dungeon Entrance Shuffle: Dungeon entrances can be shuffled between each other, these are coupled so you will always enter/exit to the same Dungeon and Outside area. The Element icons on the map show the vanilla location of the dungeon that element has been shuffled to, for example if there is a Wind Element on the map in Crenel then that means that Cave of Flames has the Wind Element, but you don’t know where the entrance to Cave of Flames has been shuffled to.

We plan to in the future have it place the element icons over the dungeon entrance you go to in order to get the element. For example, if Palace of Winds has the Fire Element, and you go to the Temple of Droplets entrance to get to Palace of Winds, then the Fire Element will show up over Lake Hylia on the map.

Seeded Shared Fusions: temporarily unavailable until we resolve an issue with logical addition.
Start with Wind Crests: Each wind crest can be selected to have it activated from the start. Some wind crests can give access to areas not normally accessible due to the fusion settings; activated wind crests are all considered in logic when you obtain the ocarina. Here are the following Wind Crests that can be toggled:

Mt Crenel
Veil Falls
Cloud Tops
Swamp
Link’s House
Minish Woods

Logic Settings:

‘Items can lock themselves’ is now permanently on. Despite it being ‘nice’ to have locations always reachable, it is far more interesting logically to have a much smarter and more advanced logic in place. Maintaining support for the older logic is far more difficult the more we change the current logic; it has now reached a point where it is not worth the effort it takes to keep it compatible with new settings.
Every seed will always be beatable. Any item can lock themselves once Vaati is beatable.
Weapon options: the setting has been split based on the item you want to consider a weapon or not.

Bombs:

‘No’: Bombs never considered
‘Yes’: Bombs considered for normal enemies except Bosses, MiniBosses, Simon Simulations and Golden Enemies.
‘Yes + Bosses’: Bombs considered for normal enemies, Bosses and Minibosses, Bombs are not considered damage for Octo or Gyorg.

Bows:

‘No’: Bows never considered
‘Yes’: Bows considered weapons for all fights except for Chu Bosses, Darknuts, Scissor Beetles, Madderpillars, Wizrobes, Simon Simulations, and Golden enemies.

Gust Jar:

‘No’: Gust Jar is never considered a weapon
‘Yes’ Gust Jar is considered a weapon when fighting enemies that can be sucked up by it, these are: Ghini (Ghosts), and Helmasaurs.

Lantern:

‘No’: Lantern is never considered a weapon
‘Yes’: Lantern is considered a weapon when fighting Wizrobes.

Logic Tricks have better names, tooltips are more descriptive, and the options have an explicit No/Yes selection.
New Logic Tricks:

‘Mole Mitts farm Infinite Rupees’, shops can require farming rupees outside links house if you have the mole mitts.
‘Use Bobombs to destroy walls’, bobombs can be used to blow up the bomb walls in Cave of Flames.

Other Settings:

This section is a bit of a mix of options that don’t obviously combine well with other settings or don’t have enough settings to be worth placing on their own page. Any feedback on where to move these settings is appreciated.

Progressive items is now an option:

Non-Progressive Items: The first version of the randomizer in 2019 had Non-Progressive items, eg: not having any sword and then the first sword you find is the Blue Sword. Items that are affected are: Swords, Bows, Boomerangs, Shields and Scrolls.
Progressive Items: What most people are used to, Items now have a special sprite to show they are progressive.

Fun Junk: More items added such as bakery goods.
‘Random Bottle Contents’ is temporarily unavailable until we resolve an issue with item replacement.

Gameplay Changes:

In Game Changes:

Newly created files have their text speed set to fast automatically.
Progressive items now have a new sprite with a Plus symbol to identify they are progressive. Non-Progressive forms of those items use their original sprite, so you always know exactly what you are getting.
Kinstones no longer spawn as RNG drops.
Fairies have been removed from the item pool temporarily until they can behave themselves.

Logic Changes:

All key logic has been revamped, if all locations that a key can be located are reachable then keys are allowed to lock themselves, this specifically affects these locations:

Deepwood_1F_East_MulldozerFight_Item
Deepwood_B1_West_BigChest

Fortress_BackRight_Statue_ItemDrop
Fortress_BackRight_Minish_ItemDrop
Fortress_BackRight_BigChest

Droplets_Entrance_B2_WestIceblock
Droplets_RightPath_B1_BluChu_BigChest

Palace_1stHalf_5F_FanLoop_Chest
Palace_1stHalf_5F_BigChest
Anything that requires rupees to collect has been revamped to check if enough rupees are available, with plenty to spare, to avoid having to farm for them.

Once Vaati is beatable in logic then items can be placed ANYWHERE, this includes locations made inaccessible due to the settings (ie: Removed Fusion Locations)

UI Improvements:

New Features:

Minified Settings Strings:

We now have a working implementation of settings strings! The current implementation is the “minified” implementation. If any of the settings in a logic file have changed, these strings will not be usable in that new version. However, this doesn’t prevent something like translations, since it only checks that the name of the define matches what was intended and not the name that appears on the UI. As such, settings strings generated on the English Default Logic file will also be usable on the French Default Logic file. More info on translations can be found in the future plans section.

To use a settings string, paste it into the settings string window and click “Load Settings”.

To get a settings string to share with other people, click “Generate String” and copy your string. Additionally, when you randomize a seed there is a button on the seed output page to copy the generated settings string. The seed generated on that page is the same one that would be generated if you click the “Generate Settings” button.

To reset your settings to the logic file defaults, click “Reset Defaults”.

These same steps apply for cosmetics strings as well, which can be found just below settings strings on the UI.

Cached Configuration:

The randomizer now caches your configuration when you close the program. This means that when you re-open the randomizer, some settings will be automatically selected for you! As of right now the following settings are cached:

ROM Path (Yes, this means you don’t need to load a rom every time you start the randomizer anymore!)
Use Special Shuffler (More details in Experiments section below)
Maximum Seed Generation Retry Count (Only saved when you hit randomize)
Default Logger Output Path
Logger Verbosity (currently disabled since verbose logs were easily becoming 50mb+ in size)
Whether you want to use custom logic

The file path to the custom logic file

Whether you want to use custom patches

The file path to the custom patches

Settings and Cosmetics Presets:

In addition to settings strings, we now also have settings presets! Presets allow you to quickly save and load certain settings and cosmetics with just a few button clicks, so you don’t have to manually go through and select every setting you want to play with. To save a setting, you simply click the Save Current as Preset button and put in the name you want to save it as in the dialog that pops up. You can then load it at any time. The following settings presets are shipping with this release:

Beginner settings, settings meant for people where this is their first time playing the game, most things are closed with plentiful item pool
Intermediate settings, settings meant for people who want decently randomized seeds without getting into more advanced settings. No more plentiful pool, Palace and Fortress areas added to logic, and a few other changes from beginner.
Advanced settings, settings meant for the majority of the players. These settings are very similar to current weekly settings with the intention that weekly settings will likely be changing sometime soon.
Max Rando Settings, settings meant to maximize the amount of checks and items in the pool. Fully vanilla fusions, dungeon entrances randomized, and every single logic trick and location available with full keysanity.
Current Weekly Settings, the settings currently used for weekly races. We will update this setting string once we have voted on new weekly settings to make generating seeds very easy.
0.7 Special Showcase Settings, the settings used for the 0.7 special showcase if you want to play them again later!

Returning Features

Export Default Logic:

Export default logic makes its triumphant return! You can export the logic by clicking “Logic -> Export Default Logic”.

Experimental Features

Sphere Based Shuffler (Hendrus Shuffler™)

An experimental shuffler that places items starting at sphere 0 and going until it can beat Vaati. If it becomes impossible to progress, it steps backwards and retries earlier spheres to make it possible. This shuffler can take a very long time to generate seeds and also generates very linear and plando-esque seeds. Use at your own risk (and if you want to inflict pain on others!)

Miscellaneous:

Spoiler Log Changes:

A new section has been added below the sphere layout called: “Playthrough”, this only prints the Major Items in each sphere so can be much more useful for reading the intended progression through a seed.
Item Subtypes now have names instead of ID numbers, Dungeon Keys say which dungeon they belong to and Shuffled Dungeon Entrances say which dungeon they have.

Bug Fixes to the Previous Build:

Tooltips display faster and also work when hovering over dropdowns.
Tooltips for settings have been corrected.
Bugs involving key settings have been resolved.
All Keys have the correct IDs no matter where they get shuffled to.
‘Non-Element Dungeons’ setting can be set to anything and won’t cause seeds to fail generation.
Elements display correctly on the map, refer to the section on Dungeon Entrance Shuffle to see how they are meant to display.
Fortress and Crypt can have dungeon prizes again.
Dungeon Requirement can be set to any value now.
DHC Never Open has been fixed
Melari Mines dig spots now correctly require Mole Mitts.
Golden enemies now drop the item they are supposed to.
Fusions such as Beanstalks and Tornados now spawn when they are supposed to.
Randomize Music is now correctly in the cosmetic category.
Simon is correctly considered by logic now, including available rupees.

Plans moving Forward:

We are happy with the state of the current test build to move this onto a stable public release after a 2 week candidacy period, so that the community can beta test in the meantime and develop the other resources such as trackers and documentation.
There will be a release about 1 week from now fixing some UI issues and restoring functionality to the CLI, and after that we will go to a bi-weekly testing build until we hit the release candidate stage.
Catobat has been developing a lot of features that aren’t currently in this branch simply due to github shenanigans, we will be merging these changes in and making the branch public later tonight.

Updates Planned for Next Build:

Fix UI scaling so it works on lower DPI settings.
Fix the CLI so we can make yellari generate seeds.
Add Logic Agnostic Settings Strings (Experimental).
Fix digging spots sometimes having major items when digging spot shuffle is turned off.
Add an about page and a changelog page to the randomizer UI.
Fix for major items sometimes not showing up in the spoiler log if they have both a major and minor version (such as bomb bags and bottles)
Fix Custom Logic and Patches selector

Tentative Changes:

These changes may be in the next build, or if we cannot get them done on time they will be in the build after that.

Shuffle Minish Cracks and Minish Holes with 1 exit.
Setting certain items to be in your starting inventory.
Fix figurine hunt
Fix random bottle contents
Fix shared fusions
Fix verbose logger exploding the size of the logs.

Known Issues:

When the Graveyard Key is knocked out of your hands, it looks like the progressive sword.
Electric Chu’s have buggy animations.
In Non-Progressive items: Red/Blue/Four Swords can’t activate the 3rd and 4th Town Dojo items.
Regional Keys combined with Dungeon Entrance Shuffle is unintuitive, eg: If Fortress is shuffled to Crenel, Small Keys for Fortress can be found in Wind Ruins but not in Crenel.
Dungeon Entrance Shuffle causes Link to have weird facing angles when going through transitions.
Credits statistics are inaccurate and sometimes completely bug out, if they look wrong to you please let us know what settings you used.
UI Window doesn’t scale properly with windows scaling above 100%. You can fix this by changing your windows scaling settings to 100%. This is a top priority item for the next release.
CLI currently doesn’t work. This is a top priority item for the next release.
Major items sometimes do not show up properly in the spoiler log if they have a minor version of the same item.
About and Changelog pages are not implemented yet.
Verbose logger causes massive explosions in log size and has been disabled while we work on a fix.
Custom Logic and Patches currently can't be selected
Dungeon Items give a subvalue in the spoiler log instead of their name when they are set to shuffle Anywhere.