Unify location generation and selection

CHANGELOG.md

@@ -2,9 +2,15 @@
 - added a TR2 secret pack (Eycore) (#559)
 - added a TR2 secret pack (Towandaa) (#558)
 - added more return paths to TR2 and TR3 (#563)
+- added an option to control whether or not key items can be allocated to enemies (#474)
+- added an option to control the range in which key items can appear (#474)
+- added an option to control whether or not key items can be placed in locations that rely on return paths (#474)
+- added an option to control key item continuity e.g. The Seraph being placed as an item in Barkhang Monastery if The Deck hasn't been visited (#474)
+- added item randomization to Home Sweet Home, provided the level starts with weapons and ammo already (#474)
 - fixed spelling mistakes in TR1 French gamestring localization (#560)
+- fixed a key item softlock in Diving Area (#564)
 - improved changelog, readme and contributing documentation
-- improved item location generation in TR1-3, and added item randomization to Home Sweet Home (#474)
+- improved regular item, key item, and secret item location generation and selection in TR1-3 (#474)
 - replaced purist mode with explicit options for adding return paths, fixing OG bugs, and fixing shortcuts (#563)
 
 ## [V1.7.3](https://github.com/LostArtefacts/TR-Rando/compare/V1.7.2...V1.7.3) - 2023-09-30

LocationExport/Program.cs

@@ -5,7 +5,6 @@
 using TRLevelControl.Helpers;
 using TRLevelControl.Model;
 using TRRandomizerCore.Helpers;
-using TRRandomizerCore.Randomizers;
 using TRRandomizerCore.Utilities;
 
 namespace LocationExport;

Resources/Documentation/RETURNPATHS.md

@@ -19,7 +19,7 @@ Following are details on the return paths that are available. See `Global Settin
 | City of Khamoon | Some slopes are adjusted to make returning to the start possible, and a trapdoor in room 42 will always remain raised to allow climbing out. |
 | Obelisk of Khamoon | _Not required_ |
 | Sanctuary of the Scion | _Not required_ |
-| Natla's Mines | _Not required_ |
+| Natla's Mines | Trapdoors added in the TNT area to return back across the lava or back to the start. |
 | Atlantis | Link rooms added between rooms 30 and 50. |
 | The Great Pyramid | _Not implemented due to trap behaviour._ |
 
@@ -29,17 +29,17 @@ Following are details on the return paths that are available. See `Global Settin
 | Great Wall | Ladder added to room 3 to allow returning to the beginning. Other points of no return remain. |
 | Venice | _Not required_ |
 | Bartoli's Hideout | Links added between rooms 22, 101, and 121. |
-| Opera House | _Not required_ |
+| Opera House | Link room added between rooms 6 and 50; and a ladder added from room 5 to 61. |
 | Offshore Rig | Door 19 will remain open after passing through it. |
 | Diving Area | Link rooms added between rooms 48 and 56; door 22 will remain open after passing through it; and a ladder is added to room 3. |
 | 40 Fathoms | Ladders added to rooms 21 and 36; trapdoor 30 will always remain open. |
-| Wreck of the Maria Doria | Ladders added to rooms 43 and 27-30. |
+| Wreck of the Maria Doria | Slopes adjusted in room 43, and ladders added to rooms 43 and 27-30. |
 | Living Quarters | Portal added between rooms 18 and 33. |
-| The Deck | _Not required_ |
-| Tibetan Foothills | Ramp added to room 53 to allow returning with the red skidoo. |
+| The Deck | Ladder added between rooms 30 and 86. |
+| Tibetan Foothills | Ramp added to room 53 to allow returning with the red skidoo; ladders added in rooms 78/79 to return to the start; link rooms added between rooms 18 and 81. |
 | Barkhang Monastery | _Not required_ |
 | Catacombs of the Talion | Ladders added to rooms 19 and 117. |
-| Ice Palace | Ladder added to room 34. _Point of no return above the gong remains._ |
+| Ice Palace | Ladder added to room 34. Link rooms added between rooms 61 and 103. |
 | Temple of Xian | Link rooms added between rooms 3 and 190. |
 | Floating Islands | _Not required_ |
 | Dragon's Lair | Slopes adjusted in room 2 to allow exiting the main arena. |
@@ -57,14 +57,14 @@ Following are details on the return paths that are available. See `Global Settin
 | Madubu Gorge | _Not implemented_ |
 | Temple of Puna | _Not implemented_ |
 | Thames Wharf | _Not implemented_ |
-| Aldwych | _Not implemented_ |
-| Lud's Gate | _Not implemented_ |
+| Aldwych | _Not required_ |
+| Lud's Gate | Ladders added between rooms 69 and 72. |
 | City | _Not required_ |
 | Nevada Desert | Link room added between rooms 18 and 26. |
-| High Security Compound | _Not required_ |
-| Area 51 | Slopes adjusted in room 0 to allow returning to room 4. |
+| High Security Compound | Link room added between rooms 38 and 129. |
+| Area 51 | Slopes adjusted in room 0 to allow returning to room 4; step added in room 64 to allow climbing out to room 63. |
 | Antarctica | _Not required_ |
 | RX-Tech Mines | Platform added to room 65 to allow reaching the ladder above. |
 | Lost City of Tinnos | Trapdoor added to room 44 to allow returning across the bridge. Each element room can be re-visited. |
 | Meteorite Cavern | Ladders added to rooms 17 and 18 to allow returning up the slope. |
-| All Hallows | Link room added between rooms 2 and 49. |
+| All Hallows | Link room added between rooms 2 and 49; plus, the zipline will reset after having used it. |

Resources/Documentation/SECRETS.md

@@ -1,12 +1,16 @@
 # Secrets
 
 Jump to:
+* [Placement](#placement)
 * [TR1](#tr1)
 * [TR2](#tr2)
 * [TR3](#tr3)
 * [Generating Locations](#generating-locations)
 
-# TR1
+## Placement
+Refer to [zones](ZONES.MD) for details on how secret locations are selected.
+
+## TR1
 Original secret triggers are removed during randomization and artefacts are instead added to the level for Lara to collect. Once she collects all of the secrets in a level, a door will open to a new room where the rewards she would otherwise have collected can be found. When picking up a secret, a camera hint will show you the location of this room.
 
 The imported artefacts become either a key type, puzzle type or quest type, whichever is available in the level to re-purpose.
@@ -34,9 +38,6 @@ The artefact types to collect will change per level. This is in place to ensure
 | Atlantis | Gold Idol |
 | Pyramid | Gold Idol |
 
-### Zoning
-Secrets are positioned by proximity so that they are fairly equally spread out across the level.
-
 ### Secret Count
 If [Tomb1Main](https://github.com/rr-/Tomb1Main) is being used, the number of secrets to collect per level can be changed. When you start a level, check Lara's compass to find out how many secrets you need to collect.
 
@@ -48,13 +49,12 @@ The options are:
 | Shuffled | Use the secret count from another level - the total number of secrets in the game will remain the same. |
 | Custom | Allocate a number of secrets of your choice (the maximum is currently 5 due to the current reward room implementations). |
 
-
 ----
 # TR2
-Zoning details for TR2 can be found at https://github.com/DanzaG/TR2-Rando/wiki/Zones#secrets
+The standard Stone, Jade and Gold dragons will be placed in each level.
 
 ----
-# TR3
+## TR3
 Secret randomization logic in TR3 works in exactly the same way as TR1.
 
 ### Artefacts
@@ -71,7 +71,7 @@ Several artefacts are imported per level. This will depend on the secret count a
 Currently, the number of secrets per level is hard-coded to the level's original sequence.
 
 ----
-# Generating Locations
+## Generating Locations
 Use trview to generate secret locations by making use of the available [randomizer settings](https://github.com/chreden/trview#randomizer-integration) feature. The file below should be copied locally to `%LOCALAPPDATA%/trview`.
 
 https://github.com/LostArtefacts/TR-Rando/blob/master/TRRandomizerCore/Resources/Shared/randomizer.json
@@ -121,8 +121,5 @@ Note that in normal mode, secrets whose states do not match the level are simply
 
 Other environment changes should also be kept in mind when placing secrets; for example, rooms may be flooded/drained or some geometry may change. Refer to the specific level environment files in each case. Conditional changes can be made to either undo other environment modifications, or to add your own changes to fit your secrets. Conditional changes are performed following all other standard environment changes, aside from level mirroring, which is always performed last.
 
-### TR2 Zoning
-As pre-defined secrets may not necessarily fall into the default [zones](https://github.com/LostArtefacts/TR-Rando/wiki/Zones#secrets), you should position your waypoints manually in stone-jade-gold order instead. For TR1 and TR3, this is not important due to the different zoning technique and the arbitrary artefact types.
-
 ### Underwater Corner Secrets
 When placing secrets in corners underwater, there is a minimum distance from each wall the secret will need to be positioned - this is 130 units. Any closer to the wall and Lara won't pick the secret up.

Resources/Documentation/ZONES.md

@@ -0,0 +1,26 @@
+# Zones
+Zones are used to mark areas within a level in which items can appear. Each game behaves in the same way, and the zoning is applied in three separate cases.
+
+## Regular items
+Guns, ammo, medipacks etc are placed at completely random points in the level, but will always be within reach. Items are placed centre-tile and if placed on a slope, it will always be a slope Lara can stand on. Locations are filtered based on several factors, such as death tiles, tiles that contain large static meshes or other objects that could interfere with Lara picking up the item.
+
+## Key items
+Keys, puzzle items and quest items are placed in well-defined zones, so that the items will always appear before their respective locks/slots. The randomizer provides a `range` option to generally allow controlling the area in which a key item can appear. This is not a uniform setting for every level, because some levels are less linear than others. In addition, the randomizer allows key items to be placed based on whether or not there are [return paths](RETURNPATHS.md) available. This can produce lots of variety as a result - consider the following scenarios as an example, using *The Talion* from Ice Palace in TR2.
+
+| Range | Return Paths | Zone |
+|-|-|-|
+| Small | Disabled | The ice structure around the gong at the end of the level. |
+| Small | Enabled | The ice structure around the gong at the end of the level, plus the return path from here leading to the yeti pit (and no further). |
+| Medium | Disabled | The entire area at the end of the level after dropping to the gong. |
+| Medium | Enabled | Anywhere from room 29 onwards (where the gong hammer is normally located). |
+| Large | Disabled | _Same as Medium/Disabled_ |
+| Large | Enabled | Anywhere from level start to level end. |
+
+## Secrets
+Zone lines for secrets are not as clear-cut as they are for key items. Rather, secrets are placed based on how close they are to each other. So the first secret is placed by the randomizer, then when trying to place the next, if it's deemed too close to the first, another location will be picked. This process continues until all locations are populated, and the required distance is reduced if the randomizer is unable to find suitable locations.
+
+For TR2, once all locations are selected, they are allocated as Stone, Jade and Gold based on the dev-intended completion route of a level.
+For TR1 and TR3, models are imported artefacts so their order is irrelevant.
+
+## Zone management
+The above zoning is achieved using trview JSON files that define level routes, and along each route key waypoints are marked, for example to delimit key item zones. Zones can be managed and visualised using the `key_items` plugin located at https://github.com/LostArtefacts/TR-Rando/tree/master/Resources/trview/plugins. Refer to the [trview documentation](https://github.com/chreden/trview/blob/master/doc/lua/plugins.md) for guidance on setting this up.

Resources/trview/plugins/key_items/manifest.json

@@ -0,0 +1,5 @@
+{
+    "name": "Key Item Zones",
+    "author": "TRRando",
+    "description": "Show key item zones"
+}