# 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, 
syntax = "proto2";

import "data.proto";

package com.fourisland.lingo2_archipelago;

message RoomIdentifier {
  optional string map = 1;
  optional string name = 2;
}

message DoorIdentifier {
  optional string map = 1;
  optional string name = 2;
}

message PortIdentifier {
  optional string map = 1;
  optional string room = 2;
  optional string name = 3;
}

message PaintingIdentifier {
  optional string map = 1;
  optional string room = 2;
  optional string name = 3;
}

message PanelIdentifier {
  optional string map = 1;
  optional string room = 2;
  optional string name = 3;
  optional string answer = 4;
}

message KeyholderIdentifier {
  optional string map = 1;
  optional string room = 2;
  optional string name = 3;
  optional string key = 4;
}

message HumanConnection {
  message Endpoint {
    oneof endpoint {
      RoomIdentifier room = 1;
      PortIdentifier port = 2;
      PaintingIdentifier painting = 3;
      PanelIdentifier panel = 4;
    }
  }

  oneof From {
    Endpoint from = 1;
    string from_room = 5;
  }

  oneof To {
    Endpoint to = 2;
    string to_room = 6;
  }

  optional bool oneway = 3;
  optional DoorIdentifier door = 4;

  // If true, this connection will only be logically allowed if the Daedalus
  // Roof Access option is enabled.
  optional bool roof_access = 7;

  // This means that the connection intentionally skips the target object's
  // required door.
  optional bool bypass_target_door = 8;

  // This means that the connection should additionally require all purple
  // letters when the Strict Purple Ending option is on.
  optional bool purple_ending = 9;

  // This means that the connection should additionally require all cyan letters
  // when the Strict Cyan Ending option is on.
  optional bool cyan_ending = 10;
}

message HumanConnections {
  repeated HumanConnection connections = 1;
}

message HumanDoor {
  optional string name = 1;

  repeated string receivers = 2;
  repeated PaintingIdentifier move_paintings = 8;

  // The set of panels that must be solved to open this door.
  repeated PanelIdentifier panels = 3;

  // If set, the number of panels from the above set that need to be solved.
  // Warning: this is a messy kind of OR logic! Consider if there's another way.
  optional uint64 complete_at = 9;

  optional string control_center_color = 6;
  repeated KeyholderIdentifier keyholders = 10;
  repeated RoomIdentifier rooms = 11;
  repeated DoorIdentifier doors = 12;
  repeated string endings = 13;
  optional bool double_letters = 15;

  // Sender nodes to be added to the list of requirements for triggering the
  // location. Only for senders that have no logic requirements.
  repeated string senders = 16;

  optional DoorType type = 4;
  optional string location_room = 5;
  optional string location_name = 14;
}

message HumanDoors {
  repeated HumanDoor doors = 1;
}

message HumanPanel {
  optional string name = 1;
  optional string path = 5;
  
  optional string clue = 2;
  optional string answer = 3;
  repeated PuzzleSymbol symbols = 4;

  repeated Proxy proxies = 6;

  optional DoorIdentifier required_door = 7;
  optional RoomIdentifier required_room = 8;

  optional string display_name = 9;
}

message HumanPainting {
  optional string name = 1;
  optional string path = 2;

  optional string display_name = 4;

  optional string orientation = 3;
  optional bool move = 6;
  optional bool enter_only = 7;
  optional AxisDirection gravity = 8 [default = Y_MINUS];
  optional bool exit_only = 9;
  
  optional DoorIdentifier required_door = 5;
}

message HumanPort {
  optional string name = 1;
  optional string path = 2;

  optional bool no_shuffle = 7;

  // These specify how the player should be placed when a randomized entrance
  // sends them to this port. "rotation" is in degrees and is counter-clockwise 
  // from the positive X axis.
  optional Vec3d destination = 3;
  optional double rotation = 6;
  optional AxisDirection gravity = 5 [default = Y_MINUS];

  optional DoorIdentifier required_door = 4;
}

message HumanKeyholder {
  optional string name = 1;
  optional string path = 2;

  // If this is set, the keyholder will become a location when keyholder shuffle
  // is enabled. This value specifies the key that is required to clear the
  // location. It should be the same as the key needed for Green Ending. The
  // only cases when this shouldn't be set is the two disappearing keyholders in
  // The Congruent.
  optional string key = 3;
}

message HumanLetter {
  optional string key = 1;
  optional bool level2 = 2;

  optional string path = 3;
}

message HumanMastery {
  optional string name = 1;
  optional string path = 2;
}

message HumanEnding {
  optional string name = 1;
  optional string path = 2;
}

message HumanRoom {
  optional string name = 1;
  optional string display_name = 2;

  // This is used in panelsanity location names and location names for STANDARD
  // doors generated from panels in the same area.
  optional string panel_display_name = 10;

  repeated HumanPanel panels = 3;
  repeated HumanPainting paintings = 4;
  repeated HumanLetter letters = 5;
  repeated HumanPort ports = 6;
  repeated HumanKeyholder keyholders = 7;
  repeated HumanMastery masteries = 8;
  repeated HumanEnding endings = 9;
}

message HumanMap {
  optional string display_name = 1;
  repeated string excluded_nodes = 2;
}

message HumanProgressive {
  optional string name = 1;
  repeated DoorIdentifier doors = 2;
}

message HumanProgressives {
  repeated HumanProgressive progressives = 1;
}

message HumanDoorGroup {
  optional string name = 1;
  optional DoorGroupType type = 2;
  repeated DoorIdentifier doors = 3;
}

message HumanDoorGroups {
  repeated HumanDoorGroup door_groups = 1;
}

message HumanGlobalMetadata {
  repeated string special_names = 1;
  optional uint64 version = 2;
}

message IdMappings {
  message RoomIds {
    map<string, uint64> panels = 1;
    map<string, uint64> masteries = 2;
    map<string, uint64> keyholders = 3;
  }

  message MapIds {
    map<string, uint64> doors = 1;
    map<string, RoomIds> rooms = 2;
  }

  map<string, MapIds> maps = 1;
  map<string, uint64> special = 2;
  map<string, uint64> letters = 3;
  map<string, uint64> endings = 4;
  map<string, uint64> progressives = 5;
  map<string, uint64> door_groups = 6;
}