From 309651a64417cee98b1dc9f36a398901eac23d01 Mon Sep 17 00:00:00 2001 From: Hussein Farran Date: Sat, 20 Aug 2022 17:20:07 -0400 Subject: [PATCH] Add mermaid support and Architecture.md. Expand index.md --- docs/sphinx/Architecture.md | 101 +++++++++++++++++++++++++++++++++ docs/sphinx/NetworkDiagram.md | 6 +- docs/sphinx/NetworkProtocol.md | 4 +- docs/sphinx/conf.py | 3 +- docs/sphinx/index.md | 60 +++++++++++++++++--- worlds/__init__.py | 1 + 6 files changed, 163 insertions(+), 12 deletions(-) create mode 100644 docs/sphinx/Architecture.md diff --git a/docs/sphinx/Architecture.md b/docs/sphinx/Architecture.md new file mode 100644 index 0000000000..c36d3abe1f --- /dev/null +++ b/docs/sphinx/Architecture.md @@ -0,0 +1,101 @@ +# Archipelago Architecture +Archipelago is split into several components. All components must operate in tandem to facilitate randomization +and gameplay. + +The components are: +* [Archipelago Generator](#archipelago-generator) +* [Archipelago Server](#archipelago-server) +* [Archipelago Game Client](#archipelago-game-client) + +Some games require additional components in order to facilitate gameplay or communication with Archipelago. +The additional components vary from game to game but are typically: +* [Retro Console Emulator](#retro-console-emulator) +* [Emulator Communication Bridge (SNI)](#emulator-communication-bridge) + +## Archipelago Generator +The Archipelago Generator is the part of Archipelago which takes YAML configuration files as input and produces a ZIP +file containing the data necessary for the Archipelago Server to service a session. The generator software is standalone +from the server or game clients and is run outside the server context. The server may then be pointed to the resulting +file to serve that session. + +For more information on using the Archipelago Generator as a user, please visit the user facing MultiWorld Setup Guide +section on [Rolling a YAML Locally](https://archipelago.gg/tutorial/Archipelago/setup/en#rolling-a-yaml-locally). + +The Generator functions by using the classes defined in the `/worlds` folder to understand each game's items, location, +YAML options, and logic. The "World" classes define these properties in code and are loaded by the generator to allow it +to validate YAML options and create a multiworld with cohesive and solvable logic despite the possibility of disparate +games being played. + +## Archipelago Server +The Archipelago Server facilitates gameplay for a multiworld session. A session may have any number of players. +As Archipelago is client-server software the server is still required for sessions even if only a single player is +present. The server takes a ZIP file or an ARCHIPELAGO file as input and serves the session using the information from +the input to properly serve the game clients over network. + +## Archipelago Game Client +Archipelago game clients are currently implemented in two main ways. The first are in-process clients, which operate as +a mod loaded within the game process. The game process will then facilitate the WebSocket communication with the +Archipelago Server. Typically, more "modern" games will use this approach as they are typically easier to mod or are +easier to inject with code at runtime. + +Some examples of Archipelago games implementing the in-process model are: +* [Risk of Rain 2](https://github.com/Ijwu/Archipelago.RiskOfRain2) +* [Subnautica](https://github.com/Berserker66/ArchipelagoSubnauticaModSrc) +* [Hollow Knight](https://github.com/Ijwu/Archipelago.HollowKnight) + +The in-process model can be visualized using the following diagram: +```{mermaid} +flowchart LR + APS[Archipelago Server] + APGC[Archipelago Game Client] + + APS <-- WebSockets --> APGC +``` + +The second model of game client are those which operate out-of-process. The out-of-process clients are shipped with the +Archipelago installation and live within the Archipelago codebase. They are implemented in Python using [CommonClient.py](https://github.com/ArchipelagoMW/Archipelago/blob/main/CommonClient.py) +as a base. This client model is typically used for games in which runtime modification is difficult to impossible and for +games which require additional components such as the emulator communication bridge. This model is also used for clients +which communicate with the game from outside the game process to understand game state; the client then communicates +updates to the Archipelago server based on the game state. + +Some examples of Archipelago games implementing the out-of-process model are: +* [Starcraft 2](https://github.com/ArchipelagoMW/Archipelago/blob/main/Starcraft2Client.py) +* [Factorio](https://github.com/ArchipelagoMW/Archipelago/blob/main/FactorioClient.py) +* [The Legend of Zelda: Ocarina of Time](https://github.com/ArchipelagoMW/Archipelago/blob/main/OoTClient.py) + +The out-of-process model can be visualized using the following diagram: +```{mermaid} +flowchart LR + APS[Archipelago Server] + OOPGC[Out-of-Process Game Client] + GP[Game Process] + + APS <-- WebSockets --> OOPGC <--> GP +``` + +Games which use the [SNI](https://github.com/alttpo/sni) emulator communication bridge can be connected to Archipelago using the [SNIClient](https://github.com/ArchipelagoMW/Archipelago/blob/main/SNIClient.py). + +Games communicating using SNI may be visualized using the following diagram: +```{mermaid} +flowchart LR + APS[Archipelago Server] + SNIC[SNIClient] + SNI[SNI] + GP[Game Process] + + APS <-- WebSockets --> SNIC <-- WebSockets --> SNI <--> GP +``` + +## Retro Console Emulator +Some game implementations require the use of an emulator in order to run the game and to communicate with SNI. +These games are typically "retro" games which were released on 8-bit or 16-bit consoles, although newer consoles may be +included for some game implementations. + +All emulators currently used in Archipelago game implementations which require them are lua enabled and use a lua script +to communicate with SNI. + +## Emulator Communication Bridge +All implementations of game clients for which the game is run in an emulator presently use [SuperNintendoInterface or SNI](https://github.com/alttpo/sni) +to communicate between the emulator and the SNIClient. The emulator uses lua to communicate to SNI which communicates with +the SNIClient which communicates with the Archipelago server. \ No newline at end of file diff --git a/docs/sphinx/NetworkDiagram.md b/docs/sphinx/NetworkDiagram.md index fc04b87f32..bad8777cea 100644 --- a/docs/sphinx/NetworkDiagram.md +++ b/docs/sphinx/NetworkDiagram.md @@ -1,4 +1,8 @@ -```mermaid +# Archipelago Network Diagram +(Psst, scroll down and zoom in.) + + +```{mermaid} flowchart LR %% Diagram arranged specifically so output generates no terrible crossing lines. %% AP Server diff --git a/docs/sphinx/NetworkProtocol.md b/docs/sphinx/NetworkProtocol.md index 45a1f962a0..5bd8287889 100644 --- a/docs/sphinx/NetworkProtocol.md +++ b/docs/sphinx/NetworkProtocol.md @@ -54,7 +54,7 @@ Example: ``` ## (Server -> Client) -These packets are are sent from the multiworld server to the client. They are not messages which the server accepts. +These packets are sent from the multiworld server to the client. They are not messages which the server accepts. * [RoomInfo](#roominfo) * [ConnectionRefused](#connectionrefused) * [Connected](#connected) @@ -220,7 +220,7 @@ Sent to clients if the server caught a problem with a packet. This only occurs f | original_cmd | Optional[str] | The `cmd` argument of the faulty packet, will be `None` if the `cmd` failed to be parsed. | | text | str | A descriptive message of the problem at hand. | -##### PacketProblemType +#### PacketProblemType `PacketProblemType` indicates the type of problem that was detected in the faulty packet, the known problem types are below but others may be added in the future. | Type | Notes | diff --git a/docs/sphinx/conf.py b/docs/sphinx/conf.py index 0c1ca57633..1e5471c378 100644 --- a/docs/sphinx/conf.py +++ b/docs/sphinx/conf.py @@ -28,6 +28,7 @@ author = 'Archipelago Team and Contributors' # ones. extensions = [ "myst_parser", + "sphinxcontrib.mermaid", "sphinx.ext.autodoc", "sphinx.ext.autosummary", ] @@ -40,7 +41,7 @@ templates_path = ['_templates'] # This pattern also affects html_static_path and html_extra_path. exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store'] -myst_heading_anchors = 3 +myst_heading_anchors = 4 # -- Options for HTML output ------------------------------------------------- diff --git a/docs/sphinx/index.md b/docs/sphinx/index.md index e38c8f8017..7282d29e77 100644 --- a/docs/sphinx/index.md +++ b/docs/sphinx/index.md @@ -3,24 +3,68 @@ % You can adapt this file completely to your liking, but it should at least % contain the root `toctree` directive. -Welcome to Archipelago's documentation! -======================================= +Welcome to Archipelago's Technical Documentation! +================================================= +## What is Archipelago? +Archipelago provides a generic framework for developing multiworld capability for game randomizers. +In all cases, presently, Archipelago is also the randomizer itself. + +Archipelago is end-user facing software intended to facilitate randomizer and multiworld play for a variety of +supported games. + +Archipelago presently supports the following games: +* The Legend of Zelda: A Link to the Past +* Factorio +* Minecraft +* Subnautica +* Slay the Spire +* Risk of Rain 2 +* The Legend of Zelda: Ocarina of Time +* Timespinner +* Super Metroid +* Secret of Evermore +* Final Fantasy +* Rogue Legacy +* VVVVVV +* Raft +* Super Mario 64 +* Meritous +* Super Metroid/Link to the Past combo randomizer (SMZ3) +* ChecksFinder +* ArchipIDLE +* Hollow Knight +* The Witness +* Sonic Adventure 2: Battle +* Starcraft 2: Wings of Liberty +* Donkey Kong Country 3 +* Dark Souls 3 + +For more information on the technical architecture of Archipelago, +please refer to the [Archipelago Technical Architecture](Architecture.md) document. + +## Contributing to Archipelago +Contributions to the Archipelago code are welcome and dearly appreciated. Contributions may occur as changes to website +content, changes to Archipelago core code, additions of game integrations, or alterations to website functionality. + +Please visit our [contributing guidelines on our GitHub README](https://github.com/ArchipelagoMW/Archipelago#contributing) +for some more information on what may be expected. + +For information on contributing a game integration, check out our [document on adding games to Archipelago](./AddingGames.md). + +## Table of Contents ```{toctree} --- maxdepth: 2 -caption: "Contents:" +caption: "Documentation contents:" --- AddingGames WorldAPI NetworkProtocol +NetworkDiagram ``` - - -Indices and tables -================== - +## Indices and tables * {ref}`genindex` * {ref}`modindex` * {ref}`search` diff --git a/worlds/__init__.py b/worlds/__init__.py index a331257166..5d78c7fff8 100644 --- a/worlds/__init__.py +++ b/worlds/__init__.py @@ -12,6 +12,7 @@ __all__ = [ "AutoWorldRegister", "world_sources", "folder", + "World" ] if typing.TYPE_CHECKING: