1 files changed, 200 insertions, 20 deletions

@@ -9,17 +9,50 @@ This is a project that modifies the game
 [Lingo 2](https://www.lingothegame.com/lingo2.html) so that it can be played as
 part of an Archipelago multiworld game.
 
-## How To Play
+## Installation
 
-Here are the components needed in order to play:
+1. Download the Lingo 2 Apworld from
+   [the releases page](https://code.fourisland.com/lingo2-archipelago/about/CHANGELOG.md).
+2. If you do not already have it, download and install the
+   [Archipelago software](https://github.com/ArchipelagoMW/Archipelago/releases/).
+3. Double click on `lingo2.apworld` to install it, or copy it manually to the
+   `custom_worlds` folder of your Archipelago installation.
 
-- **Apworld**: This is used by Archipelago to generate randomized Lingo 2
-  worlds.
-    - [Installation & FAQ](https://code.fourisland.com/lingo2-archipelago/about/apworld/README.md)
-    - [Downloads](https://code.fourisland.com/lingo2-archipelago/about/apworld/CHANGELOG.md)
-- **Client**: This is how Lingo 2 connects to an Archipelago multiworld.
-    - [Installation & FAQ](https://code.fourisland.com/lingo2-archipelago/about/client/README.md)
-    - [Downloads](https://code.fourisland.com/lingo2-archipelago/about/client/CHANGELOG.md)
+## Joining a Multiworld game (Windows)
+
+1. Open the Archipelago Launcher.
+2. Select "Lingo 2 Client".
+3. The first time you do this, Archipelago will prompt you for the location of
+   the Lingo 2 executable file ("Lingo2.exe"). You can find this by
+   right-clicking on Lingo 2 in Steam, going to "Manage", and clicking "Browse
+   local files".
+4. Lingo 2 will open, and you will see a form asking for your connection
+   details. Enter the Archipelago address, slot name, and password into the
+   fields.
+5. Press Connect.
+6. Enjoy!
+
+To continue an earlier game, you can perform the exact same steps as above.
+
+## Joining a Multiworld game (Non-Windows)
+
+Lingo 2 only officially supports Windows, but has been known to work on Linux
+using Proton. Archipelago can be played on a non-Windows system, but the process
+is a little more complex.
+
+1. Download
+   [archipelago.tscn](https://code.fourisland.com/lingo2-archipelago/plain/client/archipelago.tscn)
+   and put it in your custom maps folder. You only have to do this once.
+2. Open Lingo 2, and select Archipelago from the level selection list.
+3. Put the path to your `lingo2.apworld` into the field provided. You only have
+   to do this once, as the game will remember what you put in.
+4. Click Start and wait for the connection settings screen to load.
+5. Open the Archipelago Launcher.
+6. Select "Lingo 2 Client".
+7. You should see "Connected to Lingo 2!" You can then return to Lingo 2 and
+   fill out your connection details.
+8. Press Connect.
+9. Enjoy!
 
 ## Frequently Asked Questions
 
@@ -38,13 +71,31 @@ same time as collecting the letter.
 
 ### What areas are randomized?
 
-Almost all maps that you can access from the base game are randomized. The
-exceptions are:
+Almost all maps that you can access from the base game are randomized. The only
+exception is The Hinterlands, which will probably be repurposed into a hint
+area. Some advanced/hidden maps are also disabled by default (as discussed
+below).
+
+### Is my progress saved locally?
+
+Lingo 2 autosaves your progress every time you solve a puzzle, get a
+collectable, or interact with a keyholder. The randomizer generates a savefile
+name based on your Multiworld seed and slot number, so you should be able to
+seamlessly switch between multiworlds and even slots within a multiworld.
+
+The exception to this is different rooms created from the same multiworld seed.
+The client is unable to tell rooms in a seed apart (this is a limitation of the
+Archipelago API), so the client will use the same save file for the same slot in
+different rooms on the same seed. You can work around this by manually moving or
+removing the save folder from the users directory in Lingo 2's game files.
+
+If you play the base game again, you will see one or more save files with a long
+name that begins with "zzAP\_". These are the saves for your multiworlds. They
+can be safely deleted after you have completed the associated multiworld. It is
+not recommended to load these save files outside of the randomizer.
 
-- Icarus (this will be randomized at some point, although it will be optional)
-- Demo
-- The Hinterlands (this will probably be repurposed)
-- The beta tester gift maps
+A connection to Archipelago is required to resume playing a multiworld. This is
+because the set of items you have received is not stored locally.
 
 ### What about wall snipes?
 
@@ -95,10 +146,139 @@ before leaving solve mode, as the keyholder will still be considered to be
 "focused", even though it has moved. If you have already moved, though, there is
 another way to get your letters back: just use the Key Return in The Entry.
 
-## Project Details
+### Why is the tracker telling me to solve a panel that's currently red?
+
+Red usually indicates that a panel cannot be solved because of missing letters.
+However, that only applies to the puzzle's main answer. If a puzzle has
+alternate answers, you may be expected to use one of those instead of the main
+one. As long as you have all of the necessary letters, an alternate answer can
+be typed into a red panel even though it does not show you typing. When you
+finish typing the answer, the panel will solve as normal.
+
+### Why does the tracker say "The Entry (Colored Doors Area) - OPEN" is in logic?
+
+This is an infamous panel, both in the base game and in the randomizer. There
+are _two_ valid answers that open the door / clear the location. These are
+"ORANGE" and "WALL".
+
+### I can't solve the COLORS panel in The Sturdy!
+
+The Sturdy contains a rainbow painting that leads to the Gold Ending area in
+Daedalus. There are three ways to spawn this painting, which have different
+logical requirements:
+
+- Solve the COLORS panel that appears after collecting S2. This is the most
+  well-known way, and causes the most confusion because you may be expected to
+  enter the painting even if you are unable to solve the panel (e.g. if you are
+  missing letters or missing Boxes Symbol).
+- Solve the panels in the order that you walk across the colors on the way
+  toward S2: Magenta, Red, Orange, Yellow, Green, Blue, Purple, Cyan. This has
+  the same logic as accessing S2.
+- Type "MOVE" into the Green and Yellow panels, and none of the other ones. This
+  is a subset of the logic for accessing S2, so you may actually be expected to
+  use the rainbow painting before you can even collect S2.
+
+### How does Icarus work?
+
+While Icarus is easily accessible during normal play, it is not randomized by
+default. The main reason for this is that Icarus employs significantly more use
+of gravity changing mechanics than the rest of the game and as a result tends to
+cause motion sickness in a lot of players. It is also an infamously confusing
+area to navigate.
+
+Because of this, the player may enter and exit Icarus from the usual place in
+Daedalus, but it will not contain any locations, and no items will be added to
+the pool for it. The worldport will not be included in the randomization if
+worldport shuffle is on. Icarus can also still be entered from The Crystalline,
+but doing so (in order to then access Daedalus) will not be logically required.
+
+However, Icarus can be randomized via the "Enable Icarus" option. Doing so
+creates locations and items for the map, and includes the worldport in worldport
+shuffle. The aforementioned connection from The Crystalline also becomes
+logical, if The Crystalline is enabled.
+
+It is not trivial to telegraph exactly what is logical within Icarus. It is very
+easy to break logic because the gravity changers allow you to fall in almost any
+direction you want to. In general, falling is only in logic if it is "guided",
+i.e. falling through a hole or an open door to another platform, or using a
+gravity inverter. You may also sometimes be required to solve panels that are
+physically near you and easily visible, but not on your plane of gravity. The
+tracker can help you determine what is considered logical, if you want to stay
+within the randomizer's logic.
+
+### How do the gift maps work?
+
+The beta tester gift maps are hidden levels intended for specific people. By
+default, these are not accessible at all from within the randomizer. The "Enable
+Gift Maps" option allows you to enter the maps, and creates items and locations
+for them. If worldport shuffle is on, their worldports will be included in the
+randomization.
+
+The gift maps are accessed via a panel in The Entry's Starting Room, which only
+appears if at least one gift map is enabled. It is also treated like a cyan
+door, and will not appear until the condition specified in the Cyan Door
+Behavior option is satisfied. Solving this panel with the name of one of the
+beta testers will teleport you to their corresponding gift map. This README
+purposefully does not list the names you need to enter the maps via the panel.
+
+In the base game, nothing happens once you complete a gift map. Masteries have
+been added to the gift maps in the randomizer so that the player can be rewarded
+for completing them.
+
+Note that the gift maps were originally only intended to be played by specific
+people, and as a result may be frustrating or require knowledge of inside jokes.
+The Crystalline is particularly difficult as it requires completing a parkour
+course. It is highly recommended that you complete these maps vanilla or solo
+before bringing them to a multiworld. It is also perfectly acceptable to never
+enable them.
+
+## Running from source
+
+The randomizer is mostly written in Python and GDScript, which do not need to be
+compiled. However, there are three files that need to be generated before the
+apworld can be used.
+
+The first file is `data.binpb`, the datafile containing the randomizer logic.
+You can read about how to generate it on
+[its own README page](https://code.fourisland.com/lingo2-archipelago/about/data/README.md).
+Once you have it, put it in a subfolder of `apworld` called `generated`.
+
+The second generated file is `data_pb2.py`. This file allows Archipelago to read
+the datafile. We use `protoc`, the Protocol Buffer compiler, to generate it. As
+of 0.6.3, Archipelago has protobuf 3.20.3 packaged with it, which means we need
+to compile our proto file with a similar version.
+
+If you followed the steps to generate `data.binpb` and compiled the `datapacker`
+tool yourself, you will already have protobuf version 3.21.12 installed through
+vcpkg. You can then run a command similar to this in order to generate the
+python file.
+
+```shell
+.\out\build\x64-Debug\vcpkg_installed\x64-windows\tools\protobuf\protoc.exe -Iproto\ ^
+  --python_out=apworld\generated\ .\proto\data.proto
+```
+
+The exact path to `protoc.exe` is going to depend on where vcpkg installed its
+packages. The above location is where Visual Studio will probably put it.
+
+The third generated file is `proto.gd`. This is the GDScript version of the
+previous file. We use a Godot script to generate it, which means
+[the Godot Editor](https://godotengine.org/download/) is required. From the root
+of the repository:
+
+```shell
+cd vendor\godobuf
+godot --headless -s addons\protobuf\protobuf_cmdln.gd --input=..\..\proto\data.proto ^
+  --output=..\..\apworld\generated\proto.gd
+```
 
-There are multiple parts of this project:
+If you are not on Windows, replace the forward slashes with backslashes as
+appropriate (and the caret with a forward slash). You will also probably need to
+replace "godot" at the start of the second line with a path to a Godot Editor
+executable.
 
-- [Client](https://code.fourisland.com/lingo2-archipelago/about/client/README.md)
-- [Apworld](https://code.fourisland.com/lingo2-archipelago/about/apworld/README.md)
-- [Data](https://code.fourisland.com/lingo2-archipelago/about/data/README.md)
+After generating those three files, the apworld should be functional. You can
+copy it into an Archipelago source tree (rename the folder `apworld` to `lingo2`
+if you do so) if you want to edit/debug the code. Otherwise, you can zip up the
+folder and rename it to `lingo2.apworld` in order to package it for
+distribution.