1 files changed, 284 insertions, 0 deletions

@@ -0,0 +1,284 @@
+# 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 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.
+
+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.
+
+### 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
+```
+
+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.