7 files changed, 167 insertions, 13 deletions

@@ -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/lingo2-archipelago/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/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.
+
+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.
@@ -1,7 +1,7 @@
 """
 Archipelago init file for Lingo 2
 """
-from BaseClasses import ItemClassification, Item
+from BaseClasses import ItemClassification, Item, Tutorial
 from worlds.AutoWorld import WebWorld, World
 from .items import Lingo2Item
 from .options import Lingo2Options
@@ -13,6 +13,14 @@ from .static_logic import Lingo2StaticLogic
 class Lingo2WebWorld(WebWorld):
     rich_text_options_doc = True
     theme = "grass"
+    tutorials = [Tutorial(
+        "Multiworld Setup Guide",
+        "A guide to playing Lingo 2 with Archipelago.",
+        "English",
+        "en_Lingo_2.md",
+        "setup/en",
+        ["hatkirby"]
+    )]
 
 
 class Lingo2World(World):
@@ -32,6 +40,8 @@ class Lingo2World(World):
     static_logic = Lingo2StaticLogic()
     item_name_to_id = static_logic.item_name_to_id
     location_name_to_id = static_logic.location_name_to_id
+    item_name_groups = static_logic.item_name_groups
+    location_name_groups = static_logic.location_name_groups
 
     player_logic: Lingo2PlayerLogic
 
@@ -66,8 +76,10 @@ class Lingo2World(World):
 
     def fill_slot_data(self):
         slot_options = [
+            "cyan_door_behavior",
             "daedalus_roof_access",
             "keyholder_sanity",
+            "shuffle_control_center_colors",
             "shuffle_doors",
             "shuffle_letters",
             "victory_condition",
@@ -0,0 +1,4 @@
+# Lingo 2
+
+See [the project README](https://code.fourisland.com/lingo2-archipelago/about/)
+for installation instructions and frequently asked questions. 
\ No newline at end of file
@@ -8,6 +8,14 @@ class ShuffleDoors(Toggle):
     display_name = "Shuffle Doors"
 
 
+class ShuffleControlCenterColors(Toggle):
+    """
+    Some doors open after solving the COLOR panel in the Control Center. If this option is enabled, these doors will
+    instead open upon receiving an item.
+    """
+    display_name = "Shuffle Control Center Colors"
+
+
 class ShuffleLetters(Choice):
     """
     Controls how letter unlocks are handled. Note that H1, I1, N1, and T1 will always be present at their vanilla
@@ -40,6 +48,27 @@ class KeyholderSanity(Toggle):
     display_name = "Keyholder Sanity"
 
 
+class CyanDoorBehavior(Choice):
+    """
+    Cyan-colored doors usually only open upon unlocking double letters. Some panels also only appear upon unlocking
+    double letters. This option determines how these unlocks should behave.
+
+    - **Collect H2**: In the base game, H2 is the first double letter you are intended to collect, so cyan doors only
+      open when you collect the H2 pickup in The Repetitive. Collecting the actual pickup is still required even with
+      remote letter shuffle enabled.
+    - **Any Double Letter**: Cyan doors will open when you have unlocked any cyan letter on your keyboard. In letter
+      shuffle, this means receiving a cyan letter, not picking up a cyan letter collectable.
+    - **Item**: Cyan doors will be grouped together in a single item.
+
+    Note that some cyan doors are impacted by door shuffle (e.g. the entrance to The Tower). When door shuffle is
+    enabled, these doors won't be affected by the value of this option.
+    """
+    display_name = "Cyan Door Behavior"
+    option_collect_h2 = 0
+    option_any_double_letter = 1
+    option_item = 2
+
+
 class DaedalusRoofAccess(Toggle):
     """
     If enabled, the player will be logically expected to be able to go from the castle entrance to any part of Daedalus
@@ -71,7 +100,9 @@ class VictoryCondition(Choice):
 @dataclass
 class Lingo2Options(PerGameCommonOptions):
     shuffle_doors: ShuffleDoors
+    shuffle_control_center_colors: ShuffleControlCenterColors
     shuffle_letters: ShuffleLetters
     keyholder_sanity: KeyholderSanity
+    cyan_door_behavior: CyanDoorBehavior
     daedalus_roof_access: DaedalusRoofAccess
     victory_condition: VictoryCondition
@@ -3,7 +3,7 @@ from enum import IntEnum, auto
 from .generated import data_pb2 as data_pb2
 from typing import TYPE_CHECKING, NamedTuple
 
-from .options import VictoryCondition, ShuffleLetters
+from .options import VictoryCondition, ShuffleLetters, CyanDoorBehavior
 
 if TYPE_CHECKING:
     from . import Lingo2World
@@ -123,16 +123,57 @@ class Lingo2PlayerLogic:
                     self.item_by_door[progressive.doors[i]] = (progressive.name, i + 1)
                     self.real_items.append(progressive.name)
 
+        for door_group in world.static_logic.objects.door_groups:
+            if door_group.type == data_pb2.DoorGroupType.CONNECTOR:
+                if not self.world.options.shuffle_doors:
+                    continue
+            elif door_group.type == data_pb2.DoorGroupType.COLOR_CONNECTOR:
+                if not self.world.options.shuffle_control_center_colors:
+                    continue
+            elif door_group.type == data_pb2.DoorGroupType.SHUFFLE_GROUP:
+                if not self.world.options.shuffle_doors:
+                    continue
+            else:
+                continue
+
+            for door in door_group.doors:
+                self.item_by_door[door] = (door_group.name, 1)
+
+            self.real_items.append(door_group.name)
+
         # We iterate through the doors in two parts because it is essential that we determine which doors are shuffled
         # before we calculate any access requirements.
         for door in world.static_logic.objects.doors:
-            if door.type in [data_pb2.DoorType.STANDARD, data_pb2.DoorType.ITEM_ONLY] and self.world.options.shuffle_doors:
-                if door.id in self.item_by_door:
+            if door.type in [data_pb2.DoorType.EVENT, data_pb2.DoorType.LOCATION_ONLY, data_pb2.DoorType.GRAVESTONE]:
+                continue
+
+            if door.id in self.item_by_door:
+                continue
+
+            if (door.type in [data_pb2.DoorType.STANDARD, data_pb2.DoorType.ITEM_ONLY] and
+                    not self.world.options.shuffle_doors):
+                continue
+
+            if (door.type == data_pb2.DoorType.CONTROL_CENTER_COLOR and
+                    not self.world.options.shuffle_control_center_colors):
+                continue
+
+            door_item_name = self.world.static_logic.get_door_item_name(door)
+            self.item_by_door[door.id] = (door_item_name, 1)
+            self.real_items.append(door_item_name)
+
+        # We handle cyan_door_behavior = Item after door shuffle, because cyan doors that are impacted by door shuffle
+        # should be exempt from cyan_door_behavior.
+        if world.options.cyan_door_behavior == CyanDoorBehavior.option_item:
+            for door_group in world.static_logic.objects.door_groups:
+                if door_group.type != data_pb2.DoorGroupType.CYAN_DOORS:
                     continue
 
-                door_item_name = self.world.static_logic.get_door_item_name(door)
-                self.item_by_door[door.id] = (door_item_name, 1)
-                self.real_items.append(door_item_name)
+                for door in door_group.doors:
+                    if not door in self.item_by_door:
+                        self.item_by_door[door] = (door_group.name, 1)
+
+                self.real_items.append(door_group.name)
 
         for door in world.static_logic.objects.doors:
             if door.type in [data_pb2.DoorType.STANDARD, data_pb2.DoorType.LOCATION_ONLY, data_pb2.DoorType.GRAVESTONE]:
@@ -272,12 +313,13 @@ class Lingo2PlayerLogic:
             self.add_solution_reqs(reqs, door.control_center_color)
 
         if door.double_letters:
-            if self.world.options.shuffle_letters in [ShuffleLetters.option_vanilla,
-                                                      ShuffleLetters.option_vanilla_cyan]:
+            if self.world.options.cyan_door_behavior == CyanDoorBehavior.option_collect_h2:
                 reqs.rooms.add("The Repetitive - Main Room")
-            elif self.world.options.shuffle_letters in [ShuffleLetters.option_progressive,
-                                                        ShuffleLetters.option_item_cyan]:
+            elif self.world.options.cyan_door_behavior == CyanDoorBehavior.option_any_double_letter:
                 reqs.cyans = True
+            elif self.world.options.cyan_door_behavior == CyanDoorBehavior.option_item:
+                # There shouldn't be any locations that are cyan doors.
+                pass
 
         for keyholder_uses in door.keyholders:
             key_name = keyholder_uses.key.upper()
@@ -293,7 +335,11 @@ class Lingo2PlayerLogic:
 
         for ending_id in door.endings:
             ending = self.world.static_logic.objects.endings[ending_id]
-            reqs.items.add(f"{ending.name.capitalize()} Ending (Achieved)")
+
+            if self.world.options.victory_condition.current_key.removesuffix("_ending").upper() == ending.name:
+                reqs.items.add("Victory")
+            else:
+                reqs.items.add(f"{ending.name.capitalize()} Ending (Achieved)")
 
         for sub_door_id in door.doors:
             sub_reqs = self.get_door_open_reqs(sub_door_id)
@@ -1 +1 @@
-protobuf>=5.29.3
\ No newline at end of file
+protobuf==3.20.3
@@ -8,9 +8,14 @@ class Lingo2StaticLogic:
     item_name_to_id: dict[str, int]
     location_name_to_id: dict[str, int]
 
+    item_name_groups: dict[str, list[str]]
+    location_name_groups: dict[str, list[str]]
+
     def __init__(self):
         self.item_id_to_name = {}
         self.location_id_to_name = {}
+        self.item_name_groups = {}
+        self.location_name_groups = {}
 
         file = pkgutil.get_data(__name__, "generated/data.binpb")
         self.objects = data_pb2.AllObjects()
@@ -29,25 +34,33 @@ class Lingo2StaticLogic:
             letter_name = f"{letter.key.upper()}{'2' if letter.level2 else '1'}"
             location_name = f"{self.get_room_object_map_name(letter)} - {letter_name}"
             self.location_id_to_name[letter.ap_id] = location_name
+            self.location_name_groups.setdefault("Letters", []).append(location_name)
 
             if not letter.level2:
                 self.item_id_to_name[letter.ap_id] = letter.key.upper()
+                self.item_name_groups.setdefault("Letters", []).append(letter.key.upper())
 
         for mastery in self.objects.masteries:
             location_name = f"{self.get_room_object_map_name(mastery)} - Mastery"
             self.location_id_to_name[mastery.ap_id] = location_name
+            self.location_name_groups.setdefault("Masteries", []).append(location_name)
 
         for ending in self.objects.endings:
             location_name = f"{self.get_room_object_map_name(ending)} - {ending.name.title()} Ending"
             self.location_id_to_name[ending.ap_id] = location_name
+            self.location_name_groups.setdefault("Endings", []).append(location_name)
 
         for progressive in self.objects.progressives:
             self.item_id_to_name[progressive.ap_id] = progressive.name
 
+        for door_group in self.objects.door_groups:
+            self.item_id_to_name[door_group.ap_id] = door_group.name
+
         for keyholder in self.objects.keyholders:
             if keyholder.HasField("key"):
                 location_name = f"{self.get_room_object_location_prefix(keyholder)} - {keyholder.key.upper()} Keyholder"
                 self.location_id_to_name[keyholder.ap_id] = location_name
+                self.location_name_groups.setdefault("Keyholders", []).append(location_name)
 
         self.item_id_to_name[self.objects.special_ids["A Job Well Done"]] = "A Job Well Done"