From a31d7a6d3a473cb044d717b666fd73dc43f2df51 Mon Sep 17 00:00:00 2001 From: Star Rauchenberger Date: Mon, 8 Sep 2025 17:37:09 -0400 Subject: Started writing READMEs --- README.md | 16 +++++++++ apworld/README.md | 48 +++++++++++++++++++++++++++ client/README.md | 97 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ data/README.md | 13 ++++++++ 4 files changed, 174 insertions(+) create mode 100644 README.md create mode 100644 apworld/README.md create mode 100644 client/README.md create mode 100644 data/README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..144ee2b --- /dev/null +++ b/README.md @@ -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) diff --git a/apworld/README.md b/apworld/README.md new file mode 100644 index 0000000..386a2a1 --- /dev/null +++ b/apworld/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. diff --git a/client/README.md b/client/README.md new file mode 100644 index 0000000..07c5459 --- /dev/null +++ b/client/README.md @@ -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. diff --git a/data/README.md b/data/README.md new file mode 100644 index 0000000..bf0a51b --- /dev/null +++ b/data/README.md @@ -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. -- cgit 1.4.1