Documentation of fill algorithms

RELEASENOTES.md

@@ -2,6 +2,76 @@
 
 ## New Features
 
+## Restricted Item Placement Algorithm
+
+
+The "Item Sorting" option or ```--algorithm``` has been updated with new placement algorithms. Older algorithms have been removed.
+ 
+ When referenced below, Major Items include all Y items, all A items, all equipment (swords, shields, & armor) and Heart Containers. Dungeon items are considered major if shuffled outside of dungeons. Bomb and arrows upgrades are Major if shopsanity is turned on. The arrow quiver and universal small keys are Major if retro is turned on. Triforce Pieces are Major if that is the goal, and the Bomb Bag is Major if that is enabled.
+ 
+ Here are the current fill options:
+
+### Balanced 
+
+This one stays the same as before as is recommended for the most random distribution of items.
+
+### Equitable
+
+This one is currently under development and may not fill correctly. It is a new method that should allow item and key logic ot interact. (Vanilla key placement in PoD is theoretically possible, but isn't yet.
+
+### Vanilla Fill 
+
+This fill attempts to place all items in their vanilla locations when possible. Obviously shuffling entrances or the dungeon interiors will often prevent items from being placed in their vanilla location. If the vanilla fill is not possible, then other locations are tried in sequence preferring "major" locations (see below), then heart piece locations, then the rest except for GT locations which are preferred last.
+
+### Major Location Restriction
+
+This fill attempts to place major items in major locations. Major locations are where the major items are found in the vanilla game. This includes the spot next to Uncle in the Sewers, and the Boomerang chest in Hyrule Castle. Note the PoD small key that is normally found in the dark maze in vanilla is move to Harmless Hellway due to the placement algorithm limitation.
+
+This pool is expanded to where dungeon items are locations if those dungeon items are shuffled. The Capacity Fairy locations are included if Shopsanity is on. If retro is enabled in addition to shopsanity, then the Old Man Sword Cave and one location in each retro cave is included. Key drop locations can be included if small or big key shuffle is on. This gives a very good balance between overworld and underworld location though the dungeons one will be on bosses and in big chests. Seed do become more linear but usually easier to figure out.
+
+### Dungeon Restriction
+
+The fill attempt to place all major items in dungeons. It will overflow to the overworld if there are more items than locations (e.g. Triforce hunt.) This fill does attempt to run the GT trash fill when possible. Seeds are typically very linear but tend to be more difficult.
+
+### District Restriction
+ 
+The world is divided up into different regions or districts. Each dungeon is it's own district. The overworld consists of the following districts:
+
+Light world:
+
+* Kakariko (The main screen, blacksmith screen, and library/maze race screens)
+* Northwest Hyrule (The lost woods and fortune teller all the way to the rive west of the potion shop)
+* Central Hyrule (Hyrule castle, Link's House, the marsh, and the haunted grove)
+* Desert (From the thief to the main desert screen)
+* Lake Hylia (Around the lake)
+* Eastern Hyrule (The eastern wild, the potion shop, and Zora's Domain)
+* Death Mountain
+
+Dark world:
+
+* East Dark World (The pyramid, Palace of darkness, and Catfish)
+* South Dark World (The dark lake, swamp area, to the dig game)
+* Northwest Dark World (Village of Outcasts, to the Dark Sanctuary and screens in between)
+* The Mire
+* Dark Death Mountain
+
+These districts are chosen at random and then filled with major items. If a location is part of a chosen district but there are no more major items to place. A single green rupee is used to indicate that as a placeholder. All other single green rupee are changed to be a blue rupee in order to not give a false positive.
+
+In entrance shuffle, what is shuffled to the entrances is considered instead of where the interior was originally. For example, if Blind's Hut is shuffled to the Dam, then the 5 chests in Blind's Hut are part of Central Hyrule instead of Kakariko.
+
+Bombos Table, Lake Hylia Island, Bumper Cave Ledge, the Floating Island, Cave 45, the Graveyard Cave, Checkerboard Cave and Mimic Cave are considered part of the dark world region that you mirror from to get there (except in inverted where these are only accessible in the Light World). Note that Spectacle Rock is always part of light Death Mountain.
+
+In multiworld, the districts chosen apply to all players.  
+
+### CLI values:
+
+```balanced, equitable, vanilla_fill, major_only, dungeon_only, district```
+
+## New Hints
+
+Based on the district algorithm above (whether it is enabled or not) New hints can appear stating that a district or dungeon is considered a "foolish" choice. The means there are no advancement items in that district (or that the district was not chosen if the district restriction is in place).
+
+
 ### Overworld Map shows dungeon location
 
 Option to move indicators on overworld map to reference dungeon location. The non-default options include indicators for Hyrule Castle, Agahnim's Tower, and Ganon's Tower.