path: root/README.md

# 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

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.

**Note**: Running the randomizer modifies the game's memory. If you want to play
the base game after playing the randomizer, you need to restart Lingo 2 first.

## 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.

## 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.