1 files changed, 210 insertions, 0 deletions

@@ -0,0 +1,210 @@
+# lingo2-archipelago
+
+[Archipelago](https://archipelago.gg/) is an open-source project that supports
+randomizing a number of different games and combining them into one cooperative
+experience. Items from each game are hidden in other games. For more information
+about Archipelago, you can look at their website.
+
+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.
+
+## Installation
+
+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.
+
+## 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
+
+### Why aren't the starting room letters shuffled?
+
+The letter requirements for solving puzzles are very restrictive, especially in
+the early game. It is possible for the generator to find some subset of letters
+and doors to place in the starting room such that you are not trapped, but this
+places a lot of strain on generation and leads to significantly more generation
+failures.
+
+As a result, the starting room letters (H1, I1, N1, and T1) are always present
+in the starting room, even when remote letter shuffle is enabled. These letters
+will _also_ count as clearing a check, so you will send out another item at the
+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:
+
+- 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
+
+### 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.
+
+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?
+
+"Wall sniping" refers to the fact that you are able to solve puzzles on the
+other side of opaque walls. The player is never expected to or required to do
+this in normal gameplay. This randomizer does not change how wall snipes work,
+but it will likewise never require the use of them.
+
+### How do cyan doors work?
+
+In the base game, there are a number of cyan-colored doors that ordinarily open
+once you collect H2 in The Repetitive. There are also a handful of panels that
+only appear upon getting H2 as well, which the apworld treats the same as the
+cyan doors.
+
+There is an option that lets you choose how these doors and panels behave. By
+default, they act the same as in the base game: they only open or appear after
+collecting H2. Note that this means the actual H2 collectable in The Repetitive.
+Receiving H2 via remote letter shuffle does not count for this requirement.
+However, you can also make cyan doors activate upon collecting or receiving your
+first double letter, regardless of what it is or if it's remote. Finally, you
+can lock cyan doors behind an item called "Cyan Doors".
+
+It is important to note, however, that the Cyan Door Behavior option only
+applies to cyan doors that are not already affected by another type of
+shuffling. When door shuffle is on, the following cyan doors are activated by
+individual items and are not impacted by your choice of Cyan Door Behavior:
+
+- The entrance to The Tower from The Great (The Great - Tower Entrance)
+- The entrance to The Butterfly from The Bearer (The Bearer - Butterfly
+  Entrance)
+- The entrance to The Repetitive from The Entry (The Entry - Repetitive
+  Entrance)
+- The eye painting near the yellow color hallway in Daedalus (Daedalus - Eye
+  Painting)
+- The Red I room in The Repetitive (The Repetitive - Anti Collectable Room)
+
+Additionally, when control center color shuffle is enabled, the orange door in
+The Unkempt (which ordinarily doubles as a cyan door) opens upon receiving the
+Control Center Orange Doors item, instead of following the Cyan Door Behavior
+option.
+
+### Help! I lost C/G in The Congruent!
+
+If you place C or G into the relevant keyholders in The Congruent, the keyholder
+disappears. You can retrieve your letter immediately by pressing C or G again
+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.
+
+### 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.
+
+## 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
+```
+
+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.
+
+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.