mirror/Archipelago
1
0
Fork 1
mirror of https://github.com/ArchipelagoMW/Archipelago.git synced 2026-03-07 15:13:52 -08:00
Code Issues Packages Projects Releases Wiki Activity

Add mermaid support and Architecture.md. Expand index.md

Browse Source
This commit is contained in:
Hussein Farran
2022-08-20 17:20:07 -04:00
parent dee8a2aaa9
commit 309651a644
6 changed files with 163 additions and 12 deletions
Download Patch File Download Diff File Expand all files Collapse all files

101
docs/sphinx/Architecture.md Normal file
View File

@@ -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.

6
docs/sphinx/NetworkDiagram.md
View File

@@ -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

4
docs/sphinx/NetworkProtocol.md
View File

@@ -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 |

3
docs/sphinx/conf.py
View File

@@ -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 -------------------------------------------------

60
docs/sphinx/index.md
View File

@@ -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`

1
worlds/__init__.py
View File

@@ -12,6 +12,7 @@ __all__ = [
"AutoWorldRegister",
"world_sources",
"folder",
"World"
]
if typing.TYPE_CHECKING: