Started writing READMEs

4 files changed, 174 insertions, 0 deletions

@@ -0,0 +1,16 @@
+# 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.
+
+There are multiple parts of this project:
+
+- [Client](https://code.fourisland.com/lingo-archipelago2/about/client/README.md)
+- [Apworld](https://code.fourisland.com/lingo-archipelago2/about/apworld/README.md)
+- [Data](https://code.fourisland.com/lingo-archipelago2/about/data/README.md)
@@ -0,0 +1,48 @@
+# Lingo 2 Apworld
+
+The Lingo 2 Apworld allows you to generate Archipelago Multiworlds containing
+Lingo 2.
+
+## Installation
+
+1. Download the Lingo 2 Apworld from
+   [the releases page](https://code.fourisland.com/lingo-archipelago2/about/apworld/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.
+
+## Running from source
+
+The apworld is mostly written in Python, which does not need to be compiled.
+However, there are two 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/lingo-archipelago2/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.
+
+After generating those two 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.
@@ -0,0 +1,97 @@
+# Lingo 2 Archipelago Client
+
+The Lingo 2 Archipelago Client is a mod for Lingo 2 that allows you to connect
+to an Archipelago Multiworld and randomize your game.
+
+## Installation
+
+1. Download the Lingo 2 Archipelago Randomizer from
+   [the releases page](https://code.fourisland.com/lingo-archipelago2/about/client/CHANGELOG.md).
+2. Open up Lingo 2, go to settings, and click View Game Data. This should open
+   up a folder in Windows Explorer.
+3. Unzip the randomizer into the "maps" folder. Ensure that archipelago.tscn and
+   the Archipelago folder are both within the maps folder.
+
+**NOTE**: It is important that the major version number of your client matches
+the major version number of the apworld you generated with.
+
+## Joining a Multiworld game
+
+1. Launch Lingo 2.
+2. Click on Level Selection, and choose Archipelago from the list.
+3. The selected player is generally ignored by the mod, and you don't even need
+   to ensure you use the same player between connections. However, if your
+   player name has a gift map associated with it, Lingo 2 will prioritize the
+   gift map over loading the mod, so in that case you should choose another
+   player.
+4. Press Play.
+5. Enter the Archipelago address, slot name, and password into the fields.
+6. Press Connect.
+7. Enjoy!
+
+To continue an earlier game, you can perform the exact same steps as above. You
+will probably have to re-select Archipelago from the Level Selection screen, as
+the game does not remember which level you were playing.
+
+**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.
+
+## Running from source
+
+The mod is mostly written in GDScript, which is parsed and executed by Lingo 2
+itself, and thus does not need to be compiled. However, there are two files that
+need to be generated before the client can be run.
+
+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/lingo-archipelago2/about/data/README.md).
+Once you have it, put it in a subfolder of `client` called `generated`.
+
+The second generated file is `proto.gd`. This file allows Lingo 2 to read the
+datafile. 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=..\..\client\Archipelago\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 two files, the contents of the `client` folder (minus
+this README) can be pasted into the Lingo 2 maps directory as described above.
+
+## Frequently Asked Questions
+
+### 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 file from the level1 save file directory.
+
+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.
@@ -0,0 +1,13 @@
+# Lingo 2 Randomizer Data
+
+This folder contains the logic for the Lingo 2 randomizer in a human-readable
+format. This data is compiled into a single file and used in the various parts
+of the randomizer project (client, apworld, etc).
+
+The data is structured using [Protocol Buffers](https://protobuf.dev/). The
+schema for the human-readable format is
+[located in the repository](https://code.fourisland.com/lingo2-archipelago/tree/proto/human.proto).
+
+## Compiling
+
+Hi.