Muse Dash: Add mentions to Muse Plus to Docs and Options. (#2179)

* Add mentions to Muse Plus.

* Grammer fix.

* Apply Exempt-Medics Suggestion

Co-authored-by: Exempt-Medic <60412657+Exempt-Medic@users.noreply.github.com>

* Make [Just as Planned] casing consistent. Fix grammar on Available Trap Types option.

---------

Co-authored-by: Exempt-Medic <60412657+Exempt-Medic@users.noreply.github.com>

.github/ISSUE_TEMPLATE/bug_report.yaml

@@ -0,0 +1,35 @@
+name: Bug Report
+description: File a bug report.
+title: "Bug: "
+labels:
+  - bug / fix
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for taking the time to fill out this bug report! If this bug occurred during local generation check your 
+        Archipelago install for a log (probably `C:\ProgramData\Archipelago\logs`)
+        and upload it with this report, as well as all yaml files used.
+  - type: textarea
+    id: what-happened
+    attributes:
+      label: What happened?
+    validations:
+      required: true
+  - type: textarea
+    id: expected-results
+    attributes:
+      label: What were the expected results?
+    validations:
+      required: true
+  - type: dropdown
+    id: version
+    attributes:
+      label: Software
+      description: Where did this bug occur?
+      options:
+        - Website
+        - Local generation
+        - While playing
+    validations:
+      required: true

.github/ISSUE_TEMPLATE/feature_request.yaml

@@ -0,0 +1,17 @@
+name: Feature Request
+description: Request a feature!
+title: "Category: "
+labels:
+  - enhancement
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Please replace `Category` in the title with what this feature will be targeting, such as Core generation,
+        website, documentation, or a game.
+        Note: this is not for requesting new games to be added. If you would like to request a game, the best place to
+        ask is about it is in the [discord](https://archipelago.gg/discord).
+  - type: textarea
+    id: feature
+    attributes:
+      label: What feature would you like to see?

.github/ISSUE_TEMPLATE/task.yaml

@@ -0,0 +1,10 @@
+name: Task
+description: Submit a task to be done. If this is not targeting core, it should likely be elsewhere.
+title: "Core: "
+labels:
+  - core
+  - enhancement
+body:
+  - type: textarea
+    attributes:
+      label: What task needs to be completed?

.github/pull_request_template.md

@@ -0,0 +1,12 @@
+Please format your title with what portion of the project this pull request is
+targeting and what it's changing.
+
+ex. "MyGame4: implement new game" or "Docs: add new guide for customizing MyGame3"
+
+## What is this fixing or adding?
+
+
+## How was this tested?
+
+
+## If this makes graphical changes, please attach screenshots.

.github/workflows/analyze-modified-files.yml

@@ -0,0 +1,80 @@
+name: Analyze modified files
+
+on:
+  pull_request:
+    paths:
+      - "**.py"
+  push:
+    paths:
+      - "**.py"
+
+env:
+  BASE: ${{ github.event.pull_request.base.sha }}
+  HEAD: ${{ github.event.pull_request.head.sha }}
+  BEFORE: ${{ github.event.before }}
+  AFTER: ${{ github.event.after }}
+
+jobs:
+  flake8-or-mypy:
+    strategy:
+      fail-fast: false
+      matrix:
+        task: [flake8, mypy]
+
+    name: ${{ matrix.task }}
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v3
+
+      - name: "Determine modified files (pull_request)"
+        if: github.event_name == 'pull_request'
+        run: |
+          git fetch origin $BASE $HEAD
+          DIFF=$(git diff --diff-filter=d --name-only $BASE...$HEAD -- "*.py")
+          echo "modified files:"
+          echo "$DIFF"
+          echo "diff=${DIFF//$'\n'/$' '}" >> $GITHUB_ENV
+
+      - name: "Determine modified files (push)"
+        if: github.event_name == 'push' && github.event.before != '0000000000000000000000000000000000000000'
+        run: |
+          git fetch origin $BEFORE $AFTER
+          DIFF=$(git diff --diff-filter=d --name-only $BEFORE..$AFTER -- "*.py")
+          echo "modified files:"
+          echo "$DIFF"
+          echo "diff=${DIFF//$'\n'/$' '}" >> $GITHUB_ENV
+
+      - name: "Treat all files as modified (new branch)"
+        if: github.event_name == 'push' && github.event.before == '0000000000000000000000000000000000000000'
+        run: |
+          echo "diff=." >> $GITHUB_ENV
+
+      - uses: actions/setup-python@v4
+        if: env.diff != ''
+        with:
+          python-version: 3.8
+
+      - name: "Install dependencies"
+        if: env.diff != ''
+        run: |
+          python -m pip install --upgrade pip ${{ matrix.task }}
+          python ModuleUpdate.py --append "WebHostLib/requirements.txt" --force --yes
+
+      - name: "flake8: Stop the build if there are Python syntax errors or undefined names"
+        continue-on-error: false
+        if: env.diff != '' && matrix.task == 'flake8'
+        run: |
+          flake8 --count --select=E9,F63,F7,F82 --show-source --statistics ${{ env.diff }}
+
+      - name: "flake8: Lint modified files"
+        continue-on-error: true
+        if: env.diff != '' && matrix.task == 'flake8'
+        run: |
+          flake8 --count --max-complexity=10 --max-doc-length=120 --max-line-length=120 --statistics ${{ env.diff }}
+
+      - name: "mypy: Type check modified files"
+        continue-on-error: true
+        if: env.diff != '' && matrix.task == 'mypy'
+        run: |
+          mypy --follow-imports=silent --install-types --non-interactive --strict ${{ env.diff }}

.github/workflows/build.yml

@@ -0,0 +1,113 @@
+# This workflow will build a release-like distribution when manually dispatched
+
+name: Build
+
+on:
+  push:
+    paths:
+      - '.github/workflows/build.yml'
+      - 'setup.py'
+      - 'requirements.txt'
+  pull_request:
+    paths:
+      - '.github/workflows/build.yml'
+      - 'setup.py'
+      - 'requirements.txt'
+  workflow_dispatch:
+
+env:
+  ENEMIZER_VERSION: 7.1
+  APPIMAGETOOL_VERSION: 13
+
+jobs:
+  # build-release-macos: # LF volunteer
+
+  build-win-py38: # RCs will still be built and signed by hand
+    runs-on: windows-latest
+    steps:
+      - uses: actions/checkout@v3
+      - name: Install python
+        uses: actions/setup-python@v4
+        with:
+          python-version: '3.8'
+      - name: Download run-time dependencies
+        run: |
+          Invoke-WebRequest -Uri https://github.com/Ijwu/Enemizer/releases/download/${Env:ENEMIZER_VERSION}/win-x64.zip -OutFile enemizer.zip
+          Expand-Archive -Path enemizer.zip -DestinationPath EnemizerCLI -Force
+      - name: Build
+        run: |
+          python -m pip install --upgrade pip
+          python setup.py build_exe --yes
+          $NAME="$(ls build | Select-String -Pattern 'exe')".Split('.',2)[1]
+          $ZIP_NAME="Archipelago_$NAME.7z"
+          echo "$NAME -> $ZIP_NAME"
+          echo "ZIP_NAME=$ZIP_NAME" >> $Env:GITHUB_ENV
+          New-Item -Path dist -ItemType Directory -Force
+          cd build
+          Rename-Item "exe.$NAME" Archipelago
+          7z a -mx=9 -mhe=on -ms "../dist/$ZIP_NAME" Archipelago
+      - name: Store 7z
+        uses: actions/upload-artifact@v3
+        with:
+          name: ${{ env.ZIP_NAME }}
+          path: dist/${{ env.ZIP_NAME }}
+          retention-days: 7  # keep for 7 days, should be enough
+
+  build-ubuntu2004:
+    runs-on: ubuntu-20.04
+    steps:
+      # - copy code below to release.yml -
+      - uses: actions/checkout@v3
+      - name: Install base dependencies
+        run: |
+          sudo apt update
+          sudo apt -y install build-essential p7zip xz-utils wget libglib2.0-0
+          sudo apt -y install python3-gi libgirepository1.0-dev  # should pull dependencies for gi installation below
+      - name: Get a recent python
+        uses: actions/setup-python@v4
+        with:
+          python-version: '3.11'
+      - name: Install build-time dependencies
+        run: |
+          echo "PYTHON=python3.11" >> $GITHUB_ENV
+          wget -nv https://github.com/AppImage/AppImageKit/releases/download/$APPIMAGETOOL_VERSION/appimagetool-x86_64.AppImage
+          chmod a+rx appimagetool-x86_64.AppImage
+          ./appimagetool-x86_64.AppImage --appimage-extract
+          echo -e '#/bin/sh\n./squashfs-root/AppRun "$@"' > appimagetool
+          chmod a+rx appimagetool
+      - name: Download run-time dependencies
+        run: |
+          wget -nv https://github.com/Ijwu/Enemizer/releases/download/$ENEMIZER_VERSION/ubuntu.16.04-x64.7z
+          7za x -oEnemizerCLI/ ubuntu.16.04-x64.7z
+      - name: Build
+        run: |
+          # pygobject is an optional dependency for kivy that's not in requirements
+          # charset-normalizer was somehow incomplete in the github runner
+          "${{ env.PYTHON }}" -m venv venv
+          source venv/bin/activate
+          "${{ env.PYTHON }}" -m pip install --upgrade pip PyGObject charset-normalizer
+          python setup.py build_exe --yes bdist_appimage --yes
+          echo -e "setup.py build output:\n `ls build`"
+          echo -e "setup.py dist output:\n `ls dist`"
+          cd dist && export APPIMAGE_NAME="`ls *.AppImage`" && cd ..
+          export TAR_NAME="${APPIMAGE_NAME%.AppImage}.tar.gz"
+          (cd build && DIR_NAME="`ls | grep exe`" && mv "$DIR_NAME" Archipelago && tar -czvf ../dist/$TAR_NAME Archipelago && mv Archipelago "$DIR_NAME")
+          echo "APPIMAGE_NAME=$APPIMAGE_NAME" >> $GITHUB_ENV
+          echo "TAR_NAME=$TAR_NAME" >> $GITHUB_ENV
+      # - copy code above to release.yml -
+      - name: Build Again
+        run: |
+          source venv/bin/activate
+          python setup.py build_exe --yes
+      - name: Store AppImage
+        uses: actions/upload-artifact@v3
+        with:
+          name: ${{ env.APPIMAGE_NAME }}
+          path: dist/${{ env.APPIMAGE_NAME }}
+          retention-days: 7
+      - name: Store .tar.gz
+        uses: actions/upload-artifact@v3
+        with:
+          name: ${{ env.TAR_NAME }}
+          path: dist/${{ env.TAR_NAME }}
+          retention-days: 7

.github/workflows/codeql-analysis.yml

@@ -14,9 +14,17 @@ name: "CodeQL"
 on:
   push:
     branches: [ main ]
+    paths:
+      - '**.py'
+      - '**.js'
+      - '.github/workflows/codeql-analysis.yml'
   pull_request:
     # The branches below must be a subset of the branches above
     branches: [ main ]
+    paths:
+      - '**.py'
+      - '**.js'
+      - '.github/workflows/codeql-analysis.yml'
   schedule:
     - cron: '44 8 * * 1'
 
@@ -35,11 +43,11 @@ jobs:
 
     steps:
     - name: Checkout repository
-      uses: actions/checkout@v2
+      uses: actions/checkout@v3
 
     # Initializes the CodeQL tools for scanning.
     - name: Initialize CodeQL
-      uses: github/codeql-action/init@v1
+      uses: github/codeql-action/init@v2
       with:
         languages: ${{ matrix.language }}
         # If you wish to specify custom queries, you can do so here or in a config file.
@@ -50,7 +58,7 @@ jobs:
     # Autobuild attempts to build any compiled languages  (C/C++, C#, or Java).
     # If this step fails, then you should remove it and run the build manually (see below)
     - name: Autobuild
-      uses: github/codeql-action/autobuild@v1
+      uses: github/codeql-action/autobuild@v2
 
     # ℹ️ Command-line programs to run using the OS shell.
     # 📚 https://git.io/JvXDl
@@ -64,4 +72,4 @@ jobs:
     #   make release
 
     - name: Perform CodeQL Analysis
-      uses: github/codeql-action/analyze@v1
+      uses: github/codeql-action/analyze@v2

.github/workflows/lint.yml

@@ -1,29 +0,0 @@
-# This workflow will install Python dependencies, run tests and lint with a single version of Python
-# For more information see: https://help.github.com/actions/language-and-framework-guides/using-python-with-github-actions
-
-name: lint
-
-on: [push, pull_request]
-
-jobs:
-  build:
-
-    runs-on: ubuntu-latest
-
-    steps:
-    - uses: actions/checkout@v2
-    - name: Set up Python 3.9
-      uses: actions/setup-python@v1
-      with:
-        python-version: 3.9
-    - name: Install dependencies
-      run: |
-        python -m pip install --upgrade pip
-        pip install flake8 pytest
-        if [ -f requirements.txt ]; then pip install -r requirements.txt; fi
-    - name: Lint with flake8
-      run: |
-        # stop the build if there are Python syntax errors or undefined names
-        flake8 . --count --select=E9,F63,F7,F82 --show-source --statistics
-        # exit-zero treats all errors as warnings. The GitHub editor is 127 chars wide
-        flake8 . --count --exit-zero --max-complexity=10 --max-line-length=127 --statistics

.github/workflows/release.yml

@@ -0,0 +1,85 @@
+# This workflow will create a release and store builds to it when an x.y.z tag is pushed
+
+name: Release
+
+on:
+  push:
+    tags:
+      - '*.*.*'
+
+env:
+  ENEMIZER_VERSION: 7.1
+  APPIMAGETOOL_VERSION: 13
+
+jobs:
+  create-release:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Set env
+        run: echo "RELEASE_VERSION=${GITHUB_REF#refs/*/}" >> $GITHUB_ENV  # tag x.y.z will become "Archipelago x.y.z"
+      - name: Create Release
+        uses: softprops/action-gh-release@b7e450da2a4b4cb4bfbae528f788167786cfcedf
+        with:
+          draft: true  # don't publish right away, especially since windows build is added by hand
+          prerelease: false
+          name: Archipelago ${{ env.RELEASE_VERSION }}
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+  # build-release-windows: # this is done by hand because of signing
+  # build-release-macos: # LF volunteer
+
+  build-release-ubuntu2004:
+    runs-on: ubuntu-20.04
+    steps:
+      - name: Set env
+        run: echo "RELEASE_VERSION=${GITHUB_REF#refs/*/}" >> $GITHUB_ENV
+      # - code below copied from build.yml -
+      - uses: actions/checkout@v3
+      - name: Install base dependencies
+        run: |
+          sudo apt update
+          sudo apt -y install build-essential p7zip xz-utils wget libglib2.0-0
+          sudo apt -y install python3-gi libgirepository1.0-dev  # should pull dependencies for gi installation below
+      - name: Get a recent python
+        uses: actions/setup-python@v4
+        with:
+          python-version: '3.11'
+      - name: Install build-time dependencies
+        run: |
+          echo "PYTHON=python3.11" >> $GITHUB_ENV
+          wget -nv https://github.com/AppImage/AppImageKit/releases/download/$APPIMAGETOOL_VERSION/appimagetool-x86_64.AppImage
+          chmod a+rx appimagetool-x86_64.AppImage
+          ./appimagetool-x86_64.AppImage --appimage-extract
+          echo -e '#/bin/sh\n./squashfs-root/AppRun "$@"' > appimagetool
+          chmod a+rx appimagetool
+      - name: Download run-time dependencies
+        run: |
+          wget -nv https://github.com/Ijwu/Enemizer/releases/download/$ENEMIZER_VERSION/ubuntu.16.04-x64.7z
+          7za x -oEnemizerCLI/ ubuntu.16.04-x64.7z
+      - name: Build
+        run: |
+          # pygobject is an optional dependency for kivy that's not in requirements
+          # charset-normalizer was somehow incomplete in the github runner
+          "${{ env.PYTHON }}" -m venv venv
+          source venv/bin/activate
+          "${{ env.PYTHON }}" -m pip install --upgrade pip PyGObject charset-normalizer
+          python setup.py build_exe --yes bdist_appimage --yes
+          echo -e "setup.py build output:\n `ls build`"
+          echo -e "setup.py dist output:\n `ls dist`"
+          cd dist && export APPIMAGE_NAME="`ls *.AppImage`" && cd ..
+          export TAR_NAME="${APPIMAGE_NAME%.AppImage}.tar.gz"
+          (cd build && DIR_NAME="`ls | grep exe`" && mv "$DIR_NAME" Archipelago && tar -czvf ../dist/$TAR_NAME Archipelago && mv Archipelago "$DIR_NAME")
+          echo "APPIMAGE_NAME=$APPIMAGE_NAME" >> $GITHUB_ENV
+          echo "TAR_NAME=$TAR_NAME" >> $GITHUB_ENV
+      # - code above copied from build.yml -
+      - name: Add to Release
+        uses: softprops/action-gh-release@b7e450da2a4b4cb4bfbae528f788167786cfcedf
+        with:
+          draft: true  # see above
+          prerelease: false
+          name: Archipelago ${{ env.RELEASE_VERSION }}
+          files: |
+            dist/*
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

.github/workflows/unittests.yml

@@ -3,24 +3,60 @@
 
 name: unittests
 
-on: [push, pull_request]
+on:
+  push:
+    paths:
+      - '**'
+      - '!docs/**'
+      - '!setup.py'
+      - '!*.iss'
+      - '!.gitignore'
+      - '!.github/workflows/**'
+      - '.github/workflows/unittests.yml'
+  pull_request:
+    paths:
+      - '**'
+      - '!docs/**'
+      - '!setup.py'
+      - '!*.iss'
+      - '!.gitignore'
+      - '!.github/workflows/**'
+      - '.github/workflows/unittests.yml'
 
 jobs:
   build:
+    runs-on: ${{ matrix.os }}
+    name: Test Python ${{ matrix.python.version }} ${{ matrix.os }}
 
-    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest]
+        python:
+          - {version: '3.8'}
+          - {version: '3.9'}
+          - {version: '3.10'}
+          - {version: '3.11'}
+        include:
+          - python: {version: '3.8'}  # win7 compat
+            os: windows-latest
+          - python: {version: '3.11'}  # current
+            os: windows-latest
+          - python: {version: '3.11'}  # current
+            os: macos-latest
 
     steps:
-    - uses: actions/checkout@v2
-    - name: Set up Python 3.9
-      uses: actions/setup-python@v1
+    - uses: actions/checkout@v3
+    - name: Set up Python ${{ matrix.python.version }}
+      uses: actions/setup-python@v4
       with:
-        python-version: 3.9
+        python-version: ${{ matrix.python.version }}
     - name: Install dependencies
       run: |
         python -m pip install --upgrade pip
-        pip install flake8 pytest
-        python ModuleUpdate.py --yes --force
+        pip install pytest pytest-subtests
+        python ModuleUpdate.py --yes --force --append "WebHostLib/requirements.txt"
+        python Launcher.py --update_settings  # make sure host.yaml exists for tests
     - name: Unittests
       run: |
-        pytest test
+        pytest

.gitignore

@@ -4,14 +4,21 @@
 *_Spoiler.txt
 *.bmbp
 *.apbp
+*.apl2ac
 *.apm3
 *.apmc
 *.apz5
+*.aptloz
 *.pyc
 *.pyd
 *.sfc
 *.z64
 *.n64
+*.nes
+*.sms
+*.gb
+*.gbc
+*.gba
 *.wixobj
 *.lck
 *.db3
@@ -19,21 +26,20 @@
 *multisave
 *.archipelago
 *.apsave
+*.BIN
 
+setups
 build
 bundle/components.wxs
 dist
 README.html
 .vs/
 EnemizerCLI/
-RaceRom.py
-weights/
-/MultiMystery/
 /Players/
-/QUsb2Snes/
+/SNI/
+/host.yaml
 /options.yaml
 /config.yaml
-/uploads/
 /logs/
 _persistent_storage.yaml
 mystery_result_*.yaml
@@ -44,6 +50,12 @@ Output Logs/
 /factorio/
 /Minecraft Forge Server/
 /WebHostLib/static/generated
+/freeze_requirements.txt
+/Archipelago.zip
+/setup.ini
+/installdelete.iss
+/data/user.kv
+/datapackage
 
 # Byte-compiled / optimized / DLL files
 __pycache__/
@@ -77,6 +89,7 @@ MANIFEST
 # Installer logs
 pip-log.txt
 pip-delete-this-directory.txt
+installer.log
 
 # Unit test / coverage reports
 htmlcov/
@@ -115,17 +128,22 @@ target/
 profile_default/
 ipython_config.py
 
+# vim editor
+*.swp
+
 # SageMath parsed files
 *.sage.py
 
 # Environments
 .env
-.venv
+.venv*
 env/
 venv/
 ENV/
 env.bak/
 venv.bak/
+.code-workspace
+shell.nix
 
 # Spyder project settings
 .spyderproject
@@ -151,8 +169,25 @@ dmypy.json
 # Cython debug symbols
 cython_debug/
 
-Archipelago.zip
+# Cython intermediates
+_speedups.cpp
+_speedups.html
 
-#minecraft server stuff
+# minecraft server stuff
 jdk*/
-minecraft*/
+minecraft*/
+minecraft_versions.json
+!worlds/minecraft/
+
+# pyenv
+.python-version
+
+#undertale stuff
+/Undertale/
+
+# OS General Files
+.DS_Store
+.AppleDouble
+.LSOverride
+Thumbs.db
+[Dd]esktop.ini

AdventureClient.py

@@ -0,0 +1,516 @@
+import asyncio
+import hashlib
+import json
+import time
+import os
+import bsdiff4
+import subprocess
+import zipfile
+from asyncio import StreamReader, StreamWriter, CancelledError
+from typing import List
+
+
+import Utils
+from NetUtils import ClientStatus
+from Utils import async_start
+from CommonClient import CommonContext, server_loop, gui_enabled, ClientCommandProcessor, logger, \
+    get_base_parser
+from worlds.adventure import AdventureDeltaPatch
+
+from worlds.adventure.Locations import base_location_id
+from worlds.adventure.Rom import AdventureForeignItemInfo, AdventureAutoCollectLocation, BatNoTouchLocation
+from worlds.adventure.Items import base_adventure_item_id, standard_item_max, item_table
+from worlds.adventure.Offsets import static_item_element_size, connector_port_offset
+
+SYSTEM_MESSAGE_ID = 0
+
+CONNECTION_TIMING_OUT_STATUS = \
+    "Connection timing out. Please restart your emulator, then restart connector_adventure.lua"
+CONNECTION_REFUSED_STATUS = \
+    "Connection Refused. Please start your emulator and make sure connector_adventure.lua is running"
+CONNECTION_RESET_STATUS = \
+    "Connection was reset. Please restart your emulator, then restart connector_adventure.lua"
+CONNECTION_TENTATIVE_STATUS = "Initial Connection Made"
+CONNECTION_CONNECTED_STATUS = "Connected"
+CONNECTION_INITIAL_STATUS = "Connection has not been initiated"
+
+SCRIPT_VERSION = 1
+
+
+class AdventureCommandProcessor(ClientCommandProcessor):
+    def __init__(self, ctx: CommonContext):
+        super().__init__(ctx)
+
+    def _cmd_2600(self):
+        """Check 2600 Connection State"""
+        if isinstance(self.ctx, AdventureContext):
+            logger.info(f"2600 Status: {self.ctx.atari_status}")
+
+    def _cmd_aconnect(self):
+        """Discard current atari 2600 connection state"""
+        if isinstance(self.ctx, AdventureContext):
+            self.ctx.atari_sync_task.cancel()
+
+
+class AdventureContext(CommonContext):
+    command_processor = AdventureCommandProcessor
+    game = 'Adventure'
+    lua_connector_port: int = 17242
+
+    def __init__(self, server_address, password):
+        super().__init__(server_address, password)
+        self.freeincarnates_used: int = -1
+        self.freeincarnate_pending: int = 0
+        self.foreign_items: [AdventureForeignItemInfo] = []
+        self.autocollect_items: [AdventureAutoCollectLocation] = []
+        self.atari_streams: (StreamReader, StreamWriter) = None
+        self.atari_sync_task = None
+        self.messages = {}
+        self.locations_array = None
+        self.atari_status = CONNECTION_INITIAL_STATUS
+        self.awaiting_rom = False
+        self.display_msgs = True
+        self.deathlink_pending = False
+        self.set_deathlink = False
+        self.client_compatibility_mode = 0
+        self.items_handling = 0b111
+        self.checked_locations_sent: bool = False
+        self.port_offset = 0
+        self.bat_no_touch_locations: [BatNoTouchLocation] = []
+        self.local_item_locations = {}
+        self.dragon_speed_info = {}
+
+        options = Utils.get_options()
+        self.display_msgs = options["adventure_options"]["display_msgs"]
+
+    async def server_auth(self, password_requested: bool = False):
+        if password_requested and not self.password:
+            await super(AdventureContext, self).server_auth(password_requested)
+        if not self.auth:
+            self.auth = self.player_name
+        if not self.auth:
+            self.awaiting_rom = True
+            logger.info('Awaiting connection to adventure_connector to get Player information')
+            return
+
+        await self.send_connect()
+
+    def _set_message(self, msg: str, msg_id: int):
+        if self.display_msgs:
+            self.messages[(time.time(), msg_id)] = msg
+
+    def on_package(self, cmd: str, args: dict):
+        if cmd == 'Connected':
+            self.locations_array = None
+            if Utils.get_options()["adventure_options"].get("death_link", False):
+                self.set_deathlink = True
+            async_start(self.get_freeincarnates_used())
+        elif cmd == "RoomInfo":
+            self.seed_name = args['seed_name']
+        elif cmd == 'Print':
+            msg = args['text']
+            if ': !' not in msg:
+                self._set_message(msg, SYSTEM_MESSAGE_ID)
+        elif cmd == "ReceivedItems":
+            msg = f"Received {', '.join([self.item_names[item.item] for item in args['items']])}"
+            self._set_message(msg, SYSTEM_MESSAGE_ID)
+        elif cmd == "Retrieved":
+            self.freeincarnates_used = args["keys"][f"adventure_{self.auth}_freeincarnates_used"]
+            if self.freeincarnates_used is None:
+                self.freeincarnates_used = 0
+            self.freeincarnates_used += self.freeincarnate_pending
+            self.send_pending_freeincarnates()
+        elif cmd == "SetReply":
+            if args["key"] == f"adventure_{self.auth}_freeincarnates_used":
+                self.freeincarnates_used = args["value"]
+                if self.freeincarnates_used is None:
+                    self.freeincarnates_used = 0
+                self.freeincarnates_used += self.freeincarnate_pending
+                self.send_pending_freeincarnates()
+
+    def on_deathlink(self, data: dict):
+        self.deathlink_pending = True
+        super().on_deathlink(data)
+
+    def run_gui(self):
+        from kvui import GameManager
+
+        class AdventureManager(GameManager):
+            logging_pairs = [
+                ("Client", "Archipelago")
+            ]
+            base_title = "Archipelago Adventure Client"
+
+        self.ui = AdventureManager(self)
+        self.ui_task = asyncio.create_task(self.ui.async_run(), name="UI")
+
+    async def get_freeincarnates_used(self):
+        if self.server and not self.server.socket.closed:
+            await self.send_msgs([{"cmd": "SetNotify", "keys": [f"adventure_{self.auth}_freeincarnates_used"]}])
+            await self.send_msgs([{"cmd": "Get", "keys": [f"adventure_{self.auth}_freeincarnates_used"]}])
+
+    def send_pending_freeincarnates(self):
+        if self.freeincarnate_pending > 0:
+            async_start(self.send_pending_freeincarnates_impl(self.freeincarnate_pending))
+            self.freeincarnate_pending = 0
+
+    async def send_pending_freeincarnates_impl(self, send_val: int) -> None:
+        await self.send_msgs([{"cmd": "Set", "key": f"adventure_{self.auth}_freeincarnates_used",
+                               "default": 0, "want_reply": False,
+                               "operations": [{"operation": "add", "value": send_val}]}])
+
+    async def used_freeincarnate(self) -> None:
+        if self.server and not self.server.socket.closed:
+            await self.send_msgs([{"cmd": "Set", "key": f"adventure_{self.auth}_freeincarnates_used",
+                                   "default": 0, "want_reply": True,
+                                   "operations": [{"operation": "add", "value": 1}]}])
+        else:
+            self.freeincarnate_pending = self.freeincarnate_pending + 1
+
+
+def convert_item_id(ap_item_id: int):
+    static_item_index = ap_item_id - base_adventure_item_id
+    return static_item_index * static_item_element_size
+
+
+def get_payload(ctx: AdventureContext):
+    current_time = time.time()
+    items = []
+    dragon_speed_update = {}
+    diff_a_locked = ctx.diff_a_mode > 0
+    diff_b_locked = ctx.diff_b_mode > 0
+    freeincarnate_count = 0
+    for item in ctx.items_received:
+        item_id_str = str(item.item)
+        if base_adventure_item_id < item.item <= standard_item_max:
+            items.append(convert_item_id(item.item))
+        elif item_id_str in ctx.dragon_speed_info:
+            if item.item in dragon_speed_update:
+                last_index = len(ctx.dragon_speed_info[item_id_str]) - 1
+                dragon_speed_update[item.item] = ctx.dragon_speed_info[item_id_str][last_index]
+            else:
+                dragon_speed_update[item.item] = ctx.dragon_speed_info[item_id_str][0]
+        elif item.item == item_table["Left Difficulty Switch"].id:
+            diff_a_locked = False
+        elif item.item == item_table["Right Difficulty Switch"].id:
+            diff_b_locked = False
+        elif item.item == item_table["Freeincarnate"].id:
+            freeincarnate_count = freeincarnate_count + 1
+    freeincarnates_available = 0
+
+    if ctx.freeincarnates_used >= 0:
+        freeincarnates_available = freeincarnate_count - (ctx.freeincarnates_used + ctx.freeincarnate_pending)
+    ret = json.dumps(
+        {
+            "items": items,
+            "messages": {f'{key[0]}:{key[1]}': value for key, value in ctx.messages.items()
+                         if key[0] > current_time - 10},
+            "deathlink": ctx.deathlink_pending,
+            "dragon_speeds": dragon_speed_update,
+            "difficulty_a_locked": diff_a_locked,
+            "difficulty_b_locked": diff_b_locked,
+            "freeincarnates_available": freeincarnates_available,
+            "bat_logic": ctx.bat_logic
+        }
+    )
+    ctx.deathlink_pending = False
+    return ret
+
+
+async def parse_locations(data: List, ctx: AdventureContext):
+    locations = data
+
+    # for loc_name, loc_data in location_table.items():
+
+    # if flags["EventFlag"][280] & 1 and not ctx.finished_game:
+    #    await ctx.send_msgs([
+    #                {"cmd": "StatusUpdate",
+    #                 "status": 30}
+    #            ])
+    #    ctx.finished_game = True
+    if locations == ctx.locations_array:
+        return
+    ctx.locations_array = locations
+    if locations is not None:
+        await ctx.send_msgs([{"cmd": "LocationChecks", "locations": locations}])
+
+
+def send_ap_foreign_items(adventure_context):
+    foreign_item_json_list = []
+    autocollect_item_json_list = []
+    bat_no_touch_locations_json_list = []
+    for fi in adventure_context.foreign_items:
+        foreign_item_json_list.append(fi.get_dict())
+    for fi in adventure_context.autocollect_items:
+        autocollect_item_json_list.append(fi.get_dict())
+    for ntl in adventure_context.bat_no_touch_locations:
+        bat_no_touch_locations_json_list.append(ntl.get_dict())
+    payload = json.dumps(
+        {
+            "foreign_items": foreign_item_json_list,
+            "autocollect_items": autocollect_item_json_list,
+            "local_item_locations": adventure_context.local_item_locations,
+            "bat_no_touch_locations": bat_no_touch_locations_json_list
+        }
+    )
+    print("sending foreign items")
+    msg = payload.encode()
+    (reader, writer) = adventure_context.atari_streams
+    writer.write(msg)
+    writer.write(b'\n')
+
+
+def send_checked_locations_if_needed(adventure_context):
+    if not adventure_context.checked_locations_sent and adventure_context.checked_locations is not None:
+        if len(adventure_context.checked_locations) == 0:
+            return
+        checked_short_ids = []
+        for location in adventure_context.checked_locations:
+            checked_short_ids.append(location - base_location_id)
+        print("Sending checked locations")
+        payload = json.dumps(
+            {
+                "checked_locations": checked_short_ids,
+            }
+        )
+        msg = payload.encode()
+        (reader, writer) = adventure_context.atari_streams
+        writer.write(msg)
+        writer.write(b'\n')
+        adventure_context.checked_locations_sent = True
+
+
+async def atari_sync_task(ctx: AdventureContext):
+    logger.info("Starting Atari 2600 connector. Use /2600 for status information")
+    while not ctx.exit_event.is_set():
+        try:
+            error_status = None
+            if ctx.atari_streams:
+                (reader, writer) = ctx.atari_streams
+                msg = get_payload(ctx).encode()
+                writer.write(msg)
+                writer.write(b'\n')
+                try:
+                    await asyncio.wait_for(writer.drain(), timeout=1.5)
+                    try:
+                        # Data will return a dict with 1+ fields
+                        # 1. A keepalive response of the Players Name (always)
+                        # 2. romhash field with sha256 hash of the ROM memory region
+                        # 3. locations, messages, and deathLink
+                        # 4. freeincarnate, to indicate a freeincarnate was used
+                        data = await asyncio.wait_for(reader.readline(), timeout=5)
+                        data_decoded = json.loads(data.decode())
+                        if 'scriptVersion' not in data_decoded or data_decoded['scriptVersion'] != SCRIPT_VERSION:
+                            msg = "You are connecting with an incompatible Lua script version. Ensure your connector " \
+                                  "Lua and AdventureClient are from the same Archipelago installation."
+                            logger.info(msg, extra={'compact_gui': True})
+                            ctx.gui_error('Error', msg)
+                            error_status = CONNECTION_RESET_STATUS
+                        if ctx.seed_name and bytes(ctx.seed_name, encoding='ASCII') != ctx.seed_name_from_data:
+                            msg = "The server is running a different multiworld than your client is. " \
+                                  "(invalid seed_name)"
+                            logger.info(msg, extra={'compact_gui': True})
+                            ctx.gui_error('Error', msg)
+                            error_status = CONNECTION_RESET_STATUS
+                        if 'romhash' in data_decoded:
+                            if ctx.rom_hash.upper() != data_decoded['romhash'].upper():
+                                msg = "The rom hash does not match the client rom hash data"
+                                print("got " + data_decoded['romhash'])
+                                print("expected " + str(ctx.rom_hash))
+                                logger.info(msg, extra={'compact_gui': True})
+                                ctx.gui_error('Error', msg)
+                                error_status = CONNECTION_RESET_STATUS
+                                if ctx.auth is None:
+                                    ctx.auth = ctx.player_name
+                            if ctx.awaiting_rom:
+                                await ctx.server_auth(False)
+                        if 'locations' in data_decoded and ctx.game and ctx.atari_status == CONNECTION_CONNECTED_STATUS \
+                                and not error_status and ctx.auth:
+                            # Not just a keep alive ping, parse
+                            async_start(parse_locations(data_decoded['locations'], ctx))
+                        if 'deathLink' in data_decoded and data_decoded['deathLink'] > 0 and 'DeathLink' in ctx.tags:
+                            dragon_name = "a dragon"
+                            if data_decoded['deathLink'] == 1:
+                                dragon_name = "Rhindle"
+                            elif data_decoded['deathLink'] == 2:
+                                dragon_name = "Yorgle"
+                            elif data_decoded['deathLink'] == 3:
+                                dragon_name = "Grundle"
+                            print (ctx.auth + " has been eaten by " + dragon_name )
+                            await ctx.send_death(ctx.auth + " has been eaten by " + dragon_name)
+                            # TODO - also if player reincarnates with a dragon onscreen ' dies to avoid being eaten by '
+                        if 'victory' in data_decoded and not ctx.finished_game:
+                            await ctx.send_msgs([{"cmd": "StatusUpdate", "status": ClientStatus.CLIENT_GOAL}])
+                            ctx.finished_game = True
+                        if 'freeincarnate' in data_decoded:
+                            await ctx.used_freeincarnate()
+                        if ctx.set_deathlink:
+                            await ctx.update_death_link(True)
+                        send_checked_locations_if_needed(ctx)
+                    except asyncio.TimeoutError:
+                        logger.debug("Read Timed Out, Reconnecting")
+                        error_status = CONNECTION_TIMING_OUT_STATUS
+                        writer.close()
+                        ctx.atari_streams = None
+                    except ConnectionResetError as e:
+                        logger.debug("Read failed due to Connection Lost, Reconnecting")
+                        error_status = CONNECTION_RESET_STATUS
+                        writer.close()
+                        ctx.atari_streams = None
+                except TimeoutError:
+                    logger.debug("Connection Timed Out, Reconnecting")
+                    error_status = CONNECTION_TIMING_OUT_STATUS
+                    writer.close()
+                    ctx.atari_streams = None
+                except ConnectionResetError:
+                    logger.debug("Connection Lost, Reconnecting")
+                    error_status = CONNECTION_RESET_STATUS
+                    writer.close()
+                    ctx.atari_streams = None
+                except CancelledError:
+                    logger.debug("Connection Cancelled, Reconnecting")
+                    error_status = CONNECTION_RESET_STATUS
+                    writer.close()
+                    ctx.atari_streams = None
+                    pass
+                except Exception as e:
+                    print("unknown exception " + e)
+                    raise
+                if ctx.atari_status == CONNECTION_TENTATIVE_STATUS:
+                    if not error_status:
+                        logger.info("Successfully Connected to 2600")
+                        ctx.atari_status = CONNECTION_CONNECTED_STATUS
+                        ctx.checked_locations_sent = False
+                        send_ap_foreign_items(ctx)
+                        send_checked_locations_if_needed(ctx)
+                    else:
+                        ctx.atari_status = f"Was tentatively connected but error occurred: {error_status}"
+                elif error_status:
+                    ctx.atari_status = error_status
+                    logger.info("Lost connection to 2600 and attempting to reconnect. Use /2600 for status updates")
+            else:
+                try:
+                    port = ctx.lua_connector_port + ctx.port_offset
+                    logger.debug(f"Attempting to connect to 2600 on port {port}")
+                    print(f"Attempting to connect to 2600 on port {port}")
+                    ctx.atari_streams = await asyncio.wait_for(
+                        asyncio.open_connection("localhost",
+                                                port),
+                        timeout=10)
+                    ctx.atari_status = CONNECTION_TENTATIVE_STATUS
+                except TimeoutError:
+                    logger.debug("Connection Timed Out, Trying Again")
+                    ctx.atari_status = CONNECTION_TIMING_OUT_STATUS
+                    continue
+                except ConnectionRefusedError:
+                    logger.debug("Connection Refused, Trying Again")
+                    ctx.atari_status = CONNECTION_REFUSED_STATUS
+                    continue
+                except CancelledError:
+                    pass
+        except CancelledError:
+            pass
+    print("exiting atari sync task")
+
+
+async def run_game(romfile):
+    auto_start = Utils.get_options()["adventure_options"].get("rom_start", True)
+    rom_args = Utils.get_options()["adventure_options"].get("rom_args")
+    if auto_start is True:
+        import webbrowser
+        webbrowser.open(romfile)
+    elif os.path.isfile(auto_start):
+        open_args = [auto_start, romfile]
+        if rom_args is not None:
+            open_args.insert(1, rom_args)
+        subprocess.Popen(open_args,
+                         stdin=subprocess.DEVNULL, stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL)
+
+
+async def patch_and_run_game(patch_file, ctx):
+    base_name = os.path.splitext(patch_file)[0]
+    comp_path = base_name + '.a26'
+    try:
+        base_rom = AdventureDeltaPatch.get_source_data()
+    except Exception as msg:
+        logger.info(msg, extra={'compact_gui': True})
+        ctx.gui_error('Error', msg)
+
+    with open(Utils.local_path("data", "adventure_basepatch.bsdiff4"), "rb") as file:
+        basepatch = bytes(file.read())
+
+    base_patched_rom_data = bsdiff4.patch(base_rom, basepatch)
+
+    with zipfile.ZipFile(patch_file, 'r') as patch_archive:
+        if not AdventureDeltaPatch.check_version(patch_archive):
+            logger.error("apadvn version doesn't match this client.  Make sure your generator and client are the same")
+            raise Exception("apadvn version doesn't match this client.")
+
+        ctx.foreign_items = AdventureDeltaPatch.read_foreign_items(patch_archive)
+        ctx.autocollect_items = AdventureDeltaPatch.read_autocollect_items(patch_archive)
+        ctx.local_item_locations = AdventureDeltaPatch.read_local_item_locations(patch_archive)
+        ctx.dragon_speed_info = AdventureDeltaPatch.read_dragon_speed_info(patch_archive)
+        ctx.seed_name_from_data, ctx.player_name = AdventureDeltaPatch.read_rom_info(patch_archive)
+        ctx.diff_a_mode, ctx.diff_b_mode = AdventureDeltaPatch.read_difficulty_switch_info(patch_archive)
+        ctx.bat_logic = AdventureDeltaPatch.read_bat_logic(patch_archive)
+        ctx.bat_no_touch_locations = AdventureDeltaPatch.read_bat_no_touch(patch_archive)
+        ctx.rom_deltas = AdventureDeltaPatch.read_rom_deltas(patch_archive)
+        ctx.auth = ctx.player_name
+
+    patched_rom_data = AdventureDeltaPatch.apply_rom_deltas(base_patched_rom_data, ctx.rom_deltas)
+    rom_hash = hashlib.sha256()
+    rom_hash.update(patched_rom_data)
+    ctx.rom_hash = rom_hash.hexdigest()
+    ctx.port_offset = patched_rom_data[connector_port_offset]
+
+    with open(comp_path, "wb") as patched_rom_file:
+        patched_rom_file.write(patched_rom_data)
+
+    async_start(run_game(comp_path))
+
+
+if __name__ == '__main__':
+
+    Utils.init_logging("AdventureClient")
+
+    async def main():
+        parser = get_base_parser()
+        parser.add_argument('patch_file', default="", type=str, nargs="?",
+                            help='Path to an ADVNTURE.BIN rom file')
+        parser.add_argument('port', default=17242, type=int, nargs="?",
+                            help='port for adventure_connector connection')
+        args = parser.parse_args()
+
+        ctx = AdventureContext(args.connect, args.password)
+        ctx.server_task = asyncio.create_task(server_loop(ctx), name="ServerLoop")
+        if gui_enabled:
+            ctx.run_gui()
+        ctx.run_cli()
+        ctx.atari_sync_task = asyncio.create_task(atari_sync_task(ctx), name="Adventure Sync")
+
+        if args.patch_file:
+            ext = args.patch_file.split(".")[len(args.patch_file.split(".")) - 1].lower()
+            if ext == "apadvn":
+                logger.info("apadvn file supplied, beginning patching process...")
+                async_start(patch_and_run_game(args.patch_file, ctx))
+            else:
+                logger.warning(f"Unknown patch file extension {ext}")
+        if args.port is int:
+            ctx.lua_connector_port = args.port
+
+        await ctx.exit_event.wait()
+        ctx.server_address = None
+
+        await ctx.shutdown()
+
+        if ctx.atari_sync_task:
+            await ctx.atari_sync_task
+            print("finished atari_sync_task (main)")
+
+
+    import colorama
+
+    colorama.init()
+
+    asyncio.run(main())
+    colorama.deinit()

ChecksFinderClient.py

@@ -0,0 +1,172 @@
+from __future__ import annotations
+import os
+import sys
+import asyncio
+import shutil
+
+import ModuleUpdate
+ModuleUpdate.update()
+
+import Utils
+
+if __name__ == "__main__":
+    Utils.init_logging("ChecksFinderClient", exception_logger="Client")
+
+from NetUtils import NetworkItem, ClientStatus
+from CommonClient import gui_enabled, logger, get_base_parser, ClientCommandProcessor, \
+    CommonContext, server_loop
+
+
+class ChecksFinderClientCommandProcessor(ClientCommandProcessor):
+    def _cmd_resync(self):
+        """Manually trigger a resync."""
+        self.output(f"Syncing items.")
+        self.ctx.syncing = True
+
+
+class ChecksFinderContext(CommonContext):
+    command_processor: int = ChecksFinderClientCommandProcessor
+    game = "ChecksFinder"
+    items_handling = 0b111  # full remote
+
+    def __init__(self, server_address, password):
+        super(ChecksFinderContext, self).__init__(server_address, password)
+        self.send_index: int = 0
+        self.syncing = False
+        self.awaiting_bridge = False
+        # self.game_communication_path: files go in this path to pass data between us and the actual game
+        if "localappdata" in os.environ:
+            self.game_communication_path = os.path.expandvars(r"%localappdata%/ChecksFinder")
+        else:
+            # not windows. game is an exe so let's see if wine might be around to run it
+            if "WINEPREFIX" in os.environ:
+                wineprefix = os.environ["WINEPREFIX"]
+            elif shutil.which("wine") or shutil.which("wine-stable"):
+                wineprefix = os.path.expanduser("~/.wine") # default root of wine system data, deep in which is app data
+            else:
+                msg = "ChecksFinderClient couldn't detect system type. Unable to infer required game_communication_path"
+                logger.error("Error: " + msg)
+                Utils.messagebox("Error", msg, error=True)
+                sys.exit(1)
+            self.game_communication_path = os.path.join(
+                wineprefix,
+                "drive_c",
+                os.path.expandvars("users/$USER/Local Settings/Application Data/ChecksFinder"))
+
+    async def server_auth(self, password_requested: bool = False):
+        if password_requested and not self.password:
+            await super(ChecksFinderContext, self).server_auth(password_requested)
+        await self.get_username()
+        await self.send_connect()
+
+    async def connection_closed(self):
+        await super(ChecksFinderContext, self).connection_closed()
+        for root, dirs, files in os.walk(self.game_communication_path):
+            for file in files:
+                if file.find("obtain") <= -1:
+                    os.remove(root + "/" + file)
+
+    @property
+    def endpoints(self):
+        if self.server:
+            return [self.server]
+        else:
+            return []
+
+    async def shutdown(self):
+        await super(ChecksFinderContext, self).shutdown()
+        for root, dirs, files in os.walk(self.game_communication_path):
+            for file in files:
+                if file.find("obtain") <= -1:
+                    os.remove(root+"/"+file)
+
+    def on_package(self, cmd: str, args: dict):
+        if cmd in {"Connected"}:
+            if not os.path.exists(self.game_communication_path):
+                os.makedirs(self.game_communication_path)
+            for ss in self.checked_locations:
+                filename = f"send{ss}"
+                with open(os.path.join(self.game_communication_path, filename), 'w') as f:
+                    f.close()
+        if cmd in {"ReceivedItems"}:
+            start_index = args["index"]
+            if start_index != len(self.items_received):
+                for item in args['items']:
+                    filename = f"AP_{str(NetworkItem(*item).location)}PLR{str(NetworkItem(*item).player)}.item"
+                    with open(os.path.join(self.game_communication_path, filename), 'w') as f:
+                        f.write(str(NetworkItem(*item).item))
+                        f.close()
+
+        if cmd in {"RoomUpdate"}:
+            if "checked_locations" in args:
+                for ss in self.checked_locations:
+                    filename = f"send{ss}"
+                    with open(os.path.join(self.game_communication_path, filename), 'w') as f:
+                        f.close()
+
+    def run_gui(self):
+        """Import kivy UI system and start running it as self.ui_task."""
+        from kvui import GameManager
+
+        class ChecksFinderManager(GameManager):
+            logging_pairs = [
+                ("Client", "Archipelago")
+            ]
+            base_title = "Archipelago ChecksFinder Client"
+
+        self.ui = ChecksFinderManager(self)
+        self.ui_task = asyncio.create_task(self.ui.async_run(), name="UI")
+
+
+async def game_watcher(ctx: ChecksFinderContext):
+    from worlds.checksfinder.Locations import lookup_id_to_name
+    while not ctx.exit_event.is_set():
+        if ctx.syncing == True:
+            sync_msg = [{'cmd': 'Sync'}]
+            if ctx.locations_checked:
+                sync_msg.append({"cmd": "LocationChecks", "locations": list(ctx.locations_checked)})
+            await ctx.send_msgs(sync_msg)
+            ctx.syncing = False
+        sending = []
+        victory = False
+        for root, dirs, files in os.walk(ctx.game_communication_path):
+            for file in files:
+                if file.find("send") > -1:
+                    st = file.split("send", -1)[1]
+                    sending = sending+[(int(st))]
+                if file.find("victory") > -1:
+                    victory = True
+        ctx.locations_checked = sending
+        message = [{"cmd": 'LocationChecks', "locations": sending}]
+        await ctx.send_msgs(message)
+        if not ctx.finished_game and victory:
+            await ctx.send_msgs([{"cmd": "StatusUpdate", "status": ClientStatus.CLIENT_GOAL}])
+            ctx.finished_game = True
+        await asyncio.sleep(0.1)
+
+
+if __name__ == '__main__':
+    async def main(args):
+        ctx = ChecksFinderContext(args.connect, args.password)
+        ctx.server_task = asyncio.create_task(server_loop(ctx), name="server loop")
+        if gui_enabled:
+            ctx.run_gui()
+        ctx.run_cli()
+        progression_watcher = asyncio.create_task(
+            game_watcher(ctx), name="ChecksFinderProgressionWatcher")
+
+        await ctx.exit_event.wait()
+        ctx.server_address = None
+
+        await progression_watcher
+
+        await ctx.shutdown()
+
+    import colorama
+
+    parser = get_base_parser(description="ChecksFinder Client, for text interfacing.")
+
+    args, rest = parser.parse_known_args()
+    colorama.init()
+    asyncio.run(main(args))
+    colorama.deinit()

CommonClient.py

@@ -5,6 +5,10 @@ import urllib.parse
 import sys
 import typing
 import time
+import functools
+
+import ModuleUpdate
+ModuleUpdate.update()
 
 import websockets
 
@@ -14,16 +18,28 @@ if __name__ == "__main__":
     Utils.init_logging("TextClient", exception_logger="Client")
 
 from MultiServer import CommandProcessor
-from NetUtils import Endpoint, decode, NetworkItem, encode, JSONtoTextParser, ClientStatus, Permission
-from Utils import Version, stream_input
+from NetUtils import Endpoint, decode, NetworkItem, encode, JSONtoTextParser, \
+    ClientStatus, Permission, NetworkSlot, RawJSONtoTextParser
+from Utils import Version, stream_input, async_start
 from worlds import network_data_package, AutoWorldRegister
+import os
+import ssl
+
+if typing.TYPE_CHECKING:
+    import kvui
 
 logger = logging.getLogger("Client")
 
-# without terminal we have to use gui mode
+# without terminal, we have to use gui mode
 gui_enabled = not sys.stdout or "--nogui" not in sys.argv
 
 
+@Utils.cache_argsless
+def get_ssl_context():
+    import certifi
+    return ssl.create_default_context(ssl.Purpose.SERVER_AUTH, cafile=certifi.where())
+
+
 class ClientCommandProcessor(CommandProcessor):
     def __init__(self, ctx: CommonContext):
         self.ctx = ctx
@@ -38,31 +54,38 @@ class ClientCommandProcessor(CommandProcessor):
 
     def _cmd_connect(self, address: str = "") -> bool:
         """Connect to a MultiWorld Server"""
-        self.ctx.server_address = None
-        asyncio.create_task(self.ctx.connect(address if address else None), name="connecting")
+        if address:
+            self.ctx.server_address = None
+            self.ctx.username = None
+        elif not self.ctx.server_address:
+            self.output("Please specify an address.")
+            return False
+        async_start(self.ctx.connect(address if address else None), name="connecting")
         return True
 
     def _cmd_disconnect(self) -> bool:
         """Disconnect from a MultiWorld Server"""
-        self.ctx.server_address = None
-        asyncio.create_task(self.ctx.disconnect(), name="disconnecting")
+        async_start(self.ctx.disconnect(), name="disconnecting")
         return True
 
     def _cmd_received(self) -> bool:
         """List all received items"""
-        logger.info(f'{len(self.ctx.items_received)} received items:')
+        self.output(f'{len(self.ctx.items_received)} received items:')
         for index, item in enumerate(self.ctx.items_received, 1):
-            self.output(f"{self.ctx.item_name_getter(item.item)} from {self.ctx.player_names[item.player]}")
+            self.output(f"{self.ctx.item_names[item.item]} from {self.ctx.player_names[item.player]}")
         return True
 
-    def _cmd_missing(self) -> bool:
-        """List all missing location checks, from your local game state"""
+    def _cmd_missing(self, filter_text = "") -> bool:
+        """List all missing location checks, from your local game state.
+        Can be given text, which will be used as filter."""
         if not self.ctx.game:
             self.output("No game set, cannot determine missing checks.")
             return False
         count = 0
         checked_count = 0
         for location, location_id in AutoWorldRegister.world_types[self.ctx.game].location_name_to_id.items():
+            if filter_text and filter_text not in location:
+                continue
             if location_id < 0:
                 continue
             if location_id not in self.ctx.locations_checked:
@@ -83,12 +106,18 @@ class ClientCommandProcessor(CommandProcessor):
 
     def _cmd_items(self):
         """List all item names for the currently running game."""
+        if not self.ctx.game:
+            self.output("No game set, cannot determine existing items.")
+            return False
         self.output(f"Item Names for {self.ctx.game}")
         for item_name in AutoWorldRegister.world_types[self.ctx.game].item_name_to_id:
             self.output(item_name)
 
     def _cmd_locations(self):
         """List all location names for the currently running game."""
+        if not self.ctx.game:
+            self.output("No game set, cannot determine existing locations.")
+            return False
         self.output(f"Location Names for {self.ctx.game}")
         for location_name in AutoWorldRegister.world_types[self.ctx.game].location_name_to_id:
             self.output(location_name)
@@ -102,34 +131,85 @@ class ClientCommandProcessor(CommandProcessor):
         else:
             state = ClientStatus.CLIENT_CONNECTED
             self.output("Unreadied.")
-        asyncio.create_task(self.ctx.send_msgs([{"cmd": "StatusUpdate", "status": state}]), name="send StatusUpdate")
+        async_start(self.ctx.send_msgs([{"cmd": "StatusUpdate", "status": state}]), name="send StatusUpdate")
 
     def default(self, raw: str):
         raw = self.ctx.on_user_say(raw)
         if raw:
-            asyncio.create_task(self.ctx.send_msgs([{"cmd": "Say", "text": raw}]), name="send Say")
+            async_start(self.ctx.send_msgs([{"cmd": "Say", "text": raw}]), name="send Say")
 
 
-class CommonContext():
+class CommonContext:
+    # Should be adjusted as needed in subclasses
     tags: typing.Set[str] = {"AP"}
+    game: typing.Optional[str] = None
+    items_handling: typing.Optional[int] = None
+    want_slot_data: bool = True  # should slot_data be retrieved via Connect
+
+    # data package
+    # Contents in flux until connection to server is made, to download correct data for this multiworld.
+    item_names: typing.Dict[int, str] = Utils.KeyedDefaultDict(lambda code: f'Unknown item (ID:{code})')
+    location_names: typing.Dict[int, str] = Utils.KeyedDefaultDict(lambda code: f'Unknown location (ID:{code})')
+
+    # defaults
     starting_reconnect_delay: int = 5
     current_reconnect_delay: int = starting_reconnect_delay
-    command_processor: int = ClientCommandProcessor
-    game = None
+    command_processor: typing.Type[CommandProcessor] = ClientCommandProcessor
     ui = None
-    keep_alive_task = None
+    ui_task: typing.Optional["asyncio.Task[None]"] = None
+    input_task: typing.Optional["asyncio.Task[None]"] = None
+    keep_alive_task: typing.Optional["asyncio.Task[None]"] = None
+    server_task: typing.Optional["asyncio.Task[None]"] = None
+    autoreconnect_task: typing.Optional["asyncio.Task[None]"] = None
+    disconnected_intentionally: bool = False
+    server: typing.Optional[Endpoint] = None
+    server_version: Version = Version(0, 0, 0)
+    generator_version: Version = Version(0, 0, 0)
+    current_energy_link_value: typing.Optional[int] = None  # to display in UI, gets set by server
 
-    def __init__(self, server_address, password):
+    last_death_link: float = time.time()  # last send/received death link on AP layer
+
+    # remaining type info
+    slot_info: typing.Dict[int, NetworkSlot]
+    server_address: typing.Optional[str]
+    password: typing.Optional[str]
+    hint_cost: typing.Optional[int]
+    hint_points: typing.Optional[int]
+    player_names: typing.Dict[int, str]
+
+    finished_game: bool
+    ready: bool
+    auth: typing.Optional[str]
+    seed_name: typing.Optional[str]
+
+    # locations
+    locations_checked: typing.Set[int]  # local state
+    locations_scouted: typing.Set[int]
+    items_received: typing.List[NetworkItem]
+    missing_locations: typing.Set[int]  # server state
+    checked_locations: typing.Set[int]  # server state
+    server_locations: typing.Set[int]  # all locations the server knows of, missing_location | checked_locations
+    locations_info: typing.Dict[int, NetworkItem]
+
+    # data storage
+    stored_data: typing.Dict[str, typing.Any]
+    stored_data_notification_keys: typing.Set[str]
+
+    # internals
+    # current message box through kvui
+    _messagebox: typing.Optional["kvui.MessageBox"] = None
+    # message box reporting a loss of connection
+    _messagebox_connection_loss: typing.Optional["kvui.MessageBox"] = None
+
+    def __init__(self, server_address: typing.Optional[str], password: typing.Optional[str]) -> None:
         # server state
         self.server_address = server_address
+        self.username = None
         self.password = password
-        self.server_task = None
-        self.server: typing.Optional[Endpoint] = None
-        self.server_version = Version(0, 0, 0)
-        self.hint_cost: typing.Optional[int] = None
-        self.games: typing.Dict[int, str] = {}
+        self.hint_cost = None
+        self.slot_info = {}
         self.permissions = {
-            "forfeit": "disabled",
+            "release": "disabled",
             "collect": "disabled",
             "remaining": "disabled",
         }
@@ -142,30 +222,41 @@ class CommonContext():
         self.auth = None
         self.seed_name = None
 
-        self.locations_checked: typing.Set[int] = set()  # local state
-        self.locations_scouted: typing.Set[int] = set()
+        self.locations_checked = set()  # local state
+        self.locations_scouted = set()
         self.items_received = []
-        self.missing_locations: typing.Set[int] = set()
-        self.checked_locations: typing.Set[int] = set()  # server state
+        self.missing_locations = set()  # server state
+        self.checked_locations = set()  # server state
+        self.server_locations = set()  # all locations the server knows of, missing_location | checked_locations
         self.locations_info = {}
 
+        self.stored_data = {}
+        self.stored_data_notification_keys = set()
+
         self.input_queue = asyncio.Queue()
         self.input_requests = 0
 
-        self.last_death_link: float = time.time()  # last send/received death link on AP layer
-
         # game state
-        self.player_names: typing.Dict[int: str] = {0: "Archipelago"}
+        self.player_names = {0: "Archipelago"}
         self.exit_event = asyncio.Event()
         self.watcher_event = asyncio.Event()
 
-        self.slow_mode = False
         self.jsontotextparser = JSONtoTextParser(self)
-        self.set_getters(network_data_package)
+        self.update_data_package(network_data_package)
 
         # execution
         self.keep_alive_task = asyncio.create_task(keep_alive(self), name="Bouncy")
 
+    @property
+    def suggested_address(self) -> str:
+        if self.server_address:
+            return self.server_address
+        return Utils.persistent_load().get("client", {}).get("last_server_address", "")
+
+    @functools.cached_property
+    def raw_text_parser(self) -> RawJSONtoTextParser:
+        return RawJSONtoTextParser(self)
+
     @property
     def total_locations(self) -> typing.Optional[int]:
         """Will return None until connected."""
@@ -173,58 +264,39 @@ class CommonContext():
             return len(self.checked_locations | self.missing_locations)
 
     async def connection_closed(self):
+        if self.server and self.server.socket is not None:
+            await self.server.socket.close()
+        self.reset_server_state()
+
+    def reset_server_state(self):
         self.auth = None
+        self.slot = None
+        self.team = None
         self.items_received = []
         self.locations_info = {}
         self.server_version = Version(0, 0, 0)
-        if self.server and self.server.socket is not None:
-            await self.server.socket.close()
+        self.generator_version = Version(0, 0, 0)
         self.server = None
         self.server_task = None
+        self.hint_cost = None
+        self.permissions = {
+            "release": "disabled",
+            "collect": "disabled",
+            "remaining": "disabled",
+        }
 
-    # noinspection PyAttributeOutsideInit
-    def set_getters(self, data_package: dict, network=False):
-        if not network:  # local data; check if newer data was already downloaded
-            local_package = Utils.persistent_load().get("datapackage", {}).get("latest", {})
-            if local_package and local_package["version"] > network_data_package["version"]:
-                data_package: dict = local_package
-        elif network:  # check if data from server is newer
-
-            if data_package["version"] > network_data_package["version"]:
-                Utils.persistent_store("datapackage", "latest", network_data_package)
-
-        item_lookup: dict = {}
-        locations_lookup: dict = {}
-        for game, gamedata in data_package["games"].items():
-            for item_name, item_id in gamedata["item_name_to_id"].items():
-                item_lookup[item_id] = item_name
-            for location_name, location_id in gamedata["location_name_to_id"].items():
-                locations_lookup[location_id] = location_name
-
-        def get_item_name_from_id(code: int):
-            return item_lookup.get(code, f'Unknown item (ID:{code})')
-
-        self.item_name_getter = get_item_name_from_id
-
-        def get_location_name_from_address(address: int):
-            return locations_lookup.get(address, f'Unknown location (ID:{address})')
-
-        self.location_name_getter = get_location_name_from_address
-
-    @property
-    def endpoints(self):
-        if self.server:
-            return [self.server]
-        else:
-            return []
-
-    async def disconnect(self):
+    async def disconnect(self, allow_autoreconnect: bool = False):
+        if not allow_autoreconnect:
+            self.disconnected_intentionally = True
+            if self.cancel_autoreconnect():
+                logger.info("Cancelled auto-reconnect.")
         if self.server and not self.server.socket.closed:
             await self.server.socket.close()
         if self.server_task is not None:
             await self.server_task
 
-    async def send_msgs(self, msgs):
+    async def send_msgs(self, msgs: typing.List[typing.Any]) -> None:
+        """ `msgs` JSON serializable """
         if not self.server or not self.server.socket.open or self.server.socket.closed:
             return
         await self.server.socket.send(encode(msgs))
@@ -245,25 +317,61 @@ class CommonContext():
             self.password = await self.console_input()
             return self.password
 
-    async def send_connect(self, **kwargs):
+    async def get_username(self):
+        if not self.auth:
+            self.auth = self.username
+            if not self.auth:
+                logger.info('Enter slot name:')
+                self.auth = await self.console_input()
+
+    async def send_connect(self, **kwargs: typing.Any) -> None:
+        """ send `Connect` packet to log in to server """
         payload = {
-            "cmd": 'Connect',
+            'cmd': 'Connect',
             'password': self.password, 'name': self.auth, 'version': Utils.version_tuple,
-            'tags': self.tags,
-            'uuid': Utils.get_unique_identifier(), 'game': self.game
+            'tags': self.tags, 'items_handling': self.items_handling,
+            'uuid': Utils.get_unique_identifier(), 'game': self.game, "slot_data": self.want_slot_data,
         }
         if kwargs:
             payload.update(kwargs)
         await self.send_msgs([payload])
 
-    async def console_input(self):
+    async def console_input(self) -> str:
+        if self.ui:
+            self.ui.focus_textinput()
         self.input_requests += 1
         return await self.input_queue.get()
 
-    async def connect(self, address=None):
+    async def connect(self, address: typing.Optional[str] = None) -> None:
+        """ disconnect any previous connection, and open new connection to the server """
         await self.disconnect()
         self.server_task = asyncio.create_task(server_loop(self, address), name="server loop")
 
+    def cancel_autoreconnect(self) -> bool:
+        if self.autoreconnect_task:
+            self.autoreconnect_task.cancel()
+            self.autoreconnect_task = None
+            return True
+        return False
+
+    def slot_concerns_self(self, slot) -> bool:
+        if slot == self.slot:
+            return True
+        if slot in self.slot_info:
+            return self.slot in self.slot_info[slot].group_members
+        return False
+
+    def is_echoed_chat(self, print_json_packet: dict) -> bool:
+        return print_json_packet.get("type", "") == "Chat" \
+            and print_json_packet.get("team", None) == self.team \
+            and print_json_packet.get("slot", None) == self.slot
+
+    def is_uninteresting_item_send(self, print_json_packet: dict) -> bool:
+        """Helper function for filtering out ItemSend prints that do not concern the local player."""
+        return print_json_packet.get("type", "") == "ItemSend" \
+            and not self.slot_concerns_self(print_json_packet["receiving"]) \
+            and not self.slot_concerns_self(print_json_packet["item"].player)
+
     def on_print(self, args: dict):
         logger.info(args["text"])
 
@@ -293,7 +401,9 @@ class CommonContext():
                 logger.exception(e)
 
     async def shutdown(self):
-        self.server_address = None
+        self.server_address = ""
+        self.username = None
+        self.cancel_autoreconnect()
         if self.server and not self.server.socket.closed:
             await self.server.socket.close()
         if self.server_task:
@@ -303,10 +413,85 @@ class CommonContext():
             self.input_queue.put_nowait(None)
             self.input_requests -= 1
         self.keep_alive_task.cancel()
+        if self.ui_task:
+            await self.ui_task
+        if self.input_task:
+            self.input_task.cancel()
+
+    # DataPackage
+    async def prepare_data_package(self, relevant_games: typing.Set[str],
+                                   remote_date_package_versions: typing.Dict[str, int],
+                                   remote_data_package_checksums: typing.Dict[str, str]):
+        """Validate that all data is present for the current multiworld.
+        Download, assimilate and cache missing data from the server."""
+        # by documentation any game can use Archipelago locations/items -> always relevant
+        relevant_games.add("Archipelago")
+
+        needed_updates: typing.Set[str] = set()
+        for game in relevant_games:
+            if game not in remote_date_package_versions and game not in remote_data_package_checksums:
+                continue
+
+            remote_version: int = remote_date_package_versions.get(game, 0)
+            remote_checksum: typing.Optional[str] = remote_data_package_checksums.get(game)
+
+            if remote_version == 0 and not remote_checksum:  # custom data package and no checksum for this game
+                needed_updates.add(game)
+                continue
+
+            local_version: int = network_data_package["games"].get(game, {}).get("version", 0)
+            local_checksum: typing.Optional[str] = network_data_package["games"].get(game, {}).get("checksum")
+            # no action required if local version is new enough
+            if (not remote_checksum and (remote_version > local_version or remote_version == 0)) \
+                    or remote_checksum != local_checksum:
+                cached_game = Utils.load_data_package_for_checksum(game, remote_checksum)
+                cache_version: int = cached_game.get("version", 0)
+                cache_checksum: typing.Optional[str] = cached_game.get("checksum")
+                # download remote version if cache is not new enough
+                if (not remote_checksum and (remote_version > cache_version or remote_version == 0)) \
+                        or remote_checksum != cache_checksum:
+                    needed_updates.add(game)
+                else:
+                    self.update_game(cached_game)
+        if needed_updates:
+            await self.send_msgs([{"cmd": "GetDataPackage", "games": list(needed_updates)}])
+
+    def update_game(self, game_package: dict):
+        for item_name, item_id in game_package["item_name_to_id"].items():
+            self.item_names[item_id] = item_name
+        for location_name, location_id in game_package["location_name_to_id"].items():
+            self.location_names[location_id] = location_name
+
+    def update_data_package(self, data_package: dict):
+        for game, game_data in data_package["games"].items():
+            self.update_game(game_data)
+
+    def consume_network_data_package(self, data_package: dict):
+        self.update_data_package(data_package)
+        current_cache = Utils.persistent_load().get("datapackage", {}).get("games", {})
+        current_cache.update(data_package["games"])
+        Utils.persistent_store("datapackage", "games", current_cache)
+        for game, game_data in data_package["games"].items():
+            Utils.store_data_package_for_checksum(game, game_data)
+
+    # data storage
+
+    def set_notify(self, *keys: str) -> None:
+        """Subscribe to be notified of changes to selected data storage keys.
+
+        The values can be accessed via the "stored_data" attribute of this context, which is a dictionary mapping the
+        names of the data storage keys to the latest values received from the server.
+        """
+        if new_keys := (set(keys) - self.stored_data_notification_keys):
+            self.stored_data_notification_keys.update(new_keys)
+            async_start(self.send_msgs([{"cmd": "Get",
+                                         "keys": list(new_keys)},
+                                        {"cmd": "SetNotify",
+                                         "keys": list(new_keys)}]))
 
     # DeathLink hooks
 
-    def on_deathlink(self, data: dict):
+    def on_deathlink(self, data: typing.Dict[str, typing.Any]) -> None:
         """Gets dispatched when a new DeathLink is triggered by another linked player."""
         self.last_death_link = max(data["time"], self.last_death_link)
         text = data.get("cause", "")
@@ -316,18 +501,19 @@ class CommonContext():
             logger.info(f"DeathLink: Received from {data['source']}")
 
     async def send_death(self, death_text: str = ""):
-        logger.info("DeathLink: Sending death to your friends...")
-        self.last_death_link = time.time()
-        await self.send_msgs([{
-            "cmd": "Bounce", "tags": ["DeathLink"],
-            "data": {
-                "time": self.last_death_link,
-                "source": self.player_names[self.slot],
-                "cause": death_text
-            }
-        }])
+        if self.server and self.server.socket:
+            logger.info("DeathLink: Sending death to your friends...")
+            self.last_death_link = time.time()
+            await self.send_msgs([{
+                "cmd": "Bounce", "tags": ["DeathLink"],
+                "data": {
+                    "time": self.last_death_link,
+                    "source": self.player_names[self.slot],
+                    "cause": death_text
+                }
+            }])
 
-    async def update_death_link(self, death_link):
+    async def update_death_link(self, death_link: bool):
         old_tags = self.tags.copy()
         if death_link:
             self.tags.add("DeathLink")
@@ -336,6 +522,55 @@ class CommonContext():
         if old_tags != self.tags and self.server and not self.server.socket.closed:
             await self.send_msgs([{"cmd": "ConnectUpdate", "tags": self.tags}])
 
+    def gui_error(self, title: str, text: typing.Union[Exception, str]) -> typing.Optional["kvui.MessageBox"]:
+        """Displays an error messagebox"""
+        if not self.ui:
+            return None
+        title = title or "Error"
+        from kvui import MessageBox
+        if self._messagebox:
+            self._messagebox.dismiss()
+        # make "Multiple exceptions" look nice
+        text = str(text).replace('[Errno', '\n[Errno').strip()
+        # split long messages into title and text
+        parts = title.split('. ', 1)
+        if len(parts) == 1:
+            parts = title.split(', ', 1)
+        if len(parts) > 1:
+            text = parts[1] + '\n\n' + text
+            title = parts[0]
+        # display error
+        self._messagebox = MessageBox(title, text, error=True)
+        self._messagebox.open()
+        return self._messagebox
+
+    def handle_connection_loss(self, msg: str) -> None:
+        """Helper for logging and displaying a loss of connection. Must be called from an except block."""
+        exc_info = sys.exc_info()
+        logger.exception(msg, exc_info=exc_info, extra={'compact_gui': True})
+        self._messagebox_connection_loss = self.gui_error(msg, exc_info[1])
+
+    def run_gui(self):
+        """Import kivy UI system and start running it as self.ui_task."""
+        from kvui import GameManager
+
+        class TextManager(GameManager):
+            logging_pairs = [
+                ("Client", "Archipelago")
+            ]
+            base_title = "Archipelago Text Client"
+
+        self.ui = TextManager(self)
+        self.ui_task = asyncio.create_task(self.ui.async_run(), name="UI")
+
+    def run_cli(self):
+        if sys.stdin:
+            # steam overlay breaks when starting console_loop
+            if 'gameoverlayrenderer' in os.environ.get('LD_PRELOAD', ''):
+                logger.info("Skipping terminal input, due to conflicting Steam Overlay detected. Please use GUI only.")
+            else:
+                self.input_task = asyncio.create_task(console_loop(self), name="Input")
+
 
 async def keep_alive(ctx: CommonContext, seconds_between_checks=100):
     """some ISPs/network configurations drop TCP connections if no payload is sent (ignore TCP-keep-alive)
@@ -350,8 +585,7 @@ async def keep_alive(ctx: CommonContext, seconds_between_checks=100):
                 seconds_elapsed = 0
 
 
-async def server_loop(ctx: CommonContext, address=None):
-    cached_address = None
+async def server_loop(ctx: CommonContext, address: typing.Optional[str] = None) -> None:
     if ctx.server and ctx.server.socket:
         logger.error('Already connected')
         return
@@ -364,37 +598,62 @@ async def server_loop(ctx: CommonContext, address=None):
         logger.info('Please connect to an Archipelago server.')
         return
 
-    address = f"ws://{address}" if "://" not in address else address
-    port = urllib.parse.urlparse(address).port or 38281
+    ctx.cancel_autoreconnect()
+    if ctx._messagebox_connection_loss:
+        ctx._messagebox_connection_loss.dismiss()
+        ctx._messagebox_connection_loss = None
+
+    address = f"ws://{address}" if "://" not in address \
+        else address.replace("archipelago://", "ws://")
+
+    server_url = urllib.parse.urlparse(address)
+    if server_url.username:
+        ctx.username = server_url.username
+    if server_url.password:
+        ctx.password = server_url.password
+    port = server_url.port or 38281
+
+    def reconnect_hint() -> str:
+        return ", type /connect to reconnect" if ctx.server_address else ""
 
     logger.info(f'Connecting to Archipelago server at {address}')
     try:
-        socket = await websockets.connect(address, port=port, ping_timeout=None, ping_interval=None)
+        socket = await websockets.connect(address, port=port, ping_timeout=None, ping_interval=None,
+                                          ssl=get_ssl_context() if address.startswith("wss://") else None)
+        if ctx.ui is not None:
+            ctx.ui.update_address_bar(server_url.netloc)
         ctx.server = Endpoint(socket)
         logger.info('Connected')
         ctx.server_address = address
         ctx.current_reconnect_delay = ctx.starting_reconnect_delay
+        ctx.disconnected_intentionally = False
         async for data in ctx.server.socket:
             for msg in decode(data):
                 await process_server_cmd(ctx, msg)
-        logger.warning('Disconnected from multiworld server, type /connect to reconnect')
-    except ConnectionRefusedError:
-        if cached_address:
-            logger.error('Unable to connect to multiworld server at cached address. '
-                         'Please use the connect button above.')
+        logger.warning(f"Disconnected from multiworld server{reconnect_hint()}")
+    except websockets.InvalidMessage:
+        # probably encrypted
+        if address.startswith("ws://"):
+            # try wss
+            await server_loop(ctx, "ws" + address[1:])
         else:
-            logger.exception('Connection refused by the multiworld server')
+            ctx.handle_connection_loss(f"Lost connection to the multiworld server due to InvalidMessage"
+                                       f"{reconnect_hint()}")
+    except ConnectionRefusedError:
+        ctx.handle_connection_loss("Connection refused by the server. "
+                                   "May not be running Archipelago on that address or port.")
     except websockets.InvalidURI:
-        logger.exception('Failed to connect to the multiworld server (invalid URI)')
-    except (OSError, websockets.InvalidURI):
-        logger.exception('Failed to connect to the multiworld server')
-    except Exception as e:
-        logger.exception('Lost connection to the multiworld server, type /connect to reconnect')
+        ctx.handle_connection_loss("Failed to connect to the multiworld server (invalid URI)")
+    except OSError:
+        ctx.handle_connection_loss("Failed to connect to the multiworld server")
+    except Exception:
+        ctx.handle_connection_loss(f"Lost connection to the multiworld server{reconnect_hint()}")
     finally:
         await ctx.connection_closed()
-        if ctx.server_address:
-            logger.info(f"... reconnecting in {ctx.current_reconnect_delay}s")
-            asyncio.create_task(server_autoreconnect(ctx), name="server auto reconnect")
+        if ctx.server_address and ctx.username and not ctx.disconnected_intentionally:
+            logger.info(f"... automatically reconnecting in {ctx.current_reconnect_delay} seconds")
+            assert ctx.autoreconnect_task is None
+            ctx.autoreconnect_task = asyncio.create_task(server_autoreconnect(ctx), name="server auto reconnect")
         ctx.current_reconnect_delay *= 2
 
 
@@ -412,22 +671,27 @@ async def process_server_cmd(ctx: CommonContext, args: dict):
         raise
     if cmd == 'RoomInfo':
         if ctx.seed_name and ctx.seed_name != args["seed_name"]:
-            logger.info("The server is running a different multiworld than your client is. (invalid seed_name)")
+            msg = "The server is running a different multiworld than your client is. (invalid seed_name)"
+            logger.info(msg, extra={'compact_gui': True})
+            ctx.gui_error('Error', msg)
         else:
             logger.info('--------------------------------')
             logger.info('Room Information:')
             logger.info('--------------------------------')
             version = args["version"]
-            ctx.server_version = tuple(version)
-            version = ".".join(str(item) for item in version)
+            ctx.server_version = Version(*version)
 
-            logger.info(f'Server protocol version: {version}')
-            logger.info("Server protocol tags: " + ", ".join(args["tags"]))
+            if "generator_version" in args:
+                ctx.generator_version = Version(*args["generator_version"])
+                logger.info(f'Server protocol version: {ctx.server_version.as_simple_string()}, '
+                            f'generator version: {ctx.generator_version.as_simple_string()}, '
+                            f'tags: {", ".join(args["tags"])}')
+            else:
+                logger.info(f'Server protocol version: {ctx.server_version.as_simple_string()}, '
+                            f'tags: {", ".join(args["tags"])}')
             if args['password']:
                 logger.info('Password required')
             ctx.update_permissions(args.get("permissions", {}))
-            if "games" in args:
-                ctx.games = {x: game for x, game in enumerate(args["games"], start=1)}
             logger.info(
                 f"A !hint costs {args['hint_cost']}% of your total location count as points"
                 f" and you get {args['location_check_points']}"
@@ -435,24 +699,30 @@ async def process_server_cmd(ctx: CommonContext, args: dict):
             ctx.hint_cost = int(args['hint_cost'])
             ctx.check_points = int(args['location_check_points'])
 
-            if len(args['players']) < 1:
-                logger.info('No player connected')
-            else:
-                args['players'].sort()
-                current_team = -1
-                logger.info('Players:')
-                for network_player in args['players']:
-                    if network_player.team != current_team:
-                        logger.info(f'  Team #{network_player.team + 1}')
-                        current_team = network_player.team
-                    logger.info('    %s (Player %d)' % (network_player.alias, network_player.slot))
-            if args["datapackage_version"] > network_data_package["version"] or args["datapackage_version"] == 0:
-                await ctx.send_msgs([{"cmd": "GetDataPackage"}])
+            if "players" in args:  # TODO remove when servers sending this are outdated
+                players = args.get("players", [])
+                if len(players) < 1:
+                    logger.info('No player connected')
+                else:
+                    players.sort()
+                    current_team = -1
+                    logger.info('Connected Players:')
+                    for network_player in players:
+                        if network_player.team != current_team:
+                            logger.info(f'  Team #{network_player.team + 1}')
+                            current_team = network_player.team
+                        logger.info('    %s (Player %d)' % (network_player.alias, network_player.slot))
+
+            # update data package
+            data_package_versions = args.get("datapackage_versions", {})
+            data_package_checksums = args.get("datapackage_checksums", {})
+            await ctx.prepare_data_package(set(args["games"]), data_package_versions, data_package_checksums)
+
             await ctx.server_auth(args['password'])
 
     elif cmd == 'DataPackage':
-        logger.info("Got new ID/Name Datapackage")
-        ctx.set_getters(args['data'], network=True)
+        logger.info("Got new ID/Name DataPackage")
+        ctx.consume_network_data_package(args['data'])
 
     elif cmd == 'ConnectionRefused':
         errors = args["errors"]
@@ -460,10 +730,10 @@ async def process_server_cmd(ctx: CommonContext, args: dict):
             ctx.event_invalid_slot()
         elif 'InvalidGame' in errors:
             ctx.event_invalid_game()
-        elif 'SlotAlreadyTaken' in errors:
-            raise Exception('Player slot already in use for that team')
         elif 'IncompatibleVersion' in errors:
             raise Exception('Server reported your client version as incompatible')
+        elif 'InvalidItemsHandling' in errors:
+            raise Exception('The item handling flags requested by the client are not supported')
         # last to check, recoverable problem
         elif 'InvalidPassword' in errors:
             logger.error('Invalid password')
@@ -475,8 +745,12 @@ async def process_server_cmd(ctx: CommonContext, args: dict):
             raise Exception('Connection refused by the multiworld host, no reason provided')
 
     elif cmd == 'Connected':
+        ctx.username = ctx.auth
         ctx.team = args["team"]
         ctx.slot = args["slot"]
+        # int keys get lost in JSON transfer
+        ctx.slot_info = {int(pid): data for pid, data in args["slot_info"].items()}
+        ctx.hint_points = args.get("hint_points", 0)
         ctx.consume_players_package(args["players"])
         msgs = []
         if ctx.locations_checked:
@@ -485,6 +759,11 @@ async def process_server_cmd(ctx: CommonContext, args: dict):
         if ctx.locations_scouted:
             msgs.append({"cmd": "LocationScouts",
                          "locations": list(ctx.locations_scouted)})
+        if ctx.stored_data_notification_keys:
+            msgs.append({"cmd": "Get",
+                         "keys": list(ctx.stored_data_notification_keys)})
+            msgs.append({"cmd": "SetNotify",
+                         "keys": list(ctx.stored_data_notification_keys)})
         if msgs:
             await ctx.send_msgs(msgs)
         if ctx.finished_game:
@@ -496,6 +775,10 @@ async def process_server_cmd(ctx: CommonContext, args: dict):
         # when /missing is used for the client side view of what is missing.
         ctx.missing_locations = set(args["missing_locations"])
         ctx.checked_locations = set(args["checked_locations"])
+        ctx.server_locations = ctx.missing_locations | ctx. checked_locations
+
+        server_url = urllib.parse.urlparse(ctx.server_address)
+        Utils.persistent_store("client", "last_server_address", server_url.netloc)
 
     elif cmd == 'ReceivedItems':
         start_index = args["index"]
@@ -514,9 +797,8 @@ async def process_server_cmd(ctx: CommonContext, args: dict):
         ctx.watcher_event.set()
 
     elif cmd == 'LocationInfo':
-        for item, location, player in args['locations']:
-            if location not in ctx.locations_info:
-                ctx.locations_info[location] = (item, player)
+        for item in [NetworkItem(*item) for item in args['locations']]:
+            ctx.locations_info[item.location] = item
         ctx.watcher_event.set()
 
     elif cmd == "RoomUpdate":
@@ -546,6 +828,15 @@ async def process_server_cmd(ctx: CommonContext, args: dict):
         if "DeathLink" in tags and ctx.last_death_link != args["data"]["time"]:
             ctx.on_deathlink(args["data"])
 
+    elif cmd == "Retrieved":
+        ctx.stored_data.update(args["keys"])
+
+    elif cmd == "SetReply":
+        ctx.stored_data[args["key"]] = args["value"]
+        if args["key"].startswith("EnergyLink"):
+            ctx.current_energy_link_value = args["value"]
+            if ctx.ui:
+                ctx.ui.set_new_energy_link_value()
     else:
         logger.debug(f"unknown command {cmd}")
 
@@ -553,7 +844,6 @@ async def process_server_cmd(ctx: CommonContext, args: dict):
 
 
 async def console_loop(ctx: CommonContext):
-    import sys
     commandprocessor = ctx.command_processor(ctx)
     queue = asyncio.Queue()
     stream_input(sys.stdin, queue)
@@ -573,7 +863,7 @@ async def console_loop(ctx: CommonContext):
             logger.exception(e)
 
 
-def get_base_parser(description=None):
+def get_base_parser(description: typing.Optional[str] = None):
     import argparse
     parser = argparse.ArgumentParser(description=description)
     parser.add_argument('--connect', default=None, help='Address of the multiworld host.')
@@ -583,56 +873,60 @@ def get_base_parser(description=None):
     return parser
 
 
-if __name__ == '__main__':
-    # Text Mode to use !hint and such with games that have no text entry
-
+def run_as_textclient():
     class TextContext(CommonContext):
-        tags = {"AP", "IgnoreGame"}
-        game = "Archipelago"
+        # Text Mode to use !hint and such with games that have no text entry
+        tags = {"AP", "TextOnly"}
+        game = ""  # empty matches any game since 0.3.2
+        items_handling = 0b111  # receive all items for /received
+        want_slot_data = False  # Can't use game specific slot_data
 
         async def server_auth(self, password_requested: bool = False):
             if password_requested and not self.password:
                 await super(TextContext, self).server_auth(password_requested)
-            if not self.auth:
-                logger.info('Enter slot name:')
-                self.auth = await self.console_input()
-
+            await self.get_username()
             await self.send_connect()
 
         def on_package(self, cmd: str, args: dict):
             if cmd == "Connected":
-                self.game = self.games.get(self.slot, None)
+                self.game = self.slot_info[self.slot].game
 
+        async def disconnect(self, allow_autoreconnect: bool = False):
+            self.game = ""
+            await super().disconnect(allow_autoreconnect)
 
     async def main(args):
         ctx = TextContext(args.connect, args.password)
+        ctx.auth = args.name
         ctx.server_task = asyncio.create_task(server_loop(ctx), name="server loop")
-        input_task = None
+
         if gui_enabled:
-            from kvui import TextManager
-            ctx.ui = TextManager(ctx)
-            ui_task = asyncio.create_task(ctx.ui.async_run(), name="UI")
-        else:
-            ui_task = None
-        if sys.stdin:
-            input_task = asyncio.create_task(console_loop(ctx), name="Input")
+            ctx.run_gui()
+        ctx.run_cli()
+
         await ctx.exit_event.wait()
-
         await ctx.shutdown()
-        if ui_task:
-            await ui_task
-
-        if input_task:
-            input_task.cancel()
 
     import colorama
 
     parser = get_base_parser(description="Gameless Archipelago Client, for text interfacing.")
+    parser.add_argument('--name', default=None, help="Slot Name to connect as.")
+    parser.add_argument("url", nargs="?", help="Archipelago connection url")
+    args = parser.parse_args()
+
+    if args.url:
+        url = urllib.parse.urlparse(args.url)
+        args.connect = url.netloc
+        if url.username:
+            args.name = urllib.parse.unquote(url.username)
+        if url.password:
+            args.password = urllib.parse.unquote(url.password)
 
-    args, rest = parser.parse_known_args()
     colorama.init()
 
-    loop = asyncio.get_event_loop()
-    loop.run_until_complete(main(args))
-    loop.close()
+    asyncio.run(main(args))
     colorama.deinit()
+
+
+if __name__ == '__main__':
+    run_as_textclient()

FF1Client.py

@@ -1,4 +1,5 @@
 import asyncio
+import copy
 import json
 import time
 from asyncio import StreamReader, StreamWriter
@@ -6,18 +7,21 @@ from typing import List
 
 
 import Utils
-from CommonClient import CommonContext, server_loop, gui_enabled, console_loop, ClientCommandProcessor, logger, \
+from Utils import async_start
+from CommonClient import CommonContext, server_loop, gui_enabled, ClientCommandProcessor, logger, \
     get_base_parser
 
 SYSTEM_MESSAGE_ID = 0
 
-CONNECTION_TIMING_OUT_STATUS = "Connection timing out. Please restart your emulator, then restart ff1_connector.lua"
-CONNECTION_REFUSED_STATUS = "Connection Refused. Please start your emulator and make sure ff1_connector.lua is running"
-CONNECTION_RESET_STATUS = "Connection was reset. Please restart your emulator, then restart ff1_connector.lua"
+CONNECTION_TIMING_OUT_STATUS = "Connection timing out. Please restart your emulator, then restart connector_ff1.lua"
+CONNECTION_REFUSED_STATUS = "Connection Refused. Please start your emulator and make sure connector_ff1.lua is running"
+CONNECTION_RESET_STATUS = "Connection was reset. Please restart your emulator, then restart connector_ff1.lua"
 CONNECTION_TENTATIVE_STATUS = "Initial Connection Made"
 CONNECTION_CONNECTED_STATUS = "Connected"
 CONNECTION_INITIAL_STATUS = "Connection has not been initiated"
 
+DISPLAY_MSGS = True
+
 
 class FF1CommandProcessor(ClientCommandProcessor):
     def __init__(self, ctx: CommonContext):
@@ -28,8 +32,18 @@ class FF1CommandProcessor(ClientCommandProcessor):
         if isinstance(self.ctx, FF1Context):
             logger.info(f"NES Status: {self.ctx.nes_status}")
 
+    def _cmd_toggle_msgs(self):
+        """Toggle displaying messages in EmuHawk"""
+        global DISPLAY_MSGS
+        DISPLAY_MSGS = not DISPLAY_MSGS
+        logger.info(f"Messages are now {'enabled' if DISPLAY_MSGS  else 'disabled'}")
+
 
 class FF1Context(CommonContext):
+    command_processor = FF1CommandProcessor
+    game = 'Final Fantasy'
+    items_handling = 0b111  # full remote
+
     def __init__(self, server_address, password):
         super().__init__(server_address, password)
         self.nes_streams: (StreamReader, StreamWriter) = None
@@ -37,10 +51,8 @@ class FF1Context(CommonContext):
         self.messages = {}
         self.locations_array = None
         self.nes_status = CONNECTION_INITIAL_STATUS
-        self.game = 'Final Fantasy'
         self.awaiting_rom = False
-
-    command_processor = FF1CommandProcessor
+        self.display_msgs = True
 
     async def server_auth(self, password_requested: bool = False):
         if password_requested and not self.password:
@@ -53,44 +65,52 @@ class FF1Context(CommonContext):
         await self.send_connect()
 
     def _set_message(self, msg: str, msg_id: int):
-        self.messages[(time.time(), msg_id)] = msg
+        if DISPLAY_MSGS:
+            self.messages[time.time(), msg_id] = msg
 
     def on_package(self, cmd: str, args: dict):
         if cmd == 'Connected':
-            self.game = self.games.get(self.slot, None)
-            asyncio.create_task(parse_locations(self.locations_array, self, True))
+            async_start(parse_locations(self.locations_array, self, True))
         elif cmd == 'Print':
             msg = args['text']
             if ': !' not in msg:
                 self._set_message(msg, SYSTEM_MESSAGE_ID)
-        elif cmd == "ReceivedItems":
-            msg = f"Received {', '.join([self.item_name_getter(item.item) for item in args['items']])}"
-            self._set_message(msg, SYSTEM_MESSAGE_ID)
-        elif cmd == 'PrintJSON':
-            print_type = args['type']
-            item = args['item']
-            receiving_player_id = args['receiving']
-            receiving_player_name = self.player_names[receiving_player_id]
-            sending_player_id = item.player
-            sending_player_name = self.player_names[item.player]
-            if print_type == 'Hint':
-                msg = f"Hint: Your {self.item_name_getter(item.item)} is at" \
-                      f" {self.player_names[item.player]}'s {self.location_name_getter(item.location)}"
-                self._set_message(msg, item.item)
-            elif print_type == 'ItemSend' and receiving_player_id != self.slot:
-                if sending_player_id == self.slot:
-                    if receiving_player_id == self.slot:
-                        msg = f"You found your own {self.item_name_getter(item.item)}"
-                    else:
-                        msg = f"You sent {self.item_name_getter(item.item)} to {receiving_player_name}"
-                else:
-                    if receiving_player_id == sending_player_id:
-                        msg = f"{sending_player_name} found their {self.item_name_getter(item.item)}"
-                    else:
-                        msg = f"{sending_player_name} sent {self.item_name_getter(item.item)} to " \
-                              f"{receiving_player_name}"
+
+    def on_print_json(self, args: dict):
+        if self.ui:
+            self.ui.print_json(copy.deepcopy(args["data"]))
+        else:
+            text = self.jsontotextparser(copy.deepcopy(args["data"]))
+            logger.info(text)
+        relevant = args.get("type", None) in {"Hint", "ItemSend"}
+        if relevant:
+            item = args["item"]
+            # goes to this world
+            if self.slot_concerns_self(args["receiving"]):
+                relevant = True
+            # found in this world
+            elif self.slot_concerns_self(item.player):
+                relevant = True
+            # not related
+            else:
+                relevant = False
+            if relevant:
+                item = args["item"]
+                msg = self.raw_text_parser(copy.deepcopy(args["data"]))
                 self._set_message(msg, item.item)
 
+    def run_gui(self):
+        from kvui import GameManager
+
+        class FF1Manager(GameManager):
+            logging_pairs = [
+                ("Client", "Archipelago")
+            ]
+            base_title = "Archipelago Final Fantasy 1 Client"
+
+        self.ui = FF1Manager(self)
+        self.ui_task = asyncio.create_task(self.ui.async_run(), name="UI")
+
 
 def get_payload(ctx: FF1Context):
     current_time = time.time()
@@ -128,13 +148,13 @@ async def parse_locations(locations_array: List[int], ctx: FF1Context, force: bo
                 index -= 0x200
                 flag = 0x02
 
-            # print(f"Location: {ctx.location_name_getter(location)}")
+            # print(f"Location: {ctx.location_names[location]}")
             # print(f"Index: {str(hex(index))}")
             # print(f"value: {locations_array[index] & flag != 0}")
             if locations_array[index] & flag != 0:
                 locations_checked.append(location)
         if locations_checked:
-            # print([ctx.location_name_getter(location) for location in locations_checked])
+            # print([ctx.location_names[location] for location in locations_checked])
             await ctx.send_msgs([
                 {"cmd": "LocationChecks",
                  "locations": locations_checked}
@@ -161,9 +181,12 @@ async def nes_sync_task(ctx: FF1Context):
                     # print(data_decoded)
                     if ctx.game is not None and 'locations' in data_decoded:
                         # Not just a keep alive ping, parse
-                        asyncio.create_task(parse_locations(data_decoded['locations'], ctx, False))
+                        async_start(parse_locations(data_decoded['locations'], ctx, False))
                     if not ctx.auth:
                         ctx.auth = ''.join([chr(i) for i in data_decoded['playerName'] if i != 0])
+                        if ctx.auth == '':
+                            logger.info("Invalid ROM detected. No player name built into the ROM. Please regenerate"
+                                        "the ROM using the same link but adding your slot name")
                         if ctx.awaiting_rom:
                             await ctx.server_auth(False)
                 except asyncio.TimeoutError:
@@ -214,18 +237,15 @@ if __name__ == '__main__':
     # Text Mode to use !hint and such with games that have no text entry
     Utils.init_logging("FF1Client")
 
+    options = Utils.get_options()
+    DISPLAY_MSGS = options["ffr_options"]["display_msgs"]
+
     async def main(args):
         ctx = FF1Context(args.connect, args.password)
         ctx.server_task = asyncio.create_task(server_loop(ctx), name="ServerLoop")
         if gui_enabled:
-            input_task = None
-            from kvui import FF1Manager
-            ctx.ui = FF1Manager(ctx)
-            ui_task = asyncio.create_task(ctx.ui.async_run(), name="UI")
-        else:
-            input_task = asyncio.create_task(console_loop(ctx), name="Input")
-            ui_task = None
-
+            ctx.run_gui()
+        ctx.run_cli()
         ctx.nes_sync_task = asyncio.create_task(nes_sync_task(ctx), name="NES Sync")
 
         await ctx.exit_event.wait()
@@ -236,20 +256,12 @@ if __name__ == '__main__':
         if ctx.nes_sync_task:
             await ctx.nes_sync_task
 
-        if ui_task:
-            await ui_task
-
-        if input_task:
-            input_task.cancel()
-
 
     import colorama
 
     parser = get_base_parser()
-    args, rest = parser.parse_known_args()
+    args = parser.parse_args()
     colorama.init()
 
-    loop = asyncio.get_event_loop()
-    loop.run_until_complete(main(args))
-    loop.close()
+    asyncio.run(main(args))
     colorama.deinit()

FactorioClient.py

@@ -1,378 +1,12 @@
 from __future__ import annotations
-import os
-import logging
-import json
-import string
-import copy
-import subprocess
-import sys
-import time
-import random
 
-import factorio_rcon
-import colorama
-import asyncio
-from queue import Queue
+import ModuleUpdate
+ModuleUpdate.update()
+
+from worlds.factorio.Client import check_stdin, launch
 import Utils
 
 if __name__ == "__main__":
     Utils.init_logging("FactorioClient", exception_logger="Client")
-
-from CommonClient import CommonContext, server_loop, console_loop, ClientCommandProcessor, logger, gui_enabled, \
-     get_base_parser
-from MultiServer import mark_raw
-from NetUtils import NetworkItem, ClientStatus, JSONtoTextParser, JSONMessagePart
-
-from worlds.factorio import Factorio
-
-
-class FactorioCommandProcessor(ClientCommandProcessor):
-    ctx: FactorioContext
-
-    @mark_raw
-    def _cmd_factorio(self, text: str) -> bool:
-        """Send the following command to the bound Factorio Server."""
-        if self.ctx.rcon_client:
-            # TODO: Print the command non-silently only for race seeds, or otherwise block anything but /factorio /save in race seeds.
-            self.ctx.print_to_game(f"/factorio {text}")
-            result = self.ctx.rcon_client.send_command(text)
-            if result:
-                self.output(result)
-            return True
-        return False
-
-    def _cmd_resync(self):
-        """Manually trigger a resync."""
-        self.ctx.awaiting_bridge = True
-
-
-class FactorioContext(CommonContext):
-    command_processor = FactorioCommandProcessor
-    game = "Factorio"
-
-    # updated by spinup server
-    mod_version: Utils.Version = Utils.Version(0, 0, 0)
-
-    def __init__(self, server_address, password):
-        super(FactorioContext, self).__init__(server_address, password)
-        self.send_index: int = 0
-        self.rcon_client = None
-        self.awaiting_bridge = False
-        self.write_data_path = None
-        self.death_link_tick: int = 0  # last send death link on Factorio layer
-        self.factorio_json_text_parser = FactorioJSONtoTextParser(self)
-
-    async def server_auth(self, password_requested: bool = False):
-        if password_requested and not self.password:
-            await super(FactorioContext, self).server_auth(password_requested)
-
-        if self.rcon_client:
-            await get_info(self, self.rcon_client)  # retrieve current auth code
-        else:
-            raise Exception("Cannot connect to a server with unknown own identity, "
-                            "bridge to Factorio first.")
-
-        await self.send_connect()
-
-    def on_print(self, args: dict):
-        super(FactorioContext, self).on_print(args)
-        if self.rcon_client:
-            self.print_to_game(args['text'])
-
-    def on_print_json(self, args: dict):
-        if self.rcon_client:
-            text = self.factorio_json_text_parser(copy.deepcopy(args["data"]))
-            self.print_to_game(text)
-        super(FactorioContext, self).on_print_json(args)
-
-    @property
-    def savegame_name(self) -> str:
-        return f"AP_{self.seed_name}_{self.auth}_Save.zip"
-
-    def print_to_game(self, text):
-        self.rcon_client.send_command(f"/ap-print [font=default-large-bold]Archipelago:[/font] "
-                                      f"{text}")
-
-    def on_deathlink(self, data: dict):
-        if self.rcon_client:
-            self.rcon_client.send_command(f"/ap-deathlink {data['source']}")
-        super(FactorioContext, self).on_deathlink(data)
-
-    def on_package(self, cmd: str, args: dict):
-        if cmd in {"Connected", "RoomUpdate"}:
-            # catch up sync anything that is already cleared.
-            if "checked_locations" in args and args["checked_locations"]:
-                self.rcon_client.send_commands({item_name: f'/ap-get-technology ap-{item_name}-\t-1' for
-                                                item_name in args["checked_locations"]})
-
-
-async def game_watcher(ctx: FactorioContext):
-    bridge_logger = logging.getLogger("FactorioWatcher")
-    from worlds.factorio.Technologies import lookup_id_to_name
-    next_bridge = time.perf_counter() + 1
-    try:
-        while not ctx.exit_event.is_set():
-            if ctx.awaiting_bridge and ctx.rcon_client and time.perf_counter() > next_bridge:
-                next_bridge = time.perf_counter() + 1
-                ctx.awaiting_bridge = False
-                data = json.loads(ctx.rcon_client.send_command("/ap-sync"))
-                if data["slot_name"] != ctx.auth:
-                    bridge_logger.warning(f"Connected World is not the expected one {data['slot_name']} != {ctx.auth}")
-                elif data["seed_name"] != ctx.seed_name:
-                    bridge_logger.warning(
-                        f"Connected Multiworld is not the expected one {data['seed_name']} != {ctx.seed_name}")
-                else:
-                    data = data["info"]
-                    research_data = data["research_done"]
-                    research_data = {int(tech_name.split("-")[1]) for tech_name in research_data}
-                    victory = data["victory"]
-                    if "death_link" in data:    # TODO: Remove this if statement around version 0.2.4 or so
-                        await ctx.update_death_link(data["death_link"])
-
-                    if not ctx.finished_game and victory:
-                        await ctx.send_msgs([{"cmd": "StatusUpdate", "status": ClientStatus.CLIENT_GOAL}])
-                        ctx.finished_game = True
-
-                    if ctx.locations_checked != research_data:
-                        bridge_logger.debug(
-                            f"New researches done: "
-                            f"{[lookup_id_to_name[rid] for rid in research_data - ctx.locations_checked]}")
-                        ctx.locations_checked = research_data
-                        await ctx.send_msgs([{"cmd": 'LocationChecks', "locations": tuple(research_data)}])
-                    death_link_tick = data.get("death_link_tick", 0)
-                    if death_link_tick != ctx.death_link_tick:
-                        ctx.death_link_tick = death_link_tick
-                        if "DeathLink" in ctx.tags:
-                            await ctx.send_death()
-
-            await asyncio.sleep(0.1)
-
-    except Exception as e:
-        logging.exception(e)
-        logging.error("Aborted Factorio Server Bridge")
-
-
-def stream_factorio_output(pipe, queue, process):
-    def queuer():
-        while process.poll() is None:
-            text = pipe.readline().strip()
-            if text:
-                queue.put_nowait(text)
-
-    from threading import Thread
-
-    thread = Thread(target=queuer, name="Factorio Output Queue", daemon=True)
-    thread.start()
-    return thread
-
-
-async def factorio_server_watcher(ctx: FactorioContext):
-    savegame_name = os.path.abspath(ctx.savegame_name)
-    if not os.path.exists(savegame_name):
-        logger.info(f"Creating savegame {savegame_name}")
-        subprocess.run((
-            executable, "--create", savegame_name, "--preset", "archipelago"
-        ))
-    factorio_process = subprocess.Popen((executable, "--start-server", ctx.savegame_name,
-                                         *(str(elem) for elem in server_args)),
-                                        stderr=subprocess.PIPE,
-                                        stdout=subprocess.PIPE,
-                                        stdin=subprocess.DEVNULL,
-                                        encoding="utf-8")
-    factorio_server_logger.info("Started Factorio Server")
-    factorio_queue = Queue()
-    stream_factorio_output(factorio_process.stdout, factorio_queue, factorio_process)
-    stream_factorio_output(factorio_process.stderr, factorio_queue, factorio_process)
-    try:
-        while not ctx.exit_event.is_set():
-            if factorio_process.poll():
-                factorio_server_logger.info("Factorio server has exited.")
-                ctx.exit_event.set()
-
-            while not factorio_queue.empty():
-                msg = factorio_queue.get()
-                factorio_queue.task_done()
-
-                if not ctx.rcon_client and "Starting RCON interface at IP ADDR:" in msg:
-                    ctx.rcon_client = factorio_rcon.RCONClient("localhost", rcon_port, rcon_password)
-                    if not ctx.server:
-                        logger.info("Established bridge to Factorio Server. "
-                                    "Ready to connect to Archipelago via /connect")
-
-                if not ctx.awaiting_bridge and "Archipelago Bridge Data available for game tick " in msg:
-                    ctx.awaiting_bridge = True
-                    factorio_server_logger.debug(msg)
-                else:
-                    factorio_server_logger.info(msg)
-            if ctx.rcon_client:
-                commands = {}
-                while ctx.send_index < len(ctx.items_received):
-                    transfer_item: NetworkItem = ctx.items_received[ctx.send_index]
-                    item_id = transfer_item.item
-                    player_name = ctx.player_names[transfer_item.player]
-                    if item_id not in Factorio.item_id_to_name:
-                        factorio_server_logger.error(f"Cannot send unknown item ID: {item_id}")
-                    else:
-                        item_name = Factorio.item_id_to_name[item_id]
-                        factorio_server_logger.info(f"Sending {item_name} to Nauvis from {player_name}.")
-                        commands[ctx.send_index] = f'/ap-get-technology {item_name}\t{ctx.send_index}\t{player_name}'
-                    ctx.send_index += 1
-                if commands:
-                    ctx.rcon_client.send_commands(commands)
-            await asyncio.sleep(0.1)
-
-    except Exception as e:
-        logging.exception(e)
-        logging.error("Aborted Factorio Server Bridge")
-        ctx.rcon_client = None
-        ctx.exit_event.set()
-
-    finally:
-        factorio_process.terminate()
-        factorio_process.wait(5)
-
-
-async def get_info(ctx, rcon_client):
-    info = json.loads(rcon_client.send_command("/ap-rcon-info"))
-    ctx.auth = info["slot_name"]
-    ctx.seed_name = info["seed_name"]
-    # 0.2.0 addition, not present earlier
-    death_link = bool(info.get("death_link", False))
-    await ctx.update_death_link(death_link)
-
-
-async def factorio_spinup_server(ctx: FactorioContext) -> bool:
-    savegame_name = os.path.abspath("Archipelago.zip")
-    if not os.path.exists(savegame_name):
-        logger.info(f"Creating savegame {savegame_name}")
-        subprocess.run((
-            executable, "--create", savegame_name
-        ))
-    factorio_process = subprocess.Popen(
-        (executable, "--start-server", savegame_name, *(str(elem) for elem in server_args)),
-        stderr=subprocess.PIPE,
-        stdout=subprocess.PIPE,
-        stdin=subprocess.DEVNULL,
-        encoding="utf-8")
-    factorio_server_logger.info("Started Information Exchange Factorio Server")
-    factorio_queue = Queue()
-    stream_factorio_output(factorio_process.stdout, factorio_queue, factorio_process)
-    stream_factorio_output(factorio_process.stderr, factorio_queue, factorio_process)
-    rcon_client = None
-    try:
-        while not ctx.auth:
-            while not factorio_queue.empty():
-                msg = factorio_queue.get()
-                factorio_server_logger.info(msg)
-                if "Loading mod AP-" in msg and msg.endswith("(data.lua)"):
-                    parts = msg.split()
-                    ctx.mod_version = Utils.Version(*(int(number) for number in parts[-2].split(".")))
-                elif "Write data path: " in msg:
-                    ctx.write_data_path = Utils.get_text_between(msg, "Write data path: ", " [")
-                    if "AppData" in ctx.write_data_path:
-                        logger.warning("It appears your mods are loaded from Appdata, "
-                                       "this can lead to problems with multiple Factorio instances. "
-                                       "If this is the case, you will get a file locked error running Factorio.")
-                if not rcon_client and "Starting RCON interface at IP ADDR:" in msg:
-                    rcon_client = factorio_rcon.RCONClient("localhost", rcon_port, rcon_password)
-                    if ctx.mod_version == ctx.__class__.mod_version:
-                        raise Exception("No Archipelago mod was loaded. Aborting.")
-                    await get_info(ctx, rcon_client)
-            await asyncio.sleep(0.01)
-
-    except Exception as e:
-        logger.exception(e)
-        logger.error("Aborted Factorio Server Bridge")
-        ctx.exit_event.set()
-
-    else:
-        logger.info(
-            f"Got World Information from AP Mod {tuple(ctx.mod_version)} for seed {ctx.seed_name} in slot {ctx.auth}")
-        return True
-    finally:
-        factorio_process.terminate()
-        factorio_process.wait(5)
-    return False
-
-
-async def main(args):
-    ctx = FactorioContext(args.connect, args.password)
-    ctx.server_task = asyncio.create_task(server_loop(ctx), name="ServerLoop")
-    input_task = None
-    if gui_enabled:
-        from kvui import FactorioManager
-        ctx.ui = FactorioManager(ctx)
-        ui_task = asyncio.create_task(ctx.ui.async_run(), name="UI")
-    else:
-        ui_task = None
-    if sys.stdin:
-        input_task = asyncio.create_task(console_loop(ctx), name="Input")
-    factorio_server_task = asyncio.create_task(factorio_spinup_server(ctx), name="FactorioSpinupServer")
-    succesful_launch = await factorio_server_task
-    if succesful_launch:
-        factorio_server_task = asyncio.create_task(factorio_server_watcher(ctx), name="FactorioServer")
-        progression_watcher = asyncio.create_task(
-            game_watcher(ctx), name="FactorioProgressionWatcher")
-
-        await ctx.exit_event.wait()
-        ctx.server_address = None
-
-        await progression_watcher
-        await factorio_server_task
-
-    await ctx.shutdown()
-
-    if ui_task:
-        await ui_task
-
-    if input_task:
-        input_task.cancel()
-
-
-class FactorioJSONtoTextParser(JSONtoTextParser):
-    def _handle_color(self, node: JSONMessagePart):
-        colors = node["color"].split(";")
-        for color in colors:
-            if color in {"red", "green", "blue", "orange", "yellow", "pink", "purple", "white", "black", "gray",
-                         "brown", "cyan", "acid"}:
-                node["text"] = f"[color={color}]{node['text']}[/color]"
-                return self._handle_text(node)
-            elif color == "magenta":
-                node["text"] = f"[color=pink]{node['text']}[/color]"
-            return self._handle_text(node)
-        return self._handle_text(node)
-
-
-if __name__ == '__main__':
-    parser = get_base_parser(description="Optional arguments to FactorioClient follow. "
-                                         "Remaining arguments get passed into bound Factorio instance."
-                                         "Refer to Factorio --help for those.")
-    parser.add_argument('--rcon-port', default='24242', type=int, help='Port to use to communicate with Factorio')
-    parser.add_argument('--rcon-password', help='Password to authenticate with RCON.')
-
-    args, rest = parser.parse_known_args()
-    colorama.init()
-    rcon_port = args.rcon_port
-    rcon_password = args.rcon_password if args.rcon_password else ''.join(
-        random.choice(string.ascii_letters) for x in range(32))
-
-    factorio_server_logger = logging.getLogger("FactorioServer")
-    options = Utils.get_options()
-    executable = options["factorio_options"]["executable"]
-
-    if not os.path.exists(os.path.dirname(executable)):
-        raise FileNotFoundError(f"Path {os.path.dirname(executable)} does not exist or could not be accessed.")
-    if os.path.isdir(executable):  # user entered a path to a directory, let's find the executable therein
-        executable = os.path.join(executable, "factorio")
-    if not os.path.isfile(executable):
-        if os.path.isfile(executable + ".exe"):
-            executable = executable + ".exe"
-        else:
-            raise FileNotFoundError(f"Path {executable} is not an executable file.")
-
-    server_args = ("--rcon-port", rcon_port, "--rcon-password", rcon_password, *rest)
-
-    loop = asyncio.get_event_loop()
-    loop.run_until_complete(main(args))
-    loop.close()
-    colorama.deinit()
+    check_stdin()
+    launch()

Generate.py

@@ -1,97 +1,105 @@
+from __future__ import annotations
+
 import argparse
 import logging
-import random
-import urllib.request
-import urllib.parse
-import typing
 import os
-from collections import Counter
+import random
 import string
+import urllib.parse
+import urllib.request
+from collections import ChainMap, Counter
+from typing import Any, Callable, Dict, Tuple, Union
 
 import ModuleUpdate
 
 ModuleUpdate.update()
 
+import copy
 import Utils
-from worlds.alttp import Options as LttPOptions
-from worlds.generic import PlandoItem, PlandoConnection
-from Utils import parse_yaml, version_tuple, __version__, tuplize_version, get_options
-from worlds.alttp.EntranceRandomizer import parse_arguments
-from Main import main as ERmain
-from BaseClasses import seeddigits, get_seed
 import Options
-from worlds.alttp import Bosses
+from BaseClasses import seeddigits, get_seed, PlandoOptions
+from Main import main as ERmain
+from settings import get_settings
+from Utils import parse_yamls, version_tuple, __version__, tuplize_version, user_path
+from worlds.alttp import Options as LttPOptions
+from worlds.alttp.EntranceRandomizer import parse_arguments
 from worlds.alttp.Text import TextTable
 from worlds.AutoWorld import AutoWorldRegister
+from worlds.generic import PlandoConnection
 
-categories = set(AutoWorldRegister.world_types)
 
 def mystery_argparse():
-    options = get_options()
-    defaults = options["generator"]
+    options = get_settings()
+    defaults = options.generator
 
     parser = argparse.ArgumentParser(description="CMD Generation Interface, defaults come from host.yaml.")
-    parser.add_argument('--weights_file_path', default = defaults["weights_file_path"],
+    parser.add_argument('--weights_file_path', default=defaults.weights_file_path,
                         help='Path to the weights file to use for rolling game settings, urls are also valid')
     parser.add_argument('--samesettings', help='Rolls settings per weights file rather than per player',
                         action='store_true')
-    parser.add_argument('--player_files_path', default=defaults["player_files_path"],
+    parser.add_argument('--player_files_path', default=defaults.player_files_path,
                         help="Input directory for player files.")
     parser.add_argument('--seed', help='Define seed number to generate.', type=int)
-    parser.add_argument('--multi', default=defaults["players"], type=lambda value: max(int(value), 1))
-    parser.add_argument('--spoiler', type=int, default=defaults["spoiler"])
-    parser.add_argument('--lttp_rom', default=options["lttp_options"]["rom_file"], help="Path to the 1.0 JP LttP Baserom.")
-    parser.add_argument('--sm_rom', default=options["sm_options"]["rom_file"], help="Path to the 1.0 JP SM Baserom.")
-    parser.add_argument('--enemizercli', default=defaults["enemizer_path"])
-    parser.add_argument('--outputpath', default=options["general_options"]["output_path"])
-    parser.add_argument('--race', action='store_true', default=defaults["race"])
-    parser.add_argument('--meta_file_path', default=defaults["meta_file_path"])
+    parser.add_argument('--multi', default=defaults.players, type=lambda value: max(int(value), 1))
+    parser.add_argument('--spoiler', type=int, default=defaults.spoiler)
+    parser.add_argument('--outputpath', default=options.general_options.output_path,
+                        help="Path to output folder. Absolute or relative to cwd.")  # absolute or relative to cwd
+    parser.add_argument('--race', action='store_true', default=defaults.race)
+    parser.add_argument('--meta_file_path', default=defaults.meta_file_path)
     parser.add_argument('--log_level', default='info', help='Sets log level')
     parser.add_argument('--yaml_output', default=0, type=lambda value: max(int(value), 0),
                         help='Output rolled mystery results to yaml up to specified number (made for async multiworld)')
-    parser.add_argument('--plando', default=defaults["plando_options"],
+    parser.add_argument('--plando', default=defaults.plando_options,
                         help='List of options that can be set manually. Can be combined, for example "bosses, items"')
+    parser.add_argument("--skip_prog_balancing", action="store_true",
+                        help="Skip progression balancing step during generation.")
     args = parser.parse_args()
     if not os.path.isabs(args.weights_file_path):
         args.weights_file_path = os.path.join(args.player_files_path, args.weights_file_path)
     if not os.path.isabs(args.meta_file_path):
         args.meta_file_path = os.path.join(args.player_files_path, args.meta_file_path)
-    args.plando: typing.Set[str] = {arg.strip().lower() for arg in args.plando.split(",")}
+    args.plando: PlandoOptions = PlandoOptions.from_option_string(args.plando)
     return args, options
 
 
-def get_seed_name(random):
-    return f"{random.randint(0, pow(10, seeddigits) - 1)}".zfill(seeddigits)
+def get_seed_name(random_source) -> str:
+    return f"{random_source.randint(0, pow(10, seeddigits) - 1)}".zfill(seeddigits)
 
 
 def main(args=None, callback=ERmain):
     if not args:
         args, options = mystery_argparse()
+    else:
+        options = get_settings()
 
     seed = get_seed(args.seed)
+    Utils.init_logging(f"Generate_{seed}", loglevel=args.log_level)
     random.seed(seed)
     seed_name = get_seed_name(random)
 
     if args.race:
+        logging.info("Race mode enabled. Using non-deterministic random source.")
         random.seed()  # reset to time-based random source
 
-    weights_cache = {}
+    weights_cache: Dict[str, Tuple[Any, ...]] = {}
     if args.weights_file_path and os.path.exists(args.weights_file_path):
         try:
-            weights_cache[args.weights_file_path] = read_weights_yaml(args.weights_file_path)
+            weights_cache[args.weights_file_path] = read_weights_yamls(args.weights_file_path)
         except Exception as e:
-            raise ValueError(f"File {args.weights_file_path} is destroyed. Please fix your yaml.") from e
-        print(f"Weights: {args.weights_file_path} >> "
-              f"{get_choice('description', weights_cache[args.weights_file_path], 'No description specified')}")
+            raise ValueError(f"File {args.weights_file_path} is invalid. Please fix your yaml.") from e
+        logging.info(f"Weights: {args.weights_file_path} >> "
+                     f"{get_choice('description', weights_cache[args.weights_file_path][-1], 'No description specified')}")
 
     if args.meta_file_path and os.path.exists(args.meta_file_path):
         try:
-            weights_cache[args.meta_file_path] = read_weights_yaml(args.meta_file_path)
+            meta_weights = read_weights_yamls(args.meta_file_path)[-1]
         except Exception as e:
-            raise ValueError(f"File {args.meta_file_path} is destroyed. Please fix your yaml.") from e
-        meta_weights = weights_cache[args.meta_file_path]
-        print(f"Meta: {args.meta_file_path} >> {get_choice('meta_description', meta_weights)}")
-        del(meta_weights["meta_description"])
+            raise ValueError(f"File {args.meta_file_path} is invalid. Please fix your yaml.") from e
+        logging.info(f"Meta: {args.meta_file_path} >> {get_choice('meta_description', meta_weights)}")
+        try:  # meta description allows us to verify that the file named meta.yaml is intentionally a meta file
+            del(meta_weights["meta_description"])
+        except Exception as e:
+            raise ValueError("No meta description found for meta.yaml. Unable to verify.") from e
         if args.samesettings:
             raise Exception("Cannot mix --samesettings with --meta")
     else:
@@ -100,86 +108,99 @@ def main(args=None, callback=ERmain):
     player_files = {}
     for file in os.scandir(args.player_files_path):
         fname = file.name
-        if file.is_file() and os.path.join(args.player_files_path, fname) not in {args.meta_file_path, args.weights_file_path}:
+        if file.is_file() and not fname.startswith(".") and \
+                os.path.join(args.player_files_path, fname) not in {args.meta_file_path, args.weights_file_path}:
             path = os.path.join(args.player_files_path, fname)
             try:
-                weights_cache[fname] = read_weights_yaml(path)
+                weights_cache[fname] = read_weights_yamls(path)
             except Exception as e:
-                raise ValueError(f"File {fname} is destroyed. Please fix your yaml.") from e
-            else:
-                print(f"P{player_id} Weights: {fname} >> "
-                      f"{get_choice('description', weights_cache[fname], 'No description specified')}")
-                player_files[player_id] = fname
+                raise ValueError(f"File {fname} is invalid. Please fix your yaml.") from e
+
+    # sort dict for consistent results across platforms:
+    weights_cache = {key: value for key, value in sorted(weights_cache.items())}
+    for filename, yaml_data in weights_cache.items():
+        if filename not in {args.meta_file_path, args.weights_file_path}:
+            for yaml in yaml_data:
+                logging.info(f"P{player_id} Weights: {filename} >> "
+                             f"{get_choice('description', yaml, 'No description specified')}")
+                player_files[player_id] = filename
                 player_id += 1
 
-    args.multi = max(player_id-1, args.multi)
-    print(f"Generating for {args.multi} player{'s' if args.multi > 1 else ''}, {seed_name} Seed {seed} with plando: "
-          f"{', '.join(args.plando)}")
+    args.multi = max(player_id - 1, args.multi)
+    logging.info(f"Generating for {args.multi} player{'s' if args.multi > 1 else ''}, "
+                 f"{seed_name} Seed {seed} with plando: {args.plando}")
 
     if not weights_cache:
-        raise Exception(f"No weights found. Provide a general weights file ({args.weights_file_path}) or individual player files. "
+        raise Exception(f"No weights found. "
+                        f"Provide a general weights file ({args.weights_file_path}) or individual player files. "
                         f"A mix is also permitted.")
     erargs = parse_arguments(['--multi', str(args.multi)])
     erargs.seed = seed
-    erargs.glitch_triforce = options["generator"]["glitch_triforce_room"]
+    erargs.plando_options = args.plando
+    erargs.glitch_triforce = options.generator.glitch_triforce_room
     erargs.spoiler = args.spoiler
     erargs.race = args.race
     erargs.outputname = seed_name
     erargs.outputpath = args.outputpath
+    erargs.skip_prog_balancing = args.skip_prog_balancing
 
-    Utils.init_logging(f"Generate_{seed}", loglevel=args.log_level)
-
-    erargs.lttp_rom = args.lttp_rom
-    erargs.sm_rom = args.sm_rom
-    erargs.enemizercli = args.enemizercli
-
-    settings_cache = {k: (roll_settings(v, args.plando) if args.samesettings else None)
-                      for k, v in weights_cache.items()}
-    player_path_cache = {}
-    for player in range(1, args.multi + 1):
-        player_path_cache[player] = player_files.get(player, args.weights_file_path)
+    settings_cache: Dict[str, Tuple[argparse.Namespace, ...]] = \
+        {fname: (tuple(roll_settings(yaml, args.plando) for yaml in yamls) if args.samesettings else None)
+         for fname, yamls in weights_cache.items()}
 
     if meta_weights:
         for category_name, category_dict in meta_weights.items():
             for key in category_dict:
-                option = get_choice(key, category_dict)
+                option = roll_meta_option(key, category_name, category_dict)
                 if option is not None:
-                    for player, path in player_path_cache.items():
-                        if category_name is None:
-                            weights_cache[path][key] = option
-                        elif category_name not in weights_cache[path]:
-                            raise Exception(f"Meta: Category {category_name} is not present in {path}.")
-                        else:
-                            weights_cache[path][category_name][key] = option
+                    for path in weights_cache:
+                        for yaml in weights_cache[path]:
+                            if category_name is None:
+                                for category in yaml:
+                                    if category in AutoWorldRegister.world_types and key in Options.common_options:
+                                        yaml[category][key] = option
+                            elif category_name not in yaml:
+                                logging.warning(f"Meta: Category {category_name} is not present in {path}.")
+                            else:
+                                yaml[category_name][key] = option
 
+    player_path_cache = {}
+    for player in range(1, args.multi + 1):
+        player_path_cache[player] = player_files.get(player, args.weights_file_path)
     name_counter = Counter()
     erargs.player_settings = {}
-    for player in range(1, args.multi + 1):
+
+    player = 1
+    while player <= args.multi:
         path = player_path_cache[player]
         if path:
             try:
-                settings = settings_cache[path] if settings_cache[path] else \
-                    roll_settings(weights_cache[path], args.plando)
-                for k, v in vars(settings).items():
-                    if v is not None:
-                        try:
-                            getattr(erargs, k)[player] = v
-                        except AttributeError:
-                            setattr(erargs, k, {player: v})
-                        except Exception as e:
-                            raise Exception(f"Error setting {k} to {v} for player {player}") from e
+                settings: Tuple[argparse.Namespace, ...] = settings_cache[path] if settings_cache[path] else \
+                    tuple(roll_settings(yaml, args.plando) for yaml in weights_cache[path])
+                for settingsObject in settings:
+                    for k, v in vars(settingsObject).items():
+                        if v is not None:
+                            try:
+                                getattr(erargs, k)[player] = v
+                            except AttributeError:
+                                setattr(erargs, k, {player: v})
+                            except Exception as e:
+                                raise Exception(f"Error setting {k} to {v} for player {player}") from e
+
+                    if path == args.weights_file_path:  # if name came from the weights file, just use base player name
+                        erargs.name[player] = f"Player{player}"
+                    elif not erargs.name[player]:  # if name was not specified, generate it from filename
+                        erargs.name[player] = os.path.splitext(os.path.split(path)[-1])[0]
+                    erargs.name[player] = handle_name(erargs.name[player], player, name_counter)
+
+                    player += 1
             except Exception as e:
-                raise ValueError(f"File {path} is destroyed. Please fix your yaml.") from e
+                raise ValueError(f"File {path} is invalid. Please fix your yaml.") from e
         else:
             raise RuntimeError(f'No weights specified for player {player}')
-        if path == args.weights_file_path:  # if name came from the weights file, just use base player name
-            erargs.name[player] = f"Player{player}"
-        elif not erargs.name[player]:  # if name was not specified, generate it from filename
-            erargs.name[player] = os.path.splitext(os.path.split(path)[-1])[0]
-        erargs.name[player] = handle_name(erargs.name[player], player, name_counter)
 
-    if len(set(erargs.name.values())) != len(erargs.name):
-        raise Exception(f"Names have to be unique. Names: {erargs.name}")
+    if len(set(name.lower() for name in erargs.name.values())) != len(erargs.name):
+        raise Exception(f"Names have to be unique. Names: {Counter(name.lower() for name in erargs.name.values())}")
 
     if args.yaml_output:
         import yaml
@@ -190,8 +211,6 @@ def main(args=None, callback=ERmain):
                     if len(player_settings.values()) > 1:
                         important[option] = {player: value for player, value in player_settings.items() if
                                              player <= args.yaml_output}
-                    elif len(player_settings.values()) > 0:
-                        important[option] = player_settings[1]
                     else:
                         logging.debug(f"No player settings defined for option '{option}'")
 
@@ -208,28 +227,28 @@ def main(args=None, callback=ERmain):
     callback(erargs, seed)
 
 
-def read_weights_yaml(path):
+def read_weights_yamls(path) -> Tuple[Any, ...]:
     try:
-        if urllib.parse.urlparse(path).scheme:
-            yaml = str(urllib.request.urlopen(path).read(), "utf-8")
+        if urllib.parse.urlparse(path).scheme in ('https', 'file'):
+            yaml = str(urllib.request.urlopen(path).read(), "utf-8-sig")
         else:
             with open(path, 'rb') as f:
-                yaml = str(f.read(), "utf-8")
+                yaml = str(f.read(), "utf-8-sig")
     except Exception as e:
         raise Exception(f"Failed to read weights ({path})") from e
 
-    return parse_yaml(yaml)
+    return tuple(parse_yamls(yaml))
 
 
-def interpret_on_off(value):
+def interpret_on_off(value) -> bool:
     return {"on": True, "off": False}.get(value, value)
 
 
-def convert_to_on_off(value):
+def convert_to_on_off(value) -> str:
     return {True: "on", False: "off"}.get(value, value)
 
 
-def get_choice_legacy(option, root, value=None) -> typing.Any:
+def get_choice_legacy(option, root, value=None) -> Any:
     if option not in root:
         return value
     if type(root[option]) is list:
@@ -244,7 +263,7 @@ def get_choice_legacy(option, root, value=None) -> typing.Any:
     raise RuntimeError(f"All options specified in \"{option}\" are weighted as zero.")
 
 
-def get_choice(option, root, value=None) -> typing.Any:
+def get_choice(option, root, value=None) -> Any:
     if option not in root:
         return value
     if type(root[option]) is list:
@@ -264,11 +283,11 @@ class SafeDict(dict):
 
 
 def handle_name(name: str, player: int, name_counter: Counter):
-    name_counter[name] += 1
+    name_counter[name.lower()] += 1
+    number = name_counter[name.lower()]
     new_name = "%".join([x.replace("%number%", "{number}").replace("%player%", "{player}") for x in name.split("%%")])
-    new_name = string.Formatter().vformat(new_name, (), SafeDict(number=name_counter[name],
-                                                                 NUMBER=(name_counter[name] if name_counter[
-                                                                                                   name] > 1 else ''),
+    new_name = string.Formatter().vformat(new_name, (), SafeDict(number=number,
+                                                                 NUMBER=(number if number > 1 else ''),
                                                                  player=player,
                                                                  PLAYER=(player if player > 1 else '')))
     new_name = new_name.strip()[:16]
@@ -277,26 +296,13 @@ def handle_name(name: str, player: int, name_counter: Counter):
     return new_name
 
 
-def prefer_int(input_data: str) -> typing.Union[str, int]:
+def prefer_int(input_data: str) -> Union[str, int]:
     try:
         return int(input_data)
     except:
         return input_data
 
 
-available_boss_names: typing.Set[str] = {boss.lower() for boss in Bosses.boss_table if boss not in
-                                         {'Agahnim', 'Agahnim2', 'Ganon'}}
-available_boss_locations: typing.Set[str] = {f"{loc.lower()}{f' {level}' if level else ''}" for loc, level in
-                                             Bosses.boss_location_table}
-
-boss_shuffle_options = {None: 'none',
-                        'none': 'none',
-                        'basic': 'basic',
-                        'full': 'full',
-                        'chaos': 'chaos',
-                        'singularity': 'singularity'
-                        }
-
 goals = {
     'ganon': 'ganon',
     'crystals': 'crystals',
@@ -311,7 +317,7 @@ goals = {
 }
 
 
-def roll_percentage(percentage: typing.Union[int, float]) -> bool:
+def roll_percentage(percentage: Union[int, float]) -> bool:
     """Roll a percentage chance.
     percentage is expected to be in range [0, 100]"""
     return random.random() < (float(percentage) / 100)
@@ -329,8 +335,30 @@ def update_weights(weights: dict, new_weights: dict, type: str, name: str) -> di
     return weights
 
 
+def roll_meta_option(option_key, game: str, category_dict: Dict) -> Any:
+    if not game:
+        return get_choice(option_key, category_dict)
+    if game in AutoWorldRegister.world_types:
+        game_world = AutoWorldRegister.world_types[game]
+        options = ChainMap(game_world.option_definitions, Options.per_game_common_options)
+        if option_key in options:
+            if options[option_key].supports_weighting:
+                return get_choice(option_key, category_dict)
+            return category_dict[option_key]
+    if game == "A Link to the Past":  # TODO wow i hate this
+        if option_key in {"glitches_required", "dark_room_logic", "entrance_shuffle", "goals", "triforce_pieces_mode",
+                          "triforce_pieces_percentage", "triforce_pieces_available", "triforce_pieces_extra",
+                          "triforce_pieces_required", "shop_shuffle", "mode", "item_pool", "item_functionality",
+                          "boss_shuffle", "enemy_damage", "enemy_health", "timer", "countdown_start_time",
+                          "red_clock_time", "blue_clock_time", "green_clock_time", "dungeon_counters", "shuffle_prizes",
+                          "misery_mire_medallion", "turtle_rock_medallion", "sprite_pool", "sprite",
+                          "random_sprite_on_event"}:
+            return get_choice(option_key, category_dict)
+    raise Exception(f"Error generating meta option {option_key} for {game}.")
+
+
 def roll_linked_options(weights: dict) -> dict:
-    weights = weights.copy()  # make sure we don't write back to other weights sets in same_settings
+    weights = copy.deepcopy(weights)  # make sure we don't write back to other weights sets in same_settings
     for option_set in weights["linked_options"]:
         if "name" not in option_set:
             raise ValueError("One of your linked options does not have a name.")
@@ -346,13 +374,13 @@ def roll_linked_options(weights: dict) -> dict:
             else:
                 logging.debug(f"linked option {option_set['name']} skipped.")
         except Exception as e:
-            raise ValueError(f"Linked option {option_set['name']} is destroyed. "
+            raise ValueError(f"Linked option {option_set['name']} is invalid. "
                              f"Please fix your linked option.") from e
     return weights
 
 
 def roll_triggers(weights: dict, triggers: list) -> dict:
-    weights = weights.copy()  # make sure we don't write back to other weights sets in same_settings
+    weights = copy.deepcopy(weights)  # make sure we don't write back to other weights sets in same_settings
     weights["_Generator_Version"] = Utils.__version__
     for i, option_set in enumerate(triggers):
         try:
@@ -376,47 +404,12 @@ def roll_triggers(weights: dict, triggers: list) -> dict:
                     update_weights(currently_targeted_weights, category_options, "Triggered", option_set["option_name"])
 
         except Exception as e:
-            raise ValueError(f"Your trigger number {i + 1} is destroyed. "
+            raise ValueError(f"Your trigger number {i + 1} is invalid. "
                              f"Please fix your triggers.") from e
     return weights
 
 
-def get_plando_bosses(boss_shuffle: str, plando_options: typing.Set[str]) -> str:
-    if boss_shuffle in boss_shuffle_options:
-        return boss_shuffle_options[boss_shuffle]
-    elif "bosses" in plando_options:
-        options = boss_shuffle.lower().split(";")
-        remainder_shuffle = "none"  # vanilla
-        bosses = []
-        for boss in options:
-            if boss in boss_shuffle_options:
-                remainder_shuffle = boss_shuffle_options[boss]
-            elif "-" in boss:
-                loc, boss_name = boss.split("-")
-                if boss_name not in available_boss_names:
-                    raise ValueError(f"Unknown Boss name {boss_name}")
-                if loc not in available_boss_locations:
-                    raise ValueError(f"Unknown Boss Location {loc}")
-                level = ''
-                if loc.split(" ")[-1] in {"top", "middle", "bottom"}:
-                    # split off level
-                    loc = loc.split(" ")
-                    level = f" {loc[-1]}"
-                    loc = " ".join(loc[:-1])
-                loc = loc.title().replace("Of", "of")
-                if not Bosses.can_place_boss(boss_name.title(), loc, level):
-                    raise ValueError(f"Cannot place {boss_name} at {loc}{level}")
-                bosses.append(boss)
-            elif boss not in available_boss_names:
-                raise ValueError(f"Unknown Boss name or Boss shuffle option {boss}.")
-            else:
-                bosses.append(boss)
-        return ";".join(bosses + [remainder_shuffle])
-    else:
-        raise Exception(f"Boss Shuffle {boss_shuffle} is unknown and boss plando is turned off.")
-
-
-def handle_option(ret: argparse.Namespace, game_weights: dict, option_key: str, option: type(Options.Option)):
+def handle_option(ret: argparse.Namespace, game_weights: dict, option_key: str, option: type(Options.Option), plando_options: PlandoOptions):
     if option_key in game_weights:
         try:
             if not option.supports_weighting:
@@ -427,22 +420,12 @@ def handle_option(ret: argparse.Namespace, game_weights: dict, option_key: str,
         except Exception as e:
             raise Exception(f"Error generating option {option_key} in {ret.game}") from e
         else:
-            # verify item names existing
-            if getattr(player_option, "verify_item_name", False):
-                for item_name in player_option.value:
-                    if item_name not in AutoWorldRegister.world_types[ret.game].item_names:
-                        raise Exception(f"Item {item_name} from option {player_option} "
-                                        f"is not a valid item name from {ret.game}")
-            elif getattr(player_option, "verify_location_name", False):
-                for location_name in player_option.value:
-                    if location_name not in AutoWorldRegister.world_types[ret.game].location_names:
-                        raise Exception(f"Location {location_name} from option {player_option} "
-                                        f"is not a valid location name from {ret.game}")
+            player_option.verify(AutoWorldRegister.world_types[ret.game], ret.name, plando_options)
     else:
-        setattr(ret, option_key, option(option.default))
+        setattr(ret, option_key, option.from_any(option.default))  # call the from_any here to support default "random"
 
 
-def roll_settings(weights: dict, plando_options: typing.Set[str] = frozenset(("bosses",))):
+def roll_settings(weights: dict, plando_options: PlandoOptions = PlandoOptions.bosses):
     if "linked_options" in weights:
         weights = roll_linked_options(weights)
 
@@ -455,24 +438,23 @@ def roll_settings(weights: dict, plando_options: typing.Set[str] = frozenset(("b
         if tuplize_version(version) > version_tuple:
             raise Exception(f"Settings reports required version of generator is at least {version}, "
                             f"however generator is of version {__version__}")
-        required_plando_options = requirements.get("plando", "")
-        if required_plando_options:
-            required_plando_options = set(option.strip() for option in required_plando_options.split(","))
-            required_plando_options -= plando_options
+        required_plando_options = PlandoOptions.from_option_string(requirements.get("plando", ""))
+        if required_plando_options not in plando_options:
             if required_plando_options:
-                if len(required_plando_options) == 1:
-                    raise Exception(f"Settings reports required plando module {', '.join(required_plando_options)}, "
-                                    f"which is not enabled.")
-                else:
-                    raise Exception(f"Settings reports required plando modules {', '.join(required_plando_options)}, "
-                                    f"which are not enabled.")
+                raise Exception(f"Settings reports required plando module {str(required_plando_options)}, "
+                                f"which is not enabled.")
 
     ret = argparse.Namespace()
     for option_key in Options.per_game_common_options:
-        if option_key in weights:
+        if option_key in weights and option_key not in Options.common_options:
             raise Exception(f"Option {option_key} has to be in a game's section, not on its own.")
 
     ret.game = get_choice("game", weights)
+    if ret.game not in AutoWorldRegister.world_types:
+        picks = Utils.get_fuzzy_results(ret.game, AutoWorldRegister.world_types, limit=1)[0]
+        raise Exception(f"No world found to handle game {ret.game}. Did you mean '{picks[0]}' ({picks[1]}% sure)? "
+                        f"Check your spelling or installation of that world.")
+
     if ret.game not in weights:
         raise Exception(f"No game options for selected game \"{ret.game}\" found.")
 
@@ -487,70 +469,33 @@ def roll_settings(weights: dict, plando_options: typing.Set[str] = frozenset(("b
     for option_key, option in Options.common_options.items():
         setattr(ret, option_key, option.from_any(get_choice(option_key, weights, option.default)))
 
-    if ret.game in AutoWorldRegister.world_types:
-        for option_key, option in world_type.options.items():
-            handle_option(ret, game_weights, option_key, option)
-        for option_key, option in Options.per_game_common_options.items():
-            handle_option(ret, game_weights, option_key, option)
-        if "items" in plando_options:
-            ret.plando_items = roll_item_plando(world_type, game_weights)
-        if ret.game == "Minecraft" or ret.game == "Ocarina of Time":
-            # bad hardcoded behavior to make this work for now
-            ret.plando_connections = []
-            if "connections" in plando_options:
-                options = game_weights.get("plando_connections", [])
-                for placement in options:
-                    if roll_percentage(get_choice("percentage", placement, 100)):
-                        ret.plando_connections.append(PlandoConnection(
-                            get_choice("entrance", placement),
-                            get_choice("exit", placement),
-                            get_choice("direction", placement)
-                        ))
-        elif ret.game == "A Link to the Past":
-            roll_alttp_settings(ret, game_weights, plando_options)
-    else:
-        raise Exception(f"Unsupported game {ret.game}")
+    for option_key, option in world_type.option_definitions.items():
+        handle_option(ret, game_weights, option_key, option, plando_options)
+    for option_key, option in Options.per_game_common_options.items():
+        # skip setting this option if already set from common_options, defaulting to root option
+        if option_key not in world_type.option_definitions and \
+                (option_key not in Options.common_options or option_key in game_weights):
+            handle_option(ret, game_weights, option_key, option, plando_options)
+    if PlandoOptions.items in plando_options:
+        ret.plando_items = game_weights.get("plando_items", [])
+    if ret.game == "Minecraft" or ret.game == "Ocarina of Time":
+        # bad hardcoded behavior to make this work for now
+        ret.plando_connections = []
+        if PlandoOptions.connections in plando_options:
+            options = game_weights.get("plando_connections", [])
+            for placement in options:
+                if roll_percentage(get_choice("percentage", placement, 100)):
+                    ret.plando_connections.append(PlandoConnection(
+                        get_choice("entrance", placement),
+                        get_choice("exit", placement),
+                        get_choice("direction", placement)
+                    ))
+    elif ret.game == "A Link to the Past":
+        roll_alttp_settings(ret, game_weights, plando_options)
+
     return ret
 
 
-def roll_item_plando(world_type, weights):
-    plando_items = []
-
-    def add_plando_item(item: str, location: str):
-        if item not in world_type.item_name_to_id:
-            raise Exception(f"Could not plando item {item} as the item was not recognized")
-        if location not in world_type.location_name_to_id:
-            raise Exception(
-                f"Could not plando item {item} at location {location} as the location was not recognized")
-        plando_items.append(PlandoItem(item, location, location_world, from_pool, force))
-
-    options = weights.get("plando_items", [])
-    for placement in options:
-        if roll_percentage(get_choice_legacy("percentage", placement, 100)):
-            from_pool = get_choice_legacy("from_pool", placement, PlandoItem._field_defaults["from_pool"])
-            location_world = get_choice_legacy("world", placement, PlandoItem._field_defaults["world"])
-            force = str(get_choice_legacy("force", placement, PlandoItem._field_defaults["force"])).lower()
-            if "items" in placement and "locations" in placement:
-                items = placement["items"]
-                locations = placement["locations"]
-                if isinstance(items, dict):
-                    item_list = []
-                    for key, value in items.items():
-                        item_list += [key] * value
-                    items = item_list
-                if not items or not locations:
-                    raise Exception("You must specify at least one item and one location to place items.")
-                random.shuffle(items)
-                random.shuffle(locations)
-                for item, location in zip(items, locations):
-                    add_plando_item(item, location)
-            else:
-                item = get_choice_legacy("item", placement, get_choice_legacy("items", placement))
-                location = get_choice_legacy("location", placement)
-                add_plando_item(item, location)
-    return plando_items
-
-
 def roll_alttp_settings(ret: argparse.Namespace, weights, plando_options):
     if "dungeon_items" in weights and get_choice_legacy('dungeon_items', weights, "none") != "none":
         raise Exception(f"dungeon_items key in A Link to the Past was removed, but is present in these weights as {get_choice_legacy('dungeon_items', weights, False)}.")
@@ -580,9 +525,6 @@ def roll_alttp_settings(ret: argparse.Namespace, weights, plando_options):
 
     ret.goal = goals[goal]
 
-    # TODO consider moving open_pyramid to an automatic variable in the core roller, set to True when
-    # fast ganon + ganon at hole
-    ret.open_pyramid = get_choice_legacy('open_pyramid', weights, 'goal')
 
     extra_pieces = get_choice_legacy('triforce_pieces_mode', weights, 'available')
 
@@ -614,8 +556,6 @@ def roll_alttp_settings(ret: argparse.Namespace, weights, plando_options):
 
     ret.item_functionality = get_choice_legacy('item_functionality', weights)
 
-    boss_shuffle = get_choice_legacy('boss_shuffle', weights)
-    ret.shufflebosses = get_plando_bosses(boss_shuffle, plando_options)
 
     ret.enemy_damage = {None: 'default',
                         'default': 'default',
@@ -654,7 +594,7 @@ def roll_alttp_settings(ret: argparse.Namespace, weights, plando_options):
             raise Exception(f"unknown Medallion {medallion} for {'misery mire' if index == 0 else 'turtle rock'}")
 
     ret.plando_texts = {}
-    if "texts" in plando_options:
+    if PlandoOptions.texts in plando_options:
         tt = TextTable()
         tt.removeUnwantedText()
         options = weights.get("plando_texts", [])
@@ -666,7 +606,7 @@ def roll_alttp_settings(ret: argparse.Namespace, weights, plando_options):
                 ret.plando_texts[at] = str(get_choice_legacy("text", placement))
 
     ret.plando_connections = []
-    if "connections" in plando_options:
+    if PlandoOptions.connections in plando_options:
         options = weights.get("plando_connections", [])
         for placement in options:
             if roll_percentage(get_choice_legacy("percentage", placement, 100)):

KH2Client.py

@@ -0,0 +1,894 @@
+import os
+import asyncio
+import ModuleUpdate
+import json
+import Utils
+from pymem import pymem
+from worlds.kh2.Items import exclusionItem_table, CheckDupingItems
+from worlds.kh2 import all_locations, item_dictionary_table, exclusion_table
+
+from worlds.kh2.WorldLocations import *
+
+from worlds import network_data_package
+
+if __name__ == "__main__":
+    Utils.init_logging("KH2Client", exception_logger="Client")
+
+from NetUtils import ClientStatus
+from CommonClient import gui_enabled, logger, get_base_parser, ClientCommandProcessor, \
+    CommonContext, server_loop
+
+ModuleUpdate.update()
+
+kh2_loc_name_to_id = network_data_package["games"]["Kingdom Hearts 2"]["location_name_to_id"]
+
+
+# class KH2CommandProcessor(ClientCommandProcessor):
+
+
+class KH2Context(CommonContext):
+    # command_processor: int = KH2CommandProcessor
+    game = "Kingdom Hearts 2"
+    items_handling = 0b101  # Indicates you get items sent from other worlds.
+
+    def __init__(self, server_address, password):
+        super(KH2Context, self).__init__(server_address, password)
+        self.kh2LocalItems = None
+        self.ability = None
+        self.growthlevel = None
+        self.KH2_sync_task = None
+        self.syncing = False
+        self.kh2connected = False
+        self.serverconneced = False
+        self.item_name_to_data = {name: data for name, data, in item_dictionary_table.items()}
+        self.location_name_to_data = {name: data for name, data, in all_locations.items()}
+        self.lookup_id_to_item: typing.Dict[int, str] = {data.code: item_name for item_name, data in
+                                                         item_dictionary_table.items() if data.code}
+        self.lookup_id_to_Location: typing.Dict[int, str] = {data.code: item_name for item_name, data in
+                                                             all_locations.items() if data.code}
+        self.location_name_to_worlddata = {name: data for name, data, in all_world_locations.items()}
+
+        self.location_table = {}
+        self.collectible_table = {}
+        self.collectible_override_flags_address = 0
+        self.collectible_offsets = {}
+        self.sending = []
+        # list used to keep track of locations+items player has. Used for disoneccting
+        self.kh2seedsave = None
+        self.slotDataProgressionNames = {}
+        self.kh2seedname = None
+        self.kh2slotdata = None
+        self.itemamount = {}
+        # sora equipped, valor equipped, master equipped, final equipped
+        self.keybladeAnchorList = (0x24F0, 0x32F4, 0x339C, 0x33D4)
+        if "localappdata" in os.environ:
+            self.game_communication_path = os.path.expandvars(r"%localappdata%\KH2AP")
+        self.amountOfPieces = 0
+        # hooked object
+        self.kh2 = None
+        self.ItemIsSafe = False
+        self.game_connected = False
+        self.finalxemnas = False
+        self.worldid = {
+            #  1:   {},  # world of darkness (story cutscenes)
+            2:  TT_Checks,
+            #  3:   {},  # destiny island doesn't have checks to ima put tt checks here
+            4:  HB_Checks,
+            5:  BC_Checks,
+            6:  Oc_Checks,
+            7:  AG_Checks,
+            8:  LoD_Checks,
+            9:  HundredAcreChecks,
+            10: PL_Checks,
+            11: DC_Checks,  # atlantica isn't a supported world. if you go in atlantica it will check dc
+            12: DC_Checks,
+            13: TR_Checks,
+            14: HT_Checks,
+            15: HB_Checks,  # world map, but you only go to the world map while on the way to goa so checking hb
+            16: PR_Checks,
+            17: SP_Checks,
+            18: TWTNW_Checks,
+            #  255: {},  # starting screen
+        }
+        # 0x2A09C00+0x40 is the sve anchor. +1 is the last saved room
+        self.sveroom = 0x2A09C00 + 0x41
+        # 0 not in battle 1 in yellow battle 2 red battle #short
+        self.inBattle = 0x2A0EAC4 + 0x40
+        self.onDeath = 0xAB9078
+        # PC Address anchors
+        self.Now = 0x0714DB8
+        self.Save = 0x09A70B0
+        self.Sys3 = 0x2A59DF0
+        self.Bt10 = 0x2A74880
+        self.BtlEnd = 0x2A0D3E0
+        self.Slot1 = 0x2A20C98
+
+        self.chest_set = set(exclusion_table["Chests"])
+
+        self.keyblade_set = set(CheckDupingItems["Weapons"]["Keyblades"])
+        self.staff_set = set(CheckDupingItems["Weapons"]["Staffs"])
+        self.shield_set = set(CheckDupingItems["Weapons"]["Shields"])
+
+        self.all_weapons = self.keyblade_set.union(self.staff_set).union(self.shield_set)
+
+        self.equipment_categories = CheckDupingItems["Equipment"]
+        self.armor_set = set(self.equipment_categories["Armor"])
+        self.accessories_set = set(self.equipment_categories["Accessories"])
+        self.all_equipment = self.armor_set.union(self.accessories_set)
+
+        self.Equipment_Anchor_Dict = {
+            "Armor":       [0x2504, 0x2506, 0x2508, 0x250A],
+            "Accessories": [0x2514, 0x2516, 0x2518, 0x251A]}
+
+        self.AbilityQuantityDict = {}
+        self.ability_categories = CheckDupingItems["Abilities"]
+
+        self.sora_ability_set = set(self.ability_categories["Sora"])
+        self.donald_ability_set = set(self.ability_categories["Donald"])
+        self.goofy_ability_set = set(self.ability_categories["Goofy"])
+
+        self.all_abilities = self.sora_ability_set.union(self.donald_ability_set).union(self.goofy_ability_set)
+
+        self.boost_set = set(CheckDupingItems["Boosts"])
+        self.stat_increase_set = set(CheckDupingItems["Stat Increases"])
+        self.AbilityQuantityDict = {item: self.item_name_to_data[item].quantity for item in self.all_abilities}
+        #  Growth:[level 1,level 4,slot]
+        self.growth_values_dict = {"High Jump":    [0x05E, 0x061, 0x25DA],
+                                   "Quick Run":    [0x62, 0x65, 0x25DC],
+                                   "Dodge Roll":   [0x234, 0x237, 0x25DE],
+                                   "Aerial Dodge": [0x066, 0x069, 0x25E0],
+                                   "Glide":        [0x6A, 0x6D, 0x25E2]}
+        self.boost_to_anchor_dict = {
+            "Power Boost":   0x24F9,
+            "Magic Boost":   0x24FA,
+            "Defense Boost": 0x24FB,
+            "AP Boost":      0x24F8}
+
+        self.AbilityCodeList = [self.item_name_to_data[item].code for item in exclusionItem_table["Ability"]]
+        self.master_growth = {"High Jump", "Quick Run", "Dodge Roll", "Aerial Dodge", "Glide"}
+
+        self.bitmask_item_code = [
+            0x130000, 0x130001, 0x130002, 0x130003, 0x130004, 0x130005, 0x130006, 0x130007
+            , 0x130008, 0x130009, 0x13000A, 0x13000B, 0x13000C
+            , 0x13001F, 0x130020, 0x130021, 0x130022, 0x130023
+            , 0x13002A, 0x13002B, 0x13002C, 0x13002D]
+
+    async def server_auth(self, password_requested: bool = False):
+        if password_requested and not self.password:
+            await super(KH2Context, self).server_auth(password_requested)
+        await self.get_username()
+        await self.send_connect()
+
+    async def connection_closed(self):
+        self.kh2connected = False
+        self.serverconneced = False
+        if self.kh2seedname is not None and self.auth is not None:
+            with open(os.path.join(self.game_communication_path, f"kh2save{self.kh2seedname}{self.auth}.json"),
+                      'w') as f:
+                f.write(json.dumps(self.kh2seedsave, indent=4))
+        await super(KH2Context, self).connection_closed()
+
+    async def disconnect(self, allow_autoreconnect: bool = False):
+        self.kh2connected = False
+        self.serverconneced = False
+        if self.kh2seedname not in {None} and self.auth not in {None}:
+            with open(os.path.join(self.game_communication_path, f"kh2save{self.kh2seedname}{self.auth}.json"),
+                      'w') as f:
+                f.write(json.dumps(self.kh2seedsave, indent=4))
+        await super(KH2Context, self).disconnect()
+
+    @property
+    def endpoints(self):
+        if self.server:
+            return [self.server]
+        else:
+            return []
+
+    async def shutdown(self):
+        if self.kh2seedname not in {None} and self.auth not in {None}:
+            with open(os.path.join(self.game_communication_path, f"kh2save{self.kh2seedname}{self.auth}.json"),
+                      'w') as f:
+                f.write(json.dumps(self.kh2seedsave, indent=4))
+        await super(KH2Context, self).shutdown()
+
+    def on_package(self, cmd: str, args: dict):
+        if cmd in {"RoomInfo"}:
+            self.kh2seedname = args['seed_name']
+            if not os.path.exists(self.game_communication_path):
+                os.makedirs(self.game_communication_path)
+            if not os.path.exists(self.game_communication_path + f"\kh2save{self.kh2seedname}{self.auth}.json"):
+                self.kh2seedsave = {"itemIndex":        -1,
+                                    # back of soras invo is 0x25E2. Growth should be moved there
+                                    #  Character: [back of invo, front of invo]
+                                    "SoraInvo":         [0x25D8, 0x2546],
+                                    "DonaldInvo":       [0x26F4, 0x2658],
+                                    "GoofyInvo":        [0x280A, 0x276C],
+                                    "AmountInvo":       {
+                                        "ServerItems": {
+                                            "Ability":      {},
+                                            "Amount":       {},
+                                            "Growth":       {"High Jump":    0, "Quick Run": 0, "Dodge Roll": 0,
+                                                             "Aerial Dodge": 0,
+                                                             "Glide":        0},
+                                            "Bitmask":      [],
+                                            "Weapon":       {"Sora": [], "Donald": [], "Goofy": []},
+                                            "Equipment":    [],
+                                            "Magic":        {},
+                                            "StatIncrease": {},
+                                            "Boost":        {},
+                                        },
+                                        "LocalItems":  {
+                                            "Ability":      {},
+                                            "Amount":       {},
+                                            "Growth":       {"High Jump":    0, "Quick Run": 0, "Dodge Roll": 0,
+                                                             "Aerial Dodge": 0, "Glide": 0},
+                                            "Bitmask":      [],
+                                            "Weapon":       {"Sora": [], "Donald": [], "Goofy": []},
+                                            "Equipment":    [],
+                                            "Magic":        {},
+                                            "StatIncrease": {},
+                                            "Boost":        {},
+                                        }},
+                                    #  1,3,255 are in this list in case the player gets locations in those "worlds" and I need to still have them checked
+                                    "LocationsChecked": [],
+                                    "Levels":           {
+                                        "SoraLevel":   0,
+                                        "ValorLevel":  0,
+                                        "WisdomLevel": 0,
+                                        "LimitLevel":  0,
+                                        "MasterLevel": 0,
+                                        "FinalLevel":  0,
+                                    },
+                                    "SoldEquipment":    [],
+                                    "SoldBoosts":       {"Power Boost":   0,
+                                                         "Magic Boost":   0,
+                                                         "Defense Boost": 0,
+                                                         "AP Boost":      0}
+                                    }
+                with open(os.path.join(self.game_communication_path, f"kh2save{self.kh2seedname}{self.auth}.json"),
+                          'wt') as f:
+                    pass
+                self.locations_checked = set()
+            elif os.path.exists(self.game_communication_path + f"\kh2save{self.kh2seedname}{self.auth}.json"):
+                with open(self.game_communication_path + f"\kh2save{self.kh2seedname}{self.auth}.json", 'r') as f:
+                    self.kh2seedsave = json.load(f)
+                    self.locations_checked = set(self.kh2seedsave["LocationsChecked"])
+            self.serverconneced = True
+
+        if cmd in {"Connected"}:
+            self.kh2slotdata = args['slot_data']
+            self.kh2LocalItems = {int(location): item for location, item in self.kh2slotdata["LocalItems"].items()}
+            try:
+                self.kh2 = pymem.Pymem(process_name="KINGDOM HEARTS II FINAL MIX")
+                logger.info("You are now auto-tracking")
+                self.kh2connected = True
+            except Exception as e:
+                logger.info("Line 247")
+                if self.kh2connected:
+                    logger.info("Connection Lost")
+                    self.kh2connected = False
+                logger.info(e)
+
+        if cmd in {"ReceivedItems"}:
+            start_index = args["index"]
+            if start_index == 0:
+                # resetting everything that were sent from the server
+                self.kh2seedsave["SoraInvo"][0] = 0x25D8
+                self.kh2seedsave["DonaldInvo"][0] = 0x26F4
+                self.kh2seedsave["GoofyInvo"][0] = 0x280A
+                self.kh2seedsave["itemIndex"] = - 1
+                self.kh2seedsave["AmountInvo"]["ServerItems"] = {
+                    "Ability":      {},
+                    "Amount":       {},
+                    "Growth":       {"High Jump":    0, "Quick Run": 0, "Dodge Roll": 0,
+                                     "Aerial Dodge": 0,
+                                     "Glide":        0},
+                    "Bitmask":      [],
+                    "Weapon":       {"Sora": [], "Donald": [], "Goofy": []},
+                    "Equipment":    [],
+                    "Magic":        {},
+                    "StatIncrease": {},
+                    "Boost":        {},
+                }
+            if start_index > self.kh2seedsave["itemIndex"]:
+                self.kh2seedsave["itemIndex"] = start_index
+                for item in args['items']:
+                    asyncio.create_task(self.give_item(item.item))
+
+        if cmd in {"RoomUpdate"}:
+            if "checked_locations" in args:
+                new_locations = set(args["checked_locations"])
+                # TODO: make this take locations from other players on the same slot so proper coop happens
+                #  items_to_give = [self.kh2slotdata["LocalItems"][str(location_id)] for location_id in new_locations if
+                #                 location_id in self.kh2LocalItems.keys()]
+                self.checked_locations |= new_locations
+
+    async def checkWorldLocations(self):
+        try:
+            currentworldint = int.from_bytes(self.kh2.read_bytes(self.kh2.base_address + 0x0714DB8, 1), "big")
+            if currentworldint in self.worldid:
+                curworldid = self.worldid[currentworldint]
+                for location, data in curworldid.items():
+                    locationId = kh2_loc_name_to_id[location]
+                    if locationId not in self.locations_checked \
+                            and (int.from_bytes(
+                            self.kh2.read_bytes(self.kh2.base_address + self.Save + data.addrObtained, 1),
+                            "big") & 0x1 << data.bitIndex) > 0:
+                        self.sending = self.sending + [(int(locationId))]
+        except Exception as e:
+            logger.info("Line 285")
+            if self.kh2connected:
+                logger.info("Connection Lost.")
+                self.kh2connected = False
+            logger.info(e)
+
+    async def checkLevels(self):
+        try:
+            for location, data in SoraLevels.items():
+                currentLevel = int.from_bytes(
+                        self.kh2.read_bytes(self.kh2.base_address + self.Save + 0x24FF, 1), "big")
+                locationId = kh2_loc_name_to_id[location]
+                if locationId not in self.locations_checked \
+                        and currentLevel >= data.bitIndex:
+                    if self.kh2seedsave["Levels"]["SoraLevel"] < currentLevel:
+                        self.kh2seedsave["Levels"]["SoraLevel"] = currentLevel
+                    self.sending = self.sending + [(int(locationId))]
+            formDict = {
+                0: ["ValorLevel", ValorLevels], 1: ["WisdomLevel", WisdomLevels], 2: ["LimitLevel", LimitLevels],
+                3: ["MasterLevel", MasterLevels], 4: ["FinalLevel", FinalLevels]}
+            for i in range(5):
+                for location, data in formDict[i][1].items():
+                    formlevel = int.from_bytes(
+                            self.kh2.read_bytes(self.kh2.base_address + self.Save + data.addrObtained, 1), "big")
+                    locationId = kh2_loc_name_to_id[location]
+                    if locationId not in self.locations_checked \
+                            and formlevel >= data.bitIndex:
+                        if formlevel > self.kh2seedsave["Levels"][formDict[i][0]]:
+                            self.kh2seedsave["Levels"][formDict[i][0]] = formlevel
+                        self.sending = self.sending + [(int(locationId))]
+        except Exception as e:
+            logger.info("Line 312")
+            if self.kh2connected:
+                logger.info("Connection Lost.")
+                self.kh2connected = False
+            logger.info(e)
+
+    async def checkSlots(self):
+        try:
+            for location, data in weaponSlots.items():
+                locationId = kh2_loc_name_to_id[location]
+                if locationId not in self.locations_checked:
+                    if int.from_bytes(self.kh2.read_bytes(self.kh2.base_address + self.Save + data.addrObtained, 1),
+                                      "big") > 0:
+                        self.sending = self.sending + [(int(locationId))]
+
+            for location, data in formSlots.items():
+                locationId = kh2_loc_name_to_id[location]
+                if locationId not in self.locations_checked:
+                    if int.from_bytes(self.kh2.read_bytes(self.kh2.base_address + self.Save + data.addrObtained, 1),
+                                      "big") & 0x1 << data.bitIndex > 0:
+                        # self.locations_checked
+                        self.sending = self.sending + [(int(locationId))]
+
+        except Exception as e:
+            if self.kh2connected:
+                logger.info("Line 333")
+                logger.info("Connection Lost.")
+                self.kh2connected = False
+            logger.info(e)
+
+    async def verifyChests(self):
+        try:
+            for location in self.locations_checked:
+                locationName = self.lookup_id_to_Location[location]
+                if locationName in self.chest_set:
+                    if locationName in self.location_name_to_worlddata.keys():
+                        locationData = self.location_name_to_worlddata[locationName]
+                        if int.from_bytes(
+                                self.kh2.read_bytes(self.kh2.base_address + self.Save + locationData.addrObtained, 1),
+                                "big") & 0x1 << locationData.bitIndex == 0:
+                            roomData = int.from_bytes(
+                                    self.kh2.read_bytes(self.kh2.base_address + self.Save + locationData.addrObtained,
+                                                        1), "big")
+                            self.kh2.write_bytes(self.kh2.base_address + self.Save + locationData.addrObtained,
+                                                 (roomData | 0x01 << locationData.bitIndex).to_bytes(1, 'big'), 1)
+
+        except Exception as e:
+            if self.kh2connected:
+                logger.info("Line 350")
+                logger.info("Connection Lost.")
+                self.kh2connected = False
+            logger.info(e)
+
+    async def verifyLevel(self):
+        for leveltype, anchor in {"SoraLevel":   0x24FF,
+                                  "ValorLevel":  0x32F6,
+                                  "WisdomLevel": 0x332E,
+                                  "LimitLevel":  0x3366,
+                                  "MasterLevel": 0x339E,
+                                  "FinalLevel":  0x33D6}.items():
+            if int.from_bytes(self.kh2.read_bytes(self.kh2.base_address + self.Save + anchor, 1), "big") < \
+                    self.kh2seedsave["Levels"][leveltype]:
+                self.kh2.write_bytes(self.kh2.base_address + self.Save + anchor,
+                                     (self.kh2seedsave["Levels"][leveltype]).to_bytes(1, 'big'), 1)
+
+    async def give_item(self, item, ItemType="ServerItems"):
+        try:
+            itemname = self.lookup_id_to_item[item]
+            itemcode = self.item_name_to_data[itemname]
+            if itemcode.ability:
+                abilityInvoType = 0
+                TwilightZone = 2
+                if ItemType == "LocalItems":
+                    abilityInvoType = 1
+                    TwilightZone = -2
+                if itemname in {"High Jump", "Quick Run", "Dodge Roll", "Aerial Dodge", "Glide"}:
+                    self.kh2seedsave["AmountInvo"][ItemType]["Growth"][itemname] += 1
+                    return
+
+                if itemname not in self.kh2seedsave["AmountInvo"][ItemType]["Ability"]:
+                    self.kh2seedsave["AmountInvo"][ItemType]["Ability"][itemname] = []
+                    #  appending the slot that the ability should be in
+
+                if len(self.kh2seedsave["AmountInvo"][ItemType]["Ability"][itemname]) < \
+                        self.AbilityQuantityDict[itemname]:
+                    if itemname in self.sora_ability_set:
+                        self.kh2seedsave["AmountInvo"][ItemType]["Ability"][itemname].append(
+                                self.kh2seedsave["SoraInvo"][abilityInvoType])
+                        self.kh2seedsave["SoraInvo"][abilityInvoType] -= TwilightZone
+                    elif itemname in self.donald_ability_set:
+                        self.kh2seedsave["AmountInvo"][ItemType]["Ability"][itemname].append(
+                                self.kh2seedsave["DonaldInvo"][abilityInvoType])
+                        self.kh2seedsave["DonaldInvo"][abilityInvoType] -= TwilightZone
+                    else:
+                        self.kh2seedsave["AmountInvo"][ItemType]["Ability"][itemname].append(
+                                self.kh2seedsave["GoofyInvo"][abilityInvoType])
+                        self.kh2seedsave["GoofyInvo"][abilityInvoType] -= TwilightZone
+
+            elif itemcode.code in self.bitmask_item_code:
+
+                if itemname not in self.kh2seedsave["AmountInvo"][ItemType]["Bitmask"]:
+                    self.kh2seedsave["AmountInvo"][ItemType]["Bitmask"].append(itemname)
+
+            elif itemcode.memaddr in {0x3594, 0x3595, 0x3596, 0x3597, 0x35CF, 0x35D0}:
+
+                if itemname in self.kh2seedsave["AmountInvo"][ItemType]["Magic"]:
+                    self.kh2seedsave["AmountInvo"][ItemType]["Magic"][itemname] += 1
+                else:
+                    self.kh2seedsave["AmountInvo"][ItemType]["Magic"][itemname] = 1
+            elif itemname in self.all_equipment:
+
+                self.kh2seedsave["AmountInvo"][ItemType]["Equipment"].append(itemname)
+
+            elif itemname in self.all_weapons:
+                if itemname in self.keyblade_set:
+                    self.kh2seedsave["AmountInvo"][ItemType]["Weapon"]["Sora"].append(itemname)
+                elif itemname in self.staff_set:
+                    self.kh2seedsave["AmountInvo"][ItemType]["Weapon"]["Donald"].append(itemname)
+                else:
+                    self.kh2seedsave["AmountInvo"][ItemType]["Weapon"]["Goofy"].append(itemname)
+
+            elif itemname in self.boost_set:
+                if itemname in self.kh2seedsave["AmountInvo"][ItemType]["Boost"]:
+                    self.kh2seedsave["AmountInvo"][ItemType]["Boost"][itemname] += 1
+                else:
+                    self.kh2seedsave["AmountInvo"][ItemType]["Boost"][itemname] = 1
+
+            elif itemname in self.stat_increase_set:
+
+                if itemname in self.kh2seedsave["AmountInvo"][ItemType]["StatIncrease"]:
+                    self.kh2seedsave["AmountInvo"][ItemType]["StatIncrease"][itemname] += 1
+                else:
+                    self.kh2seedsave["AmountInvo"][ItemType]["StatIncrease"][itemname] = 1
+
+            else:
+                if itemname in self.kh2seedsave["AmountInvo"][ItemType]["Amount"]:
+                    self.kh2seedsave["AmountInvo"][ItemType]["Amount"][itemname] += 1
+                else:
+                    self.kh2seedsave["AmountInvo"][ItemType]["Amount"][itemname] = 1
+
+        except Exception as e:
+            if self.kh2connected:
+                logger.info("Line 398")
+                logger.info("Connection Lost.")
+                self.kh2connected = False
+            logger.info(e)
+
+    def run_gui(self):
+        """Import kivy UI system and start running it as self.ui_task."""
+        from kvui import GameManager
+
+        class KH2Manager(GameManager):
+            logging_pairs = [
+                ("Client", "Archipelago")
+            ]
+            base_title = "Archipelago KH2 Client"
+
+        self.ui = KH2Manager(self)
+        self.ui_task = asyncio.create_task(self.ui.async_run(), name="UI")
+
+    async def IsInShop(self, sellable, master_boost):
+        # journal = 0x741230 shop = 0x741320
+        # if journal=-1 and shop = 5 then in shop
+        # if journam !=-1 and shop = 10 then journal
+        journal = self.kh2.read_short(self.kh2.base_address + 0x741230)
+        shop = self.kh2.read_short(self.kh2.base_address + 0x741320)
+        if (journal == -1 and shop == 5) or (journal != -1 and shop == 10):
+            # print("your in the shop")
+            sellable_dict = {}
+            for itemName in sellable:
+                itemdata = self.item_name_to_data[itemName]
+                amount = int.from_bytes(
+                        self.kh2.read_bytes(self.kh2.base_address + self.Save + itemdata.memaddr, 1), "big")
+                sellable_dict[itemName] = amount
+            while (journal == -1 and shop == 5) or (journal != -1 and shop == 10):
+                journal = self.kh2.read_short(self.kh2.base_address + 0x741230)
+                shop = self.kh2.read_short(self.kh2.base_address + 0x741320)
+                await asyncio.sleep(0.5)
+            for item, amount in sellable_dict.items():
+                itemdata = self.item_name_to_data[item]
+                afterShop = int.from_bytes(
+                        self.kh2.read_bytes(self.kh2.base_address + self.Save + itemdata.memaddr, 1), "big")
+                if afterShop < amount:
+                    if item in master_boost:
+                        self.kh2seedsave["SoldBoosts"][item] += (amount - afterShop)
+                    else:
+                        self.kh2seedsave["SoldEquipment"].append(item)
+
+    async def verifyItems(self):
+        try:
+            local_amount = set(self.kh2seedsave["AmountInvo"]["LocalItems"]["Amount"].keys())
+            server_amount = set(self.kh2seedsave["AmountInvo"]["ServerItems"]["Amount"].keys())
+            master_amount = local_amount | server_amount
+
+            local_ability = set(self.kh2seedsave["AmountInvo"]["LocalItems"]["Ability"].keys())
+            server_ability = set(self.kh2seedsave["AmountInvo"]["ServerItems"]["Ability"].keys())
+            master_ability = local_ability | server_ability
+
+            local_bitmask = set(self.kh2seedsave["AmountInvo"]["LocalItems"]["Bitmask"])
+            server_bitmask = set(self.kh2seedsave["AmountInvo"]["ServerItems"]["Bitmask"])
+            master_bitmask = local_bitmask | server_bitmask
+
+            local_keyblade = set(self.kh2seedsave["AmountInvo"]["LocalItems"]["Weapon"]["Sora"])
+            local_staff = set(self.kh2seedsave["AmountInvo"]["LocalItems"]["Weapon"]["Donald"])
+            local_shield = set(self.kh2seedsave["AmountInvo"]["LocalItems"]["Weapon"]["Goofy"])
+
+            server_keyblade = set(self.kh2seedsave["AmountInvo"]["ServerItems"]["Weapon"]["Sora"])
+            server_staff = set(self.kh2seedsave["AmountInvo"]["ServerItems"]["Weapon"]["Donald"])
+            server_shield = set(self.kh2seedsave["AmountInvo"]["ServerItems"]["Weapon"]["Goofy"])
+
+            master_keyblade = local_keyblade | server_keyblade
+            master_staff = local_staff | server_staff
+            master_shield = local_shield | server_shield
+
+            local_equipment = set(self.kh2seedsave["AmountInvo"]["LocalItems"]["Equipment"])
+            server_equipment = set(self.kh2seedsave["AmountInvo"]["ServerItems"]["Equipment"])
+            master_equipment = local_equipment | server_equipment
+
+            local_magic = set(self.kh2seedsave["AmountInvo"]["LocalItems"]["Magic"].keys())
+            server_magic = set(self.kh2seedsave["AmountInvo"]["ServerItems"]["Magic"].keys())
+            master_magic = local_magic | server_magic
+
+            local_stat = set(self.kh2seedsave["AmountInvo"]["LocalItems"]["StatIncrease"].keys())
+            server_stat = set(self.kh2seedsave["AmountInvo"]["ServerItems"]["StatIncrease"].keys())
+            master_stat = local_stat | server_stat
+
+            local_boost = set(self.kh2seedsave["AmountInvo"]["LocalItems"]["Boost"].keys())
+            server_boost = set(self.kh2seedsave["AmountInvo"]["ServerItems"]["Boost"].keys())
+            master_boost = local_boost | server_boost
+
+            master_sell = master_equipment | master_staff | master_shield | master_boost
+            await asyncio.create_task(self.IsInShop(master_sell, master_boost))
+            for itemName in master_amount:
+                itemData = self.item_name_to_data[itemName]
+                amountOfItems = 0
+                if itemName in local_amount:
+                    amountOfItems += self.kh2seedsave["AmountInvo"]["LocalItems"]["Amount"][itemName]
+                if itemName in server_amount:
+                    amountOfItems += self.kh2seedsave["AmountInvo"]["ServerItems"]["Amount"][itemName]
+
+                if itemName == "Torn Page":
+                    # Torn Pages are handled differently because they can be consumed.
+                    # Will check the progression in 100 acre and - the amount of visits
+                    # amountofitems-amount of visits done
+                    for location, data in tornPageLocks.items():
+                        if int.from_bytes(self.kh2.read_bytes(self.kh2.base_address + self.Save + data.addrObtained, 1),
+                                          "big") & 0x1 << data.bitIndex > 0:
+                            amountOfItems -= 1
+                if int.from_bytes(self.kh2.read_bytes(self.kh2.base_address + self.Save + itemData.memaddr, 1),
+                                  "big") != amountOfItems and amountOfItems >= 0:
+                    self.kh2.write_bytes(self.kh2.base_address + self.Save + itemData.memaddr,
+                                         amountOfItems.to_bytes(1, 'big'), 1)
+
+            for itemName in master_keyblade:
+                itemData = self.item_name_to_data[itemName]
+                # if the inventory slot for that keyblade is less than the amount they should have
+                if int.from_bytes(self.kh2.read_bytes(self.kh2.base_address + self.Save + itemData.memaddr, 1),
+                                  "big") != 1 and int.from_bytes(self.kh2.read_bytes(self.kh2.base_address + 0x1CFF, 1),
+                                                                 "big") != 13:
+                    # Checking form anchors for the keyblade
+                    if self.kh2.read_short(self.kh2.base_address + self.Save + 0x24F0) == itemData.kh2id \
+                            or self.kh2.read_short(self.kh2.base_address + self.Save + 0x32F4) == itemData.kh2id \
+                            or self.kh2.read_short(self.kh2.base_address + self.Save + 0x339C) == itemData.kh2id \
+                            or self.kh2.read_short(self.kh2.base_address + self.Save + 0x33D4) == itemData.kh2id:
+                        self.kh2.write_bytes(self.kh2.base_address + self.Save + itemData.memaddr,
+                                             (0).to_bytes(1, 'big'), 1)
+                    else:
+                        self.kh2.write_bytes(self.kh2.base_address + self.Save + itemData.memaddr,
+                                             (1).to_bytes(1, 'big'), 1)
+            for itemName in master_staff:
+                itemData = self.item_name_to_data[itemName]
+                if int.from_bytes(self.kh2.read_bytes(self.kh2.base_address + self.Save + itemData.memaddr, 1),
+                                  "big") != 1 \
+                        and self.kh2.read_short(self.kh2.base_address + self.Save + 0x2604) != itemData.kh2id \
+                        and itemName not in self.kh2seedsave["SoldEquipment"]:
+                    self.kh2.write_bytes(self.kh2.base_address + self.Save + itemData.memaddr,
+                                         (1).to_bytes(1, 'big'), 1)
+
+            for itemName in master_shield:
+                itemData = self.item_name_to_data[itemName]
+                if int.from_bytes(self.kh2.read_bytes(self.kh2.base_address + self.Save + itemData.memaddr, 1),
+                                  "big") != 1 \
+                        and self.kh2.read_short(self.kh2.base_address + self.Save + 0x2718) != itemData.kh2id \
+                        and itemName not in self.kh2seedsave["SoldEquipment"]:
+                    self.kh2.write_bytes(self.kh2.base_address + self.Save + itemData.memaddr,
+                                         (1).to_bytes(1, 'big'), 1)
+
+            for itemName in master_ability:
+                itemData = self.item_name_to_data[itemName]
+                ability_slot = []
+                if itemName in local_ability:
+                    ability_slot += self.kh2seedsave["AmountInvo"]["LocalItems"]["Ability"][itemName]
+                if itemName in server_ability:
+                    ability_slot += self.kh2seedsave["AmountInvo"]["ServerItems"]["Ability"][itemName]
+                for slot in ability_slot:
+                    current = self.kh2.read_short(self.kh2.base_address + self.Save + slot)
+                    ability = current & 0x0FFF
+                    if ability | 0x8000 != (0x8000 + itemData.memaddr):
+                        if current - 0x8000 > 0:
+                            self.kh2.write_short(self.kh2.base_address + self.Save + slot, (0x8000 + itemData.memaddr))
+                        else:
+                            self.kh2.write_short(self.kh2.base_address + self.Save + slot, itemData.memaddr)
+            # removes the duped ability if client gave faster than the game.
+            for charInvo in {"SoraInvo", "DonaldInvo", "GoofyInvo"}:
+                if self.kh2.read_short(self.kh2.base_address + self.Save + self.kh2seedsave[charInvo][1]) != 0 and \
+                        self.kh2seedsave[charInvo][1] + 2 < self.kh2seedsave[charInvo][0]:
+                    self.kh2.write_short(self.kh2.base_address + self.Save + self.kh2seedsave[charInvo][1], 0)
+            # remove the dummy level 1 growths if they are in these invo slots.
+            for inventorySlot in {0x25CE, 0x25D0, 0x25D2, 0x25D4, 0x25D6, 0x25D8}:
+                current = self.kh2.read_short(self.kh2.base_address + self.Save + inventorySlot)
+                ability = current & 0x0FFF
+                if 0x05E <= ability <= 0x06D:
+                    self.kh2.write_short(self.kh2.base_address + self.Save + inventorySlot, 0)
+
+            for itemName in self.master_growth:
+                growthLevel = self.kh2seedsave["AmountInvo"]["ServerItems"]["Growth"][itemName] \
+                              + self.kh2seedsave["AmountInvo"]["LocalItems"]["Growth"][itemName]
+                if growthLevel > 0:
+                    slot = self.growth_values_dict[itemName][2]
+                    min_growth = self.growth_values_dict[itemName][0]
+                    max_growth = self.growth_values_dict[itemName][1]
+                    if growthLevel > 4:
+                        growthLevel = 4
+                    current_growth_level = self.kh2.read_short(self.kh2.base_address + self.Save + slot)
+                    ability = current_growth_level & 0x0FFF
+                    # if the player should be getting a growth ability
+                    if ability | 0x8000 != 0x8000 + min_growth - 1 + growthLevel:
+                        # if it should be level one of that growth
+                        if 0x8000 + min_growth - 1 + growthLevel <= 0x8000 + min_growth or ability < min_growth:
+                            self.kh2.write_short(self.kh2.base_address + self.Save + slot, min_growth)
+                        # if it is already in the inventory
+                        elif ability | 0x8000 < (0x8000 + max_growth):
+                            self.kh2.write_short(self.kh2.base_address + self.Save + slot, current_growth_level + 1)
+
+            for itemName in master_bitmask:
+                itemData = self.item_name_to_data[itemName]
+                itemMemory = int.from_bytes(
+                        self.kh2.read_bytes(self.kh2.base_address + self.Save + itemData.memaddr, 1), "big")
+                if (int.from_bytes(self.kh2.read_bytes(self.kh2.base_address + self.Save + itemData.memaddr, 1),
+                                   "big") & 0x1 << itemData.bitmask) == 0:
+                    # when getting a form anti points should be reset to 0 but bit-shift doesn't trigger the game.
+                    if itemName in {"Valor Form", "Wisdom Form", "Limit Form", "Master Form", "Final Form"}:
+                        self.kh2.write_bytes(self.kh2.base_address + self.Save + 0x3410,
+                                             (0).to_bytes(1, 'big'), 1)
+                    self.kh2.write_bytes(self.kh2.base_address + self.Save + itemData.memaddr,
+                                         (itemMemory | 0x01 << itemData.bitmask).to_bytes(1, 'big'), 1)
+
+            for itemName in master_equipment:
+                itemData = self.item_name_to_data[itemName]
+                isThere = False
+                if itemName in self.accessories_set:
+                    Equipment_Anchor_List = self.Equipment_Anchor_Dict["Accessories"]
+                else:
+                    Equipment_Anchor_List = self.Equipment_Anchor_Dict["Armor"]
+                    # Checking form anchors for the equipment
+                for slot in Equipment_Anchor_List:
+                    if self.kh2.read_short(self.kh2.base_address + self.Save + slot) == itemData.kh2id:
+                        isThere = True
+                        if int.from_bytes(self.kh2.read_bytes(self.kh2.base_address + self.Save + itemData.memaddr, 1),
+                                          "big") != 0:
+                            self.kh2.write_bytes(self.kh2.base_address + self.Save + itemData.memaddr,
+                                                 (0).to_bytes(1, 'big'), 1)
+                        break
+                if not isThere and itemName not in self.kh2seedsave["SoldEquipment"]:
+                    if int.from_bytes(self.kh2.read_bytes(self.kh2.base_address + self.Save + itemData.memaddr, 1),
+                                      "big") != 1:
+                        self.kh2.write_bytes(self.kh2.base_address + self.Save + itemData.memaddr,
+                                             (1).to_bytes(1, 'big'), 1)
+
+            for itemName in master_magic:
+                itemData = self.item_name_to_data[itemName]
+                amountOfItems = 0
+                if itemName in local_magic:
+                    amountOfItems += self.kh2seedsave["AmountInvo"]["LocalItems"]["Magic"][itemName]
+                if itemName in server_magic:
+                    amountOfItems += self.kh2seedsave["AmountInvo"]["ServerItems"]["Magic"][itemName]
+                if int.from_bytes(self.kh2.read_bytes(self.kh2.base_address + self.Save + itemData.memaddr, 1),
+                                  "big") != amountOfItems \
+                        and int.from_bytes(self.kh2.read_bytes(self.kh2.base_address + 0x741320, 1), "big") in {10, 8}:
+                    self.kh2.write_bytes(self.kh2.base_address + self.Save + itemData.memaddr,
+                                         amountOfItems.to_bytes(1, 'big'), 1)
+
+            for itemName in master_stat:
+                itemData = self.item_name_to_data[itemName]
+                amountOfItems = 0
+                if itemName in local_stat:
+                    amountOfItems += self.kh2seedsave["AmountInvo"]["LocalItems"]["StatIncrease"][itemName]
+                if itemName in server_stat:
+                    amountOfItems += self.kh2seedsave["AmountInvo"]["ServerItems"]["StatIncrease"][itemName]
+
+                # 0x130293 is Crit_1's location id for touching the computer
+                if int.from_bytes(self.kh2.read_bytes(self.kh2.base_address + self.Save + itemData.memaddr, 1),
+                                  "big") != amountOfItems \
+                        and int.from_bytes(self.kh2.read_bytes(self.kh2.base_address + self.Slot1 + 0x1B2, 1),
+                                           "big") >= 5 and int.from_bytes(
+                        self.kh2.read_bytes(self.kh2.base_address + self.Save + 0x23DF, 1),
+                        "big") > 0:
+                    self.kh2.write_bytes(self.kh2.base_address + self.Save + itemData.memaddr,
+                                         amountOfItems.to_bytes(1, 'big'), 1)
+
+            for itemName in master_boost:
+                itemData = self.item_name_to_data[itemName]
+                amountOfItems = 0
+                if itemName in local_boost:
+                    amountOfItems += self.kh2seedsave["AmountInvo"]["LocalItems"]["Boost"][itemName]
+                if itemName in server_boost:
+                    amountOfItems += self.kh2seedsave["AmountInvo"]["ServerItems"]["Boost"][itemName]
+                amountOfBoostsInInvo = int.from_bytes(
+                        self.kh2.read_bytes(self.kh2.base_address + self.Save + itemData.memaddr, 1),
+                        "big")
+                amountOfUsedBoosts = int.from_bytes(
+                        self.kh2.read_bytes(self.kh2.base_address + self.Save + self.boost_to_anchor_dict[itemName], 1),
+                        "big")
+                # Ap Boots start at +50 for some reason
+                if itemName == "AP Boost":
+                    amountOfUsedBoosts -= 50
+                totalBoosts = (amountOfBoostsInInvo + amountOfUsedBoosts)
+                if totalBoosts <= amountOfItems - self.kh2seedsave["SoldBoosts"][
+                    itemName] and amountOfBoostsInInvo < 255:
+                    self.kh2.write_bytes(self.kh2.base_address + self.Save + itemData.memaddr,
+                                         (amountOfBoostsInInvo + 1).to_bytes(1, 'big'), 1)
+
+        except Exception as e:
+            logger.info("Line 573")
+            if self.kh2connected:
+                logger.info("Connection Lost.")
+                self.kh2connected = False
+            logger.info(e)
+
+
+def finishedGame(ctx: KH2Context, message):
+    if ctx.kh2slotdata['FinalXemnas'] == 1:
+        if 0x1301ED in message[0]["locations"]:
+            ctx.finalxemnas = True
+    # three proofs
+    if ctx.kh2slotdata['Goal'] == 0:
+        if int.from_bytes(ctx.kh2.read_bytes(ctx.kh2.base_address + ctx.Save + 0x36B2, 1), "big") > 0 \
+                and int.from_bytes(ctx.kh2.read_bytes(ctx.kh2.base_address + ctx.Save + 0x36B3, 1), "big") > 0 \
+                and int.from_bytes(ctx.kh2.read_bytes(ctx.kh2.base_address + ctx.Save + 0x36B4, 1), "big") > 0:
+            if ctx.kh2slotdata['FinalXemnas'] == 1:
+                if ctx.finalxemnas:
+                    return True
+                else:
+                    return False
+            else:
+                return True
+        else:
+            return False
+    elif ctx.kh2slotdata['Goal'] == 1:
+        if int.from_bytes(ctx.kh2.read_bytes(ctx.kh2.base_address + ctx.Save + 0x3641, 1), "big") >= \
+                ctx.kh2slotdata['LuckyEmblemsRequired']:
+            ctx.kh2.write_bytes(ctx.kh2.base_address + ctx.Save + 0x36B2, (1).to_bytes(1, 'big'), 1)
+            ctx.kh2.write_bytes(ctx.kh2.base_address + ctx.Save + 0x36B3, (1).to_bytes(1, 'big'), 1)
+            ctx.kh2.write_bytes(ctx.kh2.base_address + ctx.Save + 0x36B4, (1).to_bytes(1, 'big'), 1)
+            if ctx.kh2slotdata['FinalXemnas'] == 1:
+                if ctx.finalxemnas:
+                    return True
+                else:
+                    return False
+            else:
+                return True
+        else:
+            return False
+    elif ctx.kh2slotdata['Goal'] == 2:
+        for boss in ctx.kh2slotdata["hitlist"]:
+            if boss in message[0]["locations"]:
+                ctx.amountOfPieces += 1
+        if ctx.amountOfPieces >= ctx.kh2slotdata["BountyRequired"]:
+            ctx.kh2.write_bytes(ctx.kh2.base_address + ctx.Save + 0x36B2, (1).to_bytes(1, 'big'), 1)
+            ctx.kh2.write_bytes(ctx.kh2.base_address + ctx.Save + 0x36B3, (1).to_bytes(1, 'big'), 1)
+            ctx.kh2.write_bytes(ctx.kh2.base_address + ctx.Save + 0x36B4, (1).to_bytes(1, 'big'), 1)
+            if ctx.kh2slotdata['FinalXemnas'] == 1:
+                if ctx.finalxemnas:
+                    return True
+                else:
+                    return False
+            else:
+                return True
+        else:
+            return False
+
+
+async def kh2_watcher(ctx: KH2Context):
+    while not ctx.exit_event.is_set():
+        try:
+            if ctx.kh2connected and ctx.serverconneced:
+                ctx.sending = []
+                await asyncio.create_task(ctx.checkWorldLocations())
+                await asyncio.create_task(ctx.checkLevels())
+                await asyncio.create_task(ctx.checkSlots())
+                await asyncio.create_task(ctx.verifyChests())
+                await asyncio.create_task(ctx.verifyItems())
+                await asyncio.create_task(ctx.verifyLevel())
+                message = [{"cmd": 'LocationChecks', "locations": ctx.sending}]
+                if finishedGame(ctx, message):
+                    await ctx.send_msgs([{"cmd": "StatusUpdate", "status": ClientStatus.CLIENT_GOAL}])
+                    ctx.finished_game = True
+                location_ids = []
+                location_ids = [location for location in message[0]["locations"] if location not in location_ids]
+                for location in location_ids:
+                    if location not in ctx.locations_checked:
+                        ctx.locations_checked.add(location)
+                        ctx.kh2seedsave["LocationsChecked"].append(location)
+                        if location in ctx.kh2LocalItems:
+                            item = ctx.kh2slotdata["LocalItems"][str(location)]
+                            await asyncio.create_task(ctx.give_item(item, "LocalItems"))
+                await ctx.send_msgs(message)
+            elif not ctx.kh2connected and ctx.serverconneced:
+                logger.info("Game is not open. Disconnecting from Server.")
+                await ctx.disconnect()
+        except Exception as e:
+            logger.info("Line 661")
+            if ctx.kh2connected:
+                logger.info("Connection Lost.")
+                ctx.kh2connected = False
+            logger.info(e)
+        await asyncio.sleep(0.5)
+
+
+if __name__ == '__main__':
+    async def main(args):
+        ctx = KH2Context(args.connect, args.password)
+        ctx.server_task = asyncio.create_task(server_loop(ctx), name="server loop")
+        if gui_enabled:
+            ctx.run_gui()
+        ctx.run_cli()
+        progression_watcher = asyncio.create_task(
+                kh2_watcher(ctx), name="KH2ProgressionWatcher")
+
+        await ctx.exit_event.wait()
+        ctx.server_address = None
+
+        await progression_watcher
+
+        await ctx.shutdown()
+
+
+    import colorama
+
+    parser = get_base_parser(description="KH2 Client, for text interfacing.")
+
+    args, rest = parser.parse_known_args()
+    colorama.init()
+    asyncio.run(main(args))
+    colorama.deinit()

LICENSE

@@ -1,8 +1,8 @@
 MIT License
 
 Copyright (c) 2017 LLCoolDave
-Copyright (c) 2021 Berserker66
-Copyright (c) 2021 CaitSith2
+Copyright (c) 2022 Berserker66
+Copyright (c) 2022 CaitSith2
 Copyright (c) 2021 LegendaryLinux
 
 Permission is hereby granted, free of charge, to any person obtaining a copy

Launcher.py

@@ -0,0 +1,294 @@
+"""
+Archipelago launcher for bundled app.
+
+* if run with APBP as argument, launch corresponding client.
+* if run with executable as argument, run it passing argv[2:] as arguments
+* if run without arguments, open launcher GUI
+
+Scroll down to components= to add components to the launcher as well as setup.py
+"""
+
+
+import argparse
+import itertools
+import logging
+import multiprocessing
+import shlex
+import subprocess
+import sys
+import webbrowser
+from os.path import isfile
+from shutil import which
+from typing import Sequence, Union, Optional
+
+import Utils
+import settings
+from worlds.LauncherComponents import Component, components, Type, SuffixIdentifier, icon_paths
+
+if __name__ == "__main__":
+    import ModuleUpdate
+    ModuleUpdate.update()
+
+from Utils import is_frozen, user_path, local_path, init_logging, open_filename, messagebox, \
+    is_windows, is_macos, is_linux
+
+
+def open_host_yaml():
+    file = settings.get_settings().filename
+    assert file, "host.yaml missing"
+    if is_linux:
+        exe = which('sensible-editor') or which('gedit') or \
+              which('xdg-open') or which('gnome-open') or which('kde-open')
+        subprocess.Popen([exe, file])
+    elif is_macos:
+        exe = which("open")
+        subprocess.Popen([exe, file])
+    else:
+        webbrowser.open(file)
+
+
+def open_patch():
+    suffixes = []
+    for c in components:
+        if isfile(get_exe(c)[-1]):
+            suffixes += c.file_identifier.suffixes if c.type == Type.CLIENT and \
+                                                      isinstance(c.file_identifier, SuffixIdentifier) else []
+    try:
+        filename = open_filename('Select patch', (('Patches', suffixes),))
+    except Exception as e:
+        messagebox('Error', str(e), error=True)
+    else:
+        file, component = identify(filename)
+        if file and component:
+            launch([*get_exe(component), file], component.cli)
+
+
+def generate_yamls():
+    from Options import generate_yaml_templates
+
+    target = Utils.user_path("Players", "Templates")
+    generate_yaml_templates(target, False)
+    open_folder(target)
+
+
+def browse_files():
+    open_folder(user_path())
+
+
+def open_folder(folder_path):
+    if is_linux:
+        exe = which('xdg-open') or which('gnome-open') or which('kde-open')
+        subprocess.Popen([exe, folder_path])
+    elif is_macos:
+        exe = which("open")
+        subprocess.Popen([exe, folder_path])
+    else:
+        webbrowser.open(folder_path)
+
+
+def update_settings():
+    from settings import get_settings
+    get_settings().save()
+
+
+components.extend([
+    # Functions
+    Component("Open host.yaml", func=open_host_yaml),
+    Component("Open Patch", func=open_patch),
+    Component("Generate Template Settings", func=generate_yamls),
+    Component("Discord Server", icon="discord", func=lambda: webbrowser.open("https://discord.gg/8Z65BR2")),
+    Component("18+ Discord Server", icon="discord", func=lambda: webbrowser.open("https://discord.gg/fqvNCCRsu4")),
+    Component("Browse Files", func=browse_files),
+])
+
+
+def identify(path: Union[None, str]):
+    if path is None:
+        return None, None
+    for component in components:
+        if component.handles_file(path):
+            return path,  component
+        elif path == component.display_name or path == component.script_name:
+            return None, component
+    return None, None
+
+
+def get_exe(component: Union[str, Component]) -> Optional[Sequence[str]]:
+    if isinstance(component, str):
+        name = component
+        component = None
+        if name.startswith('Archipelago'):
+            name = name[11:]
+        if name.endswith('.exe'):
+            name = name[:-4]
+        if name.endswith('.py'):
+            name = name[:-3]
+        if not name:
+            return None
+        for c in components:
+            if c.script_name == name or c.frozen_name == f'Archipelago{name}':
+                component = c
+                break
+        if not component:
+            return None
+    if is_frozen():
+        suffix = '.exe' if is_windows else ''
+        return [local_path(f'{component.frozen_name}{suffix}')]
+    else:
+        return [sys.executable, local_path(f'{component.script_name}.py')]
+
+
+def launch(exe, in_terminal=False):
+    if in_terminal:
+        if is_windows:
+            subprocess.Popen(['start', *exe], shell=True)
+            return
+        elif is_linux:
+            terminal = which('x-terminal-emulator') or which('gnome-terminal') or which('xterm')
+            if terminal:
+                subprocess.Popen([terminal, '-e', shlex.join(exe)])
+                return
+        elif is_macos:
+            terminal = [which('open'), '-W', '-a', 'Terminal.app']
+            subprocess.Popen([*terminal, *exe])
+            return
+    subprocess.Popen(exe)
+
+
+def run_gui():
+    from kvui import App, ContainerLayout, GridLayout, Button, Label
+    from kivy.uix.image import AsyncImage
+    from kivy.uix.relativelayout import RelativeLayout
+
+    class Launcher(App):
+        base_title: str = "Archipelago Launcher"
+        container: ContainerLayout
+        grid: GridLayout
+
+        _tools = {c.display_name: c for c in components if c.type == Type.TOOL}
+        _clients = {c.display_name: c for c in components if c.type == Type.CLIENT}
+        _adjusters = {c.display_name: c for c in components if c.type == Type.ADJUSTER}
+        _miscs = {c.display_name: c for c in components if c.type == Type.MISC}
+
+        def __init__(self, ctx=None):
+            self.title = self.base_title
+            self.ctx = ctx
+            self.icon = r"data/icon.png"
+            super().__init__()
+
+        def build(self):
+            self.container = ContainerLayout()
+            self.grid = GridLayout(cols=2)
+            self.container.add_widget(self.grid)
+            self.grid.add_widget(Label(text="General"))
+            self.grid.add_widget(Label(text="Clients"))
+            button_layout = self.grid  # make buttons fill the window
+
+            def build_button(component: Component):
+                """
+                Builds a button widget for a given component.
+
+                Args:
+                    component (Component): The component associated with the button.
+
+                Returns:
+                    None. The button is added to the parent grid layout.
+
+                """
+                button = Button(text=component.display_name)
+                button.component = component
+                button.bind(on_release=self.component_action)
+                if component.icon != "icon":
+                    image = AsyncImage(source=icon_paths[component.icon],
+                                       size=(38, 38), size_hint=(None, 1), pos=(5, 0))
+                    box_layout = RelativeLayout()
+                    box_layout.add_widget(button)
+                    box_layout.add_widget(image)
+                    button_layout.add_widget(box_layout)
+                else:
+                    button_layout.add_widget(button)
+
+            for (tool, client) in itertools.zip_longest(itertools.chain(
+                    self._tools.items(), self._miscs.items(), self._adjusters.items()), self._clients.items()):
+                # column 1
+                if tool:
+                    build_button(tool[1])
+                else:
+                    button_layout.add_widget(Label())
+                # column 2
+                if client:
+                    build_button(client[1])
+                else:
+                    button_layout.add_widget(Label())
+
+            return self.container
+
+        @staticmethod
+        def component_action(button):
+            if button.component.func:
+                button.component.func()
+            else:
+                launch(get_exe(button.component), button.component.cli)
+
+        def _stop(self, *largs):
+            # ran into what appears to be https://groups.google.com/g/kivy-users/c/saWDLoYCSZ4 with PyCharm.
+            # Closing the window explicitly cleans it up.
+            self.root_window.close()
+            super()._stop(*largs)
+
+    Launcher().run()
+
+
+def run_component(component: Component, *args):
+    if component.func:
+        component.func(*args)
+    elif component.script_name:
+        subprocess.run([*get_exe(component.script_name), *args])
+    else:
+        logging.warning(f"Component {component} does not appear to be executable.")
+
+
+def main(args: Optional[Union[argparse.Namespace, dict]] = None):
+    if isinstance(args, argparse.Namespace):
+        args = {k: v for k, v in args._get_kwargs()}
+    elif not args:
+        args = {}
+
+    if "Patch|Game|Component" in args:
+        file, component = identify(args["Patch|Game|Component"])
+        if file:
+            args['file'] = file
+        if component:
+            args['component'] = component
+        if not component:
+            logging.warning(f"Could not identify Component responsible for {args['Patch|Game|Component']}")
+
+    if args["update_settings"]:
+        update_settings()
+    if 'file' in args:
+        run_component(args["component"], args["file"], *args["args"])
+    elif 'component' in args:
+        run_component(args["component"], *args["args"])
+    elif not args["update_settings"]:
+        run_gui()
+
+
+if __name__ == '__main__':
+    init_logging('Launcher')
+    Utils.freeze_support()
+    multiprocessing.set_start_method("spawn")  # if launched process uses kivy, fork won't work
+    parser = argparse.ArgumentParser(description='Archipelago Launcher')
+    run_group = parser.add_argument_group("Run")
+    run_group.add_argument("--update_settings", action="store_true",
+                           help="Update host.yaml and exit.")
+    run_group.add_argument("Patch|Game|Component", type=str, nargs="?",
+                           help="Pass either a patch file, a generated game or the name of a component to run.")
+    run_group.add_argument("args", nargs="*",
+                           help="Arguments to pass to component.")
+    main(parser.parse_args())
+
+    from worlds.LauncherComponents import processes
+    for process in processes:
+        # we await all child processes to close before we tear down the process host
+        # this makes it feel like each one is its own program, as the Launcher is closed now
+        process.join()

LinksAwakeningClient.py

@@ -0,0 +1,700 @@
+import ModuleUpdate
+ModuleUpdate.update()
+
+import Utils
+
+if __name__ == "__main__":
+    Utils.init_logging("LinksAwakeningContext", exception_logger="Client")
+
+import asyncio
+import base64
+import binascii
+import colorama
+import io
+import os
+import re
+import select
+import shlex
+import socket
+import struct
+import sys
+import subprocess
+import time
+import typing
+
+
+from CommonClient import (CommonContext, get_base_parser, gui_enabled, logger,
+                          server_loop)
+from NetUtils import ClientStatus
+from worlds.ladx.Common import BASE_ID as LABaseID
+from worlds.ladx.GpsTracker import GpsTracker
+from worlds.ladx.ItemTracker import ItemTracker
+from worlds.ladx.LADXR.checkMetadata import checkMetadataTable
+from worlds.ladx.Locations import get_locations_to_id, meta_to_name
+from worlds.ladx.Tracker import LocationTracker, MagpieBridge
+
+
+class GameboyException(Exception):
+    pass
+
+
+class RetroArchDisconnectError(GameboyException):
+    pass
+
+
+class InvalidEmulatorStateError(GameboyException):
+    pass
+
+
+class BadRetroArchResponse(GameboyException):
+    pass
+
+
+def magpie_logo():
+    from kivy.uix.image import CoreImage
+    binary_data = """
+iVBORw0KGgoAAAANSUhEUgAAABAAAAAQCAIAAACQkWg2AAAAAXN
+SR0IArs4c6QAAAARnQU1BAACxjwv8YQUAAAAJcEhZcwAADsMAAA
+7DAcdvqGQAAADGSURBVDhPhVLBEcIwDHOYhjHCBuXHj2OTbAL8+
+MEGZIxOQ1CinOOk0Op0bmo7tlXXeR9FJMYDLOD9mwcLjQK7+hSZ
+wgcWMZJOAGeGKtChNHFL0j+FZD3jSCuo0w7l03wDrWdg00C4/aW
+eDEYNenuzPOfPspBnxf0kssE80vN0L8361j10P03DK4x6FHabuV
+ear8fHme+b17rwSjbAXeUMLb+EVTV2QHm46MWQanmnydA98KsVS
+XkV+qFpGQXrLhT/fqraQeQLuplpNH5g+WkAAAAASUVORK5CYII="""
+    binary_data = base64.b64decode(binary_data)
+    data = io.BytesIO(binary_data)
+    return CoreImage(data, ext="png").texture
+
+
+class LAClientConstants:
+    # Connector version
+    VERSION = 0x01
+    #
+    # Memory locations of LADXR
+    ROMGameID = 0x0051  # 4 bytes
+    SlotName = 0x0134
+    # Unused
+    # ROMWorldID = 0x0055
+    # ROMConnectorVersion = 0x0056
+    # RO: We should only act if this is higher then 6, as it indicates that the game is running normally
+    wGameplayType = 0xDB95
+    # RO: Starts at 0, increases every time an item is received from the server and processed
+    wLinkSyncSequenceNumber = 0xDDF6
+    wLinkStatusBits = 0xDDF7          # RW:
+    #      Bit0: wLinkGive* contains valid data, set from script cleared from ROM.
+    wLinkHealth = 0xDB5A
+    wLinkGiveItem = 0xDDF8  # RW
+    wLinkGiveItemFrom = 0xDDF9  # RW
+    # All of these six bytes are unused, we can repurpose
+    # wLinkSendItemRoomHigh = 0xDDFA  # RO
+    # wLinkSendItemRoomLow = 0xDDFB  # RO
+    # wLinkSendItemTarget = 0xDDFC  # RO
+    # wLinkSendItemItem = 0xDDFD  # RO
+    # wLinkSendShopItem = 0xDDFE # RO, which item to send (1 based, order of the shop items)
+    # RO, which player to send to, but it's just the X position of the NPC used, so 0x18 is player 0
+    # wLinkSendShopTarget = 0xDDFF
+
+
+    wRecvIndex = 0xDDFD # Two bytes
+    wCheckAddress = 0xC0FF - 0x4
+    WRamCheckSize = 0x4
+    WRamSafetyValue = bytearray([0]*WRamCheckSize)
+
+    MinGameplayValue = 0x06
+    MaxGameplayValue = 0x1A
+    VictoryGameplayAndSub = 0x0102
+
+
+class RAGameboy():
+    cache = []
+    cache_start = 0
+    cache_size = 0
+    last_cache_read = None
+    socket = None
+
+    def __init__(self, address, port) -> None:
+        self.address = address
+        self.port = port
+        self.socket = socket.socket(socket.AF_INET, socket.SOCK_DGRAM)
+        assert (self.socket)
+        self.socket.setblocking(False)
+
+    async def send_command(self, command, timeout=1.0):
+        self.send(f'{command}\n')
+        response_str = await self.async_recv()
+        self.check_command_response(command, response_str)
+        return response_str.rstrip()
+
+    async def get_retroarch_version(self):
+        return await self.send_command("VERSION")
+
+    async def get_retroarch_status(self):
+        return await self.send_command("GET_STATUS")
+
+    def set_cache_limits(self, cache_start, cache_size):
+        self.cache_start = cache_start
+        self.cache_size = cache_size
+
+    def send(self, b):
+        if type(b) is str:
+            b = b.encode('ascii')
+        self.socket.sendto(b, (self.address, self.port))
+
+    def recv(self):
+        select.select([self.socket], [], [])
+        response, _ = self.socket.recvfrom(4096)
+        return response
+
+    async def async_recv(self, timeout=1.0):
+        response = await asyncio.wait_for(asyncio.get_event_loop().sock_recv(self.socket, 4096), timeout)
+        return response
+
+    async def check_safe_gameplay(self, throw=True):
+        async def check_wram():
+            check_values = await self.async_read_memory(LAClientConstants.wCheckAddress, LAClientConstants.WRamCheckSize)
+
+            if check_values != LAClientConstants.WRamSafetyValue:
+                if throw:
+                    raise InvalidEmulatorStateError()
+                return False
+            return True
+
+        if not await check_wram():
+            if throw:
+                raise InvalidEmulatorStateError()
+            return False
+
+        gameplay_value = await self.async_read_memory(LAClientConstants.wGameplayType)
+        gameplay_value = gameplay_value[0]
+        # In gameplay or credits
+        if not (LAClientConstants.MinGameplayValue <= gameplay_value <= LAClientConstants.MaxGameplayValue) and gameplay_value != 0x1:
+            if throw:
+                logger.info("invalid emu state")
+                raise InvalidEmulatorStateError()
+            return False
+        if not await check_wram():
+            if throw:
+                raise InvalidEmulatorStateError()
+            return False
+        return True
+
+    # We're sadly unable to update the whole cache at once
+    # as RetroArch only gives back some number of bytes at a time
+    # So instead read as big as chunks at a time as we can manage
+    async def update_cache(self):
+        # First read the safety address - if it's invalid, bail
+        self.cache = []
+
+        if not await self.check_safe_gameplay():
+            return
+
+        cache = []
+        remaining_size = self.cache_size
+        while remaining_size:
+            block = await self.async_read_memory(self.cache_start + len(cache), remaining_size)
+            remaining_size -= len(block)
+            cache += block
+
+        if not await self.check_safe_gameplay():
+            return
+
+        self.cache = cache
+        self.last_cache_read = time.time()
+
+    async def read_memory_cache(self, addresses):
+        # TODO: can we just update once per frame?
+        if not self.last_cache_read or self.last_cache_read + 0.1 < time.time():
+            await self.update_cache()
+        if not self.cache:
+            return None
+        assert (len(self.cache) == self.cache_size)
+        for address in addresses:
+            assert self.cache_start <= address <= self.cache_start + self.cache_size
+        r = {address: self.cache[address - self.cache_start]
+             for address in addresses}
+        return r
+
+    async def async_read_memory_safe(self, address, size=1):
+        # whenever we do a read for a check, we need to make sure that we aren't reading
+        # garbage memory values - we also need to protect against reading a value, then the emulator resetting
+        #
+        # ...actually, we probably _only_ need the post check
+
+        # Check before read
+        if not await self.check_safe_gameplay():
+            return None
+
+        # Do read
+        r = await self.async_read_memory(address, size)
+
+        # Check after read
+        if not await self.check_safe_gameplay():
+            return None
+
+        return r
+
+    def check_command_response(self, command: str, response: bytes):
+        if command == "VERSION":
+            ok = re.match("\d+\.\d+\.\d+", response.decode('ascii')) is not None
+        else:
+            ok = response.startswith(command.encode())
+        if not ok:
+            logger.warning(f"Bad response to command {command} - {response}")
+            raise BadRetroArchResponse()
+
+    def read_memory(self, address, size=1):
+        command = "READ_CORE_MEMORY"
+
+        self.send(f'{command} {hex(address)} {size}\n')
+        response = self.recv()
+
+        self.check_command_response(command, response)
+
+        splits = response.decode().split(" ", 2)
+        # Ignore the address for now
+        if splits[2][:2] == "-1":
+            raise BadRetroArchResponse()
+
+        # TODO: check response address, check hex behavior between RA and BH
+
+        return bytearray.fromhex(splits[2])
+
+    async def async_read_memory(self, address, size=1):
+        command = "READ_CORE_MEMORY"
+
+        self.send(f'{command} {hex(address)} {size}\n')
+        response = await self.async_recv()
+        self.check_command_response(command, response)
+        response = response[:-1]
+        splits = response.decode().split(" ", 2)
+        try:
+            response_addr = int(splits[1], 16)
+        except ValueError:
+            raise BadRetroArchResponse()
+
+        if response_addr != address:
+            raise BadRetroArchResponse()
+
+        ret = bytearray.fromhex(splits[2])
+        if len(ret) > size:
+            raise BadRetroArchResponse()
+        return ret
+
+    def write_memory(self, address, bytes):
+        command = "WRITE_CORE_MEMORY"
+
+        self.send(f'{command} {hex(address)} {" ".join(hex(b) for b in bytes)}')
+        select.select([self.socket], [], [])
+        response, _ = self.socket.recvfrom(4096)
+        self.check_command_response(command, response)
+        splits = response.decode().split(" ", 3)
+
+        assert (splits[0] == command)
+
+        if splits[2] == "-1":
+            logger.info(splits[3])
+
+
+class LinksAwakeningClient():
+    socket = None
+    gameboy = None
+    tracker = None
+    auth = None
+    game_crc = None
+    pending_deathlink = False
+    deathlink_debounce = True
+    recvd_checks = {}
+    retroarch_address = None
+    retroarch_port = None
+    gameboy = None
+
+    def msg(self, m):
+        logger.info(m)
+        s = f"SHOW_MSG {m}\n"
+        self.gameboy.send(s)
+
+    def __init__(self, retroarch_address="127.0.0.1", retroarch_port=55355):
+        self.retroarch_address = retroarch_address
+        self.retroarch_port = retroarch_port
+        pass
+
+    stop_bizhawk_spam = False
+    async def wait_for_retroarch_connection(self):
+        if not self.stop_bizhawk_spam:
+            logger.info("Waiting on connection to Retroarch...")
+            self.stop_bizhawk_spam = True
+        self.gameboy = RAGameboy(self.retroarch_address, self.retroarch_port)
+
+        while True:
+            try:
+                version = await self.gameboy.get_retroarch_version()
+                NO_CONTENT = b"GET_STATUS CONTENTLESS"
+                status = NO_CONTENT
+                core_type = None
+                GAME_BOY = b"game_boy"
+                while status == NO_CONTENT or core_type != GAME_BOY:
+                    status = await self.gameboy.get_retroarch_status()
+                    if status.count(b" ") < 2:
+                        await asyncio.sleep(1.0)
+                        continue
+                    GET_STATUS, PLAYING, info = status.split(b" ", 2)
+                    if status.count(b",") < 2:
+                        await asyncio.sleep(1.0)
+                        continue
+                    core_type, rom_name, self.game_crc = info.split(b",", 2)
+                    if core_type != GAME_BOY:
+                        logger.info(
+                            f"Core type should be '{GAME_BOY}', found {core_type} instead - wrong type of ROM?")
+                        await asyncio.sleep(1.0)
+                        continue
+                self.stop_bizhawk_spam = False
+                logger.info(f"Connected to Retroarch {version.decode('ascii')} running {rom_name.decode('ascii')}")
+                return
+            except (BlockingIOError, TimeoutError, ConnectionResetError):
+                await asyncio.sleep(1.0)
+                pass
+
+    async def reset_auth(self):
+        auth = binascii.hexlify(await self.gameboy.async_read_memory(0x0134, 12)).decode()
+        self.auth = auth
+
+    async def wait_and_init_tracker(self):
+        await self.wait_for_game_ready()
+        self.tracker = LocationTracker(self.gameboy)
+        self.item_tracker = ItemTracker(self.gameboy)
+        self.gps_tracker = GpsTracker(self.gameboy)
+
+    async def recved_item_from_ap(self, item_id, from_player, next_index):
+        # Don't allow getting an item until you've got your first check
+        if not self.tracker.has_start_item():
+            return
+
+        # Spin until we either:
+        # get an exception from a bad read (emu shut down or reset)
+        # beat the game
+        # the client handles the last pending item
+        status = (await self.gameboy.async_read_memory_safe(LAClientConstants.wLinkStatusBits))[0]
+        while not (await self.is_victory()) and status & 1 == 1:
+            time.sleep(0.1)
+            status = (await self.gameboy.async_read_memory_safe(LAClientConstants.wLinkStatusBits))[0]
+
+        item_id -= LABaseID
+        # The player name table only goes up to 100, so don't go past that
+        # Even if it didn't, the remote player _index_ byte is just a byte, so 255 max
+        if from_player > 100:
+            from_player = 100
+
+        next_index += 1
+        self.gameboy.write_memory(LAClientConstants.wLinkGiveItem, [
+                                  item_id, from_player])
+        status |= 1
+        status = self.gameboy.write_memory(LAClientConstants.wLinkStatusBits, [status])
+        self.gameboy.write_memory(LAClientConstants.wRecvIndex, struct.pack(">H", next_index))
+
+    should_reset_auth = False
+    async def wait_for_game_ready(self):
+        logger.info("Waiting on game to be in valid state...")
+        while not await self.gameboy.check_safe_gameplay(throw=False):
+            if self.should_reset_auth:
+                self.should_reset_auth = False
+                raise GameboyException("Resetting due to wrong archipelago server")
+        logger.info("Game connection ready!")
+
+    async def is_victory(self):
+        return (await self.gameboy.read_memory_cache([LAClientConstants.wGameplayType]))[LAClientConstants.wGameplayType] == 1
+
+    async def main_tick(self, item_get_cb, win_cb, deathlink_cb):
+        await self.tracker.readChecks(item_get_cb)
+        await self.item_tracker.readItems()
+        await self.gps_tracker.read_location()
+
+        current_health = (await self.gameboy.read_memory_cache([LAClientConstants.wLinkHealth]))[LAClientConstants.wLinkHealth]
+        if self.deathlink_debounce and current_health != 0:
+            self.deathlink_debounce = False
+        elif not self.deathlink_debounce and current_health == 0:
+            # logger.info("YOU DIED.")
+            await deathlink_cb()
+            self.deathlink_debounce = True
+
+        if self.pending_deathlink:
+            logger.info("Got a deathlink")
+            self.gameboy.write_memory(LAClientConstants.wLinkHealth, [0])
+            self.pending_deathlink = False
+            self.deathlink_debounce = True
+
+        if await self.is_victory():
+            await win_cb()
+
+        recv_index = struct.unpack(">H", await self.gameboy.async_read_memory(LAClientConstants.wRecvIndex, 2))[0]
+
+        # Play back one at a time
+        if recv_index in self.recvd_checks:
+            item = self.recvd_checks[recv_index]
+            await self.recved_item_from_ap(item.item, item.player, recv_index)
+
+
+all_tasks = set()
+
+def create_task_log_exception(awaitable) -> asyncio.Task:
+    async def _log_exception(awaitable):
+        try:
+            return await awaitable
+        except Exception as e:
+            logger.exception(e)
+            pass
+        finally:
+            all_tasks.remove(task)
+    task = asyncio.create_task(_log_exception(awaitable))
+    all_tasks.add(task)
+
+
+class LinksAwakeningContext(CommonContext):
+    tags = {"AP"}
+    game = "Links Awakening DX"
+    items_handling = 0b101
+    want_slot_data = True
+    la_task = None
+    client = None
+    # TODO: does this need to re-read on reset?
+    found_checks = []
+    last_resend = time.time()
+
+    magpie_enabled = False
+    magpie = None
+    magpie_task = None
+    won = False
+
+    def __init__(self, server_address: typing.Optional[str], password: typing.Optional[str], magpie: typing.Optional[bool]) -> None:
+        self.client = LinksAwakeningClient()
+        if magpie:
+            self.magpie_enabled = True
+            self.magpie = MagpieBridge()
+        super().__init__(server_address, password)
+
+    def run_gui(self) -> None:
+        import webbrowser
+        import kvui
+        from kvui import Button, GameManager
+        from kivy.uix.image import Image
+
+        class LADXManager(GameManager):
+            logging_pairs = [
+                ("Client", "Archipelago"),
+                ("Tracker", "Tracker"),
+            ]
+            base_title = "Archipelago Links Awakening DX Client"
+
+            def build(self):
+                b = super().build()
+
+                if self.ctx.magpie_enabled:
+                    button = Button(text="", size=(30, 30), size_hint_x=None,
+                                    on_press=lambda _: webbrowser.open('https://magpietracker.us/?enable_autotracker=1'))
+                    image = Image(size=(16, 16), texture=magpie_logo())
+                    button.add_widget(image)
+
+                    def set_center(_, center):
+                        image.center = center
+                    button.bind(center=set_center)
+
+                    self.connect_layout.add_widget(button)
+                return b
+
+        self.ui = LADXManager(self)
+        self.ui_task = asyncio.create_task(self.ui.async_run(), name="UI")
+
+    async def send_checks(self):
+        message = [{"cmd": 'LocationChecks', "locations": self.found_checks}]
+        await self.send_msgs(message)
+
+    had_invalid_slot_data = None
+    def event_invalid_slot(self):
+        # The next time we try to connect, reset the game loop for new auth
+        self.had_invalid_slot_data = True
+        self.auth = None
+        # Don't try to autoreconnect, it will just fail
+        self.disconnected_intentionally = True
+        CommonContext.event_invalid_slot(self)
+
+    ENABLE_DEATHLINK = False
+    async def send_deathlink(self):
+        if self.ENABLE_DEATHLINK:
+            message = [{"cmd": 'Deathlink',
+                        'time': time.time(),
+                        'cause': 'Had a nightmare',
+                        # 'source': self.slot_info[self.slot].name,
+                        }]
+            await self.send_msgs(message)
+
+    async def send_victory(self):
+        if not self.won:
+            message = [{"cmd": "StatusUpdate",
+                        "status": ClientStatus.CLIENT_GOAL}]
+            logger.info("victory!")
+            await self.send_msgs(message)
+            self.won = True
+
+    async def on_deathlink(self, data: typing.Dict[str, typing.Any]) -> None:
+        if self.ENABLE_DEATHLINK:
+            self.client.pending_deathlink = True
+
+    def new_checks(self, item_ids, ladxr_ids):
+        self.found_checks += item_ids
+        create_task_log_exception(self.send_checks())
+        if self.magpie_enabled:
+            create_task_log_exception(self.magpie.send_new_checks(ladxr_ids))
+
+    async def server_auth(self, password_requested: bool = False):
+        if password_requested and not self.password:
+            await super(LinksAwakeningContext, self).server_auth(password_requested)
+
+        if self.had_invalid_slot_data:
+            # We are connecting when previously we had the wrong ROM or server - just in case
+            # re-read the ROM so that if the user had the correct address but wrong ROM, we
+            # allow a successful reconnect
+            self.client.should_reset_auth = True
+            self.had_invalid_slot_data = False
+
+        while self.client.auth == None:
+            await asyncio.sleep(0.1)
+        self.auth = self.client.auth
+        await self.send_connect()
+
+    def on_package(self, cmd: str, args: dict):
+        if cmd == "Connected":
+            self.game = self.slot_info[self.slot].game
+        # TODO - use watcher_event
+        if cmd == "ReceivedItems":
+            for index, item in enumerate(args["items"], start=args["index"]):
+                self.client.recvd_checks[index] = item
+
+    async def sync(self):
+        sync_msg = [{'cmd': 'Sync'}]
+        await self.send_msgs(sync_msg)
+
+    item_id_lookup = get_locations_to_id()
+
+    async def run_game_loop(self):
+        def on_item_get(ladxr_checks):
+            checks = [self.item_id_lookup[meta_to_name(
+                checkMetadataTable[check.id])] for check in ladxr_checks]
+            self.new_checks(checks, [check.id for check in ladxr_checks])
+
+        async def victory():
+            await self.send_victory()
+
+        async def deathlink():
+            await self.send_deathlink()
+
+        if self.magpie_enabled:
+            self.magpie_task = asyncio.create_task(self.magpie.serve())
+
+        # yield to allow UI to start
+        await asyncio.sleep(0)
+
+        while True:
+            try:
+                # TODO: cancel all client tasks
+                if not self.client.stop_bizhawk_spam:
+                    logger.info("(Re)Starting game loop")
+                self.found_checks.clear()
+                # On restart of game loop, clear all checks, just in case we swapped ROMs
+                # this isn't totally neccessary, but is extra safety against cross-ROM contamination
+                self.client.recvd_checks.clear()
+                await self.client.wait_for_retroarch_connection()
+                await self.client.reset_auth()
+                # If we find ourselves with new auth after the reset, reconnect
+                if self.auth and self.client.auth != self.auth:
+                    # It would be neat to reconnect here, but connection needs this loop to be running
+                    logger.info("Detected new ROM, disconnecting...")
+                    await self.disconnect()
+                    continue
+
+                if not self.client.recvd_checks:
+                    await self.sync()
+
+                await self.client.wait_and_init_tracker()
+
+                while True:
+                    await self.client.main_tick(on_item_get, victory, deathlink)
+                    await asyncio.sleep(0.1)
+                    now = time.time()
+                    if self.last_resend + 5.0 < now:
+                        self.last_resend = now
+                        await self.send_checks()
+                    if self.magpie_enabled:
+                        try:
+                            self.magpie.set_checks(self.client.tracker.all_checks)
+                            await self.magpie.set_item_tracker(self.client.item_tracker)
+                            await self.magpie.send_gps(self.client.gps_tracker)
+                        except Exception:
+                            # Don't let magpie errors take out the client
+                            pass
+                    if self.client.should_reset_auth:
+                        self.client.should_reset_auth = False
+                        raise GameboyException("Resetting due to wrong archipelago server")
+            except (GameboyException, asyncio.TimeoutError, TimeoutError, ConnectionResetError):
+                await asyncio.sleep(1.0)
+
+def run_game(romfile: str) -> None:
+    auto_start = typing.cast(typing.Union[bool, str],
+                            Utils.get_options()["ladx_options"].get("rom_start", True))
+    if auto_start is True:
+        import webbrowser
+        webbrowser.open(romfile)
+    elif isinstance(auto_start, str):
+        args = shlex.split(auto_start)
+        # Specify full path to ROM as we are going to cd in popen
+        full_rom_path = os.path.realpath(romfile)
+        args.append(full_rom_path)
+        try:
+            # set cwd so that paths to lua scripts are always relative to our client
+            if getattr(sys, 'frozen', False):
+                # The application is frozen
+                script_dir = os.path.dirname(sys.executable)
+            else:
+                script_dir = os.path.dirname(os.path.realpath(__file__))
+
+            subprocess.Popen(args, stdin=subprocess.DEVNULL, stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL, cwd=script_dir)
+        except FileNotFoundError:
+            logger.error(f"Couldn't launch ROM, {args[0]} is missing")
+
+async def main():
+    parser = get_base_parser(description="Link's Awakening Client.")
+    parser.add_argument("--url", help="Archipelago connection url")
+    parser.add_argument("--no-magpie", dest='magpie', default=True, action='store_false', help="Disable magpie bridge")
+    parser.add_argument('diff_file', default="", type=str, nargs="?",
+                        help='Path to a .apladx Archipelago Binary Patch file')
+
+    args = parser.parse_args()
+
+    if args.diff_file:
+        import Patch
+        logger.info("patch file was supplied - creating rom...")
+        meta, rom_file = Patch.create_rom_file(args.diff_file)
+        if "server" in meta and not args.connect:
+            args.connect = meta["server"]
+        logger.info(f"wrote rom file to {rom_file}")
+
+
+    ctx = LinksAwakeningContext(args.connect, args.password, args.magpie)
+
+    ctx.server_task = asyncio.create_task(server_loop(ctx), name="server loop")
+
+    # TODO: nothing about the lambda about has to be in a lambda
+    ctx.la_task = create_task_log_exception(ctx.run_game_loop())
+    if gui_enabled:
+        ctx.run_gui()
+    ctx.run_cli()
+
+    # Down below run_gui so that we get errors out of the process
+    if args.diff_file:
+        run_game(rom_file)
+
+    await ctx.exit_event.wait()
+    await ctx.shutdown()
+
+if __name__ == '__main__':
+    colorama.init()
+    asyncio.run(main())
+    colorama.deinit()

LttPAdjuster.py

@@ -14,20 +14,28 @@ import tkinter as tk
 from argparse import Namespace
 from concurrent.futures import as_completed, ThreadPoolExecutor
 from glob import glob
-from tkinter import Tk, Frame, Label, StringVar, Entry, filedialog, messagebox, Button, LEFT, X, TOP, LabelFrame, \
+from tkinter import Tk, Frame, Label, StringVar, Entry, filedialog, messagebox, Button, Radiobutton, LEFT, X, TOP, LabelFrame, \
     IntVar, Checkbutton, E, W, OptionMenu, Toplevel, BOTTOM, RIGHT, font as font, PhotoImage
+from tkinter.constants import DISABLED, NORMAL
 from urllib.parse import urlparse
 from urllib.request import urlopen
 
+import ModuleUpdate
+ModuleUpdate.update()
+
 from worlds.alttp.Rom import Sprite, LocalRom, apply_rom_settings, get_base_rom_bytes
-from Utils import output_path, local_path, open_file, get_cert_none_ssl_context, persistent_store
+from Utils import output_path, local_path, user_path, open_file, get_cert_none_ssl_context, persistent_store, \
+    get_adjuster_settings, get_adjuster_settings_no_defaults, tkinter_center_window, init_logging
+
+
+GAME_ALTTP = "A Link to the Past"
 
 
 class AdjusterWorld(object):
     def __init__(self, sprite_pool):
         import random
         self.sprite_pool = {1: sprite_pool}
-        self.slot_seeds = {1: random}
+        self.per_slot_randoms = {1: random}
 
 
 class ArgumentDefaultsHelpFormatter(argparse.RawTextHelpFormatter):
@@ -35,15 +43,58 @@ class ArgumentDefaultsHelpFormatter(argparse.RawTextHelpFormatter):
     def _get_help_string(self, action):
         return textwrap.dedent(action.help)
 
+# See argparse.BooleanOptionalAction
+class BooleanOptionalActionWithDisable(argparse.Action):
+    def __init__(self,
+                 option_strings,
+                 dest,
+                 default=None,
+                 type=None,
+                 choices=None,
+                 required=False,
+                 help=None,
+                 metavar=None):
 
-def main():
+        _option_strings = []
+        for option_string in option_strings:
+            _option_strings.append(option_string)
+
+            if option_string.startswith('--'):
+                option_string = '--disable' + option_string[2:]
+                _option_strings.append(option_string)
+
+        if help is not None and default is not None:
+            help += " (default: %(default)s)"
+
+        super().__init__(
+            option_strings=_option_strings,
+            dest=dest,
+            nargs=0,
+            default=default,
+            type=type,
+            choices=choices,
+            required=required,
+            help=help,
+            metavar=metavar)
+
+    def __call__(self, parser, namespace, values, option_string=None):
+        if option_string in self.option_strings:
+            setattr(namespace, self.dest, not option_string.startswith('--disable'))
+
+    def format_usage(self):
+        return ' | '.join(self.option_strings)
+
+
+def get_argparser() -> argparse.ArgumentParser:
     parser = argparse.ArgumentParser(formatter_class=ArgumentDefaultsHelpFormatter)
 
-    parser.add_argument('--rom', default='ER_base.sfc', help='Path to an ALttP rom to adjust.')
+    parser.add_argument('rom', nargs="?", default='AP_LttP.sfc', help='Path to an ALttP rom to adjust.')
     parser.add_argument('--baserom', default='Zelda no Densetsu - Kamigami no Triforce (Japan).sfc',
-                        help='Path to an ALttP JAP(1.0) rom to use as a base.')
+                        help='Path to an ALttP Japan(1.0) rom to use as a base.')
     parser.add_argument('--loglevel', default='info', const='info', nargs='?',
                         choices=['error', 'info', 'warning', 'debug'], help='Select level of logging for output.')
+    parser.add_argument('--auto_apply', default='ask',
+                        choices=['ask', 'always', 'never'], help='Whether or not to apply settings automatically in the future.')
     parser.add_argument('--menuspeed', default='normal', const='normal', nargs='?',
                         choices=['normal', 'instant', 'double', 'triple', 'quadruple', 'half'],
                         help='''\
@@ -52,7 +103,8 @@ def main():
                              ''')
     parser.add_argument('--quickswap', help='Enable quick item swapping with L and R.', action='store_true')
     parser.add_argument('--deathlink', help='Enable DeathLink system.', action='store_true')
-    parser.add_argument('--disablemusic', help='Disables game music.', action='store_true')
+    parser.add_argument('--allowcollect', help='Allow collection of other player items', action='store_true')
+    parser.add_argument('--music', default=True, help='Enables/Disables game music.', action=BooleanOptionalActionWithDisable)
     parser.add_argument('--triforcehud', default='hide_goal', const='hide_goal', nargs='?',
                         choices=['normal', 'hide_goal', 'hide_required', 'hide_both'],
                         help='''\
@@ -76,9 +128,6 @@ def main():
     parser.add_argument('--ow_palettes', default='default',
                         choices=['default', 'random', 'blackout', 'puke', 'classic', 'grayscale', 'negative', 'dizzy',
                                  'sick'])
-    parser.add_argument('--link_palettes', default='default',
-                        choices=['default', 'random', 'blackout', 'puke', 'classic', 'grayscale', 'negative', 'dizzy',
-                                 'sick'])
     parser.add_argument('--shield_palettes', default='default',
                         choices=['default', 'random', 'blackout', 'puke', 'classic', 'grayscale', 'negative', 'dizzy',
                                  'sick'])
@@ -98,10 +147,23 @@ def main():
                              Alternatively, can be a ALttP Rom patched with a Link
                              sprite that will be extracted.
                              ''')
-    parser.add_argument('--names', default='', type=str)
+    parser.add_argument('--sprite_pool', nargs='+', default=[], help='''
+                             A list of sprites to pull from.
+                        ''')
+    parser.add_argument('--oof', help='''\
+                             Path to a sound effect to replace Link's "oof" sound.
+                             Needs to be in a .brr format and have a length of no
+                             more than 2673 bytes, created from a 16-bit signed PCM
+                             .wav at 12khz. https://github.com/boldowa/snesbrr
+                             ''')
     parser.add_argument('--update_sprites', action='store_true', help='Update Sprite Database, then exit.')
-    args = parser.parse_args()
-    args.music = not args.disablemusic
+    return parser
+
+
+def main():
+    parser = get_argparser()
+    args = parser.parse_args(namespace=get_adjuster_settings_no_defaults(GAME_ALTTP))
+    
     # set up logger
     loglevel = {'error': logging.ERROR, 'info': logging.INFO, 'warning': logging.WARNING, 'debug': logging.DEBUG}[
         args.loglevel]
@@ -117,19 +179,29 @@ def main():
         if args.sprite is not None and not os.path.isfile(args.sprite) and not Sprite.get_sprite_from_name(args.sprite):
             input('Could not find link sprite sheet at given location. \nPress Enter to exit.')
             sys.exit(1)
+        if args.oof is not None and not os.path.isfile(args.oof):
+            input('Could not find oof sound effect at given location. \nPress Enter to exit.')
+            sys.exit(1)
+        if args.oof is not None and os.path.getsize(args.oof) > 2673:
+            input('"oof" sound effect cannot exceed 2673 bytes. \nPress Enter to exit.')
+            sys.exit(1)
+            
 
         args, path = adjust(args=args)
         if isinstance(args.sprite, Sprite):
             args.sprite = args.sprite.name
-        persistent_store("adjuster", "last_settings_3", args)
+        persistent_store("adjuster", GAME_ALTTP, args)
 
 
 def adjust(args):
     start = time.perf_counter()
+    init_logging("LttP Adjuster")
     logger = logging.getLogger('Adjuster')
     logger.info('Patching ROM.')
     vanillaRom = args.baserom
-    if os.path.splitext(args.rom)[-1].lower() == '.apbp':
+    if not os.path.exists(vanillaRom) and not os.path.isabs(vanillaRom):
+        vanillaRom = local_path(vanillaRom)
+    if os.path.splitext(args.rom)[-1].lower() == '.aplttp':
         import Patch
         meta, args.rom = Patch.create_rom_file(args.rom)
 
@@ -153,8 +225,8 @@ def adjust(args):
         world = getattr(args, "world")
 
     apply_rom_settings(rom, args.heartbeep, args.heartcolor, args.quickswap, args.menuspeed, args.music,
-                       args.sprite, palettes_options, reduceflashing=args.reduceflashing or racerom, world=world,
-                       deathlink=args.deathlink)
+                       args.sprite, args.oof, palettes_options, reduceflashing=args.reduceflashing or racerom, world=world,
+                       deathlink=args.deathlink, allowcollect=args.allowcollect)
     path = output_path(f'{os.path.basename(args.rom)[:-4]}_adjusted.sfc')
     rom.write_to_file(path)
 
@@ -168,7 +240,7 @@ def adjustGUI():
     from tkinter import Tk, LEFT, BOTTOM, TOP, \
         StringVar, Frame, Label, X, Entry, Button, filedialog, messagebox, ttk
     from argparse import Namespace
-    from Main import __version__ as MWVersion
+    from Utils import __version__ as MWVersion
     adjustWindow = Tk()
     adjustWindow.wm_title("Archipelago %s LttP Adjuster" % MWVersion)
     set_icon(adjustWindow)
@@ -185,7 +257,7 @@ def adjustGUI():
     romEntry2 = Entry(romDialogFrame, textvariable=romVar2)
 
     def RomSelect2():
-        rom = filedialog.askopenfilename(filetypes=[("Rom Files", (".sfc", ".smc", ".apbp")), ("All Files", "*")])
+        rom = filedialog.askopenfilename(filetypes=[("Rom Files", (".sfc", ".smc", ".aplttp")), ("All Files", "*")])
         romVar2.set(rom)
 
     romSelectButton2 = Button(romDialogFrame, text='Select Rom', command=RomSelect2)
@@ -196,6 +268,7 @@ def adjustGUI():
 
     def adjustRom():
         guiargs = Namespace()
+        guiargs.auto_apply = rom_vars.auto_apply.get()
         guiargs.heartbeep = rom_vars.heartbeepVar.get()
         guiargs.heartcolor = rom_vars.heartcolorVar.get()
         guiargs.menuspeed = rom_vars.menuspeedVar.get()
@@ -208,11 +281,13 @@ def adjustGUI():
         guiargs.music = bool(rom_vars.MusicVar.get())
         guiargs.reduceflashing = bool(rom_vars.disableFlashingVar.get())
         guiargs.deathlink = bool(rom_vars.DeathLinkVar.get())
+        guiargs.allowcollect = bool(rom_vars.AllowCollectVar.get())
         guiargs.rom = romVar2.get()
         guiargs.baserom = romVar.get()
         guiargs.sprite = rom_vars.sprite
         if rom_vars.sprite_pool:
             guiargs.world = AdjusterWorld(rom_vars.sprite_pool)
+        guiargs.oof = rom_vars.oof
 
         try:
             guiargs, path = adjust(args=guiargs)
@@ -226,14 +301,45 @@ def adjustGUI():
             messagebox.showinfo(title="Success", message=f"Rom patched successfully to {path}")
             if isinstance(guiargs.sprite, Sprite):
                 guiargs.sprite = guiargs.sprite.name
-            persistent_store("adjuster", "last_settings_3", guiargs)
+            delattr(guiargs, "rom")
+            persistent_store("adjuster", GAME_ALTTP, guiargs)
+
+    def saveGUISettings():
+        guiargs = Namespace()
+        guiargs.auto_apply = rom_vars.auto_apply.get()
+        guiargs.heartbeep = rom_vars.heartbeepVar.get()
+        guiargs.heartcolor = rom_vars.heartcolorVar.get()
+        guiargs.menuspeed = rom_vars.menuspeedVar.get()
+        guiargs.ow_palettes = rom_vars.owPalettesVar.get()
+        guiargs.uw_palettes = rom_vars.uwPalettesVar.get()
+        guiargs.hud_palettes = rom_vars.hudPalettesVar.get()
+        guiargs.sword_palettes = rom_vars.swordPalettesVar.get()
+        guiargs.shield_palettes = rom_vars.shieldPalettesVar.get()
+        guiargs.quickswap = bool(rom_vars.quickSwapVar.get())
+        guiargs.music = bool(rom_vars.MusicVar.get())
+        guiargs.reduceflashing = bool(rom_vars.disableFlashingVar.get())
+        guiargs.deathlink = bool(rom_vars.DeathLinkVar.get())
+        guiargs.allowcollect = bool(rom_vars.AllowCollectVar.get())
+        guiargs.baserom = romVar.get()
+        if isinstance(rom_vars.sprite, Sprite):
+            guiargs.sprite = rom_vars.sprite.name
+        else:
+            guiargs.sprite = rom_vars.sprite
+        guiargs.sprite_pool = rom_vars.sprite_pool
+        guiargs.oof = rom_vars.oof
+        persistent_store("adjuster", GAME_ALTTP, guiargs)
+        messagebox.showinfo(title="Success", message="Settings saved to persistent storage")
 
     adjustButton = Button(bottomFrame2, text='Adjust Rom', command=adjustRom)
     rom_options_frame.pack(side=TOP)
-    adjustButton.pack(side=BOTTOM, padx=(5, 5))
+    adjustButton.pack(side=LEFT, padx=(5,5))
 
-    bottomFrame2.pack(side=BOTTOM, pady=(5, 5))
+    saveButton = Button(bottomFrame2, text='Save Settings', command=saveGUISettings)
+    saveButton.pack(side=LEFT, padx=(5,5))
 
+    bottomFrame2.pack(side=TOP, pady=(5,5))
+
+    tkinter_center_window(adjustWindow)
     adjustWindow.mainloop()
 
 
@@ -247,7 +353,7 @@ def run_sprite_update():
     else:
         top.withdraw()
         task = BackgroundTaskProgress(top, update_sprites, "Updating Sprites", lambda succesful, resultmessage: done.set())
-    while not done.isSet():
+    while not done.is_set():
         task.do_events()
     logging.info("Done updating sprites")
 
@@ -255,9 +361,10 @@ def run_sprite_update():
 def update_sprites(task, on_finish=None):
     resultmessage = ""
     successful = True
-    sprite_dir = local_path("data", "sprites", "alttpr")
+    sprite_dir = user_path("data", "sprites", "alttpr")
     os.makedirs(sprite_dir, exist_ok=True)
     ctx = get_cert_none_ssl_context()
+
     def finished():
         task.close_window()
         if on_finish:
@@ -436,10 +543,42 @@ class BackgroundTaskProgressNullWindow(BackgroundTask):
         self.stop()
 
 
+class AttachTooltip(object):
+
+    def __init__(self, parent, text):
+        self._parent = parent
+        self._text = text
+        self._window = None
+        parent.bind('<Enter>', lambda event : self.show())
+        parent.bind('<Leave>', lambda event : self.hide())
+
+    def show(self):
+        if self._window or not self._text:
+            return
+        self._window = Toplevel(self._parent)
+        #remove window bar controls
+        self._window.wm_overrideredirect(1)
+        #adjust positioning
+        x, y, *_ = self._parent.bbox("insert")
+        x = x + self._parent.winfo_rootx() + 20
+        y = y + self._parent.winfo_rooty() + 20
+        self._window.wm_geometry("+{0}+{1}".format(x,y))
+        #show text
+        label = Label(self._window, text=self._text, justify=LEFT)
+        label.pack(ipadx=1)
+
+    def hide(self):
+        if self._window:
+            self._window.destroy()
+            self._window = None
+
+
 def get_rom_frame(parent=None):
+    adjuster_settings = get_adjuster_settings(GAME_ALTTP)
+
     romFrame = Frame(parent)
     baseRomLabel = Label(romFrame, text='LttP Base Rom: ')
-    romVar = StringVar(value="Zelda no Densetsu - Kamigami no Triforce (Japan).sfc")
+    romVar = StringVar(value=adjuster_settings.baserom)
     romEntry = Entry(romFrame, textvariable=romVar)
 
     def RomSelect():
@@ -463,8 +602,9 @@ def get_rom_frame(parent=None):
 
     return romFrame, romVar
 
-
 def get_rom_options_frame(parent=None):
+    adjuster_settings = get_adjuster_settings(GAME_ALTTP)
+
     romOptionsFrame = LabelFrame(parent, text="Rom options")
     romOptionsFrame.columnconfigure(0, weight=1)
     romOptionsFrame.columnconfigure(1, weight=1)
@@ -473,25 +613,29 @@ def get_rom_options_frame(parent=None):
     vars = Namespace()
 
     vars.MusicVar = IntVar()
-    vars.MusicVar.set(1)
+    vars.MusicVar.set(adjuster_settings.music)
     MusicCheckbutton = Checkbutton(romOptionsFrame, text="Music", variable=vars.MusicVar)
     MusicCheckbutton.grid(row=0, column=0, sticky=E)
 
-    vars.disableFlashingVar = IntVar(value=1)
+    vars.disableFlashingVar = IntVar(value=adjuster_settings.reduceflashing)
     disableFlashingCheckbutton = Checkbutton(romOptionsFrame, text="Disable flashing (anti-epilepsy)",
                                              variable=vars.disableFlashingVar)
     disableFlashingCheckbutton.grid(row=6, column=0, sticky=W)
 
-    vars.DeathLinkVar = IntVar(value=0)
+    vars.DeathLinkVar = IntVar(value=adjuster_settings.deathlink)
     DeathLinkCheckbutton = Checkbutton(romOptionsFrame, text="DeathLink (Team Deaths)", variable=vars.DeathLinkVar)
     DeathLinkCheckbutton.grid(row=7, column=0, sticky=W)
 
+    vars.AllowCollectVar = IntVar(value=adjuster_settings.allowcollect)
+    AllowCollectCheckbutton = Checkbutton(romOptionsFrame, text="Allow Collect", variable=vars.AllowCollectVar)
+    AllowCollectCheckbutton.grid(row=8, column=0, sticky=W)
+
     spriteDialogFrame = Frame(romOptionsFrame)
     spriteDialogFrame.grid(row=0, column=1)
     baseSpriteLabel = Label(spriteDialogFrame, text='Sprite:')
 
     vars.spriteNameVar = StringVar()
-    vars.sprite = None
+    vars.sprite = adjuster_settings.sprite
 
     def set_sprite(sprite_param):
         nonlocal vars
@@ -505,8 +649,8 @@ def get_rom_options_frame(parent=None):
             vars.sprite = sprite_param
             vars.spriteNameVar.set(vars.sprite.name)
 
-    set_sprite(None)
-    vars.spriteNameVar.set('(unchanged)')
+    set_sprite(adjuster_settings.sprite)
+    #vars.spriteNameVar.set(adjuster_settings.sprite)
     spriteEntry = Label(spriteDialogFrame, textvariable=vars.spriteNameVar)
 
     def SpriteSelect():
@@ -519,16 +663,54 @@ def get_rom_options_frame(parent=None):
     spriteEntry.pack(side=LEFT)
     spriteSelectButton.pack(side=LEFT)
 
-    vars.quickSwapVar = IntVar(value=1)
+    oofDialogFrame = Frame(romOptionsFrame)
+    oofDialogFrame.grid(row=1, column=1)
+    baseOofLabel = Label(oofDialogFrame, text='"OOF" Sound:')
+
+    vars.oofNameVar = StringVar()
+    vars.oof = adjuster_settings.oof
+
+    def set_oof(oof_param):
+        nonlocal vars
+        if isinstance(oof_param, str) and os.path.isfile(oof_param) and os.path.getsize(oof_param) <= 2673:
+            vars.oof = oof_param
+            vars.oofNameVar.set(oof_param.rsplit('/',1)[-1])
+        else:
+            vars.oof = None
+            vars.oofNameVar.set('(unchanged)')
+
+    set_oof(adjuster_settings.oof)
+    oofEntry = Label(oofDialogFrame, textvariable=vars.oofNameVar)
+
+    def OofSelect():
+        nonlocal vars
+        oof_file = filedialog.askopenfilename(
+            filetypes=[("BRR files", ".brr"),
+                       ("All Files", "*")])
+        try:
+            set_oof(oof_file)
+        except Exception:
+            set_oof(None)
+
+    oofSelectButton = Button(oofDialogFrame, text='...', command=OofSelect)
+    AttachTooltip(oofSelectButton,
+                  text="Select a .brr file no more than 2673 bytes.\n" + \
+                  "This can be created from a <=0.394s 16-bit signed PCM .wav file at 12khz using snesbrr.")
+
+    baseOofLabel.pack(side=LEFT)
+    oofEntry.pack(side=LEFT)
+    oofSelectButton.pack(side=LEFT)
+
+    vars.quickSwapVar = IntVar(value=adjuster_settings.quickswap)
     quickSwapCheckbutton = Checkbutton(romOptionsFrame, text="L/R Quickswapping", variable=vars.quickSwapVar)
     quickSwapCheckbutton.grid(row=1, column=0, sticky=E)
 
     menuspeedFrame = Frame(romOptionsFrame)
-    menuspeedFrame.grid(row=1, column=1, sticky=E)
+    menuspeedFrame.grid(row=6, column=1, sticky=E)
     menuspeedLabel = Label(menuspeedFrame, text='Menu speed')
     menuspeedLabel.pack(side=LEFT)
     vars.menuspeedVar = StringVar()
-    vars.menuspeedVar.set('normal')
+    vars.menuspeedVar.set(adjuster_settings.menuspeed)
     menuspeedOptionMenu = OptionMenu(menuspeedFrame, vars.menuspeedVar, 'normal', 'instant', 'double', 'triple',
                                      'quadruple', 'half')
     menuspeedOptionMenu.pack(side=LEFT)
@@ -538,7 +720,7 @@ def get_rom_options_frame(parent=None):
     heartcolorLabel = Label(heartcolorFrame, text='Heart color')
     heartcolorLabel.pack(side=LEFT)
     vars.heartcolorVar = StringVar()
-    vars.heartcolorVar.set('red')
+    vars.heartcolorVar.set(adjuster_settings.heartcolor)
     heartcolorOptionMenu = OptionMenu(heartcolorFrame, vars.heartcolorVar, 'red', 'blue', 'green', 'yellow', 'random')
     heartcolorOptionMenu.pack(side=LEFT)
 
@@ -547,7 +729,7 @@ def get_rom_options_frame(parent=None):
     heartbeepLabel = Label(heartbeepFrame, text='Heartbeep')
     heartbeepLabel.pack(side=LEFT)
     vars.heartbeepVar = StringVar()
-    vars.heartbeepVar.set('normal')
+    vars.heartbeepVar.set(adjuster_settings.heartbeep)
     heartbeepOptionMenu = OptionMenu(heartbeepFrame, vars.heartbeepVar, 'double', 'normal', 'half', 'quarter', 'off')
     heartbeepOptionMenu.pack(side=LEFT)
 
@@ -556,7 +738,7 @@ def get_rom_options_frame(parent=None):
     owPalettesLabel = Label(owPalettesFrame, text='Overworld palettes')
     owPalettesLabel.pack(side=LEFT)
     vars.owPalettesVar = StringVar()
-    vars.owPalettesVar.set('default')
+    vars.owPalettesVar.set(adjuster_settings.ow_palettes)
     owPalettesOptionMenu = OptionMenu(owPalettesFrame, vars.owPalettesVar, 'default', 'good', 'blackout', 'grayscale',
                                       'negative', 'classic', 'dizzy', 'sick', 'puke')
     owPalettesOptionMenu.pack(side=LEFT)
@@ -566,7 +748,7 @@ def get_rom_options_frame(parent=None):
     uwPalettesLabel = Label(uwPalettesFrame, text='Dungeon palettes')
     uwPalettesLabel.pack(side=LEFT)
     vars.uwPalettesVar = StringVar()
-    vars.uwPalettesVar.set('default')
+    vars.uwPalettesVar.set(adjuster_settings.uw_palettes)
     uwPalettesOptionMenu = OptionMenu(uwPalettesFrame, vars.uwPalettesVar, 'default', 'good', 'blackout', 'grayscale',
                                       'negative', 'classic', 'dizzy', 'sick', 'puke')
     uwPalettesOptionMenu.pack(side=LEFT)
@@ -576,7 +758,7 @@ def get_rom_options_frame(parent=None):
     hudPalettesLabel = Label(hudPalettesFrame, text='HUD palettes')
     hudPalettesLabel.pack(side=LEFT)
     vars.hudPalettesVar = StringVar()
-    vars.hudPalettesVar.set('default')
+    vars.hudPalettesVar.set(adjuster_settings.hud_palettes)
     hudPalettesOptionMenu = OptionMenu(hudPalettesFrame, vars.hudPalettesVar, 'default', 'good', 'blackout',
                                        'grayscale', 'negative', 'classic', 'dizzy', 'sick', 'puke')
     hudPalettesOptionMenu.pack(side=LEFT)
@@ -586,7 +768,7 @@ def get_rom_options_frame(parent=None):
     swordPalettesLabel = Label(swordPalettesFrame, text='Sword palettes')
     swordPalettesLabel.pack(side=LEFT)
     vars.swordPalettesVar = StringVar()
-    vars.swordPalettesVar.set('default')
+    vars.swordPalettesVar.set(adjuster_settings.sword_palettes)
     swordPalettesOptionMenu = OptionMenu(swordPalettesFrame, vars.swordPalettesVar, 'default', 'good', 'blackout',
                                          'grayscale', 'negative', 'classic', 'dizzy', 'sick', 'puke')
     swordPalettesOptionMenu.pack(side=LEFT)
@@ -596,7 +778,7 @@ def get_rom_options_frame(parent=None):
     shieldPalettesLabel = Label(shieldPalettesFrame, text='Shield palettes')
     shieldPalettesLabel.pack(side=LEFT)
     vars.shieldPalettesVar = StringVar()
-    vars.shieldPalettesVar.set('default')
+    vars.shieldPalettesVar.set(adjuster_settings.shield_palettes)
     shieldPalettesOptionMenu = OptionMenu(shieldPalettesFrame, vars.shieldPalettesVar, 'default', 'good', 'blackout',
                                           'grayscale', 'negative', 'classic', 'dizzy', 'sick', 'puke')
     shieldPalettesOptionMenu.pack(side=LEFT)
@@ -606,7 +788,7 @@ def get_rom_options_frame(parent=None):
     baseSpritePoolLabel = Label(spritePoolFrame, text='Sprite Pool:')
 
     vars.spritePoolCountVar = StringVar()
-    vars.sprite_pool = []
+    vars.sprite_pool = adjuster_settings.sprite_pool
 
     def set_sprite_pool(sprite_param):
         nonlocal vars
@@ -625,7 +807,7 @@ def get_rom_options_frame(parent=None):
         vars.spritePoolCountVar.set(str(len(vars.sprite_pool)))
 
     set_sprite_pool(None)
-    vars.spritePoolCountVar.set('0')
+    vars.spritePoolCountVar.set(len(adjuster_settings.sprite_pool))
     spritePoolEntry = Label(spritePoolFrame, textvariable=vars.spritePoolCountVar)
 
     def SpritePoolSelect():
@@ -645,6 +827,18 @@ def get_rom_options_frame(parent=None):
     spritePoolSelectButton.pack(side=LEFT)
     spritePoolClearButton.pack(side=LEFT)
 
+    vars.auto_apply = StringVar(value=adjuster_settings.auto_apply)
+    autoApplyFrame = Frame(romOptionsFrame)
+    autoApplyFrame.grid(row=9, column=0, columnspan=2, sticky=W)
+    filler = Label(autoApplyFrame, text="Automatically apply last used settings on opening .aplttp files")
+    filler.pack(side=TOP, expand=True, fill=X)
+    askRadio = Radiobutton(autoApplyFrame, text='Ask', variable=vars.auto_apply, value='ask')
+    askRadio.pack(side=LEFT, padx=5, pady=5)
+    alwaysRadio = Radiobutton(autoApplyFrame, text='Always', variable=vars.auto_apply, value='always')
+    alwaysRadio.pack(side=LEFT, padx=5, pady=5)
+    neverRadio = Radiobutton(autoApplyFrame, text='Never', variable=vars.auto_apply, value='never')
+    neverRadio.pack(side=LEFT, padx=5, pady=5)
+
     return romOptionsFrame, vars, set_sprite
 
 
@@ -663,6 +857,7 @@ class SpriteSelector():
         self.window['pady'] = 5
         self.spritesPerRow = 32
         self.all_sprites = []
+        self.invalid_sprites = []
         self.sprite_pool = spritePool
 
         def open_custom_sprite_dir(_evt):
@@ -693,6 +888,9 @@ class SpriteSelector():
 
         button = Button(frame, text="Update alttpr sprites", command=self.update_alttpr_sprites)
         button.pack(side=RIGHT, padx=(5, 0))
+        
+        button = Button(frame, text="Do not adjust sprite",command=self.use_default_sprite)
+        button.pack(side=LEFT,padx=(0,5))
 
         button = Button(frame, text="Default Link sprite", command=self.use_default_link_sprite)
         button.pack(side=LEFT, padx=(0, 5))
@@ -710,36 +908,43 @@ class SpriteSelector():
         self.randomOnItemVar = IntVar()
         self.randomOnBonkVar = IntVar()
         self.randomOnRandomVar = IntVar()
+        self.randomOnAllVar = IntVar()
 
         if self.randomOnEvent:
-            button = Checkbutton(frame, text="Hit", command=self.update_random_button, variable=self.randomOnHitVar)
-            button.pack(side=LEFT, padx=(0, 5))
+            self.buttonHit = Checkbutton(frame, text="Hit", command=self.update_random_button, variable=self.randomOnHitVar)
+            self.buttonHit.pack(side=LEFT, padx=(0, 5))
 
-            button = Checkbutton(frame, text="Enter", command=self.update_random_button, variable=self.randomOnEnterVar)
-            button.pack(side=LEFT, padx=(0, 5))
+            self.buttonEnter = Checkbutton(frame, text="Enter", command=self.update_random_button, variable=self.randomOnEnterVar)
+            self.buttonEnter.pack(side=LEFT, padx=(0, 5))
 
-            button = Checkbutton(frame, text="Exit", command=self.update_random_button, variable=self.randomOnExitVar)
-            button.pack(side=LEFT, padx=(0, 5))
+            self.buttonExit = Checkbutton(frame, text="Exit", command=self.update_random_button, variable=self.randomOnExitVar)
+            self.buttonExit.pack(side=LEFT, padx=(0, 5))
 
-            button = Checkbutton(frame, text="Slash", command=self.update_random_button, variable=self.randomOnSlashVar)
-            button.pack(side=LEFT, padx=(0, 5))
+            self.buttonSlash = Checkbutton(frame, text="Slash", command=self.update_random_button, variable=self.randomOnSlashVar)
+            self.buttonSlash.pack(side=LEFT, padx=(0, 5))
 
-            button = Checkbutton(frame, text="Item", command=self.update_random_button, variable=self.randomOnItemVar)
-            button.pack(side=LEFT, padx=(0, 5))
+            self.buttonItem = Checkbutton(frame, text="Item", command=self.update_random_button, variable=self.randomOnItemVar)
+            self.buttonItem.pack(side=LEFT, padx=(0, 5))
 
-            button = Checkbutton(frame, text="Bonk", command=self.update_random_button, variable=self.randomOnBonkVar)
-            button.pack(side=LEFT, padx=(0, 5))
+            self.buttonBonk = Checkbutton(frame, text="Bonk", command=self.update_random_button, variable=self.randomOnBonkVar)
+            self.buttonBonk.pack(side=LEFT, padx=(0, 5))
 
-            button = Checkbutton(frame, text="Random", command=self.update_random_button,
-                                 variable=self.randomOnRandomVar)
-            button.pack(side=LEFT, padx=(0, 5))
+            self.buttonRandom = Checkbutton(frame, text="Random", command=self.update_random_button, variable=self.randomOnRandomVar)
+            self.buttonRandom.pack(side=LEFT, padx=(0, 5))
 
-        if adjuster:
-            button = Button(frame, text="Current sprite from rom", command=self.use_default_sprite)
-            button.pack(side=LEFT, padx=(0, 5))
+            self.buttonAll = Checkbutton(frame, text="All", command=self.update_random_button, variable=self.randomOnAllVar)
+            self.buttonAll.pack(side=LEFT, padx=(0, 5))
 
         set_icon(self.window)
         self.window.focus()
+        tkinter_center_window(self.window)
+
+        if self.invalid_sprites:
+            invalid = sorted(self.invalid_sprites)
+            logging.warning(f"The following sprites are invalid: {', '.join(invalid)}")
+            msg = f"{invalid[0]} "
+            msg += f"and {len(invalid)-1} more are invalid" if len(invalid) > 1 else "is invalid"
+            messagebox.showerror("Invalid sprites detected", msg, parent=self.window)
 
     def remove_from_sprite_pool(self, button, spritename):
         self.callback(("remove", spritename))
@@ -805,7 +1010,13 @@ class SpriteSelector():
         sprites = []
 
         for file in os.listdir(path):
-            sprites.append((file, Sprite(os.path.join(path, file))))
+            if file == '.gitignore':
+                continue
+            sprite = Sprite(os.path.join(path, file))
+            if sprite.valid:
+                sprites.append((file, sprite))
+            else:
+                self.invalid_sprites.append(file)
 
         sprites.sort(key=lambda s: str.lower(s[1].name or "").strip())
 
@@ -879,9 +1090,31 @@ class SpriteSelector():
             self.add_to_sprite_pool("link")
 
     def update_random_button(self):
-        if self.randomOnRandomVar.get():
+        if self.randomOnAllVar.get():
+            randomon = "all"
+            self.buttonHit.config(state=DISABLED)
+            self.buttonEnter.config(state=DISABLED)
+            self.buttonExit.config(state=DISABLED)
+            self.buttonSlash.config(state=DISABLED)
+            self.buttonItem.config(state=DISABLED)
+            self.buttonBonk.config(state=DISABLED)
+            self.buttonRandom.config(state=DISABLED)
+        elif self.randomOnRandomVar.get():
             randomon = "random"
+            self.buttonHit.config(state=DISABLED)
+            self.buttonEnter.config(state=DISABLED)
+            self.buttonExit.config(state=DISABLED)
+            self.buttonSlash.config(state=DISABLED)
+            self.buttonItem.config(state=DISABLED)
+            self.buttonBonk.config(state=DISABLED)
         else:
+            self.buttonHit.config(state=NORMAL)
+            self.buttonEnter.config(state=NORMAL)
+            self.buttonExit.config(state=NORMAL)
+            self.buttonSlash.config(state=NORMAL)
+            self.buttonItem.config(state=NORMAL)
+            self.buttonBonk.config(state=NORMAL)
+            self.buttonRandom.config(state=NORMAL)
             randomon = "-hit" if self.randomOnHitVar.get() else ""
             randomon += "-enter" if self.randomOnEnterVar.get() else ""
             randomon += "-exit" if self.randomOnExitVar.get() else ""
@@ -920,12 +1153,11 @@ class SpriteSelector():
 
     @property
     def alttpr_sprite_dir(self):
-        return local_path("data", "sprites", "alttpr")
+        return user_path("data", "sprites", "alttpr")
 
     @property
     def custom_sprite_dir(self):
-        return local_path("data", "sprites", "custom")
-
+        return user_path("data", "sprites", "custom")
 
 def get_image_for_sprite(sprite, gif_only: bool = False):
     if not sprite.valid:

MMBN3Client.py

@@ -0,0 +1,376 @@
+import asyncio
+import hashlib
+import json
+import os
+import multiprocessing
+import subprocess
+import zipfile
+
+from asyncio import StreamReader, StreamWriter
+
+import bsdiff4
+
+from CommonClient import CommonContext, server_loop, gui_enabled, \
+    ClientCommandProcessor, logger, get_base_parser
+import Utils
+from NetUtils import ClientStatus
+from worlds.mmbn3.Items import items_by_id
+from worlds.mmbn3.Rom import get_base_rom_path
+from worlds.mmbn3.Locations import all_locations, scoutable_locations
+
+SYSTEM_MESSAGE_ID = 0
+
+CONNECTION_TIMING_OUT_STATUS = "Connection timing out. Please restart your emulator, then restart connector_mmbn3.lua"
+CONNECTION_REFUSED_STATUS = \
+    "Connection refused. Please start your emulator and make sure connector_mmbn3.lua is running"
+CONNECTION_RESET_STATUS = "Connection was reset. Please restart your emulator, then restart connector_mmbn3.lua"
+CONNECTION_TENTATIVE_STATUS = "Initial Connection Made"
+CONNECTION_CONNECTED_STATUS = "Connected"
+CONNECTION_INITIAL_STATUS = "Connection has not been initiated"
+CONNECTION_INCORRECT_ROM = "Supplied Base Rom does not match US GBA Blue Version. Please provide the correct ROM version"
+
+script_version: int = 2
+
+debugEnabled = False
+locations_checked = []
+items_sent = []
+itemIndex = 1
+
+CHECKSUM_BLUE = "6fe31df0144759b34ad666badaacc442"
+
+
+class MMBN3CommandProcessor(ClientCommandProcessor):
+    def __init__(self, ctx):
+        super().__init__(ctx)
+
+    def _cmd_gba(self):
+        """Check GBA Connection State"""
+        if isinstance(self.ctx, MMBN3Context):
+            logger.info(f"GBA Status: {self.ctx.gba_status}")
+
+    def _cmd_debug(self):
+        """Toggle the Debug Text overlay in ROM"""
+        global debugEnabled
+        debugEnabled = not debugEnabled
+        logger.info("Debug Overlay Enabled" if debugEnabled else "Debug Overlay Disabled")
+
+
+class MMBN3Context(CommonContext):
+    command_processor = MMBN3CommandProcessor
+    game = "MegaMan Battle Network 3"
+    items_handling = 0b001  # full local
+
+    def __init__(self, server_address, password):
+        super().__init__(server_address, password)
+        self.gba_streams: (StreamReader, StreamWriter) = None
+        self.gba_sync_task = None
+        self.gba_status = CONNECTION_INITIAL_STATUS
+        self.awaiting_rom = False
+        self.location_table = {}
+        self.version_warning = False
+        self.auth_name = None
+        self.slot_data = dict()
+        self.patching_error = False
+        self.sent_hints = []
+
+    async def server_auth(self, password_requested: bool = False):
+        if password_requested and not self.password:
+            await super(MMBN3Context, self).server_auth(password_requested)
+
+        if self.auth_name is None:
+            self.awaiting_rom = True
+            logger.info("No ROM detected, awaiting conection to Bizhawk to authenticate to the multiworld server")
+            return
+
+        logger.info("Attempting to decode from ROM... ")
+        self.awaiting_rom = False
+        self.auth = self.auth_name.decode("utf8").replace('\x00', '')
+        logger.info("Connecting as "+self.auth)
+        await self.send_connect(name=self.auth)
+
+    def run_gui(self):
+        from kvui import GameManager
+
+        class MMBN3Manager(GameManager):
+            logging_pairs = [
+                ("Client", "Archipelago")
+            ]
+            base_title = "Archipelago MegaMan Battle Network 3 Client"
+
+        self.ui = MMBN3Manager(self)
+        self.ui_task = asyncio.create_task(self.ui.async_run(), name="UI")
+
+    def on_package(self, cmd: str, args: dict):
+        if cmd == 'Connected':
+            self.slot_data = args.get("slot_data", {})
+            print(self.slot_data)
+
+class ItemInfo:
+    id = 0x00
+    sender = ""
+    type = ""
+    count = 1
+    itemName = "Unknown"
+    itemID = 0x00  # Item ID, Chip ID, etc.
+    subItemID = 0x00  # Code for chips, color for programs
+    itemIndex = 1
+
+    def __init__(self, id, sender, type):
+        self.id = id
+        self.sender = sender
+        self.type = type
+
+    def get_json(self):
+        json_data = {
+            "id": self.id,
+            "sender": self.sender,
+            "type": self.type,
+            "itemName": self.itemName,
+            "itemID": self.itemID,
+            "subItemID": self.subItemID,
+            "count": self.count,
+            "itemIndex": self.itemIndex
+        }
+        return json_data
+
+
+def get_payload(ctx: MMBN3Context):
+    global debugEnabled
+
+    items_sent = []
+    for i, item in enumerate(ctx.items_received):
+        item_data = items_by_id[item.item]
+        new_item = ItemInfo(i, ctx.player_names[item.player], item_data.type)
+        new_item.itemIndex = i+1
+        new_item.itemName = item_data.itemName
+        new_item.type = item_data.type
+        new_item.itemID = item_data.itemID
+        new_item.subItemID = item_data.subItemID
+        new_item.count = item_data.count
+        items_sent.append(new_item)
+
+    return json.dumps({
+        "items": [item.get_json() for item in items_sent],
+        "debug": debugEnabled
+        })
+
+
+async def parse_payload(payload: dict, ctx: MMBN3Context, force: bool):
+    # Game completion handling
+    if payload["gameComplete"] and not ctx.finished_game:
+        await ctx.send_msgs([{
+            "cmd": "StatusUpdate",
+            "status": ClientStatus.CLIENT_GOAL
+        }])
+        ctx.finished_game = True
+
+    # Locations handling
+    if ctx.location_table != payload["locations"]:
+        ctx.location_table = payload["locations"]
+        locs = [loc.id for loc in all_locations
+                if check_location_packet(loc, ctx.location_table)]
+        await ctx.send_msgs([{
+            "cmd": "LocationChecks",
+            "locations": locs
+        }])
+
+    # If trade hinting is enabled, send scout checks
+    if ctx.slot_data.get("trade_quest_hinting", 0) == 2:
+        trade_bits = [loc.id for loc in scoutable_locations
+                        if check_location_scouted(loc, payload["locations"])]
+        scouted_locs = [loc for loc in trade_bits if loc not in ctx.sent_hints]
+        if len(scouted_locs) > 0:
+            ctx.sent_hints.extend(scouted_locs)
+            await ctx.send_msgs([{
+                "cmd": "LocationScouts",
+                "locations": scouted_locs,
+                "create_as_hint": 2
+            }])
+
+
+def check_location_packet(location, memory):
+    if len(memory) == 0:
+        return False
+    # Our keys have to be strings to come through the JSON lua plugin so we have to turn our memory address into a string as well
+    location_key = hex(location.flag_byte)[2:]
+    byte = memory.get(location_key)
+    if byte is not None:
+        return byte & location.flag_mask
+
+
+def check_location_scouted(location, memory):
+    if len(memory) == 0:
+        return False
+    location_key = hex(location.hint_flag)[2:]
+    byte = memory.get(location_key)
+    if byte is not None:
+        return byte & location.hint_flag_mask
+
+
+async def gba_sync_task(ctx: MMBN3Context):
+    logger.info("Starting GBA connector. Use /gba for status information.")
+    if ctx.patching_error:
+        logger.error('Unable to Patch ROM. No ROM provided or ROM does not match US GBA Blue Version.')
+    while not ctx.exit_event.is_set():
+        error_status = None
+        if ctx.gba_streams:
+            (reader, writer) = ctx.gba_streams
+            msg = get_payload(ctx).encode()
+            writer.write(msg)
+            writer.write(b'\n')
+            try:
+                await asyncio.wait_for(writer.drain(), timeout=1.5)
+                try:
+                    # Data will return a dict with up to four fields
+                    # 1. str: player name (always)
+                    # 2. int: script version (always)
+                    # 3. dict[str, byte]: value of location's memory byte
+                    # 4. bool: whether the game currently registers as complete
+                    data = await asyncio.wait_for(reader.readline(), timeout=10)
+                    data_decoded = json.loads(data.decode())
+                    reported_version = data_decoded.get("scriptVersion", 0)
+                    if reported_version >= script_version:
+                        if ctx.game is not None and "locations" in data_decoded:
+                            # Not just a keep alive ping, parse
+                            asyncio.create_task((parse_payload(data_decoded, ctx, False)))
+                        if not ctx.auth:
+                            ctx.auth_name = bytes(data_decoded["playerName"])
+
+                            if ctx.awaiting_rom:
+                                logger.info("Awaiting data from ROM...")
+                                await ctx.server_auth(False)
+                    else:
+                        if not ctx.version_warning:
+                            logger.warning(f"Your Lua script is version {reported_version}, expected {script_version}."
+                                           "Please update to the latest version."
+                                           "Your connection to the Archipelago server will not be accepted.")
+                            ctx.version_warning = True
+                except asyncio.TimeoutError:
+                    logger.debug("Read Timed Out, Reconnecting")
+                    error_status = CONNECTION_TIMING_OUT_STATUS
+                    writer.close()
+                    ctx.gba_streams = None
+                except ConnectionResetError:
+                    logger.debug("Read failed due to Connection Lost, Reconnecting")
+                    error_status = CONNECTION_RESET_STATUS
+                    writer.close()
+                    ctx.gba_streams = None
+            except TimeoutError:
+                logger.debug("Connection Timed Out, Reconnecting")
+                error_status = CONNECTION_TIMING_OUT_STATUS
+                writer.close()
+                ctx.gba_streams = None
+            except ConnectionResetError:
+                logger.debug("Connection Lost, Reconnecting")
+                error_status = CONNECTION_RESET_STATUS
+                writer.close()
+                ctx.gba_streams = None
+            if ctx.gba_status == CONNECTION_TENTATIVE_STATUS:
+                if not error_status:
+                    logger.info("Successfully Connected to GBA")
+                    ctx.gba_status = CONNECTION_CONNECTED_STATUS
+                else:
+                    ctx.gba_status = f"Was tentatively connected but error occurred: {error_status}"
+            elif error_status:
+                ctx.gba_status = error_status
+                logger.info("Lost connection to GBA and attempting to reconnect. Use /gba for status updates")
+        else:
+            try:
+                logger.debug("Attempting to connect to GBA")
+                ctx.gba_streams = await asyncio.wait_for(asyncio.open_connection("localhost", 28922), timeout=10)
+                ctx.gba_status = CONNECTION_TENTATIVE_STATUS
+            except TimeoutError:
+                logger.debug("Connection Timed Out, Trying Again")
+                ctx.gba_status = CONNECTION_TIMING_OUT_STATUS
+                continue
+            except ConnectionRefusedError:
+                logger.debug("Connection Refused, Trying Again")
+                ctx.gba_status = CONNECTION_REFUSED_STATUS
+                continue
+
+
+async def run_game(romfile):
+    options = Utils.get_options().get("mmbn3_options", None)
+    if options is None:
+        auto_start = True
+    else:
+        auto_start = options.get("rom_start", True)
+    if auto_start:
+        import webbrowser
+        webbrowser.open(romfile)
+    elif os.path.isfile(auto_start):
+        subprocess.Popen([auto_start, romfile],
+                         stdin=subprocess.DEVNULL, stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL)
+
+
+async def patch_and_run_game(apmmbn3_file):
+    base_name = os.path.splitext(apmmbn3_file)[0]
+
+    with zipfile.ZipFile(apmmbn3_file, 'r') as patch_archive:
+        try:
+            with patch_archive.open("delta.bsdiff4", 'r') as stream:
+                patch_data = stream.read()
+        except KeyError:
+            raise FileNotFoundError("Patch file missing from archive.")
+    rom_file = get_base_rom_path()
+
+    with open(rom_file, 'rb') as rom:
+        rom_bytes = rom.read()
+
+    patched_bytes = bsdiff4.patch(rom_bytes, patch_data)
+    patched_rom_file = base_name+".gba"
+    with open(patched_rom_file, 'wb') as patched_rom:
+        patched_rom.write(patched_bytes)
+
+    asyncio.create_task(run_game(patched_rom_file))
+
+
+def confirm_checksum():
+    rom_file = get_base_rom_path()
+    if not os.path.exists(rom_file):
+        return False
+
+    with open(rom_file, 'rb') as rom:
+        rom_bytes = rom.read()
+
+    basemd5 = hashlib.md5()
+    basemd5.update(rom_bytes)
+    return CHECKSUM_BLUE == basemd5.hexdigest()
+
+
+if __name__ == "__main__":
+    Utils.init_logging("MMBN3Client")
+
+    async def main():
+        multiprocessing.freeze_support()
+        parser = get_base_parser()
+        parser.add_argument("patch_file", default="", type=str, nargs="?",
+                            help="Path to an APMMBN3 file")
+        args = parser.parse_args()
+        checksum_matches = confirm_checksum()
+        if checksum_matches:
+            if args.patch_file:
+                asyncio.create_task(patch_and_run_game(args.patch_file))
+
+        ctx = MMBN3Context(args.connect, args.password)
+        if not checksum_matches:
+            ctx.patching_error = True
+        ctx.server_task = asyncio.create_task(server_loop(ctx), name="Server Loop")
+        if gui_enabled:
+            ctx.run_gui()
+        ctx.run_cli()
+
+        ctx.gba_sync_task = asyncio.create_task(gba_sync_task(ctx), name="GBA Sync")
+        await ctx.exit_event.wait()
+        ctx.server_address = None
+        await ctx.shutdown()
+
+        if ctx.gba_sync_task:
+            await ctx.gba_sync_task
+
+    import colorama
+
+    colorama.init()
+
+    asyncio.run(main())
+    colorama.deinit()

Main.py

@@ -1,34 +1,30 @@
-from itertools import zip_longest, chain
+import collections
+import concurrent.futures
 import logging
 import os
-import time
-import zlib
-import concurrent.futures
 import pickle
 import tempfile
+import time
 import zipfile
-from typing import Dict, Tuple, Optional
+import zlib
+from typing import Dict, List, Optional, Set, Tuple, Union
 
-from BaseClasses import MultiWorld, CollectionState, Region, RegionType
-from worlds.alttp.Items import item_name_groups
-from worlds.alttp.Regions import lookup_vanilla_location_to_entrance
-from Fill import distribute_items_restrictive, flood_items, balance_multiworld_progression, distribute_planned
-from worlds.alttp.Shops import SHOP_ID_START, total_shop_slots, FillDisabledShopSlots
-from Utils import output_path, get_options, __version__, version_tuple
-from worlds.generic.Rules import locality_rules, exclusion_rules
+import worlds
+from BaseClasses import CollectionState, Item, Location, LocationProgressType, MultiWorld, Region
+from Fill import balance_multiworld_progression, distribute_items_restrictive, distribute_planned, flood_items
+from Options import StartInventoryPool
+from settings import get_settings
+from Utils import __version__, output_path, version_tuple
 from worlds import AutoWorld
+from worlds.generic.Rules import exclusion_rules, locality_rules
 
-
-ordered_areas = (
-    'Light World', 'Dark World', 'Hyrule Castle', 'Agahnims Tower', 'Eastern Palace', 'Desert Palace',
-    'Tower of Hera', 'Palace of Darkness', 'Swamp Palace', 'Skull Woods', 'Thieves Town', 'Ice Palace',
-    'Misery Mire', 'Turtle Rock', 'Ganons Tower', "Total"
-)
+__all__ = ["main"]
 
 
 def main(args, seed=None, baked_server_options: Optional[Dict[str, object]] = None):
     if not baked_server_options:
-        baked_server_options = get_options()["server_options"]
+        baked_server_options = get_settings().server_options.as_dict()
+    assert isinstance(baked_server_options, dict)
     if args.outputpath:
         os.makedirs(args.outputpath, exist_ok=True)
         output_path.cached_path = args.outputpath
@@ -38,7 +34,8 @@ def main(args, seed=None, baked_server_options: Optional[Dict[str, object]] = No
     world = MultiWorld(args.multi)
 
     logger = logging.getLogger()
-    world.set_seed(seed, args.race, str(args.outputname if args.outputname else world.seed))
+    world.set_seed(seed, args.race, str(args.outputname) if args.outputname else None)
+    world.plando_options = args.plando_options
 
     world.shuffle = args.shuffle.copy()
     world.logic = args.logic.copy()
@@ -47,20 +44,11 @@ def main(args, seed=None, baked_server_options: Optional[Dict[str, object]] = No
     world.item_functionality = args.item_functionality.copy()
     world.timer = args.timer.copy()
     world.goal = args.goal.copy()
-
-    if hasattr(args, "algorithm"):  # current GUI options
-        world.algorithm = args.algorithm
-        world.shuffleganon = args.shuffleganon
-        world.custom = args.custom
-        world.customitemarray = args.customitemarray
-
-    world.open_pyramid = args.open_pyramid.copy()
     world.boss_shuffle = args.shufflebosses.copy()
     world.enemy_health = args.enemy_health.copy()
     world.enemy_damage = args.enemy_damage.copy()
     world.beemizer_total_chance = args.beemizer_total_chance.copy()
     world.beemizer_trap_chance = args.beemizer_trap_chance.copy()
-    world.timer = args.timer.copy()
     world.countdown_start_time = args.countdown_start_time.copy()
     world.red_clock_time = args.red_clock_time.copy()
     world.blue_clock_time = args.blue_clock_time.copy()
@@ -77,25 +65,43 @@ def main(args, seed=None, baked_server_options: Optional[Dict[str, object]] = No
     world.plando_connections = args.plando_connections.copy()
     world.required_medallions = args.required_medallions.copy()
     world.game = args.game.copy()
-    world.set_options(args)
     world.player_name = args.name.copy()
-    world.enemizer = args.enemizercli
     world.sprite = args.sprite.copy()
     world.glitch_triforce = args.glitch_triforce  # This is enabled/disabled globally, no per player option.
 
+    world.set_options(args)
+    world.set_item_links()
+    world.state = CollectionState(world)
     logger.info('Archipelago Version %s  -  Seed: %s\n', __version__, world.seed)
 
-    logger.info("Found World Types:")
+    logger.info(f"Found {len(AutoWorld.AutoWorldRegister.world_types)} World Types:")
     longest_name = max(len(text) for text in AutoWorld.AutoWorldRegister.world_types)
-    numlength = 8
+
+    max_item = 0
+    max_location = 0
+    for cls in AutoWorld.AutoWorldRegister.world_types.values():
+        if cls.item_id_to_name:
+            max_item = max(max_item, max(cls.item_id_to_name))
+            max_location = max(max_location, max(cls.location_id_to_name))
+
+    item_digits = len(str(max_item))
+    location_digits = len(str(max_location))
+    item_count = len(str(max(len(cls.item_names) for cls in AutoWorld.AutoWorldRegister.world_types.values())))
+    location_count = len(str(max(len(cls.location_names) for cls in AutoWorld.AutoWorldRegister.world_types.values())))
+    del max_item, max_location
+
     for name, cls in AutoWorld.AutoWorldRegister.world_types.items():
-        if not cls.hidden:
-            logger.info(f"  {name:{longest_name}}: {len(cls.item_names):3} Items | "
-                        f"{len(cls.location_names):3} Locations")
-            logger.info(f"   Item IDs: {min(cls.item_id_to_name):{numlength}} - "
-                        f"{max(cls.item_id_to_name):{numlength}} | "
-                        f"Location IDs: {min(cls.location_id_to_name):{numlength}} - "
-                        f"{max(cls.location_id_to_name):{numlength}}")
+        if not cls.hidden and len(cls.item_names) > 0:
+            logger.info(f" {name:{longest_name}}: {len(cls.item_names):{item_count}} "
+                        f"Items (IDs: {min(cls.item_id_to_name):{item_digits}} - "
+                        f"{max(cls.item_id_to_name):{item_digits}}) | "
+                        f"{len(cls.location_names):{location_count}} "
+                        f"Locations (IDs: {min(cls.location_id_to_name):{location_digits}} - "
+                        f"{max(cls.location_id_to_name):{location_digits}})")
+
+    del item_digits, location_digits, item_count, location_count
+
+    AutoWorld.call_stage(world, "assert_generate")
 
     AutoWorld.call_all(world, "generate_early")
 
@@ -106,18 +112,9 @@ def main(args, seed=None, baked_server_options: Optional[Dict[str, object]] = No
             for _ in range(count):
                 world.push_precollected(world.create_item(item_name, player))
 
-    for player in world.player_ids:
-        if player in world.get_game_players("A Link to the Past"):
-            # enforce pre-defined local items.
-            if world.goal[player] in ["localtriforcehunt", "localganontriforcehunt"]:
-                world.local_items[player].value.add('Triforce Piece')
-
-            # Not possible to place pendants/crystals out side of boss prizes yet.
-            world.non_local_items[player].value -= item_name_groups['Pendants']
-            world.non_local_items[player].value -= item_name_groups['Crystals']
-
-        # items can't be both local and non-local, prefer local
-        world.non_local_items[player].value -= world.local_items[player].value
+        for item_name, count in world.start_inventory_from_pool.setdefault(player, StartInventoryPool({})).value.items():
+            for _ in range(count):
+                world.push_precollected(world.create_item(item_name, player))
 
     logger.info('Creating World.')
     AutoWorld.call_all(world, "create_regions")
@@ -125,25 +122,155 @@ def main(args, seed=None, baked_server_options: Optional[Dict[str, object]] = No
     logger.info('Creating Items.')
     AutoWorld.call_all(world, "create_items")
 
+    # All worlds should have finished creating all regions, locations, and entrances.
+    # Recache to ensure that they are all visible for locality rules.
+    world._recache()
+
     logger.info('Calculating Access Rules.')
-    if world.players > 1:
-        for player in world.player_ids:
-            locality_rules(world, player)
-    else:
-        world.non_local_items[1].value = set()
-        world.local_items[1].value = set()
+
+    for player in world.player_ids:
+        # items can't be both local and non-local, prefer local
+        world.non_local_items[player].value -= world.local_items[player].value
+        world.non_local_items[player].value -= set(world.local_early_items[player])
 
     AutoWorld.call_all(world, "set_rules")
 
     for player in world.player_ids:
         exclusion_rules(world, player, world.exclude_locations[player].value)
+        world.priority_locations[player].value -= world.exclude_locations[player].value
+        for location_name in world.priority_locations[player].value:
+            try:
+                location = world.get_location(location_name, player)
+            except KeyError as e:  # failed to find the given location. Check if it's a legitimate location
+                if location_name not in world.worlds[player].location_name_to_id:
+                    raise Exception(f"Unable to prioritize location {location_name} in player {player}'s world.") from e
+            else:
+                location.progress_type = LocationProgressType.PRIORITY
 
+    # Set local and non-local item rules.
+    if world.players > 1:
+        locality_rules(world)
+    else:
+        world.non_local_items[1].value = set()
+        world.local_items[1].value = set()
+    
     AutoWorld.call_all(world, "generate_basic")
 
-    logger.info("Running Item Plando")
+    # remove starting inventory from pool items.
+    # Because some worlds don't actually create items during create_items this has to be as late as possible.
+    if any(world.start_inventory_from_pool[player].value for player in world.player_ids):
+        new_items: List[Item] = []
+        depletion_pool: Dict[int, Dict[str, int]] = {
+            player: world.start_inventory_from_pool[player].value.copy() for player in world.player_ids}
+        for player, items in depletion_pool.items():
+            player_world: AutoWorld.World = world.worlds[player]
+            for count in items.values():
+                for _ in range(count):
+                    new_items.append(player_world.create_filler())
+        target: int = sum(sum(items.values()) for items in depletion_pool.values())
+        for i, item in enumerate(world.itempool):
+            if depletion_pool[item.player].get(item.name, 0):
+                target -= 1
+                depletion_pool[item.player][item.name] -= 1
+                # quick abort if we have found all items
+                if not target:
+                    new_items.extend(world.itempool[i+1:])
+                    break
+            else:
+                new_items.append(item)
 
-    for item in world.itempool:
-        item.world = world
+        # leftovers?
+        if target:
+            for player, remaining_items in depletion_pool.items():
+                remaining_items = {name: count for name, count in remaining_items.items() if count}
+                if remaining_items:
+                    raise Exception(f"{world.get_player_name(player)}"
+                                    f" is trying to remove items from their pool that don't exist: {remaining_items}")
+        assert len(world.itempool) == len(new_items), "Item Pool amounts should not change."
+        world.itempool[:] = new_items
+
+    # temporary home for item links, should be moved out of Main
+    for group_id, group in world.groups.items():
+        def find_common_pool(players: Set[int], shared_pool: Set[str]) -> Tuple[
+            Optional[Dict[int, Dict[str, int]]], Optional[Dict[str, int]]
+        ]:
+            classifications: Dict[str, int] = collections.defaultdict(int)
+            counters = {player: {name: 0 for name in shared_pool} for player in players}
+            for item in world.itempool:
+                if item.player in counters and item.name in shared_pool:
+                    counters[item.player][item.name] += 1
+                    classifications[item.name] |= item.classification
+
+            for player in players.copy():
+                if all([counters[player][item] == 0 for item in shared_pool]):
+                    players.remove(player)
+                    del (counters[player])
+
+            if not players:
+                return None, None
+
+            for item in shared_pool:
+                count = min(counters[player][item] for player in players)
+                if count:
+                    for player in players:
+                        counters[player][item] = count
+                else:
+                    for player in players:
+                        del (counters[player][item])
+            return counters, classifications
+
+        common_item_count, classifications = find_common_pool(group["players"], group["item_pool"])
+        if not common_item_count:
+            continue
+
+        new_itempool: List[Item] = []
+        for item_name, item_count in next(iter(common_item_count.values())).items():
+            for _ in range(item_count):
+                new_item = group["world"].create_item(item_name)
+                # mangle together all original classification bits
+                new_item.classification |= classifications[item_name]
+                new_itempool.append(new_item)
+
+        region = Region("Menu", group_id, world, "ItemLink")
+        world.regions.append(region)
+        locations = region.locations = []
+        for item in world.itempool:
+            count = common_item_count.get(item.player, {}).get(item.name, 0)
+            if count:
+                loc = Location(group_id, f"Item Link: {item.name} -> {world.player_name[item.player]} {count}",
+                               None, region)
+                loc.access_rule = lambda state, item_name = item.name, group_id_ = group_id, count_ = count: \
+                    state.has(item_name, group_id_, count_)
+
+                locations.append(loc)
+                loc.place_locked_item(item)
+                common_item_count[item.player][item.name] -= 1
+            else:
+                new_itempool.append(item)
+
+        itemcount = len(world.itempool)
+        world.itempool = new_itempool
+
+        while itemcount > len(world.itempool):
+            items_to_add = []
+            for player in group["players"]:
+                if group["link_replacement"]:
+                    item_player = group_id
+                else:
+                    item_player = player
+                if group["replacement_items"][player]:
+                    items_to_add.append(AutoWorld.call_single(world, "create_item", item_player,
+                                                                group["replacement_items"][player]))
+                else:
+                    items_to_add.append(AutoWorld.call_single(world, "create_filler", item_player))
+            world.random.shuffle(items_to_add)
+            world.itempool.extend(items_to_add[:itemcount - len(world.itempool)])
+
+    if any(world.item_links.values()):
+        world._recache()
+        world._all_state = None
+
+    logger.info("Running Item Plando")
 
     distribute_planned(world)
 
@@ -160,10 +287,16 @@ def main(args, seed=None, baked_server_options: Optional[Dict[str, object]] = No
 
     AutoWorld.call_all(world, 'post_fill')
 
-    if world.players > 1:
+    if world.players > 1 and not args.skip_prog_balancing:
         balance_multiworld_progression(world)
+    else:
+        logger.info("Progression balancing skipped.")
 
     logger.info(f'Beginning output...')
+
+    # we're about to output using multithreading, so we're removing the global random state to prevent accidental use
+    world.random.passthrough = False
+
     outfilebase = 'AP_' + world.seed_name
 
     output = tempfile.TemporaryDirectory()
@@ -178,122 +311,75 @@ def main(args, seed=None, baked_server_options: Optional[Dict[str, object]] = No
                     output_file_futures.append(
                         pool.submit(AutoWorld.call_single, world, "generate_output", player, temp_dir))
 
-            def get_entrance_to_region(region: Region):
-                for entrance in region.entrances:
-                    if entrance.parent_region.type in (RegionType.DarkWorld, RegionType.LightWorld, RegionType.Generic):
-                        return entrance
-                for entrance in region.entrances:  # BFS might be better here, trying DFS for now.
-                    return get_entrance_to_region(entrance.parent_region)
-
             # collect ER hint info
-            er_hint_data = {player: {} for player in world.get_game_players("A Link to the Past") if
-                            world.shuffle[player] != "vanilla" or world.retro[player]}
-
-            for region in world.regions:
-                if region.player in er_hint_data and region.locations:
-                    main_entrance = get_entrance_to_region(region)
-                    for location in region.locations:
-                        if type(location.address) == int:  # skips events and crystals
-                            if lookup_vanilla_location_to_entrance[location.address] != main_entrance.name:
-                                er_hint_data[region.player][location.address] = main_entrance.name
-
-            checks_in_area = {player: {area: list() for area in ordered_areas}
-                              for player in range(1, world.players + 1)}
-
-            for player in range(1, world.players + 1):
-                checks_in_area[player]["Total"] = 0
-
-            for location in world.get_filled_locations():
-                if type(location.address) is int:
-                    main_entrance = get_entrance_to_region(location.parent_region)
-                    if location.game != "A Link to the Past":
-                        checks_in_area[location.player]["Light World"].append(location.address)
-                    elif location.parent_region.dungeon:
-                        dungeonname = {'Inverted Agahnims Tower': 'Agahnims Tower',
-                                       'Inverted Ganons Tower': 'Ganons Tower'} \
-                            .get(location.parent_region.dungeon.name, location.parent_region.dungeon.name)
-                        checks_in_area[location.player][dungeonname].append(location.address)
-                    elif location.parent_region.type == RegionType.LightWorld:
-                        checks_in_area[location.player]["Light World"].append(location.address)
-                    elif location.parent_region.type == RegionType.DarkWorld:
-                        checks_in_area[location.player]["Dark World"].append(location.address)
-                    elif main_entrance.parent_region.type == RegionType.LightWorld:
-                        checks_in_area[location.player]["Light World"].append(location.address)
-                    elif main_entrance.parent_region.type == RegionType.DarkWorld:
-                        checks_in_area[location.player]["Dark World"].append(location.address)
-                    checks_in_area[location.player]["Total"] += 1
-
-            oldmancaves = []
-            takeanyregions = ["Old Man Sword Cave", "Take-Any #1", "Take-Any #2", "Take-Any #3", "Take-Any #4"]
-            for index, take_any in enumerate(takeanyregions):
-                for region in [world.get_region(take_any, player) for player in
-                               world.get_game_players("A Link to the Past") if world.retro[player]]:
-                    item = world.create_item(
-                        region.shop.inventory[(0 if take_any == "Old Man Sword Cave" else 1)]['item'],
-                        region.player)
-                    player = region.player
-                    location_id = SHOP_ID_START + total_shop_slots + index
-
-                    main_entrance = get_entrance_to_region(region)
-                    if main_entrance.parent_region.type == RegionType.LightWorld:
-                        checks_in_area[player]["Light World"].append(location_id)
-                    else:
-                        checks_in_area[player]["Dark World"].append(location_id)
-                    checks_in_area[player]["Total"] += 1
-
-                    er_hint_data[player][location_id] = main_entrance.name
-                    oldmancaves.append(((location_id, player), (item.code, player)))
-
-            FillDisabledShopSlots(world)
+            er_hint_data: Dict[int, Dict[int, str]] = {}
+            AutoWorld.call_all(world, 'extend_hint_information', er_hint_data)
 
             def write_multidata():
                 import NetUtils
                 slot_data = {}
                 client_versions = {}
-                minimum_versions = {"server": (0, 1, 8), "clients": client_versions}
                 games = {}
+                minimum_versions = {"server": AutoWorld.World.required_server_version, "clients": client_versions}
+                slot_info = {}
+                names = [[name for player, name in sorted(world.player_name.items())]]
                 for slot in world.player_ids:
-                    client_versions[slot] = world.worlds[slot].get_required_client_version()
+                    player_world: AutoWorld.World = world.worlds[slot]
+                    minimum_versions["server"] = max(minimum_versions["server"], player_world.required_server_version)
+                    client_versions[slot] = player_world.required_client_version
                     games[slot] = world.game[slot]
-                precollected_items = {player: [item.code for item in world_precollected]
+                    slot_info[slot] = NetUtils.NetworkSlot(names[0][slot - 1], world.game[slot],
+                                                           world.player_types[slot])
+                for slot, group in world.groups.items():
+                    games[slot] = world.game[slot]
+                    slot_info[slot] = NetUtils.NetworkSlot(group["name"], world.game[slot], world.player_types[slot],
+                                                           group_members=sorted(group["players"]))
+                precollected_items = {player: [item.code for item in world_precollected if type(item.code) == int]
                                       for player, world_precollected in world.precollected_items.items()}
-                precollected_hints = {player: set() for player in range(1, world.players + 1)}
-                # for now special case Factorio tech_tree_information
-                sending_visible_players = set()
+                precollected_hints = {player: set() for player in range(1, world.players + 1 + len(world.groups))}
 
                 for slot in world.player_ids:
                     slot_data[slot] = world.worlds[slot].fill_slot_data()
-                    if world.worlds[slot].sending_visible:
-                        sending_visible_players.add(slot)
 
                 def precollect_hint(location):
+                    entrance = er_hint_data.get(location.player, {}).get(location.address, "")
                     hint = NetUtils.Hint(location.item.player, location.player, location.address,
-                                         location.item.code, False)
+                                         location.item.code, False, entrance, location.item.flags)
                     precollected_hints[location.player].add(hint)
-                    precollected_hints[location.item.player].add(hint)
+                    if location.item.player not in world.groups:
+                        precollected_hints[location.item.player].add(hint)
+                    else:
+                        for player in world.groups[location.item.player]["players"]:
+                            precollected_hints[player].add(hint)
 
-                locations_data: Dict[int, Dict[int, Tuple[int, int]]] = {player: {} for player in world.player_ids}
+                locations_data: Dict[int, Dict[int, Tuple[int, int, int]]] = {player: {} for player in world.player_ids}
                 for location in world.get_filled_locations():
                     if type(location.address) == int:
-                        # item code None should be event, location.address should then also be None
-                        assert location.item.code is not None
-                        locations_data[location.player][location.address] = location.item.code, location.item.player
-                        if location.player in sending_visible_players:
-                            precollect_hint(location)
-                        elif location.name in world.start_location_hints[location.player]:
+                        assert location.item.code is not None, "item code None should be event, " \
+                                                               "location.address should then also be None. Location: " \
+                                                               f" {location}"
+                        locations_data[location.player][location.address] = \
+                            location.item.code, location.item.player, location.item.flags
+                        if location.name in world.start_location_hints[location.player]:
                             precollect_hint(location)
                         elif location.item.name in world.start_hints[location.item.player]:
                             precollect_hint(location)
+                        elif any([location.item.name in world.start_hints[player]
+                                  for player in world.groups.get(location.item.player, {}).get("players", [])]):
+                            precollect_hint(location)
+
+                # embedded data package
+                data_package = {
+                    game_world.game: worlds.network_data_package["games"][game_world.game]
+                    for game_world in world.worlds.values()
+                }
+
+                checks_in_area: Dict[int, Dict[str, Union[int, List[int]]]] = {}
 
                 multidata = {
                     "slot_data": slot_data,
-                    "games": games,
-                    "names": [[name for player, name in sorted(world.player_name.items())]],
+                    "slot_info": slot_info,
                     "connect_names": {name: (0, player) for player, name in world.player_name.items()},
-                    "remote_items": {player for player in world.player_ids if
-                                     world.worlds[player].remote_items},
-                    "remote_start_inventory": {player for player in world.player_ids if
-                                               world.worlds[player].remote_start_inventory},
                     "locations": locations_data,
                     "checks_in_area": checks_in_area,
                     "server_options": baked_server_options,
@@ -303,25 +389,25 @@ def main(args, seed=None, baked_server_options: Optional[Dict[str, object]] = No
                     "version": tuple(version_tuple),
                     "tags": ["AP"],
                     "minimum_versions": minimum_versions,
-                    "seed_name": world.seed_name
+                    "seed_name": world.seed_name,
+                    "datapackage": data_package,
                 }
                 AutoWorld.call_all(world, "modify_multidata", multidata)
 
                 multidata = zlib.compress(pickle.dumps(multidata), 9)
 
                 with open(os.path.join(temp_dir, f'{outfilebase}.archipelago'), 'wb') as f:
-                    f.write(bytes([1]))  # version of format
+                    f.write(bytes([3]))  # version of format
                     f.write(multidata)
 
-            multidata_task = pool.submit(write_multidata)
+            output_file_futures.append(pool.submit(write_multidata))
             if not check_accessibility_task.result():
                 if not world.can_beat_game():
                     raise Exception("Game appears as unbeatable. Aborting.")
                 else:
                     logger.warning("Location Accessibility requirements not fulfilled.")
 
-            # retrieve exceptions via .result() if they occured.
-            multidata_task.result()
+            # retrieve exceptions via .result() if they occurred.
             for i, future in enumerate(concurrent.futures.as_completed(output_file_futures), start=1):
                 if i % 10 == 0 or i == len(output_file_futures):
                     logger.info(f'Generating output files ({i}/{len(output_file_futures)}).')
@@ -329,13 +415,13 @@ def main(args, seed=None, baked_server_options: Optional[Dict[str, object]] = No
 
         if args.spoiler > 1:
             logger.info('Calculating playthrough.')
-            create_playthrough(world)
+            world.spoiler.create_playthrough(create_paths=args.spoiler > 2)
 
         if args.spoiler:
             world.spoiler.to_file(os.path.join(temp_dir, '%s_Spoiler.txt' % outfilebase))
 
         zipfilename = output_path(f"AP_{world.seed_name}.zip")
-        logger.info(f'Creating final archive at {zipfilename}.')
+        logger.info(f"Creating final archive at {zipfilename}")
         with zipfile.ZipFile(zipfilename, mode="w", compression=zipfile.ZIP_DEFLATED,
                              compresslevel=9) as zf:
             for file in os.scandir(temp_dir):
@@ -343,143 +429,3 @@ def main(args, seed=None, baked_server_options: Optional[Dict[str, object]] = No
 
     logger.info('Done. Enjoy. Total Time: %s', time.perf_counter() - start)
     return world
-
-
-def create_playthrough(world):
-    """Destructive to the world while it is run, damage gets repaired afterwards."""
-    # get locations containing progress items
-    prog_locations = {location for location in world.get_filled_locations() if location.item.advancement}
-    state_cache = [None]
-    collection_spheres = []
-    state = CollectionState(world)
-    sphere_candidates = set(prog_locations)
-    logging.debug('Building up collection spheres.')
-    while sphere_candidates:
-
-        # build up spheres of collection radius.
-        # Everything in each sphere is independent from each other in dependencies and only depends on lower spheres
-
-        sphere = {location for location in sphere_candidates if state.can_reach(location)}
-
-        for location in sphere:
-            state.collect(location.item, True, location)
-
-        sphere_candidates -= sphere
-        collection_spheres.append(sphere)
-        state_cache.append(state.copy())
-
-        logging.debug('Calculated sphere %i, containing %i of %i progress items.', len(collection_spheres), len(sphere),
-                      len(prog_locations))
-        if not sphere:
-            logging.debug('The following items could not be reached: %s', ['%s (Player %d) at %s (Player %d)' % (
-                location.item.name, location.item.player, location.name, location.player) for location in
-                                                                           sphere_candidates])
-            if any([world.accessibility[location.item.player] != 'minimal' for location in sphere_candidates]):
-                raise RuntimeError(f'Not all progression items reachable ({sphere_candidates}). '
-                                   f'Something went terribly wrong here.')
-            else:
-                world.spoiler.unreachables = sphere_candidates
-                break
-
-    # in the second phase, we cull each sphere such that the game is still beatable,
-    # reducing each range of influence to the bare minimum required inside it
-    restore_later = {}
-    for num, sphere in reversed(tuple(enumerate(collection_spheres))):
-        to_delete = set()
-        for location in sphere:
-            # we remove the item at location and check if game is still beatable
-            logging.debug('Checking if %s (Player %d) is required to beat the game.', location.item.name,
-                          location.item.player)
-            old_item = location.item
-            location.item = None
-            if world.can_beat_game(state_cache[num]):
-                to_delete.add(location)
-                restore_later[location] = old_item
-            else:
-                # still required, got to keep it around
-                location.item = old_item
-
-        # cull entries in spheres for spoiler walkthrough at end
-        sphere -= to_delete
-
-    # second phase, sphere 0
-    removed_precollected = []
-    for item in (i for i in chain.from_iterable(world.precollected_items.values()) if i.advancement):
-        logging.debug('Checking if %s (Player %d) is required to beat the game.', item.name, item.player)
-        world.precollected_items[item.player].remove(item)
-        world.state.remove(item)
-        if not world.can_beat_game():
-            world.push_precollected(item)
-        else:
-            removed_precollected.append(item)
-
-    # we are now down to just the required progress items in collection_spheres. Unfortunately
-    # the previous pruning stage could potentially have made certain items dependant on others
-    # in the same or later sphere (because the location had 2 ways to access but the item originally
-    # used to access it was deemed not required.) So we need to do one final sphere collection pass
-    # to build up the correct spheres
-
-    required_locations = {item for sphere in collection_spheres for item in sphere}
-    state = CollectionState(world)
-    collection_spheres = []
-    while required_locations:
-        state.sweep_for_events(key_only=True)
-
-        sphere = set(filter(state.can_reach, required_locations))
-
-        for location in sphere:
-            state.collect(location.item, True, location)
-
-        required_locations -= sphere
-
-        collection_spheres.append(sphere)
-
-        logging.debug('Calculated final sphere %i, containing %i of %i progress items.', len(collection_spheres),
-                      len(sphere), len(required_locations))
-        if not sphere:
-            raise RuntimeError(f'Not all required items reachable. Unreachable locations: {required_locations}')
-
-    def flist_to_iter(node):
-        while node:
-            value, node = node
-            yield value
-
-    def get_path(state, region):
-        reversed_path_as_flist = state.path.get(region, (region, None))
-        string_path_flat = reversed(list(map(str, flist_to_iter(reversed_path_as_flist))))
-        # Now we combine the flat string list into (region, exit) pairs
-        pathsiter = iter(string_path_flat)
-        pathpairs = zip_longest(pathsiter, pathsiter)
-        return list(pathpairs)
-
-    world.spoiler.paths = {}
-    topology_worlds = (player for player in world.player_ids if world.worlds[player].topology_present)
-    for player in topology_worlds:
-        world.spoiler.paths.update(
-            {str(location): get_path(state, location.parent_region) for sphere in collection_spheres for location in
-             sphere if location.player == player})
-        if player in world.get_game_players("A Link to the Past"):
-            # If Pyramid Fairy Entrance needs to be reached, also path to Big Bomb Shop
-            # Maybe move the big bomb over to the Event system instead?
-            if any(exit_path == 'Pyramid Fairy' for path in world.spoiler.paths.values() for (_, exit_path) in path):
-                if world.mode[player] != 'inverted':
-                    world.spoiler.paths[str(world.get_region('Big Bomb Shop', player))] = \
-                        get_path(state, world.get_region('Big Bomb Shop', player))
-                else:
-                    world.spoiler.paths[str(world.get_region('Inverted Big Bomb Shop', player))] = \
-                        get_path(state, world.get_region('Inverted Big Bomb Shop', player))
-
-    # we can finally output our playthrough
-    world.spoiler.playthrough = {"0": sorted([str(item) for item in
-                                              chain.from_iterable(world.precollected_items.values())
-                                              if item.advancement])}
-
-    for i, sphere in enumerate(collection_spheres):
-        world.spoiler.playthrough[str(i + 1)] = {str(location): str(location.item) for location in sorted(sphere)}
-
-    # repair the world again
-    for location, item in restore_later.items():
-        location.item = item
-
-    for item in removed_precollected:
-        world.push_precollected(item)

MinecraftClient.py

@@ -1,7 +1,10 @@
 import argparse
-import os, sys
+import json
+import os
+import sys
 import re
 import atexit
+import shutil
 from subprocess import Popen
 from shutil import copyfile
 from time import strftime
@@ -10,12 +13,12 @@ import logging
 import requests
 
 import Utils
+from Utils import is_windows
 
 atexit.register(input, "Press enter to exit.")
 
 # 1 or more digits followed by m or g, then optional b
 max_heap_re = re.compile(r"^\d+[mMgG][bB]?$")
-forge_version = "1.17.1-37.1.1"
 
 
 def prompt_yes_no(prompt):
@@ -31,8 +34,8 @@ def prompt_yes_no(prompt):
             print('Please respond with "y" or "n".')
 
 
-# Create mods folder if needed; find AP randomizer jar; return None if not found.
 def find_ap_randomizer_jar(forge_dir):
+    """Create mods folder if needed; find AP randomizer jar; return None if not found."""
     mods_dir = os.path.join(forge_dir, 'mods')
     if os.path.isdir(mods_dir):
         for entry in os.scandir(mods_dir):
@@ -46,8 +49,8 @@ def find_ap_randomizer_jar(forge_dir):
         return None
 
 
-# Create APData folder if needed; clean .apmc files from APData; copy given .apmc into directory.
 def replace_apmc_files(forge_dir, apmc_file):
+    """Create APData folder if needed; clean .apmc files from APData; copy given .apmc into directory."""
     if apmc_file is None:
         return
     apdata_dir = os.path.join(forge_dir, 'APData')
@@ -69,64 +72,43 @@ def replace_apmc_files(forge_dir, apmc_file):
 
 def read_apmc_file(apmc_file):
     from base64 import b64decode
-    import json
 
     with open(apmc_file, 'r') as f:
-        data = json.loads(b64decode(f.read()))
-    return data
+        return json.loads(b64decode(f.read()))
 
 
-# Check mod version, download new mod from GitHub releases page if needed. 
-def update_mod(forge_dir, apmc_file, get_prereleases=False):
+def update_mod(forge_dir, url: str):
+    """Check mod version, download new mod from GitHub releases page if needed. """
     ap_randomizer = find_ap_randomizer_jar(forge_dir)
-
-    if apmc_file is not None:
-        data = read_apmc_file(apmc_file)
-        minecraft_version = data.get('minecraft_version', '')
-
-    client_releases_endpoint = "https://api.github.com/repos/KonoTyran/Minecraft_AP_Randomizer/releases"
-    resp = requests.get(client_releases_endpoint)
-    if resp.status_code == 200:  # OK
-        try:
-            latest_release = next(filter(lambda release: (not release['prerelease'] or get_prereleases) and 
-                (apmc_file is None or minecraft_version in release['assets'][0]['name']), 
-                resp.json()))
-            if ap_randomizer != latest_release['assets'][0]['name']:
-                logging.info(f"A new release of the Minecraft AP randomizer mod was found: "
-                             f"{latest_release['assets'][0]['name']}")
-                if ap_randomizer is not None:
-                    logging.info(f"Your current mod is {ap_randomizer}.")
-                else:
-                    logging.info(f"You do not have the AP randomizer mod installed.")
-                if prompt_yes_no("Would you like to update?"):
-                    old_ap_mod = os.path.join(forge_dir, 'mods', ap_randomizer) if ap_randomizer is not None else None
-                    new_ap_mod = os.path.join(forge_dir, 'mods', latest_release['assets'][0]['name'])
-                    logging.info("Downloading AP randomizer mod. This may take a moment...")
-                    apmod_resp = requests.get(latest_release['assets'][0]['browser_download_url'])
-                    if apmod_resp.status_code == 200: 
-                        with open(new_ap_mod, 'wb') as f:
-                            f.write(apmod_resp.content)
-                            logging.info(f"Wrote new mod file to {new_ap_mod}")
-                        if old_ap_mod is not None:
-                            os.remove(old_ap_mod)
-                            logging.info(f"Removed old mod file from {old_ap_mod}")
-                    else:
-                        logging.error(f"Error retrieving the randomizer mod (status code {apmod_resp.status_code}).")
-                        logging.error(f"Please report this issue on the Archipelago Discord server.")
-                        sys.exit(1)
-        except StopIteration:
-            logging.warning(f"No compatible mod version found for {minecraft_version}.")
-            if not prompt_yes_no("Run server anyway?"):
-                sys.exit(0)
+    os.path.basename(url)
+    if ap_randomizer is not None:
+        logging.info(f"Your current mod is {ap_randomizer}.")
     else:
-        logging.error(f"Error checking for randomizer mod updates (status code {resp.status_code}).")
-        logging.error(f"If this was not expected, please report this issue on the Archipelago Discord server.")
-        if not prompt_yes_no("Continue anyways?"):
-            sys.exit(0)
+        logging.info(f"You do not have the AP randomizer mod installed.")
+
+    if ap_randomizer != os.path.basename(url):
+        logging.info(f"A new release of the Minecraft AP randomizer mod was found: "
+                     f"{os.path.basename(url)}")
+        if prompt_yes_no("Would you like to update?"):
+            old_ap_mod = os.path.join(forge_dir, 'mods', ap_randomizer) if ap_randomizer is not None else None
+            new_ap_mod = os.path.join(forge_dir, 'mods', os.path.basename(url))
+            logging.info("Downloading AP randomizer mod. This may take a moment...")
+            apmod_resp = requests.get(url)
+            if apmod_resp.status_code == 200:
+                with open(new_ap_mod, 'wb') as f:
+                    f.write(apmod_resp.content)
+                    logging.info(f"Wrote new mod file to {new_ap_mod}")
+                if old_ap_mod is not None:
+                    os.remove(old_ap_mod)
+                    logging.info(f"Removed old mod file from {old_ap_mod}")
+            else:
+                logging.error(f"Error retrieving the randomizer mod (status code {apmod_resp.status_code}).")
+                logging.error(f"Please report this issue on the Archipelago Discord server.")
+                sys.exit(1)
 
 
-# Check if the EULA is agreed to, and prompt the user to read and agree if necessary.
 def check_eula(forge_dir):
+    """Check if the EULA is agreed to, and prompt the user to read and agree if necessary."""
     eula_path = os.path.join(forge_dir, "eula.txt")
     if not os.path.isfile(eula_path):
         # Create eula.txt
@@ -149,31 +131,39 @@ def check_eula(forge_dir):
                 sys.exit(0)
 
 
-# get the current JDK16
-def find_jdk_dir() -> str:
+def find_jdk_dir(version: str) -> str:
+    """get the specified versions jdk directory"""
     for entry in os.listdir():
-        if os.path.isdir(entry) and entry.startswith("jdk16"):
+        if os.path.isdir(entry) and entry.startswith(f"jdk{version}"):
             return os.path.abspath(entry)
 
 
-# get the java exe location
-def find_jdk() -> str:
-    jdk = find_jdk_dir()
-    jdk_exe = os.path.join(jdk, "bin", "java.exe")
-    if os.path.isfile(jdk_exe):
+def find_jdk(version: str) -> str:
+    """get the java exe location"""
+
+    if is_windows:
+        jdk = find_jdk_dir(version)
+        jdk_exe = os.path.join(jdk, "bin", "java.exe")
+        if os.path.isfile(jdk_exe):
+            return jdk_exe
+    else:
+        jdk_exe = shutil.which(options["minecraft_options"].get("java", "java"))
+        if not jdk_exe:
+            raise Exception("Could not find Java. Is Java installed on the system?")
         return jdk_exe
 
 
-# Download Corretto 16 (Amazon JDK)
-def download_java():
-    jdk = find_jdk_dir()
+def download_java(java: str):
+    """Download Corretto (Amazon JDK)"""
+
+    jdk = find_jdk_dir(java)
     if jdk is not None:
         print(f"Removing old JDK...")
         from shutil import rmtree
         rmtree(jdk)
 
     print(f"Downloading Java...")
-    jdk_url = "https://corretto.aws/downloads/latest/amazon-corretto-16-x64-windows-jdk.zip"
+    jdk_url = f"https://corretto.aws/downloads/latest/amazon-corretto-{java}-x64-windows-jdk.zip"
     resp = requests.get(jdk_url)
     if resp.status_code == 200:  # OK
         print(f"Extracting...")
@@ -188,10 +178,11 @@ def download_java():
             sys.exit(0)
 
 
-# download and install forge
-def install_forge(directory: str):
-    jdk = find_jdk()
-    if jdk is not None:
+def install_forge(directory: str, forge_version: str, java_version: str):
+    """download and install forge"""
+
+    java_exe = find_jdk(java_version)
+    if java_exe is not None:
         print(f"Downloading Forge {forge_version}...")
         forge_url = f"https://maven.minecraftforge.net/net/minecraftforge/forge/{forge_version}/forge-{forge_version}-installer.jar"
         resp = requests.get(forge_url)
@@ -202,70 +193,152 @@ def install_forge(directory: str):
             with open(forge_install_jar, 'wb') as f:
                 f.write(resp.content)
             print(f"Installing Forge...")
-            argstring = ' '.join([jdk, "-jar", "\"" + forge_install_jar+ "\"", "--installServer", "\"" + directory + "\""])
-            install_process = Popen(argstring)
+            install_process = Popen([java_exe, "-jar", forge_install_jar, "--installServer", directory])
             install_process.wait()
             os.remove(forge_install_jar)
 
 
-# Run the Forge server. Return process object
-def run_forge_server(forge_dir: str, heap_arg):
+def run_forge_server(forge_dir: str, java_version: str, heap_arg: str) -> Popen:
+    """Run the Forge server."""
 
-    java_exe = find_jdk()
+    java_exe = find_jdk(java_version)
     if not os.path.isfile(java_exe):
         java_exe = "java"  # try to fall back on java in the PATH
 
-    heap_arg = max_heap_re.match(max_heap).group()
+    heap_arg = max_heap_re.match(heap_arg).group()
     if heap_arg[-1] in ['b', 'B']:
         heap_arg = heap_arg[:-1]
     heap_arg = "-Xmx" + heap_arg
 
-    args_file = os.path.join(forge_dir, "libraries", "net", "minecraftforge", "forge", forge_version, "win_args.txt")
-    win_args = []
+    os_args = "win_args.txt" if is_windows else "unix_args.txt"
+    args_file = os.path.join(forge_dir, "libraries", "net", "minecraftforge", "forge", forge_version, os_args)
+    forge_args = []
     with open(args_file) as argfile:
         for line in argfile:
-            win_args.append(line.strip())
+            forge_args.extend(line.strip().split(" "))
 
-    argstring = ' '.join([java_exe, heap_arg] + win_args + ["-nogui"])
-    logging.info(f"Running Forge server: {argstring}")
+    args = [java_exe, heap_arg, *forge_args, "-nogui"]
+    logging.info(f"Running Forge server: {args}")
     os.chdir(forge_dir)
-    return Popen(argstring)
+    return Popen(args)
+
+
+def get_minecraft_versions(version, release_channel="release"):
+    version_file_endpoint = "https://raw.githubusercontent.com/KonoTyran/Minecraft_AP_Randomizer/master/versions/minecraft_versions.json"
+    resp = requests.get(version_file_endpoint)
+    local = False
+    if resp.status_code == 200:  # OK
+        try:
+            data = resp.json()
+        except requests.exceptions.JSONDecodeError:
+            logging.warning(f"Unable to fetch version update file, using local version. (status code {resp.status_code}).")
+            local = True
+    else:
+        logging.warning(f"Unable to fetch version update file, using local version. (status code {resp.status_code}).")
+        local = True
+
+    if local:
+        with open(Utils.user_path("minecraft_versions.json"), 'r') as f:
+            data = json.load(f)
+    else:
+        with open(Utils.user_path("minecraft_versions.json"), 'w') as f:
+            json.dump(data, f)
+
+    try:
+        if version:
+            return next(filter(lambda entry: entry["version"] == version, data[release_channel]))
+        else:
+            return resp.json()[release_channel][0]
+    except (StopIteration, KeyError):
+        logging.error(f"No compatible mod version found for client version {version} on \"{release_channel}\" channel.")
+        if release_channel != "release":
+            logging.error("Consider switching \"release_channel\" to \"release\" in your Host.yaml file")
+        else:
+            logging.error("No suitable mod found on the \"release\" channel. Please Contact us on discord to report this error.")
+        sys.exit(0)
+
+
+def is_correct_forge(forge_dir) -> bool:
+    if os.path.isdir(os.path.join(forge_dir, "libraries", "net", "minecraftforge", "forge", forge_version)):
+        return True
+    return False
 
 
 if __name__ == '__main__':
     Utils.init_logging("MinecraftClient")
     parser = argparse.ArgumentParser()
     parser.add_argument("apmc_file", default=None, nargs='?', help="Path to an Archipelago Minecraft data file (.apmc)")
-    parser.add_argument('--install', '-i', dest='install', default=False, action='store_true', 
-        help="Download and install Java and the Forge server. Does not launch the client afterwards.")
-    parser.add_argument('--prerelease', default=False, action='store_true',
-        help="Auto-update prerelease versions.")
+    parser.add_argument('--install', '-i', dest='install', default=False, action='store_true',
+                        help="Download and install Java and the Forge server. Does not launch the client afterwards.")
+    parser.add_argument('--release_channel', '-r', dest="channel", type=str, action='store',
+                        help="Specify release channel to use.")
+    parser.add_argument('--java', '-j', metavar='17', dest='java', type=str, default=False, action='store',
+                        help="specify java version.")
+    parser.add_argument('--forge', '-f', metavar='1.18.2-40.1.0', dest='forge', type=str, default=False, action='store',
+                        help="specify forge version. (Minecraft Version-Forge Version)")
+    parser.add_argument('--version', '-v', metavar='9', dest='data_version', type=int, action='store',
+                        help="specify Mod data version to download.")
 
     args = parser.parse_args()
     apmc_file = os.path.abspath(args.apmc_file) if args.apmc_file else None
 
     # Change to executable's working directory
     os.chdir(os.path.abspath(os.path.dirname(sys.argv[0])))
-    
+
     options = Utils.get_options()
+    channel = args.channel or options["minecraft_options"]["release_channel"]
+    apmc_data = None
+    data_version = args.data_version or None
+
+    if apmc_file is None and not args.install:
+        apmc_file = Utils.open_filename('Select APMC file', (('APMC File', ('.apmc',)),))
+
+    if apmc_file is not None and data_version is None:
+        apmc_data = read_apmc_file(apmc_file)
+        data_version = apmc_data.get('client_version', '')
+
+    versions = get_minecraft_versions(data_version, channel)
+
     forge_dir = options["minecraft_options"]["forge_directory"]
     max_heap = options["minecraft_options"]["max_heap_size"]
+    forge_version = args.forge or versions["forge"]
+    java_version = args.java or versions["java"]
+    mod_url = versions["url"]
+    java_dir = find_jdk_dir(java_version)
 
     if args.install:
-        print("Installing Java and Minecraft Forge")
-        download_java()
-        install_forge(forge_dir)
+        if is_windows:
+            print("Installing Java")
+            download_java(java_version)
+        if not is_correct_forge(forge_dir):
+            print("Installing Minecraft Forge")
+            install_forge(forge_dir, forge_version, java_version)
+        else:
+            print("Correct Forge version already found, skipping install.")
         sys.exit(0)
 
-    if apmc_file is not None and not os.path.isfile(apmc_file):
-        raise FileNotFoundError(f"Path {apmc_file} does not exist or could not be accessed.")
-    if not os.path.isdir(forge_dir):
-        raise NotADirectoryError(f"Path {forge_dir} does not exist or could not be accessed.")
+    if apmc_data is None:
+        raise FileNotFoundError(f"APMC file does not exist or is inaccessible at the given location ({apmc_file})")
+
+    if is_windows:
+        if java_dir is None or not os.path.isdir(java_dir):
+            if prompt_yes_no("Did not find java directory. Download and install java now?"):
+                download_java(java_version)
+                java_dir = find_jdk_dir(java_version)
+            if java_dir is None or not os.path.isdir(java_dir):
+                raise NotADirectoryError(f"Path {java_dir} does not exist or could not be accessed.")
+
+    if not is_correct_forge(forge_dir):
+        if prompt_yes_no(f"Did not find forge version {forge_version} download and install it now?"):
+            install_forge(forge_dir, forge_version, java_version)
+        if not os.path.isdir(forge_dir):
+            raise NotADirectoryError(f"Path {forge_dir} does not exist or could not be accessed.")
+
     if not max_heap_re.match(max_heap):
         raise Exception(f"Max heap size {max_heap} in incorrect format. Use a number followed by M or G, e.g. 512M or 2G.")
 
-    update_mod(forge_dir, apmc_file, args.prerelease)
+    update_mod(forge_dir, mod_url)
     replace_apmc_files(forge_dir, apmc_file)
     check_eula(forge_dir)
-    server_process = run_forge_server(forge_dir, max_heap)
+    server_process = run_forge_server(forge_dir, java_version, max_heap)
     server_process.wait()

ModuleUpdate.py

@@ -1,66 +1,131 @@
 import os
 import sys
 import subprocess
-import pkg_resources
+import multiprocessing
+import warnings
 
-requirements_files = {'requirements.txt'}
+local_dir = os.path.dirname(__file__)
+requirements_files = {os.path.join(local_dir, 'requirements.txt')}
 
 if sys.version_info < (3, 8, 6):
     raise RuntimeError("Incompatible Python Version. 3.8.7+ is supported.")
 
-update_ran = getattr(sys, "frozen", False)  # don't run update if environment is frozen/compiled
+# don't run update if environment is frozen/compiled or if not the parent process (skip in subprocess)
+update_ran = getattr(sys, "frozen", False) or multiprocessing.parent_process()
 
 if not update_ran:
-    for entry in os.scandir("worlds"):
-        if entry.is_dir():
-            req_file = os.path.join(entry.path, "requirements.txt")
-            if os.path.exists(req_file):
-                requirements_files.add(req_file)
+    for entry in os.scandir(os.path.join(local_dir, "worlds")):
+        # skip .* (hidden / disabled) folders
+        if not entry.name.startswith("."):
+            if entry.is_dir():
+                req_file = os.path.join(entry.path, "requirements.txt")
+                if os.path.exists(req_file):
+                    requirements_files.add(req_file)
+
+
+def check_pip():
+    # detect if pip is available
+    try:
+        import pip  # noqa: F401
+    except ImportError:
+        raise RuntimeError("pip not available. Please install pip.")
+
+
+def confirm(msg: str):
+    try:
+        input(f"\n{msg}")
+    except KeyboardInterrupt:
+        print("\nAborting")
+        sys.exit(1)
 
 
 def update_command():
+    check_pip()
     for file in requirements_files:
-        subprocess.call([sys.executable, '-m', 'pip', 'install', '-r', file, '--upgrade'])
+        subprocess.call([sys.executable, "-m", "pip", "install", "-r", file, "--upgrade"])
 
 
-def update(yes = False, force = False):
+def install_pkg_resources(yes=False):
+    try:
+        import pkg_resources  # noqa: F401
+    except ImportError:
+        check_pip()
+        if not yes:
+            confirm("pkg_resources not found, press enter to install it")
+        subprocess.call([sys.executable, "-m", "pip", "install", "--upgrade", "setuptools"])
+
+
+def update(yes=False, force=False):
     global update_ran
     if not update_ran:
         update_ran = True
+
         if force:
             update_command()
             return
+
+        install_pkg_resources(yes=yes)
+        import pkg_resources
+
         for req_file in requirements_files:
             path = os.path.join(os.path.dirname(sys.argv[0]), req_file)
             if not os.path.exists(path):
                 path = os.path.join(os.path.dirname(__file__), req_file)
             with open(path) as requirementsfile:
                 for line in requirementsfile:
-                    if line.startswith('https://'):
-                        # extract name and version from url
-                        url = line.split(';')[0]
-                        wheel = line.split('/')[-1]
-                        name, version, _ = wheel.split('-',2)
-                        line = f'{name}=={version}'
+                    if not line or line[0] == "#":
+                        continue  # ignore comments
+                    if line.startswith(("https://", "git+https://")):
+                        # extract name and version for url
+                        rest = line.split('/')[-1]
+                        line = ""
+                        if "#egg=" in rest:
+                            # from egg info
+                            rest, egg = rest.split("#egg=", 1)
+                            egg = egg.split(";", 1)[0].rstrip()
+                            if any(compare in egg for compare in ("==", ">=", ">", "<", "<=", "!=")):
+                                warnings.warn(f"Specifying version as #egg={egg} will become unavailable in pip 25.0. "
+                                              "Use name @ url#version instead.", DeprecationWarning)
+                                line = egg
+                        else:
+                            egg = ""
+                        if "@" in rest and not line:
+                            raise ValueError("Can't deduce version from requirement")
+                        elif not line:
+                            # from filename
+                            rest = rest.replace(".zip", "-").replace(".tar.gz", "-")
+                            name, version, _ = rest.split("-", 2)
+                            line = f'{egg or name}=={version}'
+                    elif "@" in line and "#" in line:
+                        # PEP 508 does not allow us to specify a version, so we use custom syntax
+                        # name @ url#version ; marker
+                        name, rest = line.split("@", 1)
+                        version = rest.split("#", 1)[1].split(";", 1)[0].rstrip()
+                        line = f"{name.rstrip()}=={version}"
+                        if ";" in rest:  # keep marker
+                            line += rest[rest.find(";"):]
                     requirements = pkg_resources.parse_requirements(line)
-                    for requirement in requirements:
-                        requirement = str(requirement)
+                    for requirement in map(str, requirements):
                         try:
                             pkg_resources.require(requirement)
                         except pkg_resources.ResolutionError:
                             if not yes:
                                 import traceback
                                 traceback.print_exc()
-                                input(f'Requirement {requirement} is not satisfied, press enter to install it')
+                                confirm(f"Requirement {requirement} is not satisfied, press enter to install it")
                             update_command()
                             return
 
 
 if __name__ == "__main__":
     import argparse
+
     parser = argparse.ArgumentParser(description='Install archipelago requirements')
     parser.add_argument('-y', '--yes', dest='yes', action='store_true', help='answer "yes" to all questions')
     parser.add_argument('-f', '--force', dest='force', action='store_true', help='force update')
+    parser.add_argument('-a', '--append', nargs="*", dest='additional_requirements',
+                        help='List paths to additional requirement files.')
     args = parser.parse_args()
-
+    if args.additional_requirements:
+        requirements_files.update(args.additional_requirements)
     update(args.yes, args.force)

NetUtils.py

@@ -1,13 +1,13 @@
 from __future__ import annotations
 
-import logging
 import typing
 import enum
+import warnings
 from json import JSONEncoder, JSONDecoder
 
 import websockets
 
-from Utils import Version
+from Utils import ByValue, Version
 
 
 class JSONMessagePart(typing.TypedDict, total=False):
@@ -17,9 +17,11 @@ class JSONMessagePart(typing.TypedDict, total=False):
     color: str
     # owning player for location/item
     player: int
+    # if type == item indicates item flags
+    flags: int
 
 
-class ClientStatus(enum.IntEnum):
+class ClientStatus(ByValue, enum.IntEnum):
     CLIENT_UNKNOWN = 0
     CLIENT_CONNECTED = 5
     CLIENT_READY = 10
@@ -27,11 +29,22 @@ class ClientStatus(enum.IntEnum):
     CLIENT_GOAL = 30
 
 
-class Permission(enum.IntEnum):
+class SlotType(ByValue, enum.IntFlag):
+    spectator = 0b00
+    player = 0b01
+    group = 0b10
+
+    @property
+    def always_goal(self) -> bool:
+        """Mark this slot as having reached its goal instantly."""
+        return self.value != 0b01
+
+
+class Permission(ByValue, enum.IntFlag):
     disabled = 0b000  # 0, completely disables access
     enabled = 0b001  # 1, allows manual use
     goal = 0b010  # 2, allows manual use after goal completion
-    auto = 0b110  # 6, forces use after goal completion, only works for forfeit
+    auto = 0b110  # 6, forces use after goal completion, only works for release
     auto_enabled = 0b111  # 7, forces use after goal completion, allows manual use any time
 
     @staticmethod
@@ -47,16 +60,26 @@ class Permission(enum.IntEnum):
 
 
 class NetworkPlayer(typing.NamedTuple):
+    """Represents a particular player on a particular team."""
     team: int
     slot: int
     alias: str
     name: str
 
 
+class NetworkSlot(typing.NamedTuple):
+    """Represents a particular slot across teams."""
+    name: str
+    game: str
+    type: SlotType
+    group_members: typing.Union[typing.List[int], typing.Tuple] = ()  # only populated if type == group
+
+
 class NetworkItem(typing.NamedTuple):
     item: int
     location: int
     player: int
+    flags: int = 0
 
 
 def _scan_for_TypedTuples(obj: typing.Any) -> typing.Any:
@@ -64,7 +87,7 @@ def _scan_for_TypedTuples(obj: typing.Any) -> typing.Any:
         data = obj._asdict()
         data["class"] = obj.__class__.__name__
         return data
-    if isinstance(obj, (tuple, list, set)):
+    if isinstance(obj, (tuple, list, set, frozenset)):
         return tuple(_scan_for_TypedTuples(o) for o in obj)
     if isinstance(obj, dict):
         return {key: _scan_for_TypedTuples(value) for key, value in obj.items()}
@@ -74,10 +97,11 @@ def _scan_for_TypedTuples(obj: typing.Any) -> typing.Any:
 _encode = JSONEncoder(
     ensure_ascii=False,
     check_circular=False,
+    separators=(',', ':'),
 ).encode
 
 
-def encode(obj):
+def encode(obj: typing.Any) -> str:
     return _encode(_scan_for_TypedTuples(obj))
 
 
@@ -86,9 +110,11 @@ def get_any_version(data: dict) -> Version:
     return Version(int(data["major"]), int(data["minor"]), int(data["build"]))
 
 
-whitelist = {"NetworkPlayer": NetworkPlayer,
-             "NetworkItem": NetworkItem,
-             }
+allowlist = {
+    "NetworkPlayer": NetworkPlayer,
+    "NetworkItem": NetworkItem,
+    "NetworkSlot": NetworkSlot
+}
 
 custom_hooks = {
     "Version": get_any_version
@@ -100,7 +126,7 @@ def _object_hook(o: typing.Any) -> typing.Any:
         hook = custom_hooks.get(o.get("class", None), None)
         if hook:
             return hook(o)
-        cls = whitelist.get(o.get("class", None), None)
+        cls = allowlist.get(o.get("class", None), None)
         if cls:
             for key in tuple(o):
                 if key not in cls._fields:
@@ -119,9 +145,6 @@ class Endpoint:
     def __init__(self, socket):
         self.socket = socket
 
-    async def disconnect(self):
-        raise NotImplementedError
-
 
 class HandlerMeta(type):
     def __new__(mcs, name, bases, attrs):
@@ -163,6 +186,21 @@ class JSONTypes(str, enum.Enum):
 
 
 class JSONtoTextParser(metaclass=HandlerMeta):
+    color_codes = {
+        # not exact color names, close enough but decent looking
+        "black": "000000",
+        "red": "EE0000",
+        "green": "00FF7F",
+        "yellow": "FAFAD2",
+        "blue": "6495ED",
+        "magenta": "EE00EE",
+        "cyan": "00EEEE",
+        "slateblue": "6D8BE8",
+        "plum": "AF99EF",
+        "salmon": "FA8072",
+        "white": "FFFFFF"
+    }
+
     def __init__(self, ctx):
         self.ctx = ctx
 
@@ -176,7 +214,7 @@ class JSONtoTextParser(metaclass=HandlerMeta):
 
     def _handle_color(self, node: JSONMessagePart):
         codes = node["color"].split(";")
-        buffer = "".join(color_code(code) for code in codes)
+        buffer = "".join(color_code(code) for code in codes if code in color_codes)
         return buffer + self._handle_text(node) + color_code("reset")
 
     def _handle_text(self, node: JSONMessagePart):
@@ -194,12 +232,22 @@ class JSONtoTextParser(metaclass=HandlerMeta):
         return self._handle_color(node)
 
     def _handle_item_name(self, node: JSONMessagePart):
-        node["color"] = 'cyan'
+        flags = node.get("flags", 0)
+        if flags == 0:
+            node["color"] = 'cyan'
+        elif flags & 0b001:  # advancement
+            node["color"] = 'plum'
+        elif flags & 0b010:  # useful
+            node["color"] = 'slateblue'
+        elif flags & 0b100:  # trap
+            node["color"] = 'salmon'
+        else:
+            node["color"] = 'cyan'
         return self._handle_color(node)
 
     def _handle_item_id(self, node: JSONMessagePart):
         item_id = int(node["text"])
-        node["text"] = self.ctx.item_name_getter(item_id)
+        node["text"] = self.ctx.item_names[item_id]
         return self._handle_item_name(node)
 
     def _handle_location_name(self, node: JSONMessagePart):
@@ -208,7 +256,7 @@ class JSONtoTextParser(metaclass=HandlerMeta):
 
     def _handle_location_id(self, node: JSONMessagePart):
         item_id = int(node["text"])
-        node["text"] = self.ctx.location_name_getter(item_id)
+        node["text"] = self.ctx.location_names[item_id]
         return self._handle_location_name(node)
 
     def _handle_entrance_name(self, node: JSONMessagePart):
@@ -223,7 +271,7 @@ class RawJSONtoTextParser(JSONtoTextParser):
 
 color_codes = {'reset': 0, 'bold': 1, 'underline': 4, 'black': 30, 'red': 31, 'green': 32, 'yellow': 33, 'blue': 34,
                'magenta': 35, 'cyan': 36, 'white': 37, 'black_bg': 40, 'red_bg': 41, 'green_bg': 42, 'yellow_bg': 43,
-               'blue_bg': 44, 'purple_bg': 45, 'cyan_bg': 46, 'white_bg': 47}
+               'blue_bg': 44, 'magenta_bg': 45, 'cyan_bg': 46, 'white_bg': 47}
 
 
 def color_code(*args):
@@ -238,8 +286,8 @@ def add_json_text(parts: list, text: typing.Any, **kwargs) -> None:
     parts.append({"text": str(text), **kwargs})
 
 
-def add_json_item(parts: list, item_id: int, player: int = 0, **kwargs) -> None:
-    parts.append({"text": str(item_id), "player": player, "type": JSONTypes.item_id, **kwargs})
+def add_json_item(parts: list, item_id: int, player: int = 0, item_flags: int = 0, **kwargs) -> None:
+    parts.append({"text": str(item_id), "player": player, "flags": item_flags, "type": JSONTypes.item_id, **kwargs})
 
 
 def add_json_location(parts: list, item_id: int, player: int = 0, **kwargs) -> None:
@@ -253,13 +301,15 @@ class Hint(typing.NamedTuple):
     item: int
     found: bool
     entrance: str = ""
+    item_flags: int = 0
 
     def re_check(self, ctx, team) -> Hint:
         if self.found:
             return self
         found = self.location in ctx.location_checks[team, self.finding_player]
         if found:
-            return Hint(self.receiving_player, self.finding_player, self.location, self.item, found, self.entrance)
+            return Hint(self.receiving_player, self.finding_player, self.location, self.item, found, self.entrance,
+                        self.item_flags)
         return self
 
     def __hash__(self):
@@ -270,7 +320,7 @@ class Hint(typing.NamedTuple):
         add_json_text(parts, "[Hint]: ")
         add_json_text(parts, self.receiving_player, type="player_id")
         add_json_text(parts, "'s ")
-        add_json_item(parts, self.item, self.receiving_player)
+        add_json_item(parts, self.item, self.receiving_player, self.item_flags)
         add_json_text(parts, " is at ")
         add_json_location(parts, self.location, self.finding_player)
         add_json_text(parts, " in ")
@@ -288,9 +338,91 @@ class Hint(typing.NamedTuple):
 
         return {"cmd": "PrintJSON", "data": parts, "type": "Hint",
                 "receiving": self.receiving_player,
-                "item": NetworkItem(self.item, self.location, self.finding_player),
+                "item": NetworkItem(self.item, self.location, self.finding_player, self.item_flags),
                 "found": self.found}
 
     @property
     def local(self):
         return self.receiving_player == self.finding_player
+
+
+class _LocationStore(dict, typing.MutableMapping[int, typing.Dict[int, typing.Tuple[int, int, int]]]):
+    def __init__(self, values: typing.MutableMapping[int, typing.Dict[int, typing.Tuple[int, int, int]]]):
+        super().__init__(values)
+
+        if not self:
+            raise ValueError(f"Rejecting game with 0 players")
+
+        if len(self) != max(self):
+            raise ValueError("Player IDs not continuous")
+
+        if len(self.get(0, {})):
+            raise ValueError("Invalid player id 0 for location")
+
+    def find_item(self, slots: typing.Set[int], seeked_item_id: int
+                  ) -> typing.Generator[typing.Tuple[int, int, int, int, int], None, None]:
+        for finding_player, check_data in self.items():
+            for location_id, (item_id, receiving_player, item_flags) in check_data.items():
+                if receiving_player in slots and item_id == seeked_item_id:
+                    yield finding_player, location_id, item_id, receiving_player, item_flags
+
+    def get_for_player(self, slot: int) -> typing.Dict[int, typing.Set[int]]:
+        import collections
+        all_locations: typing.Dict[int, typing.Set[int]] = collections.defaultdict(set)
+        for source_slot, location_data in self.items():
+            for location_id, values in location_data.items():
+                if values[1] == slot:
+                    all_locations[source_slot].add(location_id)
+        return all_locations
+
+    def get_checked(self, state: typing.Dict[typing.Tuple[int, int], typing.Set[int]], team: int, slot: int
+                    ) -> typing.List[int]:
+        checked = state[team, slot]
+        if not checked:
+            # This optimizes the case where everyone connects to a fresh game at the same time.
+            return []
+        return [location_id for
+                location_id in self[slot] if
+                location_id in checked]
+
+    def get_missing(self, state: typing.Dict[typing.Tuple[int, int], typing.Set[int]], team: int, slot: int
+                    ) -> typing.List[int]:
+        checked = state[team, slot]
+        if not checked:
+            # This optimizes the case where everyone connects to a fresh game at the same time.
+            return list(self[slot])
+        return [location_id for
+                location_id in self[slot] if
+                location_id not in checked]
+
+    def get_remaining(self, state: typing.Dict[typing.Tuple[int, int], typing.Set[int]], team: int, slot: int
+                      ) -> typing.List[int]:
+        checked = state[team, slot]
+        player_locations = self[slot]
+        return sorted([player_locations[location_id][0] for
+                       location_id in player_locations if
+                       location_id not in checked])
+
+
+if typing.TYPE_CHECKING:  # type-check with pure python implementation until we have a typing stub
+    LocationStore = _LocationStore
+else:
+    try:
+        from _speedups import LocationStore
+        import _speedups
+        import os.path
+        if os.path.isfile("_speedups.pyx") and os.path.getctime(_speedups.__file__) < os.path.getctime("_speedups.pyx"):
+            warnings.warn(f"{_speedups.__file__} outdated! "
+                          f"Please rebuild with `cythonize -b -i _speedups.pyx` or delete it!")
+    except ImportError:
+        try:
+            import pyximport
+            pyximport.install()
+        except ImportError:
+            pyximport = None
+        try:
+            from _speedups import LocationStore
+        except ImportError:
+            warnings.warn("_speedups not available. Falling back to pure python LocationStore. "
+                          "Install a matching C++ compiler for your platform to compile _speedups.")
+            LocationStore = _LocationStore

OoTAdjuster.py

@@ -3,6 +3,7 @@ import argparse
 import logging
 import random
 import os
+import zipfile
 from itertools import chain
 
 from BaseClasses import MultiWorld
@@ -12,6 +13,7 @@ from worlds.oot.Cosmetics import patch_cosmetics
 from worlds.oot.Options import cosmetic_options, sfx_options
 from worlds.oot.Rom import Rom, compress_rom_file
 from worlds.oot.N64Patch import apply_patch_file
+from worlds.oot.Utils import data_path
 from Utils import local_path
 
 logger = logging.getLogger('OoTAdjuster')
@@ -42,7 +44,7 @@ def adjustGUI():
         StringVar, IntVar, Checkbutton, Frame, Label, X, Entry, Button, \
         OptionMenu, filedialog, messagebox, ttk
     from argparse import Namespace
-    from Main import __version__ as MWVersion
+    from Utils import __version__ as MWVersion
 
     window = tk.Tk()
     window.wm_title(f"Archipelago {MWVersion} OoT Adjuster")
@@ -86,7 +88,7 @@ def adjustGUI():
             option = sfx_options[option_name]
         optionFrame = Frame(romSettingsFrame)
         optionFrame.grid(row=row, column=column, sticky=E)
-        optionLabel = Label(optionFrame, text=option.displayname)
+        optionLabel = Label(optionFrame, text=option.display_name)
         optionLabel.pack(side=LEFT)
         setattr(opts, option_name, StringVar())
         getattr(opts, option_name).set(option.name_lookup[option.default])
@@ -142,7 +144,7 @@ def adjustGUI():
     option = cosmetic_options['sword_trail_duration']
     optionFrame = Frame(romSettingsFrame)
     optionFrame.grid(row=8, column=2, sticky=E)
-    optionLabel = Label(optionFrame, text=option.displayname)
+    optionLabel = Label(optionFrame, text=option.display_name)
     optionLabel.pack(side=LEFT)
     setattr(opts, 'sword_trail_duration', StringVar())
     getattr(opts, 'sword_trail_duration').set(option.default)
@@ -195,7 +197,7 @@ def set_icon(window):
 def adjust(args):
     # Create a fake world and OOTWorld to use as a base
     world = MultiWorld(1)
-    world.slot_seeds = {1: random}
+    world.per_slot_randoms = {1: random}
     ootworld = OOTWorld(world, 1)
     # Set options in the fake OOTWorld
     for name, option in chain(cosmetic_options.items(), sfx_options.items()):
@@ -211,26 +213,39 @@ def adjust(args):
     ootworld.logic_rules = 'glitched' if args.is_glitched else 'glitchless'
     ootworld.death_link = args.deathlink
 
+    delete_zootdec = False
     if os.path.splitext(args.rom)[-1] in ['.z64', '.n64']:
         # Load up the ROM
         rom = Rom(file=args.rom, force_use=True)
-    elif os.path.splitext(args.rom)[-1] == '.apz5':
+        delete_zootdec = True
+    elif os.path.splitext(args.rom)[-1] in ['.apz5', '.zpf']:
         # Load vanilla ROM
         rom = Rom(file=args.vanilla_rom, force_use=True)
+        apz5_file = args.rom
+        base_name = os.path.splitext(apz5_file)[0]
         # Patch file
-        apply_patch_file(rom, args.rom)
+        apply_patch_file(rom, apz5_file,
+            sub_file=(os.path.basename(base_name) + '.zpf'
+                if zipfile.is_zipfile(apz5_file)
+                else None))
     else:
-        raise Exception("Invalid file extension; requires .n64, .z64, .apz5")
+        raise Exception("Invalid file extension; requires .n64, .z64, .apz5, .zpf")
     # Call patch_cosmetics
-    patch_cosmetics(ootworld, rom)
-    rom.write_byte(rom.sym('DEATH_LINK'), args.deathlink)
-    # Output new file
-    path_pieces = os.path.splitext(args.rom)
-    decomp_path = path_pieces[0] + '-adjusted-decomp.n64'
-    comp_path = path_pieces[0] + '-adjusted.n64'
-    rom.write_to_file(decomp_path)
-    compress_rom_file(decomp_path, comp_path)
-    os.remove(decomp_path)
+    try:
+        patch_cosmetics(ootworld, rom)
+        rom.write_byte(rom.sym('DEATH_LINK'), args.deathlink)
+        # Output new file
+        path_pieces = os.path.splitext(args.rom)
+        decomp_path = path_pieces[0] + '-adjusted-decomp.n64'
+        comp_path = path_pieces[0] + '-adjusted.n64'
+        rom.write_to_file(decomp_path)
+        os.chdir(data_path("Compress"))
+        compress_rom_file(decomp_path, comp_path)
+        os.remove(decomp_path)
+    finally:
+        if delete_zootdec:
+            os.chdir(os.path.split(__file__)[0])
+            os.remove("ZOOTDEC.z64")
     return comp_path
 
 if __name__ == '__main__':

OoTClient.py

@@ -0,0 +1,352 @@
+import asyncio
+import json
+import os
+import multiprocessing
+import subprocess
+import zipfile
+from asyncio import StreamReader, StreamWriter
+
+# CommonClient import first to trigger ModuleUpdater
+from CommonClient import CommonContext, server_loop, gui_enabled, \
+    ClientCommandProcessor, logger, get_base_parser
+import Utils
+from Utils import async_start
+from worlds import network_data_package
+from worlds.oot.Rom import Rom, compress_rom_file
+from worlds.oot.N64Patch import apply_patch_file
+from worlds.oot.Utils import data_path
+
+
+CONNECTION_TIMING_OUT_STATUS = "Connection timing out. Please restart your emulator, then restart connector_oot.lua"
+CONNECTION_REFUSED_STATUS = "Connection refused. Please start your emulator and make sure connector_oot.lua is running"
+CONNECTION_RESET_STATUS = "Connection was reset. Please restart your emulator, then restart connector_oot.lua"
+CONNECTION_TENTATIVE_STATUS = "Initial Connection Made"
+CONNECTION_CONNECTED_STATUS = "Connected"
+CONNECTION_INITIAL_STATUS = "Connection has not been initiated"
+
+"""
+Payload: lua -> client
+{
+    playerName: string,
+    locations: dict,
+    deathlinkActive: bool,
+    isDead: bool,
+    gameComplete: bool
+}
+
+Payload: client -> lua
+{
+    items: list,
+    playerNames: list,
+    triggerDeath: bool
+}
+
+Deathlink logic:
+"Dead" is true <-> Link is at 0 hp.
+
+deathlink_pending: we need to kill the player
+deathlink_sent_this_death: we interacted with the multiworld on this death, waiting to reset with living link
+
+"""
+
+oot_loc_name_to_id = network_data_package["games"]["Ocarina of Time"]["location_name_to_id"]
+
+script_version: int = 3
+
+def get_item_value(ap_id):
+    return ap_id - 66000
+
+
+class OoTCommandProcessor(ClientCommandProcessor):
+    def __init__(self, ctx): 
+        super().__init__(ctx)
+
+    def _cmd_n64(self):
+        """Check N64 Connection State"""
+        if isinstance(self.ctx, OoTContext):
+            logger.info(f"N64 Status: {self.ctx.n64_status}")
+
+    def _cmd_deathlink(self):
+        """Toggle deathlink from client. Overrides default setting."""
+        if isinstance(self.ctx, OoTContext):
+            self.ctx.deathlink_client_override = True
+            self.ctx.deathlink_enabled = not self.ctx.deathlink_enabled
+            async_start(self.ctx.update_death_link(self.ctx.deathlink_enabled), name="Update Deathlink")
+
+
+class OoTContext(CommonContext):
+    command_processor = OoTCommandProcessor
+    items_handling = 0b001  # full local
+
+    def __init__(self, server_address, password):
+        super().__init__(server_address, password)
+        self.game = 'Ocarina of Time'
+        self.n64_streams: (StreamReader, StreamWriter) = None
+        self.n64_sync_task = None
+        self.n64_status = CONNECTION_INITIAL_STATUS
+        self.awaiting_rom = False
+        self.location_table = {}
+        self.collectible_table = {}
+        self.collectible_override_flags_address = 0
+        self.collectible_offsets = {}
+        self.deathlink_enabled = False
+        self.deathlink_pending = False
+        self.deathlink_sent_this_death = False
+        self.deathlink_client_override = False
+        self.version_warning = False
+
+    async def server_auth(self, password_requested: bool = False):
+        if password_requested and not self.password:
+            await super(OoTContext, self).server_auth(password_requested)
+        if not self.auth:
+            self.awaiting_rom = True
+            logger.info('Awaiting connection to EmuHawk to get player information')
+            return
+
+        await self.send_connect()
+
+    def on_deathlink(self, data: dict):
+        self.deathlink_pending = True
+        super().on_deathlink(data)
+
+    def run_gui(self):
+        from kvui import GameManager
+
+        class OoTManager(GameManager):
+            logging_pairs = [
+                ("Client", "Archipelago")
+            ]
+            base_title = "Archipelago Ocarina of Time Client"
+
+        self.ui = OoTManager(self)
+        self.ui_task = asyncio.create_task(self.ui.async_run(), name="UI")
+
+    def on_package(self, cmd, args):
+        if cmd == 'Connected':
+            slot_data = args.get('slot_data', None)
+            if slot_data:
+                self.collectible_override_flags_address = slot_data.get('collectible_override_flags', 0)
+                self.collectible_offsets = slot_data.get('collectible_flag_offsets', {})
+
+
+def get_payload(ctx: OoTContext):
+    if ctx.deathlink_enabled and ctx.deathlink_pending:
+        trigger_death = True
+        ctx.deathlink_sent_this_death = True
+    else:
+        trigger_death = False
+
+    payload = json.dumps({
+            "items": [get_item_value(item.item) for item in ctx.items_received],
+            "playerNames": [name for (i, name) in ctx.player_names.items() if i != 0],
+            "triggerDeath": trigger_death,
+            "collectibleOverrides": ctx.collectible_override_flags_address,
+            "collectibleOffsets": ctx.collectible_offsets
+        })
+    return payload
+
+
+async def parse_payload(payload: dict, ctx: OoTContext, force: bool):
+
+    # Refuse to do anything if ROM is detected as changed
+    if ctx.auth and payload['playerName'] != ctx.auth:
+        logger.warning("ROM change detected. Disconnecting and reconnecting...")
+        ctx.deathlink_enabled = False
+        ctx.deathlink_client_override = False
+        ctx.finished_game = False
+        ctx.location_table = {}
+        ctx.collectible_table = {}
+        ctx.deathlink_pending = False
+        ctx.deathlink_sent_this_death = False
+        ctx.auth = payload['playerName']
+        await ctx.send_connect()
+        return
+
+    # Turn on deathlink if it is on, and if the client hasn't overriden it
+    if payload['deathlinkActive'] and not ctx.deathlink_enabled and not ctx.deathlink_client_override:
+        await ctx.update_death_link(True)
+        ctx.deathlink_enabled = True
+
+    # Game completion handling
+    if payload['gameComplete'] and not ctx.finished_game:
+        await ctx.send_msgs([{
+            "cmd": "StatusUpdate",
+            "status": 30
+        }])
+        ctx.finished_game = True
+
+    # Locations handling
+    locations = payload['locations']
+    collectibles = payload['collectibles']
+
+    # The Lua JSON library serializes an empty table into a list instead of a dict. Verify types for safety:
+    if isinstance(locations, list):
+        locations = {}
+    if isinstance(collectibles, list):
+        collectibles = {}
+
+    if ctx.location_table != locations or ctx.collectible_table != collectibles:
+        ctx.location_table = locations
+        ctx.collectible_table = collectibles
+        locs1 = [oot_loc_name_to_id[loc] for loc, b in ctx.location_table.items() if b]
+        locs2 = [int(loc) for loc, b in ctx.collectible_table.items() if b]
+        await ctx.send_msgs([{
+            "cmd": "LocationChecks",
+            "locations": locs1 + locs2
+        }])
+
+    # Deathlink handling
+    if ctx.deathlink_enabled:
+        if payload['isDead']: # link is dead
+            ctx.deathlink_pending = False
+            if not ctx.deathlink_sent_this_death:
+                ctx.deathlink_sent_this_death = True
+                await ctx.send_death()
+        else: # link is alive
+            ctx.deathlink_sent_this_death = False
+
+
+async def n64_sync_task(ctx: OoTContext): 
+    logger.info("Starting n64 connector. Use /n64 for status information.")
+    while not ctx.exit_event.is_set():
+        error_status = None
+        if ctx.n64_streams:
+            (reader, writer) = ctx.n64_streams
+            msg = get_payload(ctx).encode()
+            writer.write(msg)
+            writer.write(b'\n')
+            try:
+                await asyncio.wait_for(writer.drain(), timeout=1.5)
+                try:
+                    data = await asyncio.wait_for(reader.readline(), timeout=10)
+                    data_decoded = json.loads(data.decode())
+                    reported_version = data_decoded.get('scriptVersion', 0)
+                    if reported_version >= script_version:
+                        if ctx.game is not None and 'locations' in data_decoded:
+                            # Not just a keep alive ping, parse
+                            async_start(parse_payload(data_decoded, ctx, False))
+                        if not ctx.auth:
+                            ctx.auth = data_decoded['playerName']
+                            if ctx.awaiting_rom:
+                                await ctx.server_auth(False)
+                    else:
+                        if not ctx.version_warning:
+                            logger.warning(f"Your Lua script is version {reported_version}, expected {script_version}. "
+                                "Please update to the latest version. "
+                                "Your connection to the Archipelago server will not be accepted.")
+                            ctx.version_warning = True
+                except asyncio.TimeoutError:
+                    logger.debug("Read Timed Out, Reconnecting")
+                    error_status = CONNECTION_TIMING_OUT_STATUS
+                    writer.close()
+                    ctx.n64_streams = None
+                except ConnectionResetError as e:
+                    logger.debug("Read failed due to Connection Lost, Reconnecting")
+                    error_status = CONNECTION_RESET_STATUS
+                    writer.close()
+                    ctx.n64_streams = None
+            except TimeoutError:
+                logger.debug("Connection Timed Out, Reconnecting")
+                error_status = CONNECTION_TIMING_OUT_STATUS
+                writer.close()
+                ctx.n64_streams = None
+            except ConnectionResetError:
+                logger.debug("Connection Lost, Reconnecting")
+                error_status = CONNECTION_RESET_STATUS
+                writer.close()
+                ctx.n64_streams = None
+            if ctx.n64_status == CONNECTION_TENTATIVE_STATUS:
+                if not error_status:
+                    logger.info("Successfully Connected to N64")
+                    ctx.n64_status = CONNECTION_CONNECTED_STATUS
+                else:
+                    ctx.n64_status = f"Was tentatively connected but error occured: {error_status}"
+            elif error_status:
+                ctx.n64_status = error_status
+                logger.info("Lost connection to N64 and attempting to reconnect. Use /n64 for status updates")
+        else:
+            try:
+                logger.debug("Attempting to connect to N64")
+                ctx.n64_streams = await asyncio.wait_for(asyncio.open_connection("localhost", 28921), timeout=10)
+                ctx.n64_status = CONNECTION_TENTATIVE_STATUS
+            except TimeoutError:
+                logger.debug("Connection Timed Out, Trying Again")
+                ctx.n64_status = CONNECTION_TIMING_OUT_STATUS
+                continue
+            except ConnectionRefusedError:
+                logger.debug("Connection Refused, Trying Again")
+                ctx.n64_status = CONNECTION_REFUSED_STATUS
+                continue
+
+
+async def run_game(romfile):
+    auto_start = Utils.get_options()["oot_options"].get("rom_start", True)
+    if auto_start is True:
+        import webbrowser
+        webbrowser.open(romfile)
+    elif os.path.isfile(auto_start):
+        subprocess.Popen([auto_start, romfile],
+                         stdin=subprocess.DEVNULL, stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL)
+
+
+async def patch_and_run_game(apz5_file):
+    apz5_file = os.path.abspath(apz5_file)
+    base_name = os.path.splitext(apz5_file)[0]
+    decomp_path = base_name + '-decomp.z64'
+    comp_path = base_name + '.z64'
+    # Load vanilla ROM, patch file, compress ROM
+    rom_file_name = Utils.get_options()["oot_options"]["rom_file"]
+    rom = Rom(rom_file_name)
+
+    sub_file = None
+    if zipfile.is_zipfile(apz5_file):
+        for name in zipfile.ZipFile(apz5_file).namelist():
+            if name.endswith('.zpf'):
+                sub_file = name
+                break
+
+    apply_patch_file(rom, apz5_file, sub_file=sub_file)
+    rom.write_to_file(decomp_path)
+    os.chdir(data_path("Compress"))
+    compress_rom_file(decomp_path, comp_path)
+    os.remove(decomp_path)
+    async_start(run_game(comp_path))
+
+
+if __name__ == '__main__':
+
+    Utils.init_logging("OoTClient")
+
+    async def main():
+        multiprocessing.freeze_support()
+        parser = get_base_parser()
+        parser.add_argument('apz5_file', default="", type=str, nargs="?",
+                            help='Path to an APZ5 file')
+        args = parser.parse_args()
+
+        if args.apz5_file:
+            logger.info("APZ5 file supplied, beginning patching process...")
+            async_start(patch_and_run_game(args.apz5_file))
+
+        ctx = OoTContext(args.connect, args.password)
+        ctx.server_task = asyncio.create_task(server_loop(ctx), name="Server Loop")
+        if gui_enabled:
+            ctx.run_gui()
+        ctx.run_cli()
+
+        ctx.n64_sync_task = asyncio.create_task(n64_sync_task(ctx), name="N64 Sync")
+
+        await ctx.exit_event.wait()
+        ctx.server_address = None
+
+        await ctx.shutdown()
+
+        if ctx.n64_sync_task:
+            await ctx.n64_sync_task
+
+    import colorama
+
+    colorama.init()
+
+    asyncio.run(main())
+    colorama.deinit()

Patch.py

@@ -1,213 +1,35 @@
-# TODO: convert this into a system like AutoWorld
+from __future__ import annotations
 
-import bsdiff4
-import yaml
 import os
-import lzma
-import threading
-import concurrent.futures
-import zipfile
 import sys
-from typing import Tuple, Optional
+from typing import Tuple, Optional, TypedDict
 
-import Utils
+if __name__ == "__main__":
+    import ModuleUpdate
+    ModuleUpdate.update()
 
-current_patch_version = 3
-
-GAME_ALTTP = "A Link to the Past"
-GAME_SM = "Super Metroid"
-GAME_SOE = "Secret of Evermore"
-supported_games = {"A Link to the Past", "Super Metroid", "Secret of Evermore"}
-
-preferred_endings = {
-    GAME_ALTTP: "apbp",
-    GAME_SM: "apm3",
-    GAME_SOE: "apsoe"
-}
+from worlds.Files import AutoPatchRegister, APDeltaPatch
 
 
-def generate_yaml(patch: bytes, metadata: Optional[dict] = None, game: str = GAME_ALTTP) -> bytes:
-    if game == GAME_ALTTP:
-        from worlds.alttp.Rom import JAP10HASH as HASH
-    elif game == GAME_SM:
-        from worlds.sm.Rom import JAP10HASH as HASH
-    elif game == GAME_SOE:
-        from worlds.soe.Patch import USHASH as HASH
-    else:
-        raise RuntimeError(f"Selected game {game} for base rom not found.")
-
-    patch = yaml.dump({"meta": metadata,
-                       "patch": patch,
-                       "game": game,
-                       # minimum version of patch system expected for patching to be successful
-                       "compatible_version": 3,
-                       "version": current_patch_version,
-                       "base_checksum": HASH})
-    return patch.encode(encoding="utf-8-sig")
+class RomMeta(TypedDict):
+    server: str
+    player: Optional[int]
+    player_name: str
 
 
-def generate_patch(rom: bytes, metadata: Optional[dict] = None, game: str = GAME_ALTTP) -> bytes:
-    if metadata is None:
-        metadata = {}
-    patch = bsdiff4.diff(get_base_rom_data(game), rom)
-    return generate_yaml(patch, metadata, game)
-
-
-def create_patch_file(rom_file_to_patch: str, server: str = "", destination: str = None,
-                      player: int = 0, player_name: str = "", game: str = GAME_ALTTP) -> str:
-    meta = {"server": server,  # allow immediate connection to server in multiworld. Empty string otherwise
-            "player_id": player,
-            "player_name": player_name}
-    bytes = generate_patch(load_bytes(rom_file_to_patch),
-                           meta,
-                           game)
-    target = destination if destination else os.path.splitext(rom_file_to_patch)[0] + (
-        ".apbp" if game == GAME_ALTTP else ".apm3")
-    write_lzma(bytes, target)
-    return target
-
-
-def create_rom_bytes(patch_file: str, ignore_version: bool = False) -> Tuple[dict, str, bytearray]:
-    data = Utils.parse_yaml(lzma.decompress(load_bytes(patch_file)).decode("utf-8-sig"))
-    game_name = data["game"]
-    if not ignore_version and data["compatible_version"] > current_patch_version:
-        raise RuntimeError("Patch file is incompatible with this patcher, likely an update is required.")
-    patched_data = bsdiff4.patch(get_base_rom_data(game_name), data["patch"])
-    rom_hash = patched_data[int(0x7FC0):int(0x7FD5)]
-    data["meta"]["hash"] = "".join(chr(x) for x in rom_hash)
-    target = os.path.splitext(patch_file)[0] + ".sfc"
-    return data["meta"], target, patched_data
-
-
-def get_base_rom_data(game: str):
-    if game == GAME_ALTTP:
-        from worlds.alttp.Rom import get_base_rom_bytes
-    elif game == "alttp":  # old version for A Link to the Past
-        from worlds.alttp.Rom import get_base_rom_bytes
-    elif game == GAME_SM:
-        from worlds.sm.Rom import get_base_rom_bytes
-    elif game == GAME_SOE:
-        file_name = Utils.get_options()["soe_options"]["rom_file"]
-        get_base_rom_bytes = lambda: bytes(read_rom(open(file_name, "rb")))
-    else:
-        raise RuntimeError("Selected game for base rom not found.")
-    return get_base_rom_bytes()
-
-
-def create_rom_file(patch_file: str) -> Tuple[dict, str]:
-    data, target, patched_data = create_rom_bytes(patch_file)
-    with open(target, "wb") as f:
-        f.write(patched_data)
-    return data, target
-
-
-def update_patch_data(patch_data: bytes, server: str = "") -> bytes:
-    data = Utils.parse_yaml(lzma.decompress(patch_data).decode("utf-8-sig"))
-    data["meta"]["server"] = server
-    bytes = generate_yaml(data["patch"], data["meta"], data["game"])
-    return lzma.compress(bytes)
-
-
-def load_bytes(path: str) -> bytes:
-    with open(path, "rb") as f:
-        return f.read()
-
-
-def write_lzma(data: bytes, path: str):
-    with lzma.LZMAFile(path, 'wb') as f:
-        f.write(data)
-
-
-def read_rom(stream, strip_header=True) -> bytearray:
-    """Reads rom into bytearray and optionally strips off any smc header"""
-    buffer = bytearray(stream.read())
-    if strip_header and len(buffer) % 0x400 == 0x200:
-        return buffer[0x200:]
-    return buffer
+def create_rom_file(patch_file: str) -> Tuple[RomMeta, str]:
+    auto_handler = AutoPatchRegister.get_handler(patch_file)
+    if auto_handler:
+        handler: APDeltaPatch = auto_handler(patch_file)
+        target = os.path.splitext(patch_file)[0]+handler.result_file_ending
+        handler.patch(target)
+        return {"server": handler.server,
+                "player": handler.player,
+                "player_name": handler.player_name}, target
+    raise NotImplementedError(f"No Handler for {patch_file} found.")
 
 
 if __name__ == "__main__":
-    host = Utils.get_public_ipv4()
-    options = Utils.get_options()['server_options']
-    if options['host']:
-        host = options['host']
-
-    address = f"{host}:{options['port']}"
-    ziplock = threading.Lock()
-    print(f"Host for patches to be created is {address}")
-    with concurrent.futures.ThreadPoolExecutor() as pool:
-        for rom in sys.argv:
-            try:
-                if rom.endswith(".sfc"):
-                    print(f"Creating patch for {rom}")
-                    result = pool.submit(create_patch_file, rom, address)
-                    result.add_done_callback(lambda task: print(f"Created patch {task.result()}"))
-
-                elif rom.endswith(".apbp"):
-                    print(f"Applying patch {rom}")
-                    data, target = create_rom_file(rom)
-                    romfile, adjusted = Utils.get_adjuster_settings(target)
-                    if adjusted:
-                        try:
-                            os.replace(romfile, target)
-                            romfile = target
-                        except Exception as e:
-                            print(e)
-                    print(f"Created rom {romfile if adjusted else target}.")
-                    if 'server' in data:
-                        Utils.persistent_store("servers", data['hash'], data['server'])
-                        print(f"Host is {data['server']}")
-                elif rom.endswith(".apm3"):
-                    print(f"Applying patch {rom}")
-                    data, target = create_rom_file(rom)
-                    print(f"Created rom {target}.")
-                    if 'server' in data:
-                        Utils.persistent_store("servers", data['hash'], data['server'])
-                        print(f"Host is {data['server']}")
-                elif rom.endswith(".archipelago"):
-                    import json
-                    import zlib
-
-                    with open(rom, 'rb') as fr:
-
-                        multidata = zlib.decompress(fr.read()).decode("utf-8")
-                        with open(rom + '.txt', 'w') as fw:
-                            fw.write(multidata)
-                        multidata = json.loads(multidata)
-                        for romname in multidata['roms']:
-                            Utils.persistent_store("servers", "".join(chr(byte) for byte in romname[2]), address)
-                        from Utils import get_options
-
-                        multidata["server_options"] = get_options()["server_options"]
-                        multidata = zlib.compress(json.dumps(multidata).encode("utf-8"), 9)
-                        with open(rom + "_updated.archipelago", 'wb') as f:
-                            f.write(multidata)
-
-                elif rom.endswith(".zip"):
-                    print(f"Updating host in patch files contained in {rom}")
-
-
-                    def _handle_zip_file_entry(zfinfo: zipfile.ZipInfo, server: str):
-                        data = zfr.read(zfinfo)
-                        if zfinfo.filename.endswith(".apbp") or zfinfo.filename.endswith(".apm3"):
-                            data = update_patch_data(data, server)
-                        with ziplock:
-                            zfw.writestr(zfinfo, data)
-                        return zfinfo.filename
-
-
-                    futures = []
-                    with zipfile.ZipFile(rom, "r") as zfr:
-                        updated_zip = os.path.splitext(rom)[0] + "_updated.zip"
-                        with zipfile.ZipFile(updated_zip, "w", compression=zipfile.ZIP_DEFLATED,
-                                             compresslevel=9) as zfw:
-                            for zfname in zfr.namelist():
-                                futures.append(pool.submit(_handle_zip_file_entry, zfr.getinfo(zfname), address))
-                            for future in futures:
-                                print(f"File {future.result()} added to {os.path.split(updated_zip)[1]}")
-
-            except:
-                import traceback
-
-                traceback.print_exc()
-                input("Press enter to close.")
+    for file in sys.argv[1:]:
+        meta_data, result_file = create_rom_file(file)
+        print(f"Patch with meta-data {meta_data} was written to {result_file}")

PokemonClient.py

@@ -0,0 +1,382 @@
+import asyncio
+import json
+import time
+import os
+import bsdiff4
+import subprocess
+import zipfile
+from asyncio import StreamReader, StreamWriter
+from typing import List
+
+
+import Utils
+from Utils import async_start
+from CommonClient import CommonContext, server_loop, gui_enabled, ClientCommandProcessor, logger, \
+    get_base_parser
+
+from worlds.pokemon_rb.locations import location_data
+from worlds.pokemon_rb.rom import RedDeltaPatch, BlueDeltaPatch
+
+location_map = {"Rod": {}, "EventFlag": {}, "Missable": {}, "Hidden": {}, "list": {}, "DexSanityFlag": {}}
+location_bytes_bits = {}
+for location in location_data:
+    if location.ram_address is not None:
+        if type(location.ram_address) == list:
+            location_map[type(location.ram_address).__name__][(location.ram_address[0].flag, location.ram_address[1].flag)] = location.address
+            location_bytes_bits[location.address] = [{'byte': location.ram_address[0].byte, 'bit': location.ram_address[0].bit},
+                                                     {'byte': location.ram_address[1].byte, 'bit': location.ram_address[1].bit}]
+        else:
+            location_map[type(location.ram_address).__name__][location.ram_address.flag] = location.address
+            location_bytes_bits[location.address] = {'byte': location.ram_address.byte, 'bit': location.ram_address.bit}
+
+location_name_to_id = {location.name: location.address for location in location_data if location.type == "Item"
+                           and location.address is not None}
+
+SYSTEM_MESSAGE_ID = 0
+
+CONNECTION_TIMING_OUT_STATUS = "Connection timing out. Please restart your emulator, then restart pkmn_rb.lua"
+CONNECTION_REFUSED_STATUS = "Connection Refused. Please start your emulator and make sure pkmn_rb.lua is running"
+CONNECTION_RESET_STATUS = "Connection was reset. Please restart your emulator, then restart pkmn_rb.lua"
+CONNECTION_TENTATIVE_STATUS = "Initial Connection Made"
+CONNECTION_CONNECTED_STATUS = "Connected"
+CONNECTION_INITIAL_STATUS = "Connection has not been initiated"
+
+DISPLAY_MSGS = True
+
+SCRIPT_VERSION = 3
+
+
+class GBCommandProcessor(ClientCommandProcessor):
+    def __init__(self, ctx: CommonContext):
+        super().__init__(ctx)
+
+    def _cmd_gb(self):
+        """Check Gameboy Connection State"""
+        if isinstance(self.ctx, GBContext):
+            logger.info(f"Gameboy Status: {self.ctx.gb_status}")
+
+
+class GBContext(CommonContext):
+    command_processor = GBCommandProcessor
+    game = 'Pokemon Red and Blue'
+
+    def __init__(self, server_address, password):
+        super().__init__(server_address, password)
+        self.gb_streams: (StreamReader, StreamWriter) = None
+        self.gb_sync_task = None
+        self.messages = {}
+        self.locations_array = None
+        self.gb_status = CONNECTION_INITIAL_STATUS
+        self.awaiting_rom = False
+        self.display_msgs = True
+        self.deathlink_pending = False
+        self.set_deathlink = False
+        self.client_compatibility_mode = 0
+        self.items_handling = 0b001
+        self.sent_release = False
+        self.sent_collect = False
+        self.auto_hints = set()
+
+    async def server_auth(self, password_requested: bool = False):
+        if password_requested and not self.password:
+            await super(GBContext, self).server_auth(password_requested)
+        if not self.auth:
+            self.awaiting_rom = True
+            logger.info('Awaiting connection to EmuHawk to get Player information')
+            return
+
+        await self.send_connect()
+
+    def _set_message(self, msg: str, msg_id: int):
+        if DISPLAY_MSGS:
+            self.messages[(time.time(), msg_id)] = msg
+
+    def on_package(self, cmd: str, args: dict):
+        if cmd == 'Connected':
+            self.locations_array = None
+            if 'death_link' in args['slot_data'] and args['slot_data']['death_link']:
+                self.set_deathlink = True
+        elif cmd == "RoomInfo":
+            self.seed_name = args['seed_name']
+        elif cmd == 'Print':
+            msg = args['text']
+            if ': !' not in msg:
+                self._set_message(msg, SYSTEM_MESSAGE_ID)
+        elif cmd == "ReceivedItems":
+            msg = f"Received {', '.join([self.item_names[item.item] for item in args['items']])}"
+            self._set_message(msg, SYSTEM_MESSAGE_ID)
+
+    def on_deathlink(self, data: dict):
+        self.deathlink_pending = True
+        super().on_deathlink(data)
+
+    def run_gui(self):
+        from kvui import GameManager
+
+        class GBManager(GameManager):
+            logging_pairs = [
+                ("Client", "Archipelago")
+            ]
+            base_title = "Archipelago Pokémon Client"
+
+        self.ui = GBManager(self)
+        self.ui_task = asyncio.create_task(self.ui.async_run(), name="UI")
+
+
+def get_payload(ctx: GBContext):
+    current_time = time.time()
+    ret = json.dumps(
+        {
+            "items": [item.item for item in ctx.items_received],
+            "messages": {f'{key[0]}:{key[1]}': value for key, value in ctx.messages.items()
+                         if key[0] > current_time - 10},
+            "deathlink": ctx.deathlink_pending,
+            "options": ((ctx.permissions['release'] in ('goal', 'enabled')) * 2) + (ctx.permissions['collect'] in ('goal', 'enabled'))
+        }
+    )
+    ctx.deathlink_pending = False
+    return ret
+
+
+async def parse_locations(data: List, ctx: GBContext):
+    locations = []
+    flags = {"EventFlag": data[:0x140], "Missable": data[0x140:0x140 + 0x20],
+             "Hidden": data[0x140 + 0x20: 0x140 + 0x20 + 0x0E],
+             "Rod": data[0x140 + 0x20 + 0x0E:0x140 + 0x20 + 0x0E + 0x01]}
+
+    if len(data) > 0x140 + 0x20 + 0x0E + 0x01:
+        flags["DexSanityFlag"] = data[0x140 + 0x20 + 0x0E + 0x01:]
+    else:
+        flags["DexSanityFlag"] = [0] * 19
+
+    for flag_type, loc_map in location_map.items():
+        for flag, loc_id in loc_map.items():
+            if flag_type == "list":
+                if (flags["EventFlag"][location_bytes_bits[loc_id][0]['byte']] & 1 << location_bytes_bits[loc_id][0]['bit']
+                        and flags["Missable"][location_bytes_bits[loc_id][1]['byte']] & 1 << location_bytes_bits[loc_id][1]['bit']):
+                    locations.append(loc_id)
+            elif flags[flag_type][location_bytes_bits[loc_id]['byte']] & 1 << location_bytes_bits[loc_id]['bit']:
+                locations.append(loc_id)
+
+    hints = []
+    if flags["EventFlag"][280] & 16:
+        hints.append("Cerulean Bicycle Shop")
+    if flags["EventFlag"][280] & 32:
+        hints.append("Route 2 Gate - Oak's Aide")
+    if flags["EventFlag"][280] & 64:
+        hints.append("Route 11 Gate 2F - Oak's Aide")
+    if flags["EventFlag"][280] & 128:
+        hints.append("Route 15 Gate 2F - Oak's Aide")
+    if flags["EventFlag"][281] & 1:
+        hints += ["Celadon Prize Corner - Item Prize 1", "Celadon Prize Corner - Item Prize 2",
+                  "Celadon Prize Corner - Item Prize 3"]
+    if (location_name_to_id["Fossil - Choice A"] in ctx.checked_locations and location_name_to_id["Fossil - Choice B"]
+            not in ctx.checked_locations):
+        hints.append("Fossil - Choice B")
+    elif (location_name_to_id["Fossil - Choice B"] in ctx.checked_locations and location_name_to_id["Fossil - Choice A"]
+            not in ctx.checked_locations):
+        hints.append("Fossil - Choice A")
+    hints = [
+        location_name_to_id[loc] for loc in hints if location_name_to_id[loc] not in ctx.auto_hints and
+        location_name_to_id[loc] in ctx.missing_locations and location_name_to_id[loc] not in ctx.locations_checked
+    ]
+    if hints:
+        await ctx.send_msgs([{"cmd": "LocationScouts", "locations": hints, "create_as_hint": 2}])
+    ctx.auto_hints.update(hints)
+
+    if flags["EventFlag"][280] & 1 and not ctx.finished_game:
+        await ctx.send_msgs([
+                    {"cmd": "StatusUpdate",
+                     "status": 30}
+                ])
+        ctx.finished_game = True
+    if locations == ctx.locations_array:
+        return
+    ctx.locations_array = locations
+    if locations is not None:
+        await ctx.send_msgs([{"cmd": "LocationChecks", "locations": locations}])
+
+
+async def gb_sync_task(ctx: GBContext):
+    logger.info("Starting GB connector. Use /gb for status information")
+    while not ctx.exit_event.is_set():
+        error_status = None
+        if ctx.gb_streams:
+            (reader, writer) = ctx.gb_streams
+            msg = get_payload(ctx).encode()
+            writer.write(msg)
+            writer.write(b'\n')
+            try:
+                await asyncio.wait_for(writer.drain(), timeout=1.5)
+                try:
+                    # Data will return a dict with up to two fields:
+                    # 1. A keepalive response of the Players Name (always)
+                    # 2. An array representing the memory values of the locations area (if in game)
+                    data = await asyncio.wait_for(reader.readline(), timeout=5)
+                    data_decoded = json.loads(data.decode())
+                    if 'scriptVersion' not in data_decoded or data_decoded['scriptVersion'] != SCRIPT_VERSION:
+                        msg = "You are connecting with an incompatible Lua script version. Ensure your connector Lua " \
+                            "and PokemonClient are from the same Archipelago installation."
+                        logger.info(msg, extra={'compact_gui': True})
+                        ctx.gui_error('Error', msg)
+                        error_status = CONNECTION_RESET_STATUS
+                    ctx.client_compatibility_mode = data_decoded['clientCompatibilityVersion']
+                    if ctx.client_compatibility_mode == 0:
+                        ctx.items_handling = 0b101  # old patches will not have local start inventory, must be requested
+                    if ctx.seed_name and ctx.seed_name != ''.join([chr(i) for i in data_decoded['seedName'] if i != 0]):
+                        msg = "The server is running a different multiworld than your client is. (invalid seed_name)"
+                        logger.info(msg, extra={'compact_gui': True})
+                        ctx.gui_error('Error', msg)
+                        error_status = CONNECTION_RESET_STATUS
+                    ctx.seed_name = ''.join([chr(i) for i in data_decoded['seedName'] if i != 0])
+                    if not ctx.auth:
+                        ctx.auth = ''.join([chr(i) for i in data_decoded['playerName'] if i != 0])
+                        if ctx.auth == '':
+                            msg = "Invalid ROM detected. No player name built into the ROM."
+                            logger.info(msg, extra={'compact_gui': True})
+                            ctx.gui_error('Error', msg)
+                            error_status = CONNECTION_RESET_STATUS
+                        if ctx.awaiting_rom:
+                            await ctx.server_auth(False)
+                    if 'locations' in data_decoded and ctx.game and ctx.gb_status == CONNECTION_CONNECTED_STATUS \
+                            and not error_status and ctx.auth:
+                        # Not just a keep alive ping, parse
+                        async_start(parse_locations(data_decoded['locations'], ctx))
+                    if 'deathLink' in data_decoded and data_decoded['deathLink'] and 'DeathLink' in ctx.tags:
+                        await ctx.send_death(ctx.auth + " is out of usable Pokémon! " + ctx.auth + " blacked out!")
+                    if 'options' in data_decoded:
+                        msgs = []
+                        if data_decoded['options'] & 4 and not ctx.sent_release:
+                            ctx.sent_release = True
+                            msgs.append({"cmd": "Say", "text": "!release"})
+                        if data_decoded['options'] & 8 and not ctx.sent_collect:
+                            ctx.sent_collect = True
+                            msgs.append({"cmd": "Say", "text": "!collect"})
+                        if msgs:
+                            await ctx.send_msgs(msgs)
+                    if ctx.set_deathlink:
+                        await ctx.update_death_link(True)
+                except asyncio.TimeoutError:
+                    logger.debug("Read Timed Out, Reconnecting")
+                    error_status = CONNECTION_TIMING_OUT_STATUS
+                    writer.close()
+                    ctx.gb_streams = None
+                except ConnectionResetError as e:
+                    logger.debug("Read failed due to Connection Lost, Reconnecting")
+                    error_status = CONNECTION_RESET_STATUS
+                    writer.close()
+                    ctx.gb_streams = None
+            except TimeoutError:
+                logger.debug("Connection Timed Out, Reconnecting")
+                error_status = CONNECTION_TIMING_OUT_STATUS
+                writer.close()
+                ctx.gb_streams = None
+            except ConnectionResetError:
+                logger.debug("Connection Lost, Reconnecting")
+                error_status = CONNECTION_RESET_STATUS
+                writer.close()
+                ctx.gb_streams = None
+            if ctx.gb_status == CONNECTION_TENTATIVE_STATUS:
+                if not error_status:
+                    logger.info("Successfully Connected to Gameboy")
+                    ctx.gb_status = CONNECTION_CONNECTED_STATUS
+                else:
+                    ctx.gb_status = f"Was tentatively connected but error occured: {error_status}"
+            elif error_status:
+                ctx.gb_status = error_status
+                logger.info("Lost connection to Gameboy and attempting to reconnect. Use /gb for status updates")
+        else:
+            try:
+                logger.debug("Attempting to connect to Gameboy")
+                ctx.gb_streams = await asyncio.wait_for(asyncio.open_connection("localhost", 17242), timeout=10)
+                ctx.gb_status = CONNECTION_TENTATIVE_STATUS
+            except TimeoutError:
+                logger.debug("Connection Timed Out, Trying Again")
+                ctx.gb_status = CONNECTION_TIMING_OUT_STATUS
+                continue
+            except ConnectionRefusedError:
+                logger.debug("Connection Refused, Trying Again")
+                ctx.gb_status = CONNECTION_REFUSED_STATUS
+                continue
+
+
+async def run_game(romfile):
+    auto_start = Utils.get_options()["pokemon_rb_options"].get("rom_start", True)
+    if auto_start is True:
+        import webbrowser
+        webbrowser.open(romfile)
+    elif os.path.isfile(auto_start):
+        subprocess.Popen([auto_start, romfile],
+                         stdin=subprocess.DEVNULL, stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL)
+
+
+async def patch_and_run_game(game_version, patch_file, ctx):
+    base_name = os.path.splitext(patch_file)[0]
+    comp_path = base_name + '.gb'
+    if game_version == "blue":
+        delta_patch = BlueDeltaPatch
+    else:
+        delta_patch = RedDeltaPatch
+
+    try:
+        base_rom = delta_patch.get_source_data()
+    except Exception as msg:
+        logger.info(msg, extra={'compact_gui': True})
+        ctx.gui_error('Error', msg)
+
+    with zipfile.ZipFile(patch_file, 'r') as patch_archive:
+        with patch_archive.open('delta.bsdiff4', 'r') as stream:
+            patch = stream.read()
+    patched_rom_data = bsdiff4.patch(base_rom, patch)
+
+    with open(comp_path, "wb") as patched_rom_file:
+        patched_rom_file.write(patched_rom_data)
+
+    async_start(run_game(comp_path))
+
+
+if __name__ == '__main__':
+
+    Utils.init_logging("PokemonClient")
+
+    options = Utils.get_options()
+
+    async def main():
+        parser = get_base_parser()
+        parser.add_argument('patch_file', default="", type=str, nargs="?",
+                            help='Path to an APRED or APBLUE patch file')
+        args = parser.parse_args()
+
+        ctx = GBContext(args.connect, args.password)
+        ctx.server_task = asyncio.create_task(server_loop(ctx), name="ServerLoop")
+        if gui_enabled:
+            ctx.run_gui()
+        ctx.run_cli()
+        ctx.gb_sync_task = asyncio.create_task(gb_sync_task(ctx), name="GB Sync")
+
+        if args.patch_file:
+            ext = args.patch_file.split(".")[len(args.patch_file.split(".")) - 1].lower()
+            if ext == "apred":
+                logger.info("APRED file supplied, beginning patching process...")
+                async_start(patch_and_run_game("red", args.patch_file, ctx))
+            elif ext == "apblue":
+                logger.info("APBLUE file supplied, beginning patching process...")
+                async_start(patch_and_run_game("blue", args.patch_file, ctx))
+            else:
+                logger.warning(f"Unknown patch file extension {ext}")
+
+        await ctx.exit_event.wait()
+        ctx.server_address = None
+
+        await ctx.shutdown()
+
+        if ctx.gb_sync_task:
+            await ctx.gb_sync_task
+
+
+    import colorama
+
+    colorama.init()
+
+    asyncio.run(main())
+    colorama.deinit()

README.md

@@ -14,6 +14,43 @@ Currently, the following games are supported:
 * 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
+* Super Mario World
+* Pokémon Red and Blue
+* Hylics 2
+* Overcooked! 2
+* Zillion
+* Lufia II Ancient Cave
+* Blasphemous
+* Wargroove
+* Stardew Valley
+* The Legend of Zelda
+* The Messenger
+* Kingdom Hearts 2
+* The Legend of Zelda: Link's Awakening DX
+* Clique
+* Adventure
+* DLC Quest
+* Noita
+* Undertale
+* Bumper Stickers
+* Mega Man Battle Network 3: Blue Version
+* Muse Dash
+* DOOM 1993
+* Terraria
 
 For setup and instructions check out our [tutorials page](https://archipelago.gg/tutorial/).
 Downloads can be found at [Releases](https://github.com/ArchipelagoMW/Archipelago/releases), including compiled
@@ -37,7 +74,7 @@ Archipelago was directly forked from bonta0's `multiworld_31` branch of ALttPEnt
 ## Running Archipelago
 For most people all you need to do is head over to the [releases](https://github.com/ArchipelagoMW/Archipelago/releases) page then download and run the appropriate installer. The installers function on Windows only.
 
-If you are running Archipelago from a non-Windows system then the likely scenario is that you are comfortable running source code directly. Please see our wiki page on [running Archipelago from source](https://github.com/ArchipelagoMW/Archipelago/wiki/Running-from-source).
+If you are running Archipelago from a non-Windows system then the likely scenario is that you are comfortable running source code directly. Please see our doc on [running Archipelago from source](docs/running%20from%20source.md).
 
 ## Related Repositories
 This project makes use of multiple other projects. We wouldn't be here without these other repositories and the contributions of their developers, past and present.
@@ -47,21 +84,10 @@ This project makes use of multiple other projects. We wouldn't be here without t
 * [Ocarina of Time Randomizer](https://github.com/TestRunnerSRL/OoT-Randomizer)
 
 ## Contributing
-Contributions are welcome. We have a few asks of any new contributors.
+For contribution guidelines, please see our [Contributing doc.](/docs/contributing.md)
 
-* Ensure that all changes which affect logic are covered by unit tests. 
-* Do not introduce any unit test failures/regressions.
-
-Otherwise, we tend to judge code on a case to case basis. It is a generally good idea to stick to PEP-8 guidelines to ensure consistency with existing code. (And to make the linter happy.)
+## FAQ
+For Frequently asked questions, please see the website's [FAQ Page.](https://archipelago.gg/faq/en/)
 
 ## Code of Conduct
-We conduct ourselves openly and inclusively here. Please do not contribute to an environment which makes other people uncomfortable. This means that we expect all contributors or participants here to:
-
-* Be welcoming and inclusive in tone and language.
-* Be respectful of others and their abilities.
-* Show empathy when speaking with others.
-* Be gracious and accept feedback and constructive criticism.
-
-These guidelines apply to all channels of communication within this GitHub repository. Please be respectful in both public channels, such as issues, and private, such as private messaging or emails.
-
-Any incidents of abuse may be reported directly to Ijwu at hmfarran@gmail.com.
+Please refer to our [code of conduct.](/docs/code_of_conduct.md)

Starcraft2Client.py

@@ -0,0 +1,11 @@
+from __future__ import annotations
+
+import ModuleUpdate
+ModuleUpdate.update()
+
+from worlds.sc2wol.Client import launch
+import Utils
+
+if __name__ == "__main__":
+    Utils.init_logging("Starcraft2Client", exception_logger="Client")
+    launch()

UndertaleClient.py

@@ -0,0 +1,512 @@
+from __future__ import annotations
+import os
+import sys
+import asyncio
+import typing
+import bsdiff4
+import shutil
+
+import Utils
+
+from NetUtils import NetworkItem, ClientStatus
+from worlds import undertale
+from MultiServer import mark_raw
+from CommonClient import CommonContext, server_loop, \
+    gui_enabled, ClientCommandProcessor, logger, get_base_parser
+from Utils import async_start
+
+
+class UndertaleCommandProcessor(ClientCommandProcessor):
+    def __init__(self, ctx):
+        super().__init__(ctx)
+
+    def _cmd_resync(self):
+        """Manually trigger a resync."""
+        if isinstance(self.ctx, UndertaleContext):
+            self.output(f"Syncing items.")
+            self.ctx.syncing = True
+
+    def _cmd_patch(self):
+        """Patch the game."""
+        if isinstance(self.ctx, UndertaleContext):
+            os.makedirs(name=os.path.join(os.getcwd(), "Undertale"), exist_ok=True)
+            self.ctx.patch_game()
+            self.output("Patched.")
+
+    def _cmd_savepath(self, directory: str):
+        """Redirect to proper save data folder. (Use before connecting!)"""
+        if isinstance(self.ctx, UndertaleContext):
+            self.ctx.save_game_folder = directory
+            self.output("Changed to the following directory: " + self.ctx.save_game_folder)
+
+    @mark_raw
+    def _cmd_auto_patch(self, steaminstall: typing.Optional[str] = None):
+        """Patch the game automatically."""
+        if isinstance(self.ctx, UndertaleContext):
+            os.makedirs(name=os.path.join(os.getcwd(), "Undertale"), exist_ok=True)
+            tempInstall = steaminstall
+            if not os.path.isfile(os.path.join(tempInstall, "data.win")):
+                tempInstall = None
+            if tempInstall is None:
+                tempInstall = "C:\\Program Files (x86)\\Steam\\steamapps\\common\\Undertale"
+                if not os.path.exists(tempInstall):
+                    tempInstall = "C:\\Program Files\\Steam\\steamapps\\common\\Undertale"
+            elif not os.path.exists(tempInstall):
+                tempInstall = "C:\\Program Files (x86)\\Steam\\steamapps\\common\\Undertale"
+                if not os.path.exists(tempInstall):
+                    tempInstall = "C:\\Program Files\\Steam\\steamapps\\common\\Undertale"
+            if not os.path.exists(tempInstall) or not os.path.exists(tempInstall) or not os.path.isfile(os.path.join(tempInstall, "data.win")):
+                self.output("ERROR: Cannot find Undertale. Please rerun the command with the correct folder."
+                            " command. \"/auto_patch (Steam directory)\".")
+            else:
+                for file_name in os.listdir(tempInstall):
+                    if file_name != "steam_api.dll":
+                        shutil.copy(os.path.join(tempInstall, file_name),
+                               os.path.join(os.getcwd(), "Undertale", file_name))
+                self.ctx.patch_game()
+                self.output("Patching successful!")
+
+    def _cmd_online(self):
+        """Makes you no longer able to see other Undertale players."""
+        if isinstance(self.ctx, UndertaleContext):
+            self.ctx.update_online_mode(not ("Online" in self.ctx.tags))
+            if "Online" in self.ctx.tags:
+                self.output(f"Now online.")
+            else:
+                self.output(f"Now offline.")
+
+    def _cmd_deathlink(self):
+        """Toggles deathlink"""
+        if isinstance(self.ctx, UndertaleContext):
+            self.ctx.deathlink_status = not self.ctx.deathlink_status
+            if self.ctx.deathlink_status:
+                self.output(f"Deathlink enabled.")
+            else:
+                self.output(f"Deathlink disabled.")
+
+
+class UndertaleContext(CommonContext):
+    tags = {"AP", "Online"}
+    game = "Undertale"
+    command_processor = UndertaleCommandProcessor
+    items_handling = 0b111
+    route = None
+    pieces_needed = None
+    completed_routes = None
+    completed_count = 0
+    save_game_folder = os.path.expandvars(r"%localappdata%/UNDERTALE")
+
+    def __init__(self, server_address, password):
+        super().__init__(server_address, password)
+        self.pieces_needed = 0
+        self.finished_game = False
+        self.game = "Undertale"
+        self.got_deathlink = False
+        self.syncing = False
+        self.deathlink_status = False
+        self.tem_armor = False
+        self.completed_count = 0
+        self.completed_routes = {"pacifist": 0, "genocide": 0, "neutral": 0}
+        # self.save_game_folder: files go in this path to pass data between us and the actual game
+        self.save_game_folder = os.path.expandvars(r"%localappdata%/UNDERTALE")
+
+    def patch_game(self):
+        with open(os.path.join(os.getcwd(), "Undertale", "data.win"), "rb") as f:
+            patchedFile = bsdiff4.patch(f.read(), undertale.data_path("patch.bsdiff"))
+        with open(os.path.join(os.getcwd(), "Undertale", "data.win"), "wb") as f:
+            f.write(patchedFile)
+        os.makedirs(name=os.path.join(os.getcwd(), "Undertale", "Custom Sprites"), exist_ok=True)
+        with open(os.path.expandvars(os.path.join(os.getcwd(), "Undertale", "Custom Sprites",
+                                     "Which Character.txt")), "w") as f:
+            f.writelines(["// Put the folder name of the sprites you want to play as, make sure it is the only "
+                          "line other than this one.\n", "frisk"])
+            f.close()
+
+    async def server_auth(self, password_requested: bool = False):
+        if password_requested and not self.password:
+            await super().server_auth(password_requested)
+        await self.get_username()
+        await self.send_connect()
+
+    def clear_undertale_files(self):
+        path = self.save_game_folder
+        self.finished_game = False
+        for root, dirs, files in os.walk(path):
+            for file in files:
+                if "check.spot" == file or "scout" == file:
+                    os.remove(os.path.join(root, file))
+                elif file.endswith((".item", ".victory", ".route", ".playerspot", ".mad", 
+                                            ".youDied", ".LV", ".mine", ".flag", ".hint")):
+                    os.remove(os.path.join(root, file))
+
+    async def connect(self, address: typing.Optional[str] = None):
+        self.clear_undertale_files()
+        await super().connect(address)
+
+    async def disconnect(self, allow_autoreconnect: bool = False):
+        self.clear_undertale_files()
+        await super().disconnect(allow_autoreconnect)
+
+    async def connection_closed(self):
+        self.clear_undertale_files()
+        await super().connection_closed()
+
+    async def shutdown(self):
+        self.clear_undertale_files()
+        await super().shutdown()
+
+    def update_online_mode(self, online):
+        old_tags = self.tags.copy()
+        if online:
+            self.tags.add("Online")
+        else:
+            self.tags -= {"Online"}
+        if old_tags != self.tags and self.server and not self.server.socket.closed:
+            async_start(self.send_msgs([{"cmd": "ConnectUpdate", "tags": self.tags}]))
+
+    def on_package(self, cmd: str, args: dict):
+        if cmd == "Connected":
+            self.game = self.slot_info[self.slot].game
+        async_start(process_undertale_cmd(self, cmd, args))
+
+    def run_gui(self):
+        from kvui import GameManager
+
+        class UTManager(GameManager):
+            logging_pairs = [
+                ("Client", "Archipelago")
+            ]
+            base_title = "Archipelago Undertale Client"
+
+        self.ui = UTManager(self)
+        self.ui_task = asyncio.create_task(self.ui.async_run(), name="UI")
+
+    def on_deathlink(self, data: typing.Dict[str, typing.Any]):
+        self.got_deathlink = True
+        super().on_deathlink(data)
+
+
+def to_room_name(place_name: str):
+    if place_name == "Old Home Exit":
+        return "room_ruinsexit"
+    elif place_name == "Snowdin Forest":
+        return "room_tundra1"
+    elif place_name == "Snowdin Town Exit":
+        return "room_fogroom"
+    elif place_name == "Waterfall":
+        return "room_water1"
+    elif place_name == "Waterfall Exit":
+        return "room_fire2"
+    elif place_name == "Hotland":
+        return "room_fire_prelab"
+    elif place_name == "Hotland Exit":
+        return "room_fire_precore"
+    elif place_name == "Core":
+        return "room_fire_core1"
+
+
+async def process_undertale_cmd(ctx: UndertaleContext, cmd: str, args: dict):
+    if cmd == "Connected":
+        if not os.path.exists(ctx.save_game_folder):
+            os.mkdir(ctx.save_game_folder)
+        ctx.route = args["slot_data"]["route"]
+        ctx.pieces_needed = args["slot_data"]["key_pieces"]
+        ctx.tem_armor = args["slot_data"]["temy_armor_include"]
+
+        await ctx.send_msgs([{"cmd": "Get", "keys": [str(ctx.slot)+" RoutesDone neutral",
+                                                     str(ctx.slot)+" RoutesDone pacifist",
+                                                     str(ctx.slot)+" RoutesDone genocide"]}])
+        await ctx.send_msgs([{"cmd": "SetNotify", "keys": [str(ctx.slot)+" RoutesDone neutral",
+                                                           str(ctx.slot)+" RoutesDone pacifist",
+                                                           str(ctx.slot)+" RoutesDone genocide"]}])
+        if args["slot_data"]["only_flakes"]:
+            with open(os.path.join(ctx.save_game_folder, "GenoNoChest.flag"), "w") as f:
+                f.close()
+        if not args["slot_data"]["key_hunt"]:
+            ctx.pieces_needed = 0
+        if args["slot_data"]["rando_love"]:
+            filename = f"LOVErando.LV"
+            with open(os.path.join(ctx.save_game_folder, filename), "w") as f:
+                f.close()
+        if args["slot_data"]["rando_stats"]:
+            filename = f"STATrando.LV"
+            with open(os.path.join(ctx.save_game_folder, filename), "w") as f:
+                f.close()
+        filename = f"{ctx.route}.route"
+        with open(os.path.join(ctx.save_game_folder, filename), "w") as f:
+            f.close()
+        filename = f"check.spot"
+        with open(os.path.join(ctx.save_game_folder, filename), "a") as f:
+            for ss in set(args["checked_locations"]):
+                f.write(str(ss-12000)+"\n")
+            f.close()
+    elif cmd == "LocationInfo":
+        for l in args["locations"]:
+            locationid = l.location
+            filename = f"{str(locationid-12000)}.hint"
+            with open(os.path.join(ctx.save_game_folder, filename), "w") as f:
+                toDraw = ""
+                for i in range(20):
+                    if i < len(str(ctx.item_names[l.item])):
+                        toDraw += str(ctx.item_names[l.item])[i]
+                    else:
+                        break
+                f.write(toDraw)
+                f.close()
+    elif cmd == "Retrieved":
+        if str(ctx.slot)+" RoutesDone neutral" in args["keys"]:
+            if args["keys"][str(ctx.slot)+" RoutesDone neutral"] is not None:
+                ctx.completed_routes["neutral"] = args["keys"][str(ctx.slot)+" RoutesDone neutral"]
+        if str(ctx.slot)+" RoutesDone genocide" in args["keys"]:
+            if args["keys"][str(ctx.slot)+" RoutesDone genocide"] is not None:
+                ctx.completed_routes["genocide"] = args["keys"][str(ctx.slot)+" RoutesDone genocide"]
+        if str(ctx.slot)+" RoutesDone pacifist" in args["keys"]:
+            if args["keys"][str(ctx.slot) + " RoutesDone pacifist"] is not None:
+                ctx.completed_routes["pacifist"] = args["keys"][str(ctx.slot)+" RoutesDone pacifist"]
+    elif cmd == "SetReply":
+        if args["value"] is not None:
+            if str(ctx.slot)+" RoutesDone pacifist" == args["key"]:
+                ctx.completed_routes["pacifist"] = args["value"]
+            elif str(ctx.slot)+" RoutesDone genocide" == args["key"]:
+                ctx.completed_routes["genocide"] = args["value"]
+            elif str(ctx.slot)+" RoutesDone neutral" == args["key"]:
+                ctx.completed_routes["neutral"] = args["value"]
+    elif cmd == "ReceivedItems":
+        start_index = args["index"]
+
+        if start_index == 0:
+            ctx.items_received = []
+        elif start_index != len(ctx.items_received):
+            sync_msg = [{"cmd": "Sync"}]
+            if ctx.locations_checked:
+                sync_msg.append({"cmd": "LocationChecks",
+                                 "locations": list(ctx.locations_checked)})
+            await ctx.send_msgs(sync_msg)
+        if start_index == len(ctx.items_received):
+            counter = -1
+            placedWeapon = 0
+            placedArmor = 0
+            for item in args["items"]:
+                id = NetworkItem(*item).location
+                while NetworkItem(*item).location < 0 and \
+                        counter <= id:
+                    id -= 1
+                if NetworkItem(*item).location < 0:
+                    counter -= 1
+                filename = f"{str(id)}PLR{str(NetworkItem(*item).player)}.item"
+                with open(os.path.join(ctx.save_game_folder, filename), "w") as f:
+                    if NetworkItem(*item).item == 77701:
+                        if placedWeapon == 0:
+                            f.write(str(77013-11000))
+                        elif placedWeapon == 1:
+                            f.write(str(77014-11000))
+                        elif placedWeapon == 2:
+                            f.write(str(77025-11000))
+                        elif placedWeapon == 3:
+                            f.write(str(77045-11000))
+                        elif placedWeapon == 4:
+                            f.write(str(77049-11000))
+                        elif placedWeapon == 5:
+                            f.write(str(77047-11000))
+                        elif placedWeapon == 6:
+                            if str(ctx.route) == "genocide" or str(ctx.route) == "all_routes":
+                                f.write(str(77052-11000))
+                            else:
+                                f.write(str(77051-11000))
+                        else:
+                            f.write(str(77003-11000))
+                        placedWeapon += 1
+                    elif NetworkItem(*item).item == 77702:
+                        if placedArmor == 0:
+                            f.write(str(77012-11000))
+                        elif placedArmor == 1:
+                            f.write(str(77015-11000))
+                        elif placedArmor == 2:
+                            f.write(str(77024-11000))
+                        elif placedArmor == 3:
+                            f.write(str(77044-11000))
+                        elif placedArmor == 4:
+                            f.write(str(77048-11000))
+                        elif placedArmor == 5:
+                            if str(ctx.route) == "genocide":
+                                f.write(str(77053-11000))
+                            else:
+                                f.write(str(77046-11000))
+                        elif placedArmor == 6 and ((not str(ctx.route) == "genocide") or ctx.tem_armor):
+                            if str(ctx.route) == "all_routes":
+                                f.write(str(77053-11000))
+                            elif str(ctx.route) == "genocide":
+                                f.write(str(77064-11000))
+                            else:
+                                f.write(str(77050-11000))
+                        elif placedArmor == 7 and ctx.tem_armor and not str(ctx.route) == "genocide":
+                            f.write(str(77064-11000))
+                        else:
+                            f.write(str(77004-11000))
+                        placedArmor += 1
+                    else:
+                        f.write(str(NetworkItem(*item).item-11000))
+                    f.close()
+                ctx.items_received.append(NetworkItem(*item))
+                if [item.item for item in ctx.items_received].count(77000) >= ctx.pieces_needed > 0:
+                    filename = f"{str(-99999)}PLR{str(0)}.item"
+                    with open(os.path.join(ctx.save_game_folder, filename), "w") as f:
+                        f.write(str(77787 - 11000))
+                        f.close()
+                    filename = f"{str(-99998)}PLR{str(0)}.item"
+                    with open(os.path.join(ctx.save_game_folder, filename), "w") as f:
+                        f.write(str(77789 - 11000))
+                        f.close()
+        ctx.watcher_event.set()
+
+    elif cmd == "RoomUpdate":
+        if "checked_locations" in args:
+            filename = f"check.spot"
+            with open(os.path.join(ctx.save_game_folder, filename), "a") as f:
+                for ss in set(args["checked_locations"]):
+                    f.write(str(ss-12000)+"\n")
+                f.close()
+
+    elif cmd == "Bounced":
+        tags = args.get("tags", [])
+        if "Online" in tags:
+            data = args.get("data", {})
+            if data["player"] != ctx.slot and data["player"] is not None:
+                filename = f"FRISK" + str(data["player"]) + ".playerspot"
+                with open(os.path.join(ctx.save_game_folder, filename), "w") as f:
+                    f.write(str(data["x"]) + str(data["y"]) + str(data["room"]) + str(
+                        data["spr"]) + str(data["frm"]))
+                    f.close()
+
+
+async def multi_watcher(ctx: UndertaleContext):
+    while not ctx.exit_event.is_set():
+        path = ctx.save_game_folder
+        for root, dirs, files in os.walk(path):
+            for file in files:
+                if "spots.mine" in file and "Online" in ctx.tags:
+                    with open(os.path.join(root, file), "r") as mine:
+                        this_x = mine.readline()
+                        this_y = mine.readline()
+                        this_room = mine.readline()
+                        this_sprite = mine.readline()
+                        this_frame = mine.readline()
+                        mine.close()
+                    message = [{"cmd": "Bounce", "tags": ["Online"],
+                                "data": {"player": ctx.slot, "x": this_x, "y": this_y, "room": this_room,
+                                         "spr": this_sprite, "frm": this_frame}}]
+                    await ctx.send_msgs(message)
+
+        await asyncio.sleep(0.1)
+
+
+async def game_watcher(ctx: UndertaleContext):
+    while not ctx.exit_event.is_set():
+        await ctx.update_death_link(ctx.deathlink_status)
+        path = ctx.save_game_folder
+        if ctx.syncing:
+            for root, dirs, files in os.walk(path):
+                for file in files:
+                    if ".item" in file:
+                        os.remove(os.path.join(root, file))
+            sync_msg = [{"cmd": "Sync"}]
+            if ctx.locations_checked:
+                sync_msg.append({"cmd": "LocationChecks", "locations": list(ctx.locations_checked)})
+            await ctx.send_msgs(sync_msg)
+            ctx.syncing = False
+        if ctx.got_deathlink:
+            ctx.got_deathlink = False
+            with open(os.path.join(ctx.save_game_folder, "WelcomeToTheDead.youDied"), "w") as f:
+                f.close()
+        sending = []
+        victory = False
+        found_routes = 0
+        for root, dirs, files in os.walk(path):
+            for file in files:
+                if "DontBeMad.mad" in file:
+                    os.remove(os.path.join(root, file))
+                    if "DeathLink" in ctx.tags:
+                        await ctx.send_death()
+                if "scout" == file:
+                    sending = []
+                    try:
+                        with open(os.path.join(root, file), "r") as f:
+                            lines = f.readlines()
+                        for l in lines:
+                            if ctx.server_locations.__contains__(int(l)+12000):
+                                sending = sending + [int(l.rstrip('\n'))+12000]
+                    finally:
+                        await ctx.send_msgs([{"cmd": "LocationScouts", "locations": sending,
+                                                          "create_as_hint": int(2)}])
+                        os.remove(os.path.join(root, file))
+                if "check.spot" in file:
+                    sending = []
+                    try:
+                        with open(os.path.join(root, file), "r") as f:
+                            lines = f.readlines()
+                        for l in lines:
+                            sending = sending+[(int(l.rstrip('\n')))+12000]
+                    finally:
+                        await ctx.send_msgs([{"cmd": "LocationChecks", "locations": sending}])
+                if "victory" in file and str(ctx.route) in file:
+                    victory = True
+                if ".playerspot" in file and "Online" not in ctx.tags:
+                    os.remove(os.path.join(root, file))
+                if "victory" in file:
+                    if str(ctx.route) == "all_routes":
+                        if "neutral" in file and ctx.completed_routes["neutral"] != 1:
+                            await ctx.send_msgs([{"cmd": "Set", "key": str(ctx.slot)+" RoutesDone neutral",
+                                                  "default": 0, "want_reply": True, "operations": [{"operation": "max",
+                                                                                                    "value": 1}]}])
+                        elif "pacifist" in file and ctx.completed_routes["pacifist"] != 1:
+                            await ctx.send_msgs([{"cmd": "Set", "key": str(ctx.slot)+" RoutesDone pacifist",
+                                                  "default": 0, "want_reply": True, "operations": [{"operation": "max",
+                                                                                                    "value": 1}]}])
+                        elif "genocide" in file and ctx.completed_routes["genocide"] != 1:
+                            await ctx.send_msgs([{"cmd": "Set", "key": str(ctx.slot)+" RoutesDone genocide",
+                                                  "default": 0, "want_reply": True, "operations": [{"operation": "max",
+                                                                                                    "value": 1}]}])
+        if str(ctx.route) == "all_routes":
+            found_routes += ctx.completed_routes["neutral"]
+            found_routes += ctx.completed_routes["pacifist"]
+            found_routes += ctx.completed_routes["genocide"]
+        if str(ctx.route) == "all_routes" and found_routes >= 3:
+            victory = True
+        ctx.locations_checked = sending
+        if (not ctx.finished_game) and victory:
+            await ctx.send_msgs([{"cmd": "StatusUpdate", "status": ClientStatus.CLIENT_GOAL}])
+            ctx.finished_game = True
+        await asyncio.sleep(0.1)
+
+
+def main():
+    Utils.init_logging("UndertaleClient", exception_logger="Client")
+
+    async def _main():
+        ctx = UndertaleContext(None, None)
+        ctx.server_task = asyncio.create_task(server_loop(ctx), name="server loop")
+        asyncio.create_task(
+            game_watcher(ctx), name="UndertaleProgressionWatcher")
+
+        asyncio.create_task(
+            multi_watcher(ctx), name="UndertaleMultiplayerWatcher")
+
+        if gui_enabled:
+            ctx.run_gui()
+        ctx.run_cli()
+
+        await ctx.exit_event.wait()
+        await ctx.shutdown()
+
+    import colorama
+
+    colorama.init()
+
+    asyncio.run(_main())
+    colorama.deinit()
+
+
+if __name__ == "__main__":
+    parser = get_base_parser(description="Undertale Client, for text interfacing.")
+    args = parser.parse_args()
+    main()

Utils.py

@@ -1,5 +1,7 @@
 from __future__ import annotations
 
+import asyncio
+import json
 import typing
 import builtins
 import os
@@ -12,6 +14,22 @@ import collections
 import importlib
 import logging
 
+from argparse import Namespace
+from settings import Settings, get_settings
+from typing import BinaryIO, Coroutine, Optional, Set, Dict, Any, Union
+from yaml import load, load_all, dump, SafeLoader
+
+try:
+    from yaml import CLoader as UnsafeLoader
+    from yaml import CDumper as Dumper
+except ImportError:
+    from yaml import Loader as UnsafeLoader
+    from yaml import Dumper
+
+if typing.TYPE_CHECKING:
+    import tkinter
+    import pathlib
+
 
 def tuplize_version(version: str) -> Version:
     return Version(*(int(piece, 10) for piece in version.split(".")))
@@ -22,59 +40,65 @@ class Version(typing.NamedTuple):
     minor: int
     build: int
 
+    def as_simple_string(self) -> str:
+        return ".".join(str(item) for item in self)
 
-__version__ = "0.2.2"
+
+__version__ = "0.4.3"
 version_tuple = tuplize_version(__version__)
 
-from yaml import load, dump, safe_load
-
-try:
-    from yaml import CLoader as Loader
-except ImportError:
-    from yaml import Loader
+is_linux = sys.platform.startswith("linux")
+is_macos = sys.platform == "darwin"
+is_windows = sys.platform in ("win32", "cygwin", "msys")
 
 
-def int16_as_bytes(value):
+def int16_as_bytes(value: int) -> typing.List[int]:
     value = value & 0xFFFF
     return [value & 0xFF, (value >> 8) & 0xFF]
 
 
-def int32_as_bytes(value):
+def int32_as_bytes(value: int) -> typing.List[int]:
     value = value & 0xFFFFFFFF
     return [value & 0xFF, (value >> 8) & 0xFF, (value >> 16) & 0xFF, (value >> 24) & 0xFF]
 
 
-def pc_to_snes(value):
+def pc_to_snes(value: int) -> int:
     return ((value << 1) & 0x7F0000) | (value & 0x7FFF) | 0x8000
 
 
-def snes_to_pc(value):
+def snes_to_pc(value: int) -> int:
     return ((value & 0x7F0000) >> 1) | (value & 0x7FFF)
 
 
-def cache_argsless(function):
-    if function.__code__.co_argcount:
-        raise Exception("Can only cache 0 argument functions with this cache.")
+RetType = typing.TypeVar("RetType")
 
-    result = sentinel = object()
 
-    def _wrap():
+def cache_argsless(function: typing.Callable[[], RetType]) -> typing.Callable[[], RetType]:
+    assert not function.__code__.co_argcount, "Can only cache 0 argument functions with this cache."
+
+    sentinel = object()
+    result: typing.Union[object, RetType] = sentinel
+
+    def _wrap() -> RetType:
         nonlocal result
         if result is sentinel:
             result = function()
-        return result
+        return typing.cast(RetType, result)
 
     return _wrap
 
 
 def is_frozen() -> bool:
-    return getattr(sys, 'frozen', False)
+    return typing.cast(bool, getattr(sys, 'frozen', False))
 
 
-def local_path(*path):
-    if local_path.cached_path:
-        return os.path.join(local_path.cached_path, *path)
-
+def local_path(*path: str) -> str:
+    """
+    Returns path to a file in the local Archipelago installation or source.
+    This might be read-only and user_path should be used instead for ROMs, configuration, etc.
+    """
+    if hasattr(local_path, 'cached_path'):
+        pass
     elif is_frozen():
         if hasattr(sys, "_MEIPASS"):
             # we are running in a PyInstaller bundle
@@ -84,7 +108,7 @@ def local_path(*path):
             local_path.cached_path = os.path.dirname(os.path.abspath(sys.argv[0]))
     else:
         import __main__
-        if hasattr(__main__, "__file__"):
+        if hasattr(__main__, "__file__") and os.path.isfile(__main__.__file__):
             # we are running in a normal Python environment
             local_path.cached_path = os.path.dirname(os.path.abspath(__main__.__file__))
         else:
@@ -94,31 +118,89 @@ def local_path(*path):
     return os.path.join(local_path.cached_path, *path)
 
 
-local_path.cached_path = None
+def home_path(*path: str) -> str:
+    """Returns path to a file in the user home's Archipelago directory."""
+    if hasattr(home_path, 'cached_path'):
+        pass
+    elif sys.platform.startswith('linux'):
+        home_path.cached_path = os.path.expanduser('~/Archipelago')
+        os.makedirs(home_path.cached_path, 0o700, exist_ok=True)
+    else:
+        # not implemented
+        home_path.cached_path = local_path()  # this will generate the same exceptions we got previously
+
+    return os.path.join(home_path.cached_path, *path)
 
 
-def output_path(*path):
-    if output_path.cached_path:
+def user_path(*path: str) -> str:
+    """Returns either local_path or home_path based on write permissions."""
+    if hasattr(user_path, "cached_path"):
+        pass
+    elif os.access(local_path(), os.W_OK):
+        user_path.cached_path = local_path()
+    else:
+        user_path.cached_path = home_path()
+        # populate home from local
+        if user_path.cached_path != local_path():
+            import filecmp
+            if not os.path.exists(user_path("manifest.json")) or \
+                    not filecmp.cmp(local_path("manifest.json"), user_path("manifest.json"), shallow=True):
+                import shutil
+                for dn in ("Players", "data/sprites"):
+                    shutil.copytree(local_path(dn), user_path(dn), dirs_exist_ok=True)
+                for fn in ("manifest.json",):
+                    shutil.copy2(local_path(fn), user_path(fn))
+
+    return os.path.join(user_path.cached_path, *path)
+
+
+def cache_path(*path: str) -> str:
+    """Returns path to a file in the user's Archipelago cache directory."""
+    if hasattr(cache_path, "cached_path"):
+        pass
+    else:
+        import platformdirs
+        cache_path.cached_path = platformdirs.user_cache_dir("Archipelago", False)
+
+    return os.path.join(cache_path.cached_path, *path)
+
+
+def output_path(*path: str) -> str:
+    if hasattr(output_path, 'cached_path'):
         return os.path.join(output_path.cached_path, *path)
-    output_path.cached_path = local_path(get_options()["general_options"]["output_path"])
+    output_path.cached_path = user_path(get_options()["general_options"]["output_path"])
     path = os.path.join(output_path.cached_path, *path)
     os.makedirs(os.path.dirname(path), exist_ok=True)
     return path
 
 
-output_path.cached_path = None
-
-
-def open_file(filename):
-    if sys.platform == 'win32':
+def open_file(filename: typing.Union[str, "pathlib.Path"]) -> None:
+    if is_windows:
         os.startfile(filename)
     else:
-        open_command = 'open' if sys.platform == 'darwin' else 'xdg-open'
+        from shutil import which
+        open_command = which("open") if is_macos else (which("xdg-open") or which("gnome-open") or which("kde-open"))
         subprocess.call([open_command, filename])
 
 
-parse_yaml = safe_load
-unsafe_parse_yaml = functools.partial(load, Loader=Loader)
+# from https://gist.github.com/pypt/94d747fe5180851196eb#gistcomment-4015118 with some changes
+class UniqueKeyLoader(SafeLoader):
+    def construct_mapping(self, node, deep=False):
+        mapping = set()
+        for key_node, value_node in node.value:
+            key = self.construct_object(key_node, deep=deep)
+            if key in mapping:
+                logging.error(f"YAML duplicates sanity check failed{key_node.start_mark}")
+                raise KeyError(f"Duplicate key {key} found in YAML. Already found keys: {mapping}.")
+            mapping.add(key)
+        return super().construct_mapping(node, deep)
+
+
+parse_yaml = functools.partial(load, Loader=UniqueKeyLoader)
+parse_yamls = functools.partial(load_all, Loader=UniqueKeyLoader)
+unsafe_parse_yaml = functools.partial(load, Loader=UnsafeLoader)
+
+del load, load_all  # should not be used. don't leak their names
 
 
 def get_cert_none_ssl_context():
@@ -136,11 +218,12 @@ def get_public_ipv4() -> str:
     ip = socket.gethostbyname(socket.gethostname())
     ctx = get_cert_none_ssl_context()
     try:
-        ip = urllib.request.urlopen('https://checkip.amazonaws.com/', context=ctx).read().decode('utf8').strip()
+        ip = urllib.request.urlopen("https://checkip.amazonaws.com/", context=ctx, timeout=10).read().decode("utf8").strip()
     except Exception as e:
+        # noinspection PyBroadException
         try:
-            ip = urllib.request.urlopen('https://v4.ident.me', context=ctx).read().decode('utf8').strip()
-        except:
+            ip = urllib.request.urlopen("https://v4.ident.me", context=ctx, timeout=10).read().decode("utf8").strip()
+        except Exception:
             logging.exception(e)
             pass  # we could be offline, in a local game, so no point in erroring out
     return ip
@@ -153,141 +236,38 @@ def get_public_ipv6() -> str:
     ip = socket.gethostbyname(socket.gethostname())
     ctx = get_cert_none_ssl_context()
     try:
-        ip = urllib.request.urlopen('https://v6.ident.me', context=ctx).read().decode('utf8').strip()
+        ip = urllib.request.urlopen("https://v6.ident.me", context=ctx, timeout=10).read().decode("utf8").strip()
     except Exception as e:
         logging.exception(e)
         pass  # we could be offline, in a local game, or ipv6 may not be available
     return ip
 
 
-@cache_argsless
-def get_default_options() -> dict:
-    # Refer to host.yaml for comments as to what all these options mean.
-    options = {
-        "general_options": {
-            "output_path": "output",
-        },
-        "factorio_options": {
-            "executable": "factorio\\bin\\x64\\factorio",
-        },
-        "sm_options": {
-            "rom_file": "Super Metroid (JU).sfc",
-            "sni": "SNI",
-            "rom_start": True,
-        },
-        "soe_options": {
-            "rom_file": "Secret of Evermore (USA).sfc",
-        },
-        "lttp_options": {
-            "rom_file": "Zelda no Densetsu - Kamigami no Triforce (Japan).sfc",
-            "sni": "SNI",
-            "rom_start": True,
-
-        },
-        "server_options": {
-            "host": None,
-            "port": 38281,
-            "password": None,
-            "multidata": None,
-            "savefile": None,
-            "disable_save": False,
-            "loglevel": "info",
-            "server_password": None,
-            "disable_item_cheat": False,
-            "location_check_points": 1,
-            "hint_cost": 10,
-            "forfeit_mode": "goal",
-            "collect_mode": "disabled",
-            "remaining_mode": "goal",
-            "auto_shutdown": 0,
-            "compatibility": 2,
-            "log_network": 0
-        },
-        "generator": {
-            "teams": 1,
-            "enemizer_path": "EnemizerCLI/EnemizerCLI.Core.exe",
-            "player_files_path": "Players",
-            "players": 0,
-            "weights_file_path": "weights.yaml",
-            "meta_file_path": "meta.yaml",
-            "spoiler": 2,
-            "glitch_triforce_room": 1,
-            "race": 0,
-            "plando_options": "bosses",
-        },
-        "minecraft_options": {
-            "forge_directory": "Minecraft Forge server",
-            "max_heap_size": "2G"
-        },
-        "oot_options": {
-            "rom_file": "The Legend of Zelda - Ocarina of Time.z64",
-        }
-    }
-
-    return options
-
-
-def update_options(src: dict, dest: dict, filename: str, keys: list) -> dict:
-    for key, value in src.items():
-        new_keys = keys.copy()
-        new_keys.append(key)
-        option_name = '.'.join(new_keys)
-        if key not in dest:
-            dest[key] = value
-            if filename.endswith("options.yaml"):
-                logging.info(f"Warning: {filename} is missing {option_name}")
-        elif isinstance(value, dict):
-            if not isinstance(dest.get(key, None), dict):
-                if filename.endswith("options.yaml"):
-                    logging.info(f"Warning: {filename} has {option_name}, but it is not a dictionary. overwriting.")
-                dest[key] = value
-            else:
-                dest[key] = update_options(value, dest[key], filename, new_keys)
-    return dest
+OptionsType = Settings  # TODO: remove ~2 versions after 0.4.1
 
 
 @cache_argsless
-def get_options() -> dict:
-    if not hasattr(get_options, "options"):
-        locations = ("options.yaml", "host.yaml",
-                     local_path("options.yaml"), local_path("host.yaml"))
-
-        for location in locations:
-            if os.path.exists(location):
-                with open(location) as f:
-                    options = parse_yaml(f.read())
-
-                get_options.options = update_options(get_default_options(), options, location, list())
-                break
-        else:
-            raise FileNotFoundError(f"Could not find {locations[1]} to load options.")
-    return get_options.options
+def get_default_options() -> Settings:  # TODO: remove ~2 versions after 0.4.1
+    return Settings(None)
 
 
-def get_item_name_from_id(code: int) -> str:
-    from worlds import lookup_any_item_id_to_name
-    return lookup_any_item_id_to_name.get(code, f'Unknown item (ID:{code})')
-
-
-def get_location_name_from_id(code: int) -> str:
-    from worlds import lookup_any_location_id_to_name
-    return lookup_any_location_id_to_name.get(code, f'Unknown location (ID:{code})')
+get_options = get_settings  # TODO: add a warning ~2 versions after 0.4.1 and remove once all games are ported
 
 
 def persistent_store(category: str, key: typing.Any, value: typing.Any):
-    path = local_path("_persistent_storage.yaml")
+    path = user_path("_persistent_storage.yaml")
     storage: dict = persistent_load()
     category = storage.setdefault(category, {})
     category[key] = value
     with open(path, "wt") as f:
-        f.write(dump(storage))
+        f.write(dump(storage, Dumper=Dumper))
 
 
-def persistent_load() -> typing.Dict[dict]:
+def persistent_load() -> typing.Dict[str, dict]:
     storage = getattr(persistent_load, "storage", None)
     if storage:
         return storage
-    path = local_path("_persistent_storage.yaml")
+    path = user_path("_persistent_storage.yaml")
     storage: dict = {}
     if os.path.exists(path):
         try:
@@ -301,63 +281,63 @@ def persistent_load() -> typing.Dict[dict]:
     return storage
 
 
-def get_adjuster_settings(romfile: str, skip_questions: bool = False) -> typing.Tuple[str, bool]:
-    if hasattr(get_adjuster_settings, "adjuster_settings"):
-        adjuster_settings = getattr(get_adjuster_settings, "adjuster_settings")
-    else:
-        adjuster_settings = persistent_load().get("adjuster", {}).get("last_settings_3", {})
+def get_file_safe_name(name: str) -> str:
+    return "".join(c for c in name if c not in '<>:"/\\|?*')
 
-    if adjuster_settings:
-        import pprint
-        from worlds.alttp.Rom import get_base_rom_path
-        adjuster_settings.rom = romfile
-        adjuster_settings.baserom = get_base_rom_path()
-        adjuster_settings.world = None
-        whitelist = {"music", "menuspeed", "heartbeep", "heartcolor", "ow_palettes", "quickswap",
-                     "uw_palettes", "sprite"}
-        printed_options = {name: value for name, value in vars(adjuster_settings).items() if name in whitelist}
-        if hasattr(adjuster_settings, "sprite_pool"):
-            sprite_pool = {}
-            for sprite in getattr(adjuster_settings, "sprite_pool"):
-                if sprite in sprite_pool:
-                    sprite_pool[sprite] += 1
-                else:
-                    sprite_pool[sprite] = 1
-            if sprite_pool:
-                printed_options["sprite_pool"] = sprite_pool
 
-        if hasattr(get_adjuster_settings, "adjust_wanted"):
-            adjust_wanted = getattr(get_adjuster_settings, "adjust_wanted")
-        elif persistent_load().get("adjuster", {}).get("never_adjust", False):  # never adjust, per user request
-            return romfile, False
-        elif skip_questions:
-            return romfile, False
-        else:
-            adjust_wanted = input(f"Last used adjuster settings were found. Would you like to apply these? \n"
-                                  f"{pprint.pformat(printed_options)}\n"
-                                  f"Enter yes, no or never: ")
-        if adjust_wanted and adjust_wanted.startswith("y"):
-            if hasattr(adjuster_settings, "sprite_pool"):
-                from LttPAdjuster import AdjusterWorld
-                adjuster_settings.world = AdjusterWorld(getattr(adjuster_settings, "sprite_pool"))
+def load_data_package_for_checksum(game: str, checksum: typing.Optional[str]) -> Dict[str, Any]:
+    if checksum and game:
+        if checksum != get_file_safe_name(checksum):
+            raise ValueError(f"Bad symbols in checksum: {checksum}")
+        path = cache_path("datapackage", get_file_safe_name(game), f"{checksum}.json")
+        if os.path.exists(path):
+            try:
+                with open(path, "r", encoding="utf-8-sig") as f:
+                    return json.load(f)
+            except Exception as e:
+                logging.debug(f"Could not load data package: {e}")
 
-            adjusted = True
-            import LttPAdjuster
-            _, romfile = LttPAdjuster.adjust(adjuster_settings)
+    # fall back to old cache
+    cache = persistent_load().get("datapackage", {}).get("games", {}).get(game, {})
+    if cache.get("checksum") == checksum:
+        return cache
 
-            if hasattr(adjuster_settings, "world"):
-                delattr(adjuster_settings, "world")
-        elif adjust_wanted and "never" in adjust_wanted:
-            persistent_store("adjuster", "never_adjust", True)
-            return romfile, False
-        else:
-            adjusted = False
-            if not hasattr(get_adjuster_settings, "adjust_wanted"):
-                logging.info(f"Skipping post-patch adjustment")
-        get_adjuster_settings.adjuster_settings = adjuster_settings
-        get_adjuster_settings.adjust_wanted = adjust_wanted
-        return romfile, adjusted
-    return romfile, False
+    # cache does not match
+    return {}
+
+
+def store_data_package_for_checksum(game: str, data: typing.Dict[str, Any]) -> None:
+    checksum = data.get("checksum")
+    if checksum and game:
+        if checksum != get_file_safe_name(checksum):
+            raise ValueError(f"Bad symbols in checksum: {checksum}")
+        game_folder = cache_path("datapackage", get_file_safe_name(game))
+        os.makedirs(game_folder, exist_ok=True)
+        try:
+            with open(os.path.join(game_folder, f"{checksum}.json"), "w", encoding="utf-8-sig") as f:
+                json.dump(data, f, ensure_ascii=False, separators=(",", ":"))
+        except Exception as e:
+            logging.debug(f"Could not store data package: {e}")
+
+def get_default_adjuster_settings(game_name: str) -> Namespace:
+    import LttPAdjuster
+    adjuster_settings = Namespace()
+    if game_name == LttPAdjuster.GAME_ALTTP:
+        return LttPAdjuster.get_argparser().parse_known_args(args=[])[0]
+
+    return adjuster_settings
+
+
+def get_adjuster_settings_no_defaults(game_name: str) -> Namespace:
+    return persistent_load().get("adjuster", {}).get(game_name, Namespace())
+
+
+def get_adjuster_settings(game_name: str) -> Namespace:
+    adjuster_settings = get_adjuster_settings_no_defaults(game_name)
+    default_settings = get_default_adjuster_settings(game_name)
+
+    # Fill in any arguments from the argparser that we haven't seen before
+    return Namespace(**vars(adjuster_settings), **{k:v for k,v in vars(default_settings).items() if k not in vars(adjuster_settings)})
 
 
 @cache_argsless
@@ -372,29 +352,34 @@ def get_unique_identifier():
     return uuid
 
 
-safe_builtins = {
+safe_builtins = frozenset((
     'set',
     'frozenset',
-}
+))
 
 
 class RestrictedUnpickler(pickle.Unpickler):
+    generic_properties_module: Optional[object]
+
     def __init__(self, *args, **kwargs):
         super(RestrictedUnpickler, self).__init__(*args, **kwargs)
         self.options_module = importlib.import_module("Options")
         self.net_utils_module = importlib.import_module("NetUtils")
-        self.generic_properties_module = importlib.import_module("worlds.generic")
+        self.generic_properties_module = None
 
     def find_class(self, module, name):
         if module == "builtins" and name in safe_builtins:
             return getattr(builtins, name)
         # used by MultiServer -> savegame/multidata
-        if module == "NetUtils" and name in {"NetworkItem", "ClientStatus", "Hint"}:
+        if module == "NetUtils" and name in {"NetworkItem", "ClientStatus", "Hint", "SlotType", "NetworkSlot"}:
             return getattr(self.net_utils_module, name)
         # Options and Plando are unpickled by WebHost -> Generate
         if module == "worlds.generic" and name in {"PlandoItem", "PlandoConnection"}:
+            if not self.generic_properties_module:
+                self.generic_properties_module = importlib.import_module("worlds.generic")
             return getattr(self.generic_properties_module, name)
-        if module.endswith("Options"):
+        # pep 8 specifies that modules should have "all-lowercase names" (options, not Options)
+        if module.lower().endswith("options"):
             if module == "Options":
                 mod = self.options_module
             else:
@@ -403,8 +388,7 @@ class RestrictedUnpickler(pickle.Unpickler):
             if issubclass(obj, self.options_module.Option):
                 return obj
         # Forbid everything else.
-        raise pickle.UnpicklingError("global '%s.%s' is forbidden" %
-                                     (module, name))
+        raise pickle.UnpicklingError(f"global '{module}.{name}' is forbidden")
 
 
 def restricted_loads(s):
@@ -412,7 +396,19 @@ def restricted_loads(s):
     return RestrictedUnpickler(io.BytesIO(s)).load()
 
 
+class ByValue:
+    """
+    Mixin for enums to pickle value instead of name (restores pre-3.11 behavior). Use as left-most parent.
+    See https://github.com/python/cpython/pull/26658 for why this exists.
+    """
+    def __reduce_ex__(self, prot):
+        return self.__class__, (self._value_, )
+
+
 class KeyedDefaultDict(collections.defaultdict):
+    """defaultdict variant that uses the missing key as argument to default_factory"""
+    default_factory: typing.Callable[[typing.Any], typing.Any]
+
     def __missing__(self, key):
         self[key] = value = self.default_factory(key)
         return value
@@ -422,19 +418,28 @@ def get_text_between(text: str, start: str, end: str) -> str:
     return text[text.index(start) + len(start): text.rindex(end)]
 
 
+def get_text_after(text: str, start: str) -> str:
+    return text[text.index(start) + len(start):]
+
+
 loglevel_mapping = {'error': logging.ERROR, 'info': logging.INFO, 'warning': logging.WARNING, 'debug': logging.DEBUG}
 
 
 def init_logging(name: str, loglevel: typing.Union[str, int] = logging.INFO, write_mode: str = "w",
-                 log_format: str = "[%(name)s]: %(message)s", exception_logger: str = ""):
+                 log_format: str = "[%(name)s at %(asctime)s]: %(message)s",
+                 exception_logger: typing.Optional[str] = None):
+    import datetime
     loglevel: int = loglevel_mapping.get(loglevel, loglevel)
-    log_folder = local_path("logs")
+    log_folder = user_path("logs")
     os.makedirs(log_folder, exist_ok=True)
     root_logger = logging.getLogger()
     for handler in root_logger.handlers[:]:
         root_logger.removeHandler(handler)
         handler.close()
     root_logger.setLevel(loglevel)
+    logging.getLogger("websockets").setLevel(loglevel)  # make sure level is applied for websockets
+    if "a" not in write_mode:
+        name += f"_{datetime.datetime.now().strftime('%Y_%m_%d_%H_%M_%S')}"
     file_handler = logging.FileHandler(
         os.path.join(log_folder, f"{name}.txt"),
         write_mode,
@@ -462,15 +467,302 @@ def init_logging(name: str, loglevel: typing.Union[str, int] = logging.INFO, wri
 
         sys.excepthook = handle_exception
 
+    def _cleanup():
+        for file in os.scandir(log_folder):
+            if file.name.endswith(".txt"):
+                last_change = datetime.datetime.fromtimestamp(file.stat().st_mtime)
+                if datetime.datetime.now() - last_change > datetime.timedelta(days=7):
+                    try:
+                        os.unlink(file.path)
+                    except Exception as e:
+                        logging.exception(e)
+                    else:
+                        logging.debug(f"Deleted old logfile {file.path}")
+    import threading
+    threading.Thread(target=_cleanup, name="LogCleaner").start()
+    import platform
+    logging.info(
+        f"Archipelago ({__version__}) logging initialized"
+        f" on {platform.platform()}"
+        f" running Python {sys.version_info.major}.{sys.version_info.minor}.{sys.version_info.micro}"
+    )
+
 
 def stream_input(stream, queue):
     def queuer():
         while 1:
-            text = stream.readline().strip()
-            if text:
-                queue.put_nowait(text)
+            try:
+                text = stream.readline().strip()
+            except UnicodeDecodeError as e:
+                logging.exception(e)
+            else:
+                if text:
+                    queue.put_nowait(text)
 
     from threading import Thread
     thread = Thread(target=queuer, name=f"Stream handler for {stream.name}", daemon=True)
     thread.start()
     return thread
+
+
+def tkinter_center_window(window: "tkinter.Tk") -> None:
+    window.update()
+    x = int(window.winfo_screenwidth() / 2 - window.winfo_reqwidth() / 2)
+    y = int(window.winfo_screenheight() / 2 - window.winfo_reqheight() / 2)
+    window.geometry(f"+{x}+{y}")
+
+
+class VersionException(Exception):
+    pass
+
+
+def chaining_prefix(index: int, labels: typing.Tuple[str]) -> str:
+    text = ""
+    max_label = len(labels) - 1
+    while index > max_label:
+        text += labels[-1]
+        index -= max_label
+    return labels[index] + text
+
+
+# noinspection PyPep8Naming
+def format_SI_prefix(value, power=1000, power_labels=("", "k", "M", "G", "T", "P", "E", "Z", "Y")) -> str:
+    """Formats a value into a value + metric/si prefix. More info at https://en.wikipedia.org/wiki/Metric_prefix"""
+    import decimal
+    n = 0
+    value = decimal.Decimal(value)
+    limit = power - decimal.Decimal("0.005")
+    while value >= limit:
+        value /= power
+        n += 1
+
+    return f"{value.quantize(decimal.Decimal('1.00'))} {chaining_prefix(n, power_labels)}"
+
+
+def get_fuzzy_results(input_word: str, wordlist: typing.Sequence[str], limit: typing.Optional[int] = None) \
+        -> typing.List[typing.Tuple[str, int]]:
+    import jellyfish
+
+    def get_fuzzy_ratio(word1: str, word2: str) -> float:
+        return (1 - jellyfish.damerau_levenshtein_distance(word1.lower(), word2.lower())
+                / max(len(word1), len(word2)))
+
+    limit: int = limit if limit else len(wordlist)
+    return list(
+        map(
+            lambda container: (container[0], int(container[1]*100)),  # convert up to limit to int %
+            sorted(
+                map(lambda candidate:
+                    (candidate,  get_fuzzy_ratio(input_word, candidate)),
+                    wordlist),
+                key=lambda element: element[1],
+                reverse=True)[0:limit]
+        )
+    )
+
+
+def open_filename(title: str, filetypes: typing.Sequence[typing.Tuple[str, typing.Sequence[str]]], suggest: str = "") \
+        -> typing.Optional[str]:
+    def run(*args: str):
+        return subprocess.run(args, capture_output=True, text=True).stdout.split("\n", 1)[0] or None
+
+    if is_linux:
+        # prefer native dialog
+        from shutil import which
+        kdialog = which("kdialog")
+        if kdialog:
+            k_filters = '|'.join((f'{text} (*{" *".join(ext)})' for (text, ext) in filetypes))
+            return run(kdialog, f"--title={title}", "--getopenfilename", suggest or ".", k_filters)
+        zenity = which("zenity")
+        if zenity:
+            z_filters = (f'--file-filter={text} ({", ".join(ext)}) | *{" *".join(ext)}' for (text, ext) in filetypes)
+            selection = (f"--filename={suggest}",) if suggest else ()
+            return run(zenity, f"--title={title}", "--file-selection", *z_filters, *selection)
+
+    # fall back to tk
+    try:
+        import tkinter
+        import tkinter.filedialog
+    except Exception as e:
+        logging.error('Could not load tkinter, which is likely not installed. '
+                      f'This attempt was made because open_filename was used for "{title}".')
+        raise e
+    else:
+        try:
+            root = tkinter.Tk()
+        except tkinter.TclError:
+            return None  # GUI not available. None is the same as a user clicking "cancel"
+        root.withdraw()
+        return tkinter.filedialog.askopenfilename(title=title, filetypes=((t[0], ' '.join(t[1])) for t in filetypes),
+                                                  initialfile=suggest or None)
+
+
+def open_directory(title: str, suggest: str = "") -> typing.Optional[str]:
+    def run(*args: str):
+        return subprocess.run(args, capture_output=True, text=True).stdout.split("\n", 1)[0] or None
+
+    if is_linux:
+        # prefer native dialog
+        from shutil import which
+        kdialog = which("kdialog")
+        if kdialog:
+            return run(kdialog, f"--title={title}", "--getexistingdirectory",
+                       os.path.abspath(suggest) if suggest else ".")
+        zenity = which("zenity")
+        if zenity:
+            z_filters = ("--directory",)
+            selection = (f"--filename={os.path.abspath(suggest)}/",) if suggest else ()
+            return run(zenity, f"--title={title}", "--file-selection", *z_filters, *selection)
+
+    # fall back to tk
+    try:
+        import tkinter
+        import tkinter.filedialog
+    except Exception as e:
+        logging.error('Could not load tkinter, which is likely not installed. '
+                      f'This attempt was made because open_filename was used for "{title}".')
+        raise e
+    else:
+        try:
+            root = tkinter.Tk()
+        except tkinter.TclError:
+            return None  # GUI not available. None is the same as a user clicking "cancel"
+        root.withdraw()
+        return tkinter.filedialog.askdirectory(title=title, mustexist=True, initialdir=suggest or None)
+
+
+def messagebox(title: str, text: str, error: bool = False) -> None:
+    def run(*args: str):
+        return subprocess.run(args, capture_output=True, text=True).stdout.split("\n", 1)[0] or None
+
+    def is_kivy_running():
+        if "kivy" in sys.modules:
+            from kivy.app import App
+            return App.get_running_app() is not None
+        return False
+
+    if is_kivy_running():
+        from kvui import MessageBox
+        MessageBox(title, text, error).open()
+        return
+
+    if is_linux and "tkinter" not in sys.modules:
+        # prefer native dialog
+        from shutil import which
+        kdialog = which("kdialog")
+        if kdialog:
+            return run(kdialog, f"--title={title}", "--error" if error else "--msgbox", text)
+        zenity = which("zenity")
+        if zenity:
+            return run(zenity, f"--title={title}", f"--text={text}", "--error" if error else "--info")
+
+    # fall back to tk
+    try:
+        import tkinter
+        from tkinter.messagebox import showerror, showinfo
+    except Exception as e:
+        logging.error('Could not load tkinter, which is likely not installed. '
+                      f'This attempt was made because messagebox was used for "{title}".')
+        raise e
+    else:
+        root = tkinter.Tk()
+        root.withdraw()
+        showerror(title, text) if error else showinfo(title, text)
+        root.update()
+
+
+def title_sorted(data: typing.Sequence, key=None, ignore: typing.Set = frozenset(("a", "the"))):
+    """Sorts a sequence of text ignoring typical articles like "a" or "the" in the beginning."""
+    def sorter(element: Union[str, Dict[str, Any]]) -> str:
+        if (not isinstance(element, str)):
+            element = element["title"]
+
+        parts = element.split(maxsplit=1)
+        if parts[0].lower() in ignore:
+            return parts[1].lower()
+        else:
+            return element.lower()
+    return sorted(data, key=lambda i: sorter(key(i)) if key else sorter(i))
+
+
+def read_snes_rom(stream: BinaryIO, strip_header: bool = True) -> bytearray:
+    """Reads rom into bytearray and optionally strips off any smc header"""
+    buffer = bytearray(stream.read())
+    if strip_header and len(buffer) % 0x400 == 0x200:
+        return buffer[0x200:]
+    return buffer
+
+
+_faf_tasks: "Set[asyncio.Task[typing.Any]]" = set()
+
+
+def async_start(co: Coroutine[None, None, typing.Any], name: Optional[str] = None) -> None:
+    """
+    Use this to start a task when you don't keep a reference to it or immediately await it,
+    to prevent early garbage collection. "fire-and-forget"
+    """
+    # https://docs.python.org/3.10/library/asyncio-task.html#asyncio.create_task
+    # Python docs:
+    # ```
+    # Important: Save a reference to the result of [asyncio.create_task],
+    # to avoid a task disappearing mid-execution.
+    # ```
+    # This implementation follows the pattern given in that documentation.
+
+    task: asyncio.Task[typing.Any] = asyncio.create_task(co, name=name)
+    _faf_tasks.add(task)
+    task.add_done_callback(_faf_tasks.discard)
+
+
+def deprecate(message: str):
+    if __debug__:
+        raise Exception(message)
+    import warnings
+    warnings.warn(message)
+
+def _extend_freeze_support() -> None:
+    """Extend multiprocessing.freeze_support() to also work on Non-Windows for spawn."""
+    # upstream issue: https://github.com/python/cpython/issues/76327
+    # code based on https://github.com/pyinstaller/pyinstaller/blob/develop/PyInstaller/hooks/rthooks/pyi_rth_multiprocessing.py#L26
+    import multiprocessing
+    import multiprocessing.spawn
+
+    def _freeze_support() -> None:
+        """Minimal freeze_support. Only apply this if frozen."""
+        from subprocess import _args_from_interpreter_flags
+
+        # Prevent `spawn` from trying to read `__main__` in from the main script
+        multiprocessing.process.ORIGINAL_DIR = None
+
+        # Handle the first process that MP will create
+        if (
+            len(sys.argv) >= 2 and sys.argv[-2] == '-c' and sys.argv[-1].startswith((
+                'from multiprocessing.semaphore_tracker import main',  # Py<3.8
+                'from multiprocessing.resource_tracker import main',  # Py>=3.8
+                'from multiprocessing.forkserver import main'
+            )) and set(sys.argv[1:-2]) == set(_args_from_interpreter_flags())
+        ):
+            exec(sys.argv[-1])
+            sys.exit()
+
+        # Handle the second process that MP will create
+        if multiprocessing.spawn.is_forking(sys.argv):
+            kwargs = {}
+            for arg in sys.argv[2:]:
+                name, value = arg.split('=')
+                if value == 'None':
+                    kwargs[name] = None
+                else:
+                    kwargs[name] = int(value)
+            multiprocessing.spawn.spawn_main(**kwargs)
+            sys.exit()
+
+    if not is_windows and is_frozen():
+        multiprocessing.freeze_support = multiprocessing.spawn.freeze_support = _freeze_support
+
+
+def freeze_support() -> None:
+    """This behaves like multiprocessing.freeze_support but also works on Non-Windows."""
+    import multiprocessing
+    _extend_freeze_support()
+    multiprocessing.freeze_support()

WargrooveClient.py

@@ -0,0 +1,445 @@
+from __future__ import annotations
+
+import atexit
+import os
+import sys
+import asyncio
+import random
+import shutil
+from typing import Tuple, List, Iterable, Dict
+
+from worlds.wargroove import WargrooveWorld
+from worlds.wargroove.Items import item_table, faction_table, CommanderData, ItemData
+
+import ModuleUpdate
+ModuleUpdate.update()
+
+import Utils
+import json
+import logging
+
+if __name__ == "__main__":
+    Utils.init_logging("WargrooveClient", exception_logger="Client")
+
+from NetUtils import NetworkItem, ClientStatus
+from CommonClient import gui_enabled, logger, get_base_parser, ClientCommandProcessor, \
+    CommonContext, server_loop
+
+wg_logger = logging.getLogger("WG")
+
+
+class WargrooveClientCommandProcessor(ClientCommandProcessor):
+    def _cmd_resync(self):
+        """Manually trigger a resync."""
+        self.output(f"Syncing items.")
+        self.ctx.syncing = True
+
+    def _cmd_commander(self, *commander_name: Iterable[str]):
+        """Set the current commander to the given commander."""
+        if commander_name:
+            self.ctx.set_commander(' '.join(commander_name))
+        else:
+            if self.ctx.can_choose_commander:
+                commanders = self.ctx.get_commanders()
+                wg_logger.info('Unlocked commanders: ' +
+                               ', '.join((commander.name for commander, unlocked in commanders if unlocked)))
+                wg_logger.info('Locked commanders: ' +
+                               ', '.join((commander.name for commander, unlocked in commanders if not unlocked)))
+            else:
+                wg_logger.error('Cannot set commanders in this game mode.')
+
+
+class WargrooveContext(CommonContext):
+    command_processor: int = WargrooveClientCommandProcessor
+    game = "Wargroove"
+    items_handling = 0b111  # full remote
+    current_commander: CommanderData = faction_table["Starter"][0]
+    can_choose_commander: bool = False
+    commander_defense_boost_multiplier: int = 0
+    income_boost_multiplier: int = 0
+    starting_groove_multiplier: float
+    faction_item_ids = {
+        'Starter': 0,
+        'Cherrystone': 52025,
+        'Felheim': 52026,
+        'Floran': 52027,
+        'Heavensong': 52028,
+        'Requiem': 52029,
+        'Outlaw': 52030
+    }
+    buff_item_ids = {
+        'Income Boost': 52023,
+        'Commander Defense Boost': 52024,
+    }
+
+    def __init__(self, server_address, password):
+        super(WargrooveContext, self).__init__(server_address, password)
+        self.send_index: int = 0
+        self.syncing = False
+        self.awaiting_bridge = False
+        # self.game_communication_path: files go in this path to pass data between us and the actual game
+        if "appdata" in os.environ:
+            options = Utils.get_options()
+            root_directory = os.path.join(options["wargroove_options"]["root_directory"])
+            data_directory = os.path.join("lib", "worlds", "wargroove", "data")
+            dev_data_directory = os.path.join("worlds", "wargroove", "data")
+            appdata_wargroove = os.path.expandvars(os.path.join("%APPDATA%", "Chucklefish", "Wargroove"))
+            if not os.path.isfile(os.path.join(root_directory, "win64_bin", "wargroove64.exe")):
+                print_error_and_close("WargrooveClient couldn't find wargroove64.exe. "
+                                      "Unable to infer required game_communication_path")
+            self.game_communication_path = os.path.join(root_directory, "AP")
+            if not os.path.exists(self.game_communication_path):
+                os.makedirs(self.game_communication_path)
+            self.remove_communication_files()
+            atexit.register(self.remove_communication_files)
+            if not os.path.isdir(appdata_wargroove):
+                print_error_and_close("WargrooveClient couldn't find Wargoove in appdata!"
+                                      "Boot Wargroove and then close it to attempt to fix this error")
+            if not os.path.isdir(data_directory):
+                data_directory = dev_data_directory
+            if not os.path.isdir(data_directory):
+                print_error_and_close("WargrooveClient couldn't find Wargoove mod and save files in install!")
+            shutil.copytree(data_directory, appdata_wargroove, dirs_exist_ok=True)
+        else:
+            print_error_and_close("WargrooveClient couldn't detect system type. "
+                                  "Unable to infer required game_communication_path")
+
+    async def server_auth(self, password_requested: bool = False):
+        if password_requested and not self.password:
+            await super(WargrooveContext, self).server_auth(password_requested)
+        await self.get_username()
+        await self.send_connect()
+
+    async def connection_closed(self):
+        await super(WargrooveContext, self).connection_closed()
+        self.remove_communication_files()
+
+    @property
+    def endpoints(self):
+        if self.server:
+            return [self.server]
+        else:
+            return []
+
+    async def shutdown(self):
+        await super(WargrooveContext, self).shutdown()
+        self.remove_communication_files()
+
+    def remove_communication_files(self):
+        for root, dirs, files in os.walk(self.game_communication_path):
+            for file in files:
+                os.remove(root + "/" + file)
+
+    def on_package(self, cmd: str, args: dict):
+        if cmd in {"Connected"}:
+            filename = f"AP_settings.json"
+            with open(os.path.join(self.game_communication_path, filename), 'w') as f:
+                slot_data = args["slot_data"]
+                json.dump(args["slot_data"], f)
+                self.can_choose_commander = slot_data["can_choose_commander"]
+                print('can choose commander:', self.can_choose_commander)
+                self.starting_groove_multiplier = slot_data["starting_groove_multiplier"]
+                self.income_boost_multiplier = slot_data["income_boost"]
+                self.commander_defense_boost_multiplier = slot_data["commander_defense_boost"]
+                f.close()
+            for ss in self.checked_locations:
+                filename = f"send{ss}"
+                with open(os.path.join(self.game_communication_path, filename), 'w') as f:
+                    f.close()
+            self.update_commander_data()
+            self.ui.update_tracker()
+
+            random.seed(self.seed_name + str(self.slot))
+            # Our indexes start at 1 and we have 24 levels
+            for i in range(1, 25):
+                filename = f"seed{i}"
+                with open(os.path.join(self.game_communication_path, filename), 'w') as f:
+                    f.write(str(random.randint(0, 4294967295)))
+                    f.close()
+
+        if cmd in {"RoomInfo"}:
+            self.seed_name = args["seed_name"]
+
+        if cmd in {"ReceivedItems"}:
+            received_ids = [item.item for item in self.items_received]
+            for network_item in self.items_received:
+                filename = f"AP_{str(network_item.item)}.item"
+                path = os.path.join(self.game_communication_path, filename)
+
+                # Newly-obtained items
+                if not os.path.isfile(path):
+                    open(path, 'w').close()
+                    # Announcing commander unlocks
+                    item_name = self.item_names[network_item.item]
+                    if item_name in faction_table.keys():
+                        for commander in faction_table[item_name]:
+                            logger.info(f"{commander.name} has been unlocked!")
+
+                with open(path, 'w') as f:
+                    item_count = received_ids.count(network_item.item)
+                    if self.buff_item_ids["Income Boost"] == network_item.item:
+                        f.write(f"{item_count * self.income_boost_multiplier}")
+                    elif self.buff_item_ids["Commander Defense Boost"] == network_item.item:
+                        f.write(f"{item_count * self.commander_defense_boost_multiplier}")
+                    else:
+                        f.write(f"{item_count}")
+                    f.close()
+
+                print_filename = f"AP_{str(network_item.item)}.item.print"
+                print_path = os.path.join(self.game_communication_path, print_filename)
+                if not os.path.isfile(print_path):
+                    open(print_path, 'w').close()
+                    with open(print_path, 'w') as f:
+                        f.write("Received " +
+                                self.item_names[network_item.item] +
+                                " from " +
+                                self.player_names[network_item.player])
+                        f.close()
+            self.update_commander_data()
+            self.ui.update_tracker()
+
+        if cmd in {"RoomUpdate"}:
+            if "checked_locations" in args:
+                for ss in self.checked_locations:
+                    filename = f"send{ss}"
+                    with open(os.path.join(self.game_communication_path, filename), 'w') as f:
+                        f.close()
+
+    def run_gui(self):
+        """Import kivy UI system and start running it as self.ui_task."""
+        from kvui import GameManager, HoverBehavior, ServerToolTip
+        from kivy.uix.tabbedpanel import TabbedPanelItem
+        from kivy.lang import Builder
+        from kivy.uix.button import Button
+        from kivy.uix.togglebutton import ToggleButton
+        from kivy.uix.boxlayout import BoxLayout
+        from kivy.uix.gridlayout import GridLayout
+        from kivy.uix.image import AsyncImage, Image
+        from kivy.uix.stacklayout import StackLayout
+        from kivy.uix.label import Label
+        from kivy.properties import ColorProperty
+        from kivy.uix.image import Image
+        import pkgutil
+
+        class TrackerLayout(BoxLayout):
+            pass
+
+        class CommanderSelect(BoxLayout):
+            pass
+
+        class CommanderButton(ToggleButton):
+            pass
+
+        class FactionBox(BoxLayout):
+            pass
+
+        class CommanderGroup(BoxLayout):
+            pass
+
+        class ItemTracker(BoxLayout):
+            pass
+
+        class ItemLabel(Label):
+            pass
+
+        class WargrooveManager(GameManager):
+            logging_pairs = [
+                ("Client", "Archipelago"),
+                ("WG", "WG Console"),
+            ]
+            base_title = "Archipelago Wargroove Client"
+            ctx: WargrooveContext
+            unit_tracker: ItemTracker
+            trigger_tracker: BoxLayout
+            boost_tracker: BoxLayout
+            commander_buttons: Dict[int, List[CommanderButton]]
+            tracker_items = {
+                "Swordsman": ItemData(None, "Unit", False),
+                "Dog": ItemData(None, "Unit", False),
+                **item_table
+            }
+
+            def build(self):
+                container = super().build()
+                panel = TabbedPanelItem(text="Wargroove")
+                panel.content = self.build_tracker()
+                self.tabs.add_widget(panel)
+                return container
+
+            def build_tracker(self) -> TrackerLayout:
+                try:
+                    tracker = TrackerLayout(orientation="horizontal")
+                    commander_select = CommanderSelect(orientation="vertical")
+                    self.commander_buttons = {}
+
+                    for faction, commanders in faction_table.items():
+                        faction_box = FactionBox(size_hint=(None, None), width=100 * len(commanders), height=70)
+                        commander_group = CommanderGroup()
+                        commander_buttons = []
+                        for commander in commanders:
+                            commander_button = CommanderButton(text=commander.name, group="commanders")
+                            if faction == "Starter":
+                                commander_button.disabled = False
+                            commander_button.bind(on_press=lambda instance: self.ctx.set_commander(instance.text))
+                            commander_buttons.append(commander_button)
+                            commander_group.add_widget(commander_button)
+                        self.commander_buttons[faction] = commander_buttons
+                        faction_box.add_widget(Label(text=faction, size_hint_x=None, pos_hint={'left': 1}, size_hint_y=None, height=10))
+                        faction_box.add_widget(commander_group)
+                        commander_select.add_widget(faction_box)
+                    item_tracker = ItemTracker(padding=[0,20])
+                    self.unit_tracker = BoxLayout(orientation="vertical")
+                    other_tracker = BoxLayout(orientation="vertical")
+                    self.trigger_tracker = BoxLayout(orientation="vertical")
+                    self.boost_tracker = BoxLayout(orientation="vertical")
+                    other_tracker.add_widget(self.trigger_tracker)
+                    other_tracker.add_widget(self.boost_tracker)
+                    item_tracker.add_widget(self.unit_tracker)
+                    item_tracker.add_widget(other_tracker)
+                    tracker.add_widget(commander_select)
+                    tracker.add_widget(item_tracker)
+                    self.update_tracker()
+                    return tracker
+                except Exception as e:
+                    print(e)
+
+            def update_tracker(self):
+                received_ids = [item.item for item in self.ctx.items_received]
+                for faction, item_id in self.ctx.faction_item_ids.items():
+                    for commander_button in self.commander_buttons[faction]:
+                        commander_button.disabled = not (faction == "Starter" or item_id in received_ids)
+                self.unit_tracker.clear_widgets()
+                self.trigger_tracker.clear_widgets()
+                for name, item in self.tracker_items.items():
+                    if item.type in ("Unit", "Trigger"):
+                        status_color = (1, 1, 1, 1) if item.code is None or item.code in received_ids else (0.6, 0.2, 0.2, 1)
+                        label = ItemLabel(text=name, color=status_color)
+                        if item.type == "Unit":
+                            self.unit_tracker.add_widget(label)
+                        else:
+                            self.trigger_tracker.add_widget(label)
+                self.boost_tracker.clear_widgets()
+                extra_income = received_ids.count(52023) * self.ctx.income_boost_multiplier
+                extra_defense = received_ids.count(52024) * self.ctx.commander_defense_boost_multiplier
+                income_boost = ItemLabel(text="Extra Income: " + str(extra_income))
+                defense_boost = ItemLabel(text="Comm Defense: " + str(100 + extra_defense))
+                self.boost_tracker.add_widget(income_boost)
+                self.boost_tracker.add_widget(defense_boost)
+
+        self.ui = WargrooveManager(self)
+        data = pkgutil.get_data(WargrooveWorld.__module__, "Wargroove.kv").decode()
+        Builder.load_string(data)
+        self.ui_task = asyncio.create_task(self.ui.async_run(), name="UI")
+
+    def update_commander_data(self):
+        if self.can_choose_commander:
+            faction_items = 0
+            faction_item_names = [faction + ' Commanders' for faction in faction_table.keys()]
+            for network_item in self.items_received:
+                if self.item_names[network_item.item] in faction_item_names:
+                    faction_items += 1
+            starting_groove = (faction_items - 1) * self.starting_groove_multiplier
+            # Must be an integer larger than 0
+            starting_groove = int(max(starting_groove, 0))
+            data = {
+                "commander": self.current_commander.internal_name,
+                "starting_groove": starting_groove
+            }
+        else:
+            data = {
+                "commander": "seed",
+                "starting_groove": 0
+            }
+        filename = 'commander.json'
+        with open(os.path.join(self.game_communication_path, filename), 'w') as f:
+            json.dump(data, f)
+        if self.ui:
+            self.ui.update_tracker()
+
+    def set_commander(self, commander_name: str) -> bool:
+        """Sets the current commander to the given one, if possible"""
+        if not self.can_choose_commander:
+            wg_logger.error("Cannot set commanders in this game mode.")
+            return
+        match_name = commander_name.lower()
+        for commander, unlocked in self.get_commanders():
+            if commander.name.lower() == match_name or commander.alt_name and commander.alt_name.lower() == match_name:
+                if unlocked:
+                    self.current_commander = commander
+                    self.syncing = True
+                    wg_logger.info(f"Commander set to {commander.name}.")
+                    self.update_commander_data()
+                    return True
+                else:
+                    wg_logger.error(f"Commander {commander.name} has not been unlocked.")
+                    return False
+        else:
+            wg_logger.error(f"{commander_name} is not a recognized Wargroove commander.")
+
+    def get_commanders(self) -> List[Tuple[CommanderData, bool]]:
+        """Gets a list of commanders with their unlocked status"""
+        commanders = []
+        received_ids = [item.item for item in self.items_received]
+        for faction in faction_table.keys():
+            unlocked = faction == 'Starter' or self.faction_item_ids[faction] in received_ids
+            commanders += [(commander, unlocked) for commander in faction_table[faction]]
+        return commanders
+
+
+async def game_watcher(ctx: WargrooveContext):
+    from worlds.wargroove.Locations import location_table
+    while not ctx.exit_event.is_set():
+        if ctx.syncing == True:
+            sync_msg = [{'cmd': 'Sync'}]
+            if ctx.locations_checked:
+                sync_msg.append({"cmd": "LocationChecks", "locations": list(ctx.locations_checked)})
+            await ctx.send_msgs(sync_msg)
+            ctx.syncing = False
+        sending = []
+        victory = False
+        for root, dirs, files in os.walk(ctx.game_communication_path):
+            for file in files:
+                if file.find("send") > -1:
+                    st = file.split("send", -1)[1]
+                    sending = sending+[(int(st))]
+                if file.find("victory") > -1:
+                    victory = True
+        ctx.locations_checked = sending
+        message = [{"cmd": 'LocationChecks', "locations": sending}]
+        await ctx.send_msgs(message)
+        if not ctx.finished_game and victory:
+            await ctx.send_msgs([{"cmd": "StatusUpdate", "status": ClientStatus.CLIENT_GOAL}])
+            ctx.finished_game = True
+        await asyncio.sleep(0.1)
+
+
+def print_error_and_close(msg):
+    logger.error("Error: " + msg)
+    Utils.messagebox("Error", msg, error=True)
+    sys.exit(1)
+
+if __name__ == '__main__':
+    async def main(args):
+        ctx = WargrooveContext(args.connect, args.password)
+        ctx.server_task = asyncio.create_task(server_loop(ctx), name="server loop")
+        if gui_enabled:
+            ctx.run_gui()
+        ctx.run_cli()
+        progression_watcher = asyncio.create_task(
+            game_watcher(ctx), name="WargrooveProgressionWatcher")
+
+        await ctx.exit_event.wait()
+        ctx.server_address = None
+
+        await progression_watcher
+
+        await ctx.shutdown()
+
+    import colorama
+
+    parser = get_base_parser(description="Wargroove Client, for text interfacing.")
+
+    args, rest = parser.parse_known_args()
+    colorama.init()
+    asyncio.run(main(args))
+    colorama.deinit()

WebHost.py

@@ -1,41 +1,125 @@
 import os
 import multiprocessing
 import logging
+import typing
 
 import ModuleUpdate
+
 ModuleUpdate.requirements_files.add(os.path.join("WebHostLib", "requirements.txt"))
 ModuleUpdate.update()
 
 # in case app gets imported by something like gunicorn
 import Utils
-Utils.local_path.cached_path = os.path.dirname(__file__)
-
-from WebHostLib import app as raw_app
-from waitress import serve
-
-from WebHostLib.models import db
-from WebHostLib.autolauncher import autohost, autogen
-from WebHostLib.lttpsprites import update_sprites_lttp
-from WebHostLib.options import create as create_options_files
+import settings
 
+Utils.local_path.cached_path = os.path.dirname(__file__) or "."  # py3.8 is not abs. remove "." when dropping 3.8
+settings.no_gui = True
 configpath = os.path.abspath("config.yaml")
+if not os.path.exists(configpath):  # fall back to config.yaml in home
+    configpath = os.path.abspath(Utils.user_path('config.yaml'))
 
 
 def get_app():
+    from WebHostLib import register, cache, app as raw_app
+    from WebHostLib.models import db
+
+    register()
     app = raw_app
-    if os.path.exists(configpath):
+    if os.path.exists(configpath) and not app.config["TESTING"]:
         import yaml
         app.config.from_file(configpath, yaml.safe_load)
         logging.info(f"Updated config from {configpath}")
+    if not app.config["HOST_ADDRESS"]:
+        logging.info("Getting public IP, as HOST_ADDRESS is empty.")
+        app.config["HOST_ADDRESS"] = Utils.get_public_ipv4()
+        logging.info(f"HOST_ADDRESS was set to {app.config['HOST_ADDRESS']}")
+
+    cache.init_app(app)
     db.bind(**app.config["PONY"])
     db.generate_mapping(create_tables=True)
     return app
 
 
+def create_ordered_tutorials_file() -> typing.List[typing.Dict[str, typing.Any]]:
+    import json
+    import shutil
+    import zipfile
+
+    zfile: zipfile.ZipInfo
+
+    from worlds.AutoWorld import AutoWorldRegister
+    worlds = {}
+    data = []
+    for game, world in AutoWorldRegister.world_types.items():
+        if hasattr(world.web, 'tutorials') and (not world.hidden or game == 'Archipelago'):
+            worlds[game] = world
+
+    base_target_path = Utils.local_path("WebHostLib", "static", "generated", "docs")
+    for game, world in worlds.items():
+        # copy files from world's docs folder to the generated folder
+        target_path = os.path.join(base_target_path, game)
+        os.makedirs(target_path, exist_ok=True)
+
+        if world.zip_path:
+            zipfile_path = world.zip_path
+
+            assert os.path.isfile(zipfile_path), f"{zipfile_path} is not a valid file(path)."
+            assert zipfile.is_zipfile(zipfile_path), f"{zipfile_path} is not a valid zipfile."
+
+            with zipfile.ZipFile(zipfile_path) as zf:
+                for zfile in zf.infolist():
+                    if not zfile.is_dir() and "/docs/" in zfile.filename:
+                        zfile.filename = os.path.basename(zfile.filename)
+                        zf.extract(zfile, target_path)
+        else:
+            source_path = Utils.local_path(os.path.dirname(world.__file__), "docs")
+            files = os.listdir(source_path)
+            for file in files:
+                shutil.copyfile(Utils.local_path(source_path, file), Utils.local_path(target_path, file))
+
+        # build a json tutorial dict per game
+        game_data = {'gameTitle': game, 'tutorials': []}
+        for tutorial in world.web.tutorials:
+            # build dict for the json file
+            current_tutorial = {
+                'name': tutorial.tutorial_name,
+                'description': tutorial.description,
+                'files': [{
+                    'language': tutorial.language,
+                    'filename': game + '/' + tutorial.file_name,
+                    'link': f'{game}/{tutorial.link}',
+                    'authors': tutorial.authors
+                }]
+            }
+
+            # check if the name of the current guide exists already
+            for guide in game_data['tutorials']:
+                if guide and tutorial.tutorial_name == guide['name']:
+                    guide['files'].append(current_tutorial['files'][0])
+                    break
+            else:
+                game_data['tutorials'].append(current_tutorial)
+
+        data.append(game_data)
+    with open(Utils.local_path("WebHostLib", "static", "generated", "tutorials.json"), 'w', encoding='utf-8-sig') as json_target:
+        generic_data = {}
+        for games in data:
+            if 'Archipelago' in games['gameTitle']:
+                generic_data = data.pop(data.index(games))
+        sorted_data = [generic_data] + Utils.title_sorted(data, key=lambda entry: entry["gameTitle"])
+        json.dump(sorted_data, json_target, indent=2, ensure_ascii=False)
+    return sorted_data
+
+
 if __name__ == "__main__":
     multiprocessing.freeze_support()
     multiprocessing.set_start_method('spawn')
     logging.basicConfig(format='[%(asctime)s] %(message)s', level=logging.INFO)
+
+    from WebHostLib.lttpsprites import update_sprites_lttp
+    from WebHostLib.autolauncher import autohost, autogen
+    from WebHostLib.options import create as create_options_files
+
     try:
         update_sprites_lttp()
     except Exception as e:
@@ -43,13 +127,14 @@ if __name__ == "__main__":
         logging.warning("Could not update LttP sprites.")
     app = get_app()
     create_options_files()
+    create_ordered_tutorials_file()
     if app.config["SELFLAUNCH"]:
         autohost(app.config)
     if app.config["SELFGEN"]:
         autogen(app.config)
     if app.config["SELFHOST"]:  # using WSGI, you just want to run get_app()
         if app.config["DEBUG"]:
-            autohost(app.config)
             app.run(debug=True, port=app.config["PORT"])
         else:
+            from waitress import serve
             serve(app, port=app.config["PORT"], threads=app.config["WAITRESS_THREADS"])

WebHostLib/README.md

@@ -0,0 +1,46 @@
+# WebHost
+
+## Contribution Guidelines
+**Thank you for your interest in contributing to the Archipelago website!**  
+Much of the content on the website is generated automatically, but there are some things
+that need a personal touch. For those things, we rely on contributions from both the core
+team and the community. The current primary maintainer of the website is Farrak Kilhn.
+He may be found on Discord as `Farrak Kilhn#0418`, or on GitHub as `LegendaryLinux`.
+
+### Small Changes
+Little changes like adding a button or a couple new select elements are perfectly fine.
+Tweaks to style specific to a PR's content are also probably not a problem. For example, if
+you build a new page which needs two side by side tables, and you need to write a CSS file
+specific to your page, that is perfectly reasonable.
+
+### Content Additions
+Once you develop a new feature or add new content the website, make a pull request. It will
+be reviewed by the community and there will probably be some discussion around it. Depending
+on the size of the feature, and if new styles are required, there may be an additional step
+before the PR is accepted wherein Farrak works with the designer to implement styles.
+
+### Restrictions on Style Changes
+A professional designer is paid to develop the styles and assets for the Archipelago website.
+In an effort to maintain a consistent look and feel, pull requests which *exclusively*
+change site styles are rejected. Please note this applies to code which changes the overall
+look and feel of the site, not to small tweaks to CSS for your custom page. The intention
+behind these restrictions is to maintain a curated feel for the design of the site. If
+any PR affects the overall feel of the site but includes additive changes, there will
+likely be a conversation about how to implement those changes without compromising the
+curated site style. It is therefore worth noting there are a couple files which, if
+changed in your pull request, will cause it to draw additional scrutiny.
+
+These closely guarded files are:
+- `globalStyles.css`
+- `islandFooter.css`
+- `landing.css`
+- `markdown.css`
+- `tooltip.css`
+
+### Site Themes
+There are several themes available for game pages. It is possible to request a new theme in
+the `#art-and-design` channel on Discord. Because themes are created by the designer, they
+are not free, and take some time to create. Farrak works closely with the designer to implement
+these themes, and pays for the assets out of pocket. Therefore, only a couple themes per year
+are added. If a proposed theme seems like a cool idea and the community likes it, there is a
+good chance it will become a reality.

WebHostLib/__init__.py

@@ -1,16 +1,15 @@
-import os
-import uuid
 import base64
+import os
 import socket
+import uuid
 
-import jinja2.exceptions
-from pony.flask import Pony
-from flask import Flask, request, redirect, url_for, render_template, Response, session, abort, send_from_directory
+from flask import Flask
 from flask_caching import Cache
 from flask_compress import Compress
-from worlds.AutoWorld import AutoWorldRegister
+from pony.flask import Pony
+from werkzeug.routing import BaseConverter
 
-from .models import *
+from Utils import title_sorted
 
 UPLOAD_FOLDER = os.path.relpath('uploads')
 LOGS_FOLDER = os.path.relpath('logs')
@@ -25,6 +24,8 @@ app.jinja_env.filters['all'] = all
 app.config["SELFHOST"] = True  # application process is in charge of running the websites
 app.config["GENERATORS"] = 8  # maximum concurrent world gens
 app.config["SELFLAUNCH"] = True  # application process is in charge of launching Rooms.
+app.config["SELFLAUNCHCERT"] = None  # can point to a SSL Certificate to encrypt Room websocket connections
+app.config["SELFLAUNCHKEY"] = None  # can point to a SSL Certificate Key to encrypt Room websocket connections
 app.config["SELFGEN"] = True  # application process is in charge of scheduling Generations.
 app.config["DEBUG"] = False
 app.config["PORT"] = 80
@@ -32,8 +33,10 @@ app.config['UPLOAD_FOLDER'] = UPLOAD_FOLDER
 app.config['MAX_CONTENT_LENGTH'] = 64 * 1024 * 1024  # 64 megabyte limit
 # if you want to deploy, make sure you have a non-guessable secret key
 app.config["SECRET_KEY"] = bytes(socket.gethostname(), encoding="utf-8")
-# at what amount of worlds should scheduling be used, instead of rolling in the webthread
-app.config["JOB_THRESHOLD"] = 2
+# at what amount of worlds should scheduling be used, instead of rolling in the web-thread
+app.config["JOB_THRESHOLD"] = 1
+# after what time in seconds should generation be aborted, freeing the queue slot. Can be set to None to disable.
+app.config["JOB_TIME"] = 600
 app.config['SESSION_PERMANENT'] = True
 
 # waitress uses one thread for I/O, these are for processing of views that then get sent
@@ -46,15 +49,13 @@ app.config["PONY"] = {
     'create_db': True
 }
 app.config["MAX_ROLL"] = 20
-app.config["CACHE_TYPE"] = "simple"
+app.config["CACHE_TYPE"] = "SimpleCache"
 app.config["JSON_AS_ASCII"] = False
-app.config["PATCH_TARGET"] = "archipelago.gg"
+app.config["HOST_ADDRESS"] = ""
 
-cache = Cache(app)
+cache = Cache()
 Compress(app)
 
-from werkzeug.routing import BaseConverter
-
 
 class B64UUIDConverter(BaseConverter):
 
@@ -68,127 +69,20 @@ class B64UUIDConverter(BaseConverter):
 # short UUID
 app.url_map.converters["suuid"] = B64UUIDConverter
 app.jinja_env.filters['suuid'] = lambda value: base64.urlsafe_b64encode(value.bytes).rstrip(b'=').decode('ascii')
+app.jinja_env.filters["title_sorted"] = title_sorted
 
 
-@app.before_request
-def register_session():
-    session.permanent = True  # technically 31 days after the last visit
-    if not session.get("_id", None):
-        session["_id"] = uuid4()  # uniquely identify each session without needing a login
+def register():
+    """Import submodules, triggering their registering on flask routing.
+    Note: initializes worlds subsystem."""
+    # has automatic patch integration
+    import worlds.AutoWorld
+    import worlds.Files
+    app.jinja_env.filters['supports_apdeltapatch'] = lambda game_name: \
+        game_name in worlds.Files.AutoPatchRegister.patch_types
 
+    from WebHostLib.customserver import run_server_process
+    # to trigger app routing picking up on it
+    from . import tracker, upload, landing, check, generate, downloads, api, stats, misc
 
-@app.errorhandler(404)
-@app.errorhandler(jinja2.exceptions.TemplateNotFound)
-def page_not_found(err):
-    return render_template('404.html'), 404
-
-
-# Start Playing Page
-@app.route('/start-playing')
-def start_playing():
-    return render_template(f"startPlaying.html")
-
-
-# Player settings pages
-@app.route('/games/<string:game>/player-settings')
-def player_settings(game):
-    return render_template(f"player-settings.html", game=game)
-
-
-# Game Info Pages
-@app.route('/games/<string:game>/info/<string:lang>')
-def game_info(game, lang):
-    return render_template('gameInfo.html', game=game, lang=lang)
-
-
-# List of supported games
-@app.route('/games')
-def games():
-    worlds = {}
-    for game, world in AutoWorldRegister.world_types.items():
-        if not world.hidden:
-            worlds[game] = world.__doc__ if world.__doc__ else "No description provided."
-    return render_template("supportedGames.html", worlds=worlds)
-
-
-@app.route('/tutorial/<string:game>/<string:file>/<string:lang>')
-def tutorial(game, file, lang):
-    return render_template("tutorial.html", game=game, file=file, lang=lang)
-
-
-@app.route('/tutorial/')
-def tutorial_landing():
-    return render_template("tutorialLanding.html")
-
-
-@app.route('/faq/<string:lang>/')
-def faq(lang):
-    return render_template("faq.html", lang=lang)
-
-
-@app.route('/seed/<suuid:seed>')
-def view_seed(seed: UUID):
-    seed = Seed.get(id=seed)
-    if not seed:
-        abort(404)
-    return render_template("viewSeed.html", seed=seed,
-                           rooms=[room for room in seed.rooms if room.owner == session["_id"]])
-
-
-@app.route('/new_room/<suuid:seed>')
-def new_room(seed: UUID):
-    seed = Seed.get(id=seed)
-    if not seed:
-        abort(404)
-    room = Room(seed=seed, owner=session["_id"], tracker=uuid4())
-    commit()
-    return redirect(url_for("host_room", room=room.id))
-
-
-def _read_log(path: str):
-    if os.path.exists(path):
-        with open(path, encoding="utf-8-sig") as log:
-            yield from log
-    else:
-        yield f"Logfile {path} does not exist. " \
-              f"Likely a crash during spinup of multiworld instance or it is still spinning up."
-
-
-@app.route('/log/<suuid:room>')
-def display_log(room: UUID):
-    return Response(_read_log(os.path.join("logs", str(room) + ".txt")), mimetype="text/plain;charset=UTF-8")
-
-
-@app.route('/room/<suuid:room>', methods=['GET', 'POST'])
-def host_room(room: UUID):
-    room = Room.get(id=room)
-    if room is None:
-        return abort(404)
-    if request.method == "POST":
-        if room.owner == session["_id"]:
-            cmd = request.form["cmd"]
-            if cmd:
-                Command(room=room, commandtext=cmd)
-                commit()
-
-    with db_session:
-        room.last_activity = datetime.utcnow()  # will trigger a spinup, if it's not already running
-
-    return render_template("hostRoom.html", room=room)
-
-
-@app.route('/favicon.ico')
-def favicon():
-    return send_from_directory(os.path.join(app.root_path, 'static/static'),
-                               'favicon.ico', mimetype='image/vnd.microsoft.icon')
-
-
-@app.route('/discord')
-def discord():
-    return redirect("https://discord.gg/archipelago")
-
-
-from WebHostLib.customserver import run_server_process
-from . import tracker, upload, landing, check, generate, downloads, api  # to trigger app routing picking up on it
-
-app.register_blueprint(api.api_endpoints)
+    app.register_blueprint(api.api_endpoints)

WebHostLib/api/__init__.py

@@ -1,40 +1,59 @@
 """API endpoints package."""
+from typing import List, Tuple
 from uuid import UUID
 
 from flask import Blueprint, abort
 
-from ..models import Room
 from .. import cache
+from ..models import Room, Seed
 
 api_endpoints = Blueprint('api', __name__, url_prefix="/api")
 
-from . import generate, user  # trigger registration
-
 # unsorted/misc endpoints
 
 
+def get_players(seed: Seed) -> List[Tuple[str, str]]:
+    return [(slot.player_name, slot.game) for slot in seed.slots]
+
+
 @api_endpoints.route('/room_status/<suuid:room>')
 def room_info(room: UUID):
     room = Room.get(id=room)
     if room is None:
         return abort(404)
-    return {"tracker": room.tracker,
-            "players": room.seed.multidata["names"],
-            "last_port": room.last_port,
-            "last_activity": room.last_activity,
-            "timeout": room.timeout}
+    return {
+        "tracker": room.tracker,
+        "players": get_players(room.seed),
+        "last_port": room.last_port,
+        "last_activity": room.last_activity,
+        "timeout": room.timeout
+    }
 
 
 @api_endpoints.route('/datapackage')
 @cache.cached()
-def get_datapackge():
+def get_datapackage():
     from worlds import network_data_package
     return network_data_package
 
+
 @api_endpoints.route('/datapackage_version')
 @cache.cached()
-def get_datapackge_versions():
-    from worlds import network_data_package, AutoWorldRegister
+def get_datapackage_versions():
+    from worlds import AutoWorldRegister
+
     version_package = {game: world.data_version for game, world in AutoWorldRegister.world_types.items()}
-    version_package["version"] = network_data_package["version"]
     return version_package
+
+
+@api_endpoints.route('/datapackage_checksum')
+@cache.cached()
+def get_datapackage_checksums():
+    from worlds import network_data_package
+    version_package = {
+        game: game_data["checksum"] for game, game_data in network_data_package["games"].items()
+    }
+    return version_package
+
+
+from . import generate, user  # trigger registration

WebHostLib/api/generate.py

@@ -1,15 +1,16 @@
 import json
 import pickle
-
 from uuid import UUID
 
-from . import api_endpoints
 from flask import request, session, url_for
+from markupsafe import Markup
 from pony.orm import commit
 
-from WebHostLib import app, Generation, STATE_QUEUED, Seed, STATE_ERROR
+from WebHostLib import app
 from WebHostLib.check import get_yaml_data, roll_options
 from WebHostLib.generate import get_meta
+from WebHostLib.models import Generation, STATE_QUEUED, Seed, STATE_ERROR
+from . import api_endpoints
 
 
 @api_endpoints.route('/generate', methods=['POST'])
@@ -21,13 +22,18 @@ def generate_api():
         if 'file' in request.files:
             file = request.files['file']
             options = get_yaml_data(file)
-            if type(options) == str:
+            if isinstance(options, Markup):
+                return {"text": options.striptags()}, 400
+            if isinstance(options, str):
                 return {"text": options}, 400
             if "race" in request.form:
                 race = bool(0 if request.form["race"] in {"false"} else int(request.form["race"]))
             meta_options_source = request.form
 
-        json_data = request.get_json()
+        # json_data is optional, we can have it silently fall to None as it used to do.
+        # See https://flask.palletsprojects.com/en/2.2.x/api/#flask.Request.get_json -> Changelog -> 2.1
+        json_data = request.get_json(silent=True)
+
         if json_data:
             meta_options_source = json_data
             if 'weights' in json_data:
@@ -43,9 +49,8 @@ def generate_api():
         if len(options) > app.config["MAX_ROLL"]:
             return {"text": "Max size of multiworld exceeded",
                     "detail": app.config["MAX_ROLL"]}, 409
-        meta = get_meta(meta_options_source)
-        meta["race"] = race
-        results, gen_options = roll_options(options)
+        meta = get_meta(meta_options_source, race)
+        results, gen_options = roll_options(options, set(meta["plando_options"]))
         if any(type(result) == str for result in results.values()):
             return {"text": str(results),
                     "detail": results}, 400
@@ -65,7 +70,6 @@ def generate_api():
         return {"text": "Uncaught Exception:" + str(e)}, 500
 
 
-
 @api_endpoints.route('/status/<suuid:seed>')
 def wait_seed_api(seed: UUID):
     seed_id = seed

WebHostLib/api/user.py

@@ -1,7 +1,8 @@
 from flask import session, jsonify
+from pony.orm import select
 
-from WebHostLib.models import *
-from . import api_endpoints
+from WebHostLib.models import Room, Seed
+from . import api_endpoints, get_players
 
 
 @api_endpoints.route('/get_rooms')
@@ -16,7 +17,6 @@ def get_rooms():
             "last_port": room.last_port,
             "timeout": room.timeout,
             "tracker": room.tracker,
-            "players": room.seed.multidata["names"] if room.seed.multidata else [["Singleplayer"]],
         })
     return jsonify(response)
 
@@ -28,6 +28,6 @@ def get_seeds():
         response.append({
             "seed_id": seed.id,
             "creation_time": seed.creation_time,
-            "players": seed.multidata["names"] if seed.multidata else [["Singleplayer"]],
+            "players": get_players(seed.slots),
         })
     return jsonify(response)

WebHostLib/autolauncher.py

@@ -1,65 +1,17 @@
 from __future__ import annotations
-import logging
+
 import json
+import logging
 import multiprocessing
-from datetime import timedelta, datetime
-import concurrent.futures
-import sys
-import typing
+import threading
 import time
-import os
+import typing
+from datetime import timedelta, datetime
 
 from pony.orm import db_session, select, commit
 
 from Utils import restricted_loads
-
-
-class CommonLocker():
-    """Uses a file lock to signal that something is already running"""
-    lock_folder = "file_locks"
-    def __init__(self, lockname: str, folder=None):
-        if folder:
-            self.lock_folder = folder
-        os.makedirs(self.lock_folder, exist_ok=True)
-        self.lockname = lockname
-        self.lockfile = os.path.join(self.lock_folder, f"{self.lockname}.lck")
-
-
-class AlreadyRunningException(Exception):
-    pass
-
-
-if sys.platform == 'win32':
-    class Locker(CommonLocker):
-        def __enter__(self):
-            try:
-                if os.path.exists(self.lockfile):
-                    os.unlink(self.lockfile)
-                self.fp = os.open(
-                    self.lockfile, os.O_CREAT | os.O_EXCL | os.O_RDWR)
-            except OSError as e:
-                raise AlreadyRunningException() from e
-
-        def __exit__(self, _type, value, tb):
-            fp = getattr(self, "fp", None)
-            if fp:
-                os.close(self.fp)
-                os.unlink(self.lockfile)
-else:  # unix
-    import fcntl
-
-
-    class Locker(CommonLocker):
-        def __enter__(self):
-            try:
-                self.fp = open(self.lockfile, "wb")
-                fcntl.flock(self.fp.fileno(), fcntl.LOCK_EX)
-            except OSError as e:
-                raise AlreadyRunningException() from e
-
-        def __exit__(self, _type, value, tb):
-            fcntl.flock(self.fp.fileno(), fcntl.LOCK_UN)
-            self.fp.close()
+from .locker import Locker, AlreadyRunningException
 
 
 def launch_room(room: Room, config: dict):
@@ -110,6 +62,7 @@ def autohost(config: dict):
     def keep_running():
         try:
             with Locker("autohost"):
+                run_guardian()
                 while 1:
                     time.sleep(0.1)
                     with db_session:
@@ -132,7 +85,7 @@ def autogen(config: dict):
             with Locker("autogen"):
 
                 with multiprocessing.Pool(config["GENERATORS"], initializer=init_db,
-                                          initargs=(config["PONY"],)) as generator_pool:
+                                          initargs=(config["PONY"],), maxtasksperchild=10) as generator_pool:
                     with db_session:
                         to_start = select(generation for generation in Generation if generation.state == STATE_STARTED)
 
@@ -151,8 +104,10 @@ def autogen(config: dict):
                     while 1:
                         time.sleep(0.1)
                         with db_session:
+                            # for update locks the database row(s) during transaction, preventing writes from elsewhere
                             to_start = select(
-                                generation for generation in Generation if generation.state == STATE_QUEUED)
+                                generation for generation in Generation
+                                if generation.state == STATE_QUEUED).for_update()
                             for generation in to_start:
                                 launch_generator(generator_pool, generation)
         except AlreadyRunningException:
@@ -162,40 +117,80 @@ def autogen(config: dict):
     threading.Thread(target=keep_running, name="AP_Autogen").start()
 
 
-multiworlds = {}
-
-guardians = concurrent.futures.ThreadPoolExecutor(2, thread_name_prefix="Guardian")
+multiworlds: typing.Dict[type(Room.id), MultiworldInstance] = {}
 
 
 class MultiworldInstance():
     def __init__(self, room: Room, config: dict):
         self.room_id = room.id
         self.process: typing.Optional[multiprocessing.Process] = None
-        multiworlds[self.room_id] = self
+        with guardian_lock:
+            multiworlds[self.room_id] = self
         self.ponyconfig = config["PONY"]
+        self.cert = config["SELFLAUNCHCERT"]
+        self.key = config["SELFLAUNCHKEY"]
+        self.host = config["HOST_ADDRESS"]
 
     def start(self):
         if self.process and self.process.is_alive():
             return False
 
         logging.info(f"Spinning up {self.room_id}")
-        self.process = multiprocessing.Process(group=None, target=run_server_process,
-                                               args=(self.room_id, self.ponyconfig),
-                                               name="MultiHost")
-        self.process.start()
-        self.guardian = guardians.submit(self._collect)
+        process = multiprocessing.Process(group=None, target=run_server_process,
+                                          args=(self.room_id, self.ponyconfig, get_static_server_data(),
+                                                self.cert, self.key, self.host),
+                                          name="MultiHost")
+        process.start()
+        # bind after start to prevent thread sync issues with guardian.
+        self.process = process
 
     def stop(self):
         if self.process:
             self.process.terminate()
             self.process = None
 
-    def _collect(self):
+    def done(self):
+        return self.process and not self.process.is_alive()
+
+    def collect(self):
         self.process.join()  # wait for process to finish
         self.process = None
-        self.guardian = None
+
+
+guardian = None
+guardian_lock = threading.Lock()
+
+
+def run_guardian():
+    global guardian
+    global multiworlds
+    with guardian_lock:
+        if not guardian:
+            try:
+                import resource
+            except ModuleNotFoundError:
+                pass  # unix only module
+            else:
+                # Each Server is another file handle, so request as many as we can from the system
+                file_limit = resource.getrlimit(resource.RLIMIT_NOFILE)[1]
+                # set soft limit to hard limit
+                resource.setrlimit(resource.RLIMIT_NOFILE, (file_limit, file_limit))
+
+            def guard():
+                while 1:
+                    time.sleep(1)
+                    done = []
+                    with guardian_lock:
+                        for key, instance in multiworlds.items():
+                            if instance.done():
+                                instance.collect()
+                                done.append(key)
+                        for key in done:
+                            del (multiworlds[key])
+
+            guardian = threading.Thread(name="Guardian", target=guard)
 
 
 from .models import Room, Generation, STATE_QUEUED, STATE_STARTED, STATE_ERROR, db, Seed
-from .customserver import run_server_process
+from .customserver import run_server_process, get_static_server_data
 from .generate import gen_game

WebHostLib/check.py

@@ -1,7 +1,8 @@
 import zipfile
 from typing import *
 
-from flask import request, flash, redirect, url_for, session, render_template
+from flask import request, flash, redirect, url_for, render_template
+from markupsafe import Markup
 
 from WebHostLib import app
 
@@ -12,69 +13,89 @@ def allowed_file(filename):
     return filename.endswith(('.txt', ".yaml", ".zip"))
 
 
-from Generate import roll_settings
-from Utils import parse_yaml
+from Generate import roll_settings, PlandoOptions
+from Utils import parse_yamls
 
 
-@app.route('/mysterycheck', methods=['GET', 'POST'])
-def mysterycheck():
+@app.route('/check', methods=['GET', 'POST'])
+def check():
     if request.method == 'POST':
         # check if the post request has the file part
         if 'file' not in request.files:
             flash('No file part')
         else:
-            file = request.files['file']
-            options = get_yaml_data(file)
-            if type(options) == str:
+            files = request.files.getlist('file')
+            options = get_yaml_data(files)
+            if isinstance(options, str):
                 flash(options)
             else:
                 results, _ = roll_options(options)
                 return render_template("checkResult.html", results=results)
-
     return render_template("check.html")
 
 
-def get_yaml_data(file) -> Union[Dict[str, str], str]:
+@app.route('/mysterycheck')
+def mysterycheck():
+    return redirect(url_for("check"), 301)
+
+
+def get_yaml_data(files) -> Union[Dict[str, str], str, Markup]:
     options = {}
-    # if user does not select file, browser also
-    # submit an empty part without filename
-    if file.filename == '':
-        return 'No selected file'
-    elif file and allowed_file(file.filename):
-        if file.filename.endswith(".zip"):
+    for file in files:
+        # if user does not select file, browser also
+        # submit an empty part without filename
+        if file.filename == '':
+            return 'No selected file'
+        elif file.filename in options:
+            return f'Conflicting files named {file.filename} submitted'
+        elif file and allowed_file(file.filename):
+            if file.filename.endswith(".zip"):
 
-            with zipfile.ZipFile(file, 'r') as zfile:
-                infolist = zfile.infolist()
+                with zipfile.ZipFile(file, 'r') as zfile:
+                    infolist = zfile.infolist()
 
-                for file in infolist:
-                    if file.filename.endswith(banned_zip_contents):
-                        return "Uploaded data contained a rom file, which is likely to contain copyrighted material. Your file was deleted."
-                    elif file.filename.endswith((".yaml", ".json", ".yml", ".txt")):
-                        options[file.filename] = zfile.open(file, "r").read()
-        else:
-            options = {file.filename: file.read()}
+                    if any(file.filename.endswith(".archipelago") for file in infolist):
+                        return Markup("Error: Your .zip file contains an .archipelago file. "
+                                    'Did you mean to <a href="/uploads">host a game</a>?')
+
+                    for file in infolist:
+                        if file.filename.endswith(banned_zip_contents):
+                            return "Uploaded data contained a rom file, which is likely to contain copyrighted material. " \
+                                "Your file was deleted."
+                        elif file.filename.endswith((".yaml", ".json", ".yml", ".txt")):
+                            options[file.filename] = zfile.open(file, "r").read()
+            else:
+                options[file.filename] = file.read()
     if not options:
         return "Did not find a .yaml file to process."
     return options
 
 
-def roll_options(options: Dict[str, Union[dict, str]]) -> Tuple[Dict[str, Union[str, bool]], Dict[str, dict]]:
+def roll_options(options: Dict[str, Union[dict, str]],
+                 plando_options: Set[str] = frozenset({"bosses", "items", "connections", "texts"})) -> \
+        Tuple[Dict[str, Union[str, bool]], Dict[str, dict]]:
+    plando_options = PlandoOptions.from_set(set(plando_options))
     results = {}
     rolled_results = {}
     for filename, text in options.items():
         try:
             if type(text) is dict:
-                yaml_data = text
+                yaml_datas = (text, )
             else:
-                yaml_data = parse_yaml(text)
+                yaml_datas = tuple(parse_yamls(text))
         except Exception as e:
             results[filename] = f"Failed to parse YAML data in {filename}: {e}"
         else:
             try:
-                rolled_results[filename] = roll_settings(yaml_data,
-                                                         plando_options={"bosses", "items", "connections", "texts"})
+                if len(yaml_datas) == 1:
+                    rolled_results[filename] = roll_settings(yaml_datas[0],
+                                                             plando_options=plando_options)
+                else:
+                    for i, yaml_data in enumerate(yaml_datas):
+                        rolled_results[f"{filename}/{i + 1}"] = roll_settings(yaml_data,
+                                                                              plando_options=plando_options)
             except Exception as e:
-                results[filename] = f"Failed to generate mystery in {filename}: {e}"
+                results[filename] = f"Failed to generate options in {filename}: {e}"
             else:
                 results[filename] = True
     return results, rolled_results

WebHostLib/customserver.py

@@ -1,20 +1,26 @@
 from __future__ import annotations
 
+import asyncio
+import collections
+import datetime
 import functools
 import logging
-import websockets
-import asyncio
+import pickle
+import random
 import socket
 import threading
 import time
-import random
-import pickle
+import typing
+
+import websockets
+from pony.orm import commit, db_session, select
 
 import Utils
-from .models import *
 
-from MultiServer import Context, server, auto_shutdown, ServerCommandProcessor, ClientMessageProcessor
-from Utils import get_public_ipv4, get_public_ipv6, restricted_loads
+from MultiServer import Context, server, auto_shutdown, ServerCommandProcessor, ClientMessageProcessor, load_server_cert
+from Utils import restricted_loads, cache_argsless
+from .locker import Locker
+from .models import Command, GameDataPackage, Room, db
 
 
 class CustomClientMessageProcessor(ClientMessageProcessor):
@@ -39,7 +45,7 @@ class CustomClientMessageProcessor(ClientMessageProcessor):
 import MultiServer
 
 MultiServer.client_message_processor = CustomClientMessageProcessor
-del (MultiServer)
+del MultiServer
 
 
 class DBCommandProcessor(ServerCommandProcessor):
@@ -48,12 +54,23 @@ class DBCommandProcessor(ServerCommandProcessor):
 
 
 class WebHostContext(Context):
-    def __init__(self):
+    room_id: int
+
+    def __init__(self, static_server_data: dict):
+        # static server data is used during _load_game_data to load required data,
+        # without needing to import worlds system, which takes quite a bit of memory
+        self.static_server_data = static_server_data
         super(WebHostContext, self).__init__("", 0, "", "", 1, 40, True, "enabled", "enabled", "enabled", 0, 2)
+        del self.static_server_data
         self.main_loop = asyncio.get_running_loop()
         self.video = {}
         self.tags = ["AP", "WebHost"]
 
+    def _load_game_data(self):
+        for key, value in self.static_server_data.items():
+            setattr(self, key, value)
+        self.non_hintable_names = collections.defaultdict(frozenset, self.non_hintable_names)
+
     def listen_to_db_commands(self):
         cmdprocessor = DBCommandProcessor(self)
 
@@ -76,7 +93,21 @@ class WebHostContext(Context):
         else:
             self.port = get_random_port()
 
-        return self._load(self._decompress(room.seed.multidata), True)
+        multidata = self.decompress(room.seed.multidata)
+        game_data_packages = {}
+        for game in list(multidata.get("datapackage", {})):
+            game_data = multidata["datapackage"][game]
+            if "checksum" in game_data:
+                if self.gamespackage.get(game, {}).get("checksum") == game_data["checksum"]:
+                    # non-custom. remove from multidata
+                    # games package could be dropped from static data once all rooms embed data package
+                    del multidata["datapackage"][game]
+                else:
+                    row = GameDataPackage.get(checksum=game_data["checksum"])
+                    if row:  # None if rolled on >= 0.3.9 but uploaded to <= 0.3.8. multidata should be complete
+                        game_data_packages[game] = Utils.restricted_loads(row.data)
+
+        return self._load(multidata, game_data_packages, True)
 
     @db_session
     def init_save(self, enabled: bool = True):
@@ -94,7 +125,7 @@ class WebHostContext(Context):
         room.multisave = pickle.dumps(self.get_save())
         # saving only occurs on activity, so we can "abuse" this information to mark this as last_activity
         if not exit_save:  # we don't want to count a shutdown as activity, which would restart the server again
-            room.last_activity = datetime.utcnow()
+            room.last_activity = datetime.datetime.utcnow()
         return True
 
     def get_save(self) -> dict:
@@ -107,45 +138,82 @@ def get_random_port():
     return random.randint(49152, 65535)
 
 
-def run_server_process(room_id, ponyconfig: dict):
+@cache_argsless
+def get_static_server_data() -> dict:
+    import worlds
+    data = {
+        "non_hintable_names": {},
+        "gamespackage": worlds.network_data_package["games"],
+        "item_name_groups": {world_name: world.item_name_groups for world_name, world in
+                             worlds.AutoWorldRegister.world_types.items()},
+        "location_name_groups": {world_name: world.location_name_groups for world_name, world in
+                                 worlds.AutoWorldRegister.world_types.items()},
+    }
+
+    for world_name, world in worlds.AutoWorldRegister.world_types.items():
+        data["non_hintable_names"][world_name] = world.hint_blacklist
+
+    return data
+
+
+def run_server_process(room_id, ponyconfig: dict, static_server_data: dict,
+                       cert_file: typing.Optional[str], cert_key_file: typing.Optional[str],
+                       host: str):
     # establish DB connection for multidata and multisave
     db.bind(**ponyconfig)
     db.generate_mapping(check_tables=False)
 
     async def main():
+        import gc
+
         Utils.init_logging(str(room_id), write_mode="a")
-        ctx = WebHostContext()
+        ctx = WebHostContext(static_server_data)
         ctx.load(room_id)
         ctx.init_save()
-
+        ssl_context = load_server_cert(cert_file, cert_key_file) if cert_file else None
+        gc.collect()  # free intermediate objects used during setup
         try:
-            ctx.server = websockets.serve(functools.partial(server, ctx=ctx), ctx.host, ctx.port, ping_timeout=None,
-                                          ping_interval=None)
+            ctx.server = websockets.serve(functools.partial(server, ctx=ctx), ctx.host, ctx.port, ssl=ssl_context)
 
             await ctx.server
-        except Exception:  # likely port in use - in windows this is OSError, but I didn't check the others
-            ctx.server = websockets.serve(functools.partial(server, ctx=ctx), ctx.host, 0, ping_timeout=None,
-                                          ping_interval=None)
+        except OSError:  # likely port in use
+            ctx.server = websockets.serve(functools.partial(server, ctx=ctx), ctx.host, 0, ssl=ssl_context)
 
             await ctx.server
+        port = 0
         for wssocket in ctx.server.ws_server.sockets:
             socketname = wssocket.getsockname()
             if wssocket.family == socket.AF_INET6:
-                logging.info(f'Hosting game at [{get_public_ipv6()}]:{socketname[1]}')
-                with db_session:
-                    room = Room.get(id=ctx.room_id)
-                    room.last_port = socketname[1]
+                # Prefer IPv4, as most users seem to not have working ipv6 support
+                if not port:
+                    port = socketname[1]
             elif wssocket.family == socket.AF_INET:
-                logging.info(f'Hosting game at {get_public_ipv4()}:{socketname[1]}')
+                port = socketname[1]
+        if port:
+            logging.info(f'Hosting game at {host}:{port}')
+            with db_session:
+                room = Room.get(id=ctx.room_id)
+                room.last_port = port
+        else:
+            logging.exception("Could not determine port. Likely hosting failure.")
         with db_session:
             ctx.auto_shutdown = Room.get(id=room_id).timeout
         ctx.shutdown_task = asyncio.create_task(auto_shutdown(ctx, []))
         await ctx.shutdown_task
         logging.info("Shutting down")
 
-    from .autolauncher import Locker
     with Locker(room_id):
-        asyncio.run(main())
-
-
-from WebHostLib import LOGS_FOLDER
+        try:
+            asyncio.run(main())
+        except (KeyboardInterrupt, SystemExit):
+            with db_session:
+                room = Room.get(id=room_id)
+                # ensure the Room does not spin up again on its own, minute of safety buffer
+                room.last_activity = datetime.datetime.utcnow() - datetime.timedelta(minutes=1, seconds=room.timeout)
+        except Exception:
+            with db_session:
+                room = Room.get(id=room_id)
+                room.last_port = -1
+                # ensure the Room does not spin up again on its own, minute of safety buffer
+                room.last_activity = datetime.datetime.utcnow() - datetime.timedelta(minutes=1, seconds=room.timeout)
+            raise

WebHostLib/downloads.py

@@ -1,9 +1,13 @@
+import json
+import zipfile
+from io import BytesIO
+
 from flask import send_file, Response, render_template
 from pony.orm import select
 
-from Patch import update_patch_data, preferred_endings
-from WebHostLib import app, Slot, Room, Seed, cache
-import zipfile
+from worlds.Files import AutoPatchRegister
+from . import app, cache
+from .models import Slot, Room, Seed
 
 
 @app.route("/dl_patch/<suuid:room_id>/<int:patch_id>")
@@ -12,17 +16,33 @@ def download_patch(room_id, patch_id):
     if not patch:
         return "Patch not found"
     else:
-        import io
-
         room = Room.get(id=room_id)
         last_port = room.last_port
-
-        patch_data = update_patch_data(patch.data, server=f"{app.config['PATCH_TARGET']}:{last_port}")
-        patch_data = io.BytesIO(patch_data)
-
-        fname = f"P{patch.player_id}_{patch.player_name}_{app.jinja_env.filters['suuid'](room_id)}." \
-                f"{preferred_endings[patch.game]}"
-        return send_file(patch_data, as_attachment=True, attachment_filename=fname)
+        filelike = BytesIO(patch.data)
+        greater_than_version_3 = zipfile.is_zipfile(filelike)
+        if greater_than_version_3:
+            # Python's zipfile module cannot overwrite/delete files in a zip, so we recreate the whole thing in ram
+            new_file = BytesIO()
+            with zipfile.ZipFile(filelike, "a") as zf:
+                with zf.open("archipelago.json", "r") as f:
+                    manifest = json.load(f)
+                manifest["server"] = f"{app.config['HOST_ADDRESS']}:{last_port}" if last_port else None
+                with zipfile.ZipFile(new_file, "w") as new_zip:
+                    for file in zf.infolist():
+                        if file.filename == "archipelago.json":
+                            new_zip.writestr("archipelago.json", json.dumps(manifest))
+                        else:
+                            new_zip.writestr(file.filename, zf.read(file), file.compress_type, 9)
+            if "patch_file_ending" in manifest:
+                patch_file_ending = manifest["patch_file_ending"]
+            else:
+                patch_file_ending = AutoPatchRegister.patch_types[patch.game].patch_file_ending
+            fname = f"P{patch.player_id}_{patch.player_name}_{app.jinja_env.filters['suuid'](room_id)}" \
+                    f"{patch_file_ending}"
+            new_file.seek(0)
+            return send_file(new_file, as_attachment=True, download_name=fname)
+        else:
+            return "Old Patch file, no longer compatible."
 
 
 @app.route("/dl_spoiler/<suuid:seed_id>")
@@ -34,7 +54,7 @@ def download_spoiler(seed_id):
 def download_slot_file(room_id, player_id: int):
     room = Room.get(id=room_id)
     slot_data: Slot = select(patch for patch in room.seed.slots if
-                   patch.player_id == player_id).first()
+                             patch.player_id == player_id).first()
 
     if not slot_data:
         return "Slot Data not found"
@@ -44,18 +64,36 @@ def download_slot_file(room_id, player_id: int):
         if slot_data.game == "Minecraft":
             from worlds.minecraft import mc_update_output
             fname = f"AP_{app.jinja_env.filters['suuid'](room_id)}_P{slot_data.player_id}_{slot_data.player_name}.apmc"
-            data = mc_update_output(slot_data.data, server=app.config['PATCH_TARGET'], port=room.last_port)
-            return send_file(io.BytesIO(data), as_attachment=True, attachment_filename=fname)
+            data = mc_update_output(slot_data.data, server=app.config['HOST_ADDRESS'], port=room.last_port)
+            return send_file(io.BytesIO(data), as_attachment=True, download_name=fname)
         elif slot_data.game == "Factorio":
             with zipfile.ZipFile(io.BytesIO(slot_data.data)) as zf:
                 for name in zf.namelist():
                     if name.endswith("info.json"):
-                        fname = name.rsplit("/", 1)[0]+".zip"
+                        fname = name.rsplit("/", 1)[0] + ".zip"
         elif slot_data.game == "Ocarina of Time":
-            fname = f"AP_{app.jinja_env.filters['suuid'](room_id)}_P{slot_data.player_id}_{slot_data.player_name}.apz5"
+            stream = io.BytesIO(slot_data.data)
+            if zipfile.is_zipfile(stream):
+                with zipfile.ZipFile(stream) as zf:
+                    for name in zf.namelist():
+                        if name.endswith(".zpf"):
+                            fname = name.rsplit(".", 1)[0] + ".apz5"
+            else: # pre-ootr-7.0 support
+                fname = f"AP_{app.jinja_env.filters['suuid'](room_id)}_P{slot_data.player_id}_{slot_data.player_name}.apz5"
+        elif slot_data.game == "VVVVVV":
+            fname = f"AP_{app.jinja_env.filters['suuid'](room_id)}_SP.apv6"
+        elif slot_data.game == "Zillion":
+            fname = f"AP_{app.jinja_env.filters['suuid'](room_id)}_SP.apzl"
+        elif slot_data.game == "Super Mario 64":
+            fname = f"AP_{app.jinja_env.filters['suuid'](room_id)}_SP.apsm64ex"
+        elif slot_data.game == "Dark Souls III":
+            fname = f"AP_{app.jinja_env.filters['suuid'](room_id)}.json"
+        elif slot_data.game == "Kingdom Hearts 2":
+            fname = f"AP_{app.jinja_env.filters['suuid'](room_id)}_P{slot_data.player_id}_{slot_data.player_name}.zip"
         else:
             return "Game download not supported."
-        return send_file(io.BytesIO(slot_data.data), as_attachment=True, attachment_filename=fname)
+        return send_file(io.BytesIO(slot_data.data), as_attachment=True, download_name=fname)
+
 
 @app.route("/templates")
 @cache.cached()
@@ -65,4 +103,4 @@ def list_yaml_templates():
     for world_name, world in AutoWorldRegister.world_types.items():
         if not world.hidden:
             files.append(world_name)
-    return render_template("templates.html", files=files)
+    return render_template("templates.html", files=files)

WebHostLib/generate.py

@@ -1,33 +1,59 @@
-import os
-import tempfile
-import random
 import json
+import os
+import pickle
+import random
+import tempfile
 import zipfile
+import concurrent.futures
 from collections import Counter
-from typing import Dict, Optional as TypeOptional
+from typing import Dict, Optional, Any, Union, List
 
 from flask import request, flash, redirect, url_for, session, render_template
+from pony.orm import commit, db_session
 
-from worlds.alttp.EntranceRandomizer import parse_arguments
-from Main import main as ERmain
 from BaseClasses import seeddigits, get_seed
-from Generate import handle_name
-import pickle
-
-from .models import *
+from Generate import handle_name, PlandoOptions
+from Main import main as ERmain
+from Utils import __version__
 from WebHostLib import app
+from worlds.alttp.EntranceRandomizer import parse_arguments
 from .check import get_yaml_data, roll_options
+from .models import Generation, STATE_ERROR, STATE_QUEUED, Seed, UUID
 from .upload import upload_zip_to_db
 
 
-def get_meta(options_source: dict) -> dict:
-    meta = {
-        "hint_cost": int(options_source.get("hint_cost", 10)),
-        "forfeit_mode": options_source.get("forfeit_mode", "goal"),
-        "remaining_mode": options_source.get("forfeit_mode", "disabled"),
-        "collect_mode": options_source.get("collect_mode", "disabled"),
+def get_meta(options_source: dict, race: bool = False) -> Dict[str, Union[List[str], Dict[str, Any]]]:
+    plando_options = {
+        options_source.get("plando_bosses", ""),
+        options_source.get("plando_items", ""),
+        options_source.get("plando_connections", ""),
+        options_source.get("plando_texts", "")
+    }
+    plando_options -= {""}
+
+    server_options = {
+        "hint_cost": int(options_source.get("hint_cost", 10)),
+        "release_mode": options_source.get("release_mode", "goal"),
+        "remaining_mode": options_source.get("remaining_mode", "disabled"),
+        "collect_mode": options_source.get("collect_mode", "disabled"),
+        "item_cheat": bool(int(options_source.get("item_cheat", 1))),
+        "server_password": options_source.get("server_password", None),
+    }
+    generator_options = {
+        "spoiler": int(options_source.get("spoiler", 0)),
+        "race": race
+    }
+
+    if race:
+        server_options["item_cheat"] = False
+        server_options["remaining_mode"] = "disabled"
+        generator_options["spoiler"] = 0
+
+    return {
+        "server_options": server_options,
+        "plando_options": list(plando_options),
+        "generator_options": generator_options,
     }
-    return meta
 
 
 @app.route('/generate', methods=['GET', 'POST'])
@@ -38,24 +64,18 @@ def generate(race=False):
         if 'file' not in request.files:
             flash('No file part')
         else:
-            file = request.files['file']
-            options = get_yaml_data(file)
-            if type(options) == str:
+            files = request.files.getlist('file')
+            options = get_yaml_data(files)
+            if isinstance(options, str):
                 flash(options)
             else:
-                results, gen_options = roll_options(options)
-                # get form data -> server settings
-                meta = get_meta(request.form)
-                meta["race"] = race
-
-                if race:
-                    meta["item_cheat"] = False
-                    meta["remaining"] = False
+                meta = get_meta(request.form, race)
+                results, gen_options = roll_options(options, set(meta["plando_options"]))
 
                 if any(type(result) == str for result in results.values()):
                     return render_template("checkResult.html", results=results)
                 elif len(gen_options) > app.config["MAX_ROLL"]:
-                    flash(f"Sorry, generating of multiworlds is limited to {app.config['MAX_ROLL']} players for now. "
+                    flash(f"Sorry, generating of multiworlds is limited to {app.config['MAX_ROLL']} players. "
                           f"If you have a larger group, please generate it yourself and upload it.")
                 elif len(gen_options) >= app.config["JOB_THRESHOLD"]:
                     gen = Generation(
@@ -78,35 +98,39 @@ def generate(race=False):
 
                     return redirect(url_for("view_seed", seed=seed_id))
 
-    return render_template("generate.html", race=race)
+    return render_template("generate.html", race=race, version=__version__)
 
 
-def gen_game(gen_options, meta: TypeOptional[Dict[str, object]] = None, owner=None, sid=None):
+def gen_game(gen_options: dict, meta: Optional[Dict[str, Any]] = None, owner=None, sid=None):
     if not meta:
-        meta: Dict[str, object] = {}
+        meta: Dict[str, Any] = {}
 
-    meta.setdefault("hint_cost", 10)
-    race = meta.get("race", False)
-    del (meta["race"])
-    try:
+    meta.setdefault("server_options", {}).setdefault("hint_cost", 10)
+    race = meta.setdefault("generator_options", {}).setdefault("race", False)
+
+    def task():
         target = tempfile.TemporaryDirectory()
         playercount = len(gen_options)
         seed = get_seed()
-        random.seed(seed)
 
         if race:
-            random.seed()  # reset to time-based random source
+            random.seed()  # use time-based random source
+        else:
+            random.seed(seed)
 
         seedname = "W" + (f"{random.randint(0, pow(10, seeddigits) - 1)}".zfill(seeddigits))
 
         erargs = parse_arguments(['--multi', str(playercount)])
         erargs.seed = seed
-        erargs.name = {x: "" for x in range(1, playercount + 1)}  # only so it can be overwrittin in mystery
-        erargs.spoiler = 0 if race else 2
+        erargs.name = {x: "" for x in range(1, playercount + 1)}  # only so it can be overwritten in mystery
+        erargs.spoiler = meta["generator_options"].get("spoiler", 0)
         erargs.race = race
         erargs.outputname = seedname
         erargs.outputpath = target.name
         erargs.teams = 1
+        erargs.plando_options = PlandoOptions.from_set(meta.setdefault("plando_options",
+                                                                       {"bosses", "items", "connections", "texts"}))
+        erargs.skip_prog_balancing = False
 
         name_counter = Counter()
         for player, (playerfile, settings) in enumerate(gen_options.items(), 1):
@@ -120,10 +144,28 @@ def gen_game(gen_options, meta: TypeOptional[Dict[str, object]] = None, owner=No
             if not erargs.name[player]:
                 erargs.name[player] = os.path.splitext(os.path.split(playerfile)[-1])[0]
             erargs.name[player] = handle_name(erargs.name[player], player, name_counter)
-
-        ERmain(erargs, seed, baked_server_options=meta)
+        if len(set(erargs.name.values())) != len(erargs.name):
+            raise Exception(f"Names have to be unique. Names: {Counter(erargs.name.values())}")
+        ERmain(erargs, seed, baked_server_options=meta["server_options"])
 
         return upload_to_db(target.name, sid, owner, race)
+    thread_pool = concurrent.futures.ThreadPoolExecutor(max_workers=1)
+    thread = thread_pool.submit(task)
+
+    try:
+        return thread.result(app.config["JOB_TIME"])
+    except concurrent.futures.TimeoutError as e:
+        if sid:
+            with db_session:
+                gen = Generation.get(id=sid)
+                if gen is not None:
+                    gen.state = STATE_ERROR
+                    meta = json.loads(gen.meta)
+                    meta["error"] = (
+                            "Allowed time for Generation exceeded, please consider generating locally instead. " +
+                            e.__class__.__name__ + ": " + str(e))
+                    gen.meta = json.dumps(meta)
+                    commit()
     except BaseException as e:
         if sid:
             with db_session:
@@ -133,7 +175,6 @@ def gen_game(gen_options, meta: TypeOptional[Dict[str, object]] = None, owner=No
                     meta = json.loads(gen.meta)
                     meta["error"] = (e.__class__.__name__ + ": " + str(e))
                     gen.meta = json.dumps(meta)
-
                     commit()
         raise
 

WebHostLib/landing.py

@@ -1,7 +1,11 @@
+from datetime import timedelta, datetime
+
 from flask import render_template
+from pony.orm import count
+
 from WebHostLib import app, cache
-from .models import *
-from datetime import timedelta
+from .models import Room, Seed
+
 
 @app.route('/', methods=['GET', 'POST'])
 @cache.cached(timeout=300)  # cache has to appear under app route for caching to work

WebHostLib/locker.py

@@ -0,0 +1,51 @@
+import os
+import sys
+
+
+class CommonLocker:
+    """Uses a file lock to signal that something is already running"""
+    lock_folder = "file_locks"
+
+    def __init__(self, lockname: str, folder=None):
+        if folder:
+            self.lock_folder = folder
+        os.makedirs(self.lock_folder, exist_ok=True)
+        self.lockname = lockname
+        self.lockfile = os.path.join(self.lock_folder, f"{self.lockname}.lck")
+
+
+class AlreadyRunningException(Exception):
+    pass
+
+
+if sys.platform == 'win32':
+    class Locker(CommonLocker):
+        def __enter__(self):
+            try:
+                if os.path.exists(self.lockfile):
+                    os.unlink(self.lockfile)
+                self.fp = os.open(
+                    self.lockfile, os.O_CREAT | os.O_EXCL | os.O_RDWR)
+            except OSError as e:
+                raise AlreadyRunningException() from e
+
+        def __exit__(self, _type, value, tb):
+            fp = getattr(self, "fp", None)
+            if fp:
+                os.close(self.fp)
+                os.unlink(self.lockfile)
+else:  # unix
+    import fcntl
+
+
+    class Locker(CommonLocker):
+        def __enter__(self):
+            try:
+                self.fp = open(self.lockfile, "wb")
+                fcntl.flock(self.fp.fileno(), fcntl.LOCK_EX | fcntl.LOCK_NB)
+            except OSError as e:
+                raise AlreadyRunningException() from e
+
+        def __exit__(self, _type, value, tb):
+            fcntl.flock(self.fp.fileno(), fcntl.LOCK_UN)
+            self.fp.close()

WebHostLib/lttpsprites.py

@@ -2,7 +2,7 @@ import os
 import threading
 import json
 
-from Utils import local_path
+from Utils import local_path, user_path
 from worlds.alttp.Rom import Sprite
 
 
@@ -14,8 +14,8 @@ def update_sprites_lttp():
     from LttPAdjuster import update_sprites
 
     # Target directories
-    input_dir = local_path("data", "sprites", "alttpr")
-    output_dir = local_path("WebHostLib", "static", "generated")
+    input_dir = user_path("data", "sprites", "alttpr")
+    output_dir = local_path("WebHostLib", "static", "generated")  # TODO: move to user_path
 
     os.makedirs(os.path.join(output_dir, "sprites"), exist_ok=True)
     # update sprites through gui.py's functions
@@ -32,7 +32,7 @@ def update_sprites_lttp():
 
     spriteData = []
 
-    for file in os.listdir(input_dir):
+    for file in (file for file in os.listdir(input_dir) if not file.startswith(".")):
         sprite = Sprite(os.path.join(input_dir, file))
 
         if not sprite.name:

WebHostLib/misc.py

@@ -0,0 +1,176 @@
+import datetime
+import os
+from typing import List, Dict, Union
+
+import jinja2.exceptions
+from flask import request, redirect, url_for, render_template, Response, session, abort, send_from_directory
+from pony.orm import count, commit, db_session
+
+from worlds.AutoWorld import AutoWorldRegister
+from . import app, cache
+from .models import Seed, Room, Command, UUID, uuid4
+
+
+def get_world_theme(game_name: str):
+    if game_name in AutoWorldRegister.world_types:
+        return AutoWorldRegister.world_types[game_name].web.theme
+    return 'grass'
+
+
+@app.before_request
+def register_session():
+    session.permanent = True  # technically 31 days after the last visit
+    if not session.get("_id", None):
+        session["_id"] = uuid4()  # uniquely identify each session without needing a login
+
+
+@app.errorhandler(404)
+@app.errorhandler(jinja2.exceptions.TemplateNotFound)
+def page_not_found(err):
+    return render_template('404.html'), 404
+
+
+# Start Playing Page
+@app.route('/start-playing')
+def start_playing():
+    return render_template(f"startPlaying.html")
+
+
+@app.route('/weighted-settings')
+def weighted_settings():
+    return render_template(f"weighted-settings.html")
+
+
+# Player settings pages
+@app.route('/games/<string:game>/player-settings')
+def player_settings(game):
+    return render_template(f"player-settings.html", game=game, theme=get_world_theme(game))
+
+
+# Game Info Pages
+@app.route('/games/<string:game>/info/<string:lang>')
+def game_info(game, lang):
+    return render_template('gameInfo.html', game=game, lang=lang, theme=get_world_theme(game))
+
+
+# List of supported games
+@app.route('/games')
+def games():
+    worlds = {}
+    for game, world in AutoWorldRegister.world_types.items():
+        if not world.hidden:
+            worlds[game] = world
+    return render_template("supportedGames.html", worlds=worlds)
+
+
+@app.route('/tutorial/<string:game>/<string:file>/<string:lang>')
+def tutorial(game, file, lang):
+    return render_template("tutorial.html", game=game, file=file, lang=lang, theme=get_world_theme(game))
+
+
+@app.route('/tutorial/')
+def tutorial_landing():
+    return render_template("tutorialLanding.html")
+
+
+@app.route('/faq/<string:lang>/')
+def faq(lang):
+    return render_template("faq.html", lang=lang)
+
+
+@app.route('/glossary/<string:lang>/')
+def terms(lang):
+    return render_template("glossary.html", lang=lang)
+
+
+@app.route('/seed/<suuid:seed>')
+def view_seed(seed: UUID):
+    seed = Seed.get(id=seed)
+    if not seed:
+        abort(404)
+    return render_template("viewSeed.html", seed=seed, slot_count=count(seed.slots))
+
+
+@app.route('/new_room/<suuid:seed>')
+def new_room(seed: UUID):
+    seed = Seed.get(id=seed)
+    if not seed:
+        abort(404)
+    room = Room(seed=seed, owner=session["_id"], tracker=uuid4())
+    commit()
+    return redirect(url_for("host_room", room=room.id))
+
+
+def _read_log(path: str):
+    if os.path.exists(path):
+        with open(path, encoding="utf-8-sig") as log:
+            yield from log
+    else:
+        yield f"Logfile {path} does not exist. " \
+              f"Likely a crash during spinup of multiworld instance or it is still spinning up."
+
+
+@app.route('/log/<suuid:room>')
+def display_log(room: UUID):
+    room = Room.get(id=room)
+    if room is None:
+        return abort(404)
+    if room.owner == session["_id"]:
+        file_path = os.path.join("logs", str(room.id) + ".txt")
+        if os.path.exists(file_path):
+            return Response(_read_log(file_path), mimetype="text/plain;charset=UTF-8")
+        return "Log File does not exist."
+
+    return "Access Denied", 403
+
+
+@app.route('/room/<suuid:room>', methods=['GET', 'POST'])
+def host_room(room: UUID):
+    room: Room = Room.get(id=room)
+    if room is None:
+        return abort(404)
+    if request.method == "POST":
+        if room.owner == session["_id"]:
+            cmd = request.form["cmd"]
+            if cmd:
+                Command(room=room, commandtext=cmd)
+                commit()
+
+    now = datetime.datetime.utcnow()
+    # indicate that the page should reload to get the assigned port
+    should_refresh = not room.last_port and now - room.creation_time < datetime.timedelta(seconds=3)
+    with db_session:
+        room.last_activity = now  # will trigger a spinup, if it's not already running
+
+    return render_template("hostRoom.html", room=room, should_refresh=should_refresh)
+
+
+@app.route('/favicon.ico')
+def favicon():
+    return send_from_directory(os.path.join(app.root_path, 'static/static'),
+                               'favicon.ico', mimetype='image/vnd.microsoft.icon')
+
+
+@app.route('/discord')
+def discord():
+    return redirect("https://discord.gg/8Z65BR2")
+
+
+@app.route('/datapackage')
+@cache.cached()
+def get_datapackage():
+    """A pretty print version of /api/datapackage"""
+    from worlds import network_data_package
+    import json
+    return Response(json.dumps(network_data_package, indent=4), mimetype="text/plain")
+
+
+@app.route('/index')
+@app.route('/sitemap')
+def get_sitemap():
+    available_games: List[Dict[str, Union[str, bool]]] = []
+    for game, world in AutoWorldRegister.world_types.items():
+        if not world.hidden:
+            has_settings: bool = isinstance(world.web.settings_page, bool) and world.web.settings_page
+            available_games.append({ 'title': game, 'has_settings': has_settings })
+    return render_template("siteMap.html", games=available_games)

WebHostLib/models.py

@@ -1,6 +1,6 @@
 from datetime import datetime
 from uuid import UUID, uuid4
-from pony.orm import *
+from pony.orm import Database, PrimaryKey, Required, Set, Optional, buffer, LongStr
 
 db = Database()
 
@@ -12,7 +12,7 @@ STATE_ERROR = -1
 class Slot(db.Entity):
     id = PrimaryKey(int, auto=True)
     player_id = Required(int)
-    player_name = Required(str, 16)
+    player_name = Required(str)
     data = Optional(bytes, lazy=True)
     seed = Optional('Seed')
     game = Required(str)
@@ -21,14 +21,15 @@ class Slot(db.Entity):
 class Room(db.Entity):
     id = PrimaryKey(UUID, default=uuid4)
     last_activity = Required(datetime, default=lambda: datetime.utcnow(), index=True)
-    creation_time = Required(datetime, default=lambda: datetime.utcnow())
+    creation_time = Required(datetime, default=lambda: datetime.utcnow(), index=True)  # index used by landing page
     owner = Required(UUID, index=True)
     commands = Set('Command')
     seed = Required('Seed', index=True)
     multisave = Optional(buffer, lazy=True)
     show_spoiler = Required(int, default=0)  # 0 -> never, 1 -> after completion, -> 2 always
-    timeout = Required(int, default=lambda: 6 * 60 * 60)  # seconds since last activity to shutdown
+    timeout = Required(int, default=lambda: 2 * 60 * 60)  # seconds since last activity to shutdown
     tracker = Optional(UUID, index=True)
+    # Port special value -1 means the server errored out. Another attempt can be made with a page refresh
     last_port = Optional(int, default=lambda: 0)
 
 
@@ -37,7 +38,7 @@ class Seed(db.Entity):
     rooms = Set(Room)
     multidata = Required(bytes, lazy=True)
     owner = Required(UUID, index=True)
-    creation_time = Required(datetime, default=lambda: datetime.utcnow())
+    creation_time = Required(datetime, default=lambda: datetime.utcnow(), index=True)  # index used by landing page
     slots = Set(Slot)
     spoiler = Optional(LongStr, lazy=True)
     meta = Required(LongStr, default=lambda: "{\"race\": false}")  # additional meta information/tags
@@ -55,3 +56,8 @@ class Generation(db.Entity):
     options = Required(buffer, lazy=True)
     meta = Required(LongStr, default=lambda: "{\"race\": false}")
     state = Required(int, default=0, index=True)
+
+
+class GameDataPackage(db.Entity):
+    checksum = PrimaryKey(str)
+    data = Required(bytes)

WebHostLib/options.py

@@ -1,89 +1,148 @@
-import os
-from Utils import __version__
-from jinja2 import Template
-import yaml
 import json
+import logging
+import os
+import typing
+
+import yaml
+from jinja2 import Template
 
-from worlds.AutoWorld import AutoWorldRegister
 import Options
+from Utils import __version__, local_path
+from worlds.AutoWorld import AutoWorldRegister
 
-target_folder = os.path.join("WebHostLib", "static", "generated")
+handled_in_js = {"start_inventory", "local_items", "non_local_items", "start_hints", "start_location_hints",
+                 "exclude_locations", "priority_locations"}
 
 
 def create():
-    def dictify_range(option):
-        data = {option.range_start: 0, option.range_end: 0, "random": 0, "random-low": 0, "random-high": 0,
-                option.default: 50}
-        notes = {
-            option.range_start: "minimum value",
-            option.range_end: "maximum value"
-        }
-        return data, notes
+    target_folder = local_path("WebHostLib", "static", "generated")
+    yaml_folder = os.path.join(target_folder, "configs")
 
-    def default_converter(default_value):
-        if isinstance(default_value, (set, frozenset)):
-            return list(default_value)
-        return default_value
+    Options.generate_yaml_templates(yaml_folder)
+
+    def get_html_doc(option_type: type(Options.Option)) -> str:
+        if not option_type.__doc__:
+            return "Please document me!"
+        return "\n".join(line.strip() for line in option_type.__doc__.split("\n")).strip()
+
+    weighted_settings = {
+        "baseOptions": {
+            "description": "Generated by https://archipelago.gg/",
+            "name": "Player",
+            "game": {},
+        },
+        "games": {},
+    }
 
     for game_name, world in AutoWorldRegister.world_types.items():
-        res = Template(open(os.path.join("WebHostLib", "templates", "options.yaml")).read()).render(
-            options={**world.options, **Options.per_game_common_options},
-            __version__=__version__, game=game_name, yaml_dump=yaml.dump,
-            dictify_range=dictify_range, default_converter=default_converter,
-        )
 
-        os.makedirs(os.path.join(target_folder, 'configs'), exist_ok=True)
-
-        with open(os.path.join(target_folder, 'configs', game_name + ".yaml"), "w") as f:
-            f.write(res)
+        all_options: typing.Dict[str, Options.AssembleOptions] = {
+            **Options.per_game_common_options,
+            **world.option_definitions
+        }
 
         # Generate JSON files for player-settings pages
         player_settings = {
             "baseOptions": {
-                "description": "Generated by https://archipelago.gg/",
+                "description": f"Generated by https://archipelago.gg/ for {game_name}",
                 "game": game_name,
                 "name": "Player",
             },
         }
 
         game_options = {}
-        for option_name, option in world.options.items():
-            if option.options:
+        for option_name, option in all_options.items():
+            if option_name in handled_in_js:
+                pass
+
+            elif issubclass(option, Options.Choice) or issubclass(option, Options.Toggle):
                 game_options[option_name] = this_option = {
                     "type": "select",
-                    "displayName": option.displayname if hasattr(option, "displayname") else option_name,
-                    "description": option.__doc__ if option.__doc__ else "Please document me!",
+                    "displayName": option.display_name if hasattr(option, "display_name") else option_name,
+                    "description": get_html_doc(option),
                     "defaultValue": None,
                     "options": []
                 }
 
                 for sub_option_id, sub_option_name in option.name_lookup.items():
-                    this_option["options"].append({
-                        "name": option.get_option_name(sub_option_id),
-                        "value": sub_option_name,
-                    })
-
+                    if sub_option_name != "random":
+                        this_option["options"].append({
+                            "name": option.get_option_name(sub_option_id),
+                            "value": sub_option_name,
+                        })
                     if sub_option_id == option.default:
                         this_option["defaultValue"] = sub_option_name
 
-                this_option["options"].append({
-                    "name": "Random",
-                    "value": "random",
-                })
+                if not this_option["defaultValue"]:
+                    this_option["defaultValue"] = "random"
 
-            elif hasattr(option, "range_start") and hasattr(option, "range_end"):
+            elif issubclass(option, Options.Range):
                 game_options[option_name] = {
                     "type": "range",
-                    "displayName": option.displayname if hasattr(option, "displayname") else option_name,
-                    "description": option.__doc__ if option.__doc__ else "Please document me!",
-                    "defaultValue": option.default if hasattr(option, "default") else option.range_start,
+                    "displayName": option.display_name if hasattr(option, "display_name") else option_name,
+                    "description": get_html_doc(option),
+                    "defaultValue": option.default if hasattr(
+                        option, "default") and option.default != "random" else option.range_start,
                     "min": option.range_start,
                     "max": option.range_end,
                 }
 
+                if issubclass(option, Options.SpecialRange):
+                    game_options[option_name]["type"] = 'special_range'
+                    game_options[option_name]["value_names"] = {}
+                    for key, val in option.special_range_names.items():
+                        game_options[option_name]["value_names"][key] = val
+
+            elif issubclass(option, Options.ItemSet):
+                game_options[option_name] = {
+                    "type": "items-list",
+                    "displayName": option.display_name if hasattr(option, "display_name") else option_name,
+                    "description": get_html_doc(option),
+                    "defaultValue": list(option.default)
+                }
+
+            elif issubclass(option, Options.LocationSet):
+                game_options[option_name] = {
+                    "type": "locations-list",
+                    "displayName": option.display_name if hasattr(option, "display_name") else option_name,
+                    "description": get_html_doc(option),
+                    "defaultValue": list(option.default)
+                }
+
+            elif issubclass(option, Options.VerifyKeys) and not issubclass(option, Options.OptionDict):
+                if option.valid_keys:
+                    game_options[option_name] = {
+                        "type": "custom-list",
+                        "displayName": option.display_name if hasattr(option, "display_name") else option_name,
+                        "description": get_html_doc(option),
+                        "options": list(option.valid_keys),
+                        "defaultValue": list(option.default) if hasattr(option, "default") else []
+                    }
+
+            else:
+                logging.debug(f"{option} not exported to Web Settings.")
+
         player_settings["gameOptions"] = game_options
 
         os.makedirs(os.path.join(target_folder, 'player-settings'), exist_ok=True)
 
         with open(os.path.join(target_folder, 'player-settings', game_name + ".json"), "w") as f:
-            f.write(json.dumps(player_settings, indent=2, separators=(',', ': ')))
+            json.dump(player_settings, f, indent=2, separators=(',', ': '))
+
+        if not world.hidden and world.web.settings_page is True:
+            # Add the random option to Choice, TextChoice, and Toggle settings
+            for option in game_options.values():
+                if option["type"] == "select":
+                    option["options"].append({"name": "Random", "value": "random"})
+
+                    if not option["defaultValue"]:
+                        option["defaultValue"] = "random"
+
+            weighted_settings["baseOptions"]["game"][game_name] = 0
+            weighted_settings["games"][game_name] = {}
+            weighted_settings["games"][game_name]["gameSettings"] = game_options
+            weighted_settings["games"][game_name]["gameItems"] = tuple(world.item_names)
+            weighted_settings["games"][game_name]["gameLocations"] = tuple(world.location_names)
+
+    with open(os.path.join(target_folder, 'weighted-settings.json'), "w") as f:
+        json.dump(weighted_settings, f, indent=2, separators=(',', ': '))

WebHostLib/requirements.txt

@@ -1,6 +1,10 @@
-flask>=2.0.2
-pony>=0.7.14
-waitress>=2.0.0
-flask-caching>=1.10.1
-Flask-Compress>=1.10.1
-Flask-Limiter>=1.4
+flask>=2.2.3
+pony>=0.7.16; python_version <= '3.10'
+pony @ https://github.com/Berserker66/pony/releases/download/v0.7.16/pony-0.7.16-py3-none-any.whl#0.7.16 ; python_version >= '3.11'
+waitress>=2.1.2
+Flask-Caching>=2.0.2
+Flask-Compress>=1.14
+Flask-Limiter>=3.5.0
+bokeh>=3.1.1; python_version <= '3.8'
+bokeh>=3.2.2; python_version >= '3.9'
+markupsafe>=2.1.3

WebHostLib/static/assets/autodatatable.js

@@ -4,6 +4,7 @@ window.addEventListener('load', () => {
         "ordering": true,
         "info": false,
         "dom": "t",
+        "stateSave": true,
     });
   console.log(tables);
 });

WebHostLib/static/assets/baseHeader.js

@@ -0,0 +1,40 @@
+window.addEventListener('load', () => {
+  // Mobile menu handling
+  const menuButton = document.getElementById('base-header-mobile-menu-button');
+  const mobileMenu = document.getElementById('base-header-mobile-menu');
+
+  menuButton.addEventListener('click', (evt) => {
+    evt.preventDefault();
+    evt.stopPropagation();
+
+    if (!mobileMenu.style.display || mobileMenu.style.display === 'none') {
+      return mobileMenu.style.display = 'flex';
+    }
+
+    mobileMenu.style.display = 'none';
+  });
+
+  window.addEventListener('resize', () => {
+    mobileMenu.style.display = 'none';
+  });
+
+  // Popover handling
+  const popoverText = document.getElementById('base-header-popover-text');
+  const popoverMenu = document.getElementById('base-header-popover-menu');
+
+  popoverText.addEventListener('click', (evt) => {
+    evt.preventDefault();
+    evt.stopPropagation();
+
+    if (!popoverMenu.style.display || popoverMenu.style.display === 'none') {
+      return popoverMenu.style.display = 'flex';
+    }
+
+    popoverMenu.style.display = 'none';
+  });
+
+  document.body.addEventListener('click', () => {
+    mobileMenu.style.display = 'none';
+    popoverMenu.style.display = 'none';
+  });
+});

WebHostLib/static/assets/checksfinderTracker.js

@@ -0,0 +1,49 @@
+window.addEventListener('load', () => {
+  // Reload tracker every 60 seconds
+  const url = window.location;
+  setInterval(() => {
+    const ajax = new XMLHttpRequest();
+    ajax.onreadystatechange = () => {
+      if (ajax.readyState !== 4) { return; }
+
+      // Create a fake DOM using the returned HTML
+      const domParser = new DOMParser();
+      const fakeDOM = domParser.parseFromString(ajax.responseText, 'text/html');
+
+      // Update item tracker
+      document.getElementById('inventory-table').innerHTML = fakeDOM.getElementById('inventory-table').innerHTML;
+      // Update only counters in the location-table
+      let counters = document.getElementsByClassName('counter');
+      const fakeCounters = fakeDOM.getElementsByClassName('counter');
+      for (let i = 0; i < counters.length; i++) {
+        counters[i].innerHTML = fakeCounters[i].innerHTML;
+      }
+    };
+    ajax.open('GET', url);
+    ajax.send();
+}, 60000)
+
+  // Collapsible advancement sections
+  const categories = document.getElementsByClassName("location-category");
+  for (let i = 0; i < categories.length; i++) {
+    let hide_id = categories[i].id.split('-')[0];
+    if (hide_id == 'Total') {
+      continue;
+    }
+    categories[i].addEventListener('click', function() {
+      // Toggle the advancement list
+      document.getElementById(hide_id).classList.toggle("hide");
+      // Change text of the header
+      const tab_header = document.getElementById(hide_id+'-header').children[0];
+      const orig_text = tab_header.innerHTML;
+      let new_text;
+      if (orig_text.includes("▼")) {
+        new_text = orig_text.replace("▼", "▲");
+      }
+      else {
+        new_text = orig_text.replace("▲", "▼");
+      }
+      tab_header.innerHTML = new_text;
+    });
+  }
+});

WebHostLib/static/assets/faq.js

@@ -26,24 +26,22 @@ window.addEventListener('load', () => {
         adjustHeaderWidth();
 
         // Reset the id of all header divs to something nicer
-        const headers = Array.from(document.querySelectorAll('h1, h2, h3, h4, h5, h6'));
-        const scrollTargetIndex = window.location.href.search(/#[A-z0-9-_]*$/);
-        for (let i=0; i < headers.length; i++){
-            const headerId = headers[i].innerText.replace(/[ ]/g,'-').toLowerCase()
-            headers[i].setAttribute('id', headerId);
-            headers[i].addEventListener('click', () =>
-                window.location.href = window.location.href.substring(0, scrollTargetIndex) + `#${headerId}`);
+        for (const header of document.querySelectorAll('h1, h2, h3, h4, h5, h6')) {
+            const headerId = header.innerText.replace(/\s+/g, '-').toLowerCase();
+            header.setAttribute('id', headerId);
+            header.addEventListener('click', () => {
+                window.location.hash = `#${headerId}`;
+                header.scrollIntoView();
+            });
         }
 
         // Manually scroll the user to the appropriate header if anchor navigation is used
-        if (scrollTargetIndex > -1) {
-            try{
-                const scrollTarget = window.location.href.substring(scrollTargetIndex + 1);
-                document.getElementById(scrollTarget).scrollIntoView({ behavior: "smooth" });
-            } catch(error) {
-                console.error(error);
+        document.fonts.ready.finally(() => {
+            if (window.location.hash) {
+                const scrollTarget = document.getElementById(window.location.hash.substring(1));
+                scrollTarget?.scrollIntoView();
             }
-        }
+        });
     }).catch((error) => {
         console.error(error);
         tutorialWrapper.innerHTML =

WebHostLib/static/assets/faq/faq_en.md

@@ -1,52 +1,69 @@
 # Frequently Asked Questions
 
 ## What is a randomizer?
-A randomizer is a modification of a video game which reorganizes the items required to progress through the game.
-A normal play-through of a game might require you to use item A to unlock item B, then C, and so forth. In a
-randomized game, you might first find item C, then A, then B.
+
+A randomizer is a modification of a video game which reorganizes the items required to progress through the game. A
+normal play-through of a game might require you to use item A to unlock item B, then C, and so forth. In a randomized
+game, you might first find item C, then A, then B.
 
 This transforms games from a linear experience into a puzzle, presenting players with a new challenge each time they
-play a randomized game. Putting items in non-standard locations can require the player to think about the game world
-and the items they encounter in new and interesting ways.
+play a randomized game. Putting items in non-standard locations can require the player to think about the game world and
+the items they encounter in new and interesting ways.
 
 ## What happens if an item is placed somewhere it is impossible to get?
-The randomizer has many strict sets of rules it must follow when generating a game. One of the functions of these
-rules is to ensure items necessary to complete the game will be accessible to the player. Many games also have a
-subset of rules allowing certain items to be placed in normally unreachable locations, provided the player has
-indicated they are comfortable exploiting certain glitches in the game.
+
+The randomizer has many strict sets of rules it must follow when generating a game. One of the functions of these rules
+is to ensure items necessary to complete the game will be accessible to the player. Many games also have a subset of
+rules allowing certain items to be placed in normally unreachable locations, provided the player has indicated they are
+comfortable exploiting certain glitches in the game.
 
 ## What is a multi-world?
-While a randomizer shuffles a game, a multi-world randomizer shuffles that game for multiple players. For example,
-in a two player multi-world, players A and B each get their own randomized version of a game, called seeds. In each
-player's game, they may find items which belong to the other player. If player A finds an item which belongs to
-player B, the item will be sent to player B's world over the internet.
+
+While a randomizer shuffles a game, a multi-world randomizer shuffles that game for multiple players. For example, in a
+two player multi-world, players A and B each get their own randomized version of a game, called a world. In each player's
+game, they may find items which belong to the other player. If player A finds an item which belongs to player B, the
+item will be sent to player B's world over the internet.
 
 This creates a cooperative experience during multi-world games, requiring players to rely upon each other to complete
 their game.
 
 ## What happens if a person has to leave early?
-If a player must leave early, they can use Archipelago's forfeit system. When a player forfeits their game, all
-the items in that game which belong to other players are sent out automatically, so other players can continue to
-play.
+
+If a player must leave early, they can use Archipelago's release system. When a player releases their game, all the
+items in that game which belong to other players are sent out automatically, so other players can continue to play.
 
 ## What does multi-game mean?
-While a multi-world game traditionally requires all players to be playing the same game, a multi-game multi-world
-allows players to randomize any of a number of supported games, and send items between them. This allows players of
-different games to interact with one another in a single multiplayer environment.
+
+While a multi-world game traditionally requires all players to be playing the same game, a multi-game multi-world allows
+players to randomize any of a number of supported games, and send items between them. This allows players of different
+games to interact with one another in a single multiplayer environment.
 
 ## Can I generate a single-player game with Archipelago?
+
 Yes. All our supported games can be generated as single-player experiences, and so long as you download the software,
 the website is not required to generate them.
 
 ## How do I get started?
-If you are ready to start randomizing games, or want to start playing your favorite randomizer with others,
-please join our [Discord server](https://discord.gg/8Z65BR2). There are always people ready to answer any questions
-you might have.
+
+If you are ready to start randomizing games, or want to start playing your favorite randomizer with others, please join
+our discord server at the [Archipelago Discord](https://discord.gg/8Z65BR2). There are always people ready to answer
+any questions you might have.
+
+## What are some common terms I should know?
+
+As randomizers and multiworld randomizers have been around for a while now there are quite a lot of common terms
+and jargon that is used in conjunction by the communities surrounding them. For a lot of the terms that are more common
+to Archipelago and its specific systems please see the [Glossary](/glossary/en).
 
 ## I want to add a game to the Archipelago randomizer. How do I do that?
-The best way to get started is to take a look at our [code on GitHub](https://github.com/ArchipelagoMW/Archipelago).
-There, you will find examples of games in the [worlds](https://github.com/ArchipelagoMW/Archipelago/tree/main/worlds)
-folder, as well as some [documentation](https://github.com/ArchipelagoMW/Archipelago/tree/main/docs) on our
-network interfaces.
+
+The best way to get started is to take a look at our code on GitHub
+at [Archipelago GitHub Page](https://github.com/ArchipelagoMW/Archipelago).
+
+There you will find examples of games in the worlds folder
+at [/worlds Folder in Archipelago Code](https://github.com/ArchipelagoMW/Archipelago/tree/main/worlds).
+
+You may also find developer documentation in the docs folder
+at [/docs Folder in Archipelago Code](https://github.com/ArchipelagoMW/Archipelago/tree/main/docs).
 
 If you have more questions, feel free to ask in the **#archipelago-dev** channel on our Discord.

WebHostLib/static/assets/faq/glossary_en.md

@@ -0,0 +1,94 @@
+# Multiworld Glossary
+
+There are a lot of common terms used when playing in different game randomizer communities and in multiworld as well.
+This document serves as a lookup for common terms that may be used by users in the community or in various other
+documentation.
+
+## Item
+Items are what get shuffled around in your world or other worlds that you then receive. This could be a sword, a stat 
+upgrade, a spell, or any other potential receivable for your game.
+
+## Location
+Locations are where items are placed in your game. Whenever you interact with a location, you or another player will
+then receive an item. A location could be a chest, an enemy drop, a shop purchase, or any other interactable that can
+contain items in your game.
+
+## Check
+A check is a common term for when you "check", or pick up, a location. In terms of Archipelago this is usually used for
+when a player goes to a location and sends its item, or "checks" the location. Players will often reference their now
+randomized locations as checks.
+
+## Slot
+A slot is the player name and number assigned during generation. The number of slots is equal to the number of players,
+or "worlds", created. Each name must be unique as these are used to identify the slot user.
+
+## World
+World in terms of Archipelago can mean multiple things and is used interchangeably in many situations.
+* During gameplay, a world is a single instance of a game, occupying one player "slot". However, 
+Archipelago allows multiple players to connect to the same slot; then those players can share a world 
+and complete it cooperatively. For games with native cooperative play, you can also play together and
+share a world that way, usually with only one player connected to the multiworld.
+* On the programming side, a world typically represents the package that integrates Archipelago with a
+particular game. For example this could be the entire `worlds/factorio` directory.
+
+## RNG
+Acronym for "Random Number Generator." Archipelago uses its own custom Random object with a unique seed per generation,
+or, if running from source, a seed can be supplied and this seed will control all randomization during generation as all
+game worlds will have access to it.
+
+## Seed
+A "seed" is a number used to initialize a pseudorandom number generator. Whenever you generate a new game on Archipelago
+this is a new "seed" as it has unique item placement, and you can create multiple "rooms" on the Archipelago site from a
+single seed. Using the same seed results in the random placement being the same.
+
+## Room
+Whenever you generate a seed on the Archipelago website you will be put on a seed page that contains all the seed info
+with a link to the spoiler if one exists and will show how many unique rooms exist per seed. Each room has its own 
+unique identifier that is separate from the seed. The room page is where you can find information to connect to the
+multiworld and download any patches if necessary. If you have a particularly fun or interesting seed, and you want to 
+share it with somebody you can link them to this seed page, where they can generate a new room to play it! For seeds 
+generated with race mode enabled, the seed page will only show rooms created by the unique user so the seed page is 
+perfectly safe to share for racing purposes.
+
+## Logic
+Base behavior of all seeds generated by Archipelago is they are expected to be completable based on the requirements of
+the settings. This is done by using "logic" in order to determine valid locations to place items while still being able
+to reach said location without this item. For the purposes of the randomizer a location is considered "in logic" if you 
+can reach it with your current toolset of items or skills based on settings. Some players are able to obtain locations
+"out of logic" by performing various glitches or tricks that the settings may not account for and tend to mention this
+when sending out an item they obtained this way.
+
+## Progression
+Certain items will allow access to more locations and are considered progression items as they "progress" the seed.
+
+## Trash
+A term used for "filler" items that have no bearing on the generation and are either marginally useful for the player
+or useless. These items can be very useful depending on the player but are never very important and as such are usually
+termed trash.
+
+## Burger King / BK Mode
+A term used in multiworlds when a player is unable to continue to progress and is awaiting an item. The term came to be 
+after a player, allegedly, was unable to progress during a multiworld and went to Burger King while waiting to receive
+items from other players.
+
+* "Logical BK" is when the player is unable to progress according to the settings of their game but may still be able to do
+things that would be "out of logic" by the generation.
+
+* "Hard / full BK" is when the player is completely unable to progress even with tricks they may know and are unable to
+continue to play, aside from doing something like killing enemies for experience or money.
+
+## Sphere
+Archipelago calculates the game playthrough by using a "sphere" system where it has a state for each player and checks
+to see what the players are able to reach with their current items. Any location that is reachable with the current
+state of items is a "sphere." For the purposes of Archipelago it starts playthrough calculation by distributing sphere 0
+items which are items that are either forced in the player's inventory by the game or placed in the `start_inventory` in
+their settings. Sphere 1 is then all accessible locations the players can reach with all the items they received from
+sphere 0, or their starting inventory. The playthrough continues in this fashion calculating a number of spheres until
+all players have completed their goal.
+
+## Scouts / Scouting
+In some games there are locations that have visible items even if the item itself is unobtainable at the current time.
+Some games utilize a scouting feature where when the player "sees" the item it will give a free hint for the item in the
+client letting the players know what the exact item is, since if the item was for that game it would know but the item
+being foreign is a lot harder to represent visually.
+

WebHostLib/static/assets/gameInfo.js

@@ -14,7 +14,7 @@ window.addEventListener('load', () => {
             }
             resolve(ajax.responseText);
         };
-        ajax.open('GET', `${window.location.origin}/static/assets/gameInfo/` +
+        ajax.open('GET', `${window.location.origin}/static/generated/docs/${gameInfo.getAttribute('data-game')}/` +
           `${gameInfo.getAttribute('data-lang')}_${gameInfo.getAttribute('data-game')}.md`, true);
         ajax.send();
     }).then((results) => {
@@ -26,24 +26,22 @@ window.addEventListener('load', () => {
         adjustHeaderWidth();
 
         // Reset the id of all header divs to something nicer
-        const headers = Array.from(document.querySelectorAll('h1, h2, h3, h4, h5, h6'));
-        const scrollTargetIndex = window.location.href.search(/#[A-z0-9-_]*$/);
-        for (let i=0; i < headers.length; i++){
-            const headerId = headers[i].innerText.replace(/[ ]/g,'-').toLowerCase()
-            headers[i].setAttribute('id', headerId);
-            headers[i].addEventListener('click', () =>
-                window.location.href = window.location.href.substring(0, scrollTargetIndex) + `#${headerId}`);
+        for (const header of document.querySelectorAll('h1, h2, h3, h4, h5, h6')) {
+            const headerId = header.innerText.replace(/\s+/g, '-').toLowerCase();
+            header.setAttribute('id', headerId);
+            header.addEventListener('click', () => {
+                window.location.hash = `#${headerId}`;
+                header.scrollIntoView();
+            });
         }
 
         // Manually scroll the user to the appropriate header if anchor navigation is used
-        if (scrollTargetIndex > -1) {
-            try{
-                const scrollTarget = window.location.href.substring(scrollTargetIndex + 1);
-                document.getElementById(scrollTarget).scrollIntoView({ behavior: "smooth" });
-            } catch(error) {
-                console.error(error);
+        document.fonts.ready.finally(() => {
+            if (window.location.hash) {
+                const scrollTarget = document.getElementById(window.location.hash.substring(1));
+                scrollTarget?.scrollIntoView();
             }
-        }
+        });
     }).catch((error) => {
         console.error(error);
         gameInfo.innerHTML =

WebHostLib/static/assets/gameInfo/en_Factorio.md

@@ -1,29 +0,0 @@
-# Factorio
-
-## Where is the settings page?
-The player settings page for this game is located <a href="../player-settings">here</a>. It contains all the options
-you need to configure and export a config file.
-
-## What does randomization do to this game?
-In Factorio, the research tree is shuffled, causing certain technologies to be obtained in a non-standard order.
-Recipe costs, technology requirements, and science pack requirements may also be shuffled at the player's discretion.
-
-## What Factorio items can appear in other players' worlds?
-Factorio's technologies are removed from its tech tree and placed into other players' worlds. When those technologies
-are found, they are sent back to Factorio along with, optionally, free samples of those technologies.
-
-## What is a free sample?
-A free sample is a single or stack of items in Factorio, granted by a technology received from another world. For
-example, receiving the technology  
-`Portable Solar Panel` may also grant the player a stack of portable solar panels,
-and place them directly into the player's inventory.
-
-## What does another world's item look like in Factorio?
-In Factorio, items which need to be sent to other worlds appear in the tech tree as new research items. They are
-represented by the Archipelago icon, and must be researched as if it were a normal technology. Upon successful
-completion of research, the item will be sent to its home world.
-
-## When the engineer receives an item, what happens?
-When the player receives a technology, it is instantly learned and able to be crafted. A message will appear in the
-chat log to notify the player, and if free samples are enabled the player may also receive some items directly to
-their inventory.

WebHostLib/static/assets/gameInfo/en_Final Fantasy.md

@@ -1,21 +0,0 @@
-# Final Fantasy 1 (NES)
-
-## Where is the settings page?
-Unlike most games on Archipelago.gg, Final Fantasy 1's settings are controlled entirely by the original randomzier.
-You can find an exhaustive list of documented settings [here](https://finalfantasyrandomizer.com/)
-
-## What does randomization do to this game?
-A better questions is what isn't randomized at this point. Enemies stats and spell, character spells, shop inventory
-and boss stats and spells are all commonly randomized. Unlike most other randomizers it is also most standard to shuffle
-progression items and non-progression items into separate pools and then redistribute them to their respective 
-locations. So ,for example, Princess Sarah may have the CANOE instead of the LUTE; however, she will never have a Heal 
-Pot or some armor. There are plenty of other things that can be randomized on our 
-[main randomizer site](https://finalfantasyrandomizer.com/)
-
-## What Final Fantasy items can appear in other players' worlds?
-All items can appear in other players worlds. This includes consumables, shards, weapons, armor and, of course,
-key items.
-
-## What does another world's item look like in Final Fantasy
-All local and remote items appear the same. It will say that you received an item and then BOTH the client log and
-the emulator will display what was found external to the in-game text box.

WebHostLib/static/assets/gameInfo/en_Minecraft.md

@@ -1,22 +0,0 @@
-# Minecraft
-
-## Where is the settings page?
-The player settings page for this game is located <a href="../player-settings">here</a>. It contains all the options
-you need to configure and export a config file.
-
-## What does randomization do to this game?
-Recipes are removed from the crafting book and shuffled into the item pool. It can also optionally change which
-structures appear in each dimension. Crafting recipes are re-learned when they are received from other players as
-item checks, and occasionally when completing your own achievements.
-
-## What is considered a location check in minecraft?
-Location checks in are completed when the player completes various Minecraft achievements. Opening the advancements
-menu in-game by pressing "L" will display outstanding achievements.
-
-## When the player receives an item, what happens?
-When the player receives an item in Minecraft, it either unlocks crafting recipes or puts items into the player's
-inventory directly.
-
-## What is the victory condition?
-Victory is achieved when the player kills the Ender Dragon, enters the portal in The End, and completes the credits
-sequence either by skipping it or watching hit play out.

WebHostLib/static/assets/gameInfo/en_Risk of Rain 2.md

@@ -1,36 +0,0 @@
-# Risk of Rain 2
-
-## Where is the settings page?
-The player settings page for this game is located <a href="../player-settings">here</a>. It contains all the options
-you need to configure and export a config file.
-
-## What does randomization do to this game?
-Risk of Rain is already a random game, by virtue of being a roguelite. The Archipelago mod implements pure multiworld
-functionality in which certain chests (made clear via a location check progress bar) will send an item out to the
-multiworld. The items that _would have been_ in those chests will be returned to the Risk of Rain player via grants
-by other players in other worlds.
-
-## What Risk of Rain items can appear in other players' worlds?
-The Risk of Rain items are:
-* `Common Item`    (White items)
-* `Uncommon Item`  (Green items)
-* `Boss Item`      (Yellow items)
-* `Legendary Item` (Red items)
-* `Lunar Item`     (Blue items)
-* `Equipment`      (Orange items)
-* `Dio's Best Friend` (Used if you set the YAML setting `total_revives_available` above `0`)
-
-Each item grants you a random in-game item from the category it belongs to.
-
-When an item is granted by another world to the Risk of Rain player (one of the items listed above) then a random
-in-game item of that tier will appear in the Risk of Rain player's inventory. If the item grant is an `Equipment`
-and the player already has an equipment item equipped then the _item that was equipped_ will be dropped on the ground
-and _the new equipment_ will take it's place. (If you want the old one back, pick it up.)
-
-## What does another world's item look like in Risk of Rain?
-When the Risk of Rain player fills up their location check bar then the next spawned item will become an item grant for another
-player's world. The item in Risk of Rain will disappear in a poof of smoke and the grant will automatically go out to the multiworld.
-
-## What is the item pickup step?
-The item pickup step is a YAML setting which allows you to set how many items you need to spawn before the _next_
-item that is spawned disappears (in a poof of smoke) and goes out to the multiworld.

WebHostLib/static/assets/gameInfo/en_Subnautica.md

@@ -1,27 +0,0 @@
-# Subnautica
-
-## Where is the settings page?
-The player settings page for this game is located <a href="../player-settings">here</a>. It contains all the options
-you need to configure and export a config file.
-
-## What does randomization do to this game?
-The most noticeable change is the complete removal of freestanding technologies. The technology blueprints normally
-awarded from scanning those items have been shuffled into location checks throughout the AP item pool.
-
-## What is the goal of Subnautica when randomized?
-The goal remains unchanged. Cure the plague, build the Neptune Escape Rocket, and escape into space.
-
-## What items and locations get shuffled?
-Most of the technologies the player will need throughout the game will be shuffled. Location checks in Subnautica are
-data pads and technology lockers.
-
-## Which items can be in another player's world?
-Most technologies may be shuffled into another player's world.
-
-## What does another world's item look like in Subnautica?
-Location checks in Subnautica are data pads and technology lockers. Opening one of these will send an item to
-another player's world.
-
-## When the player receives a technology, what happens?
-When the player receives a technology, the chat log displays a notification the technology has been received.
-

WebHostLib/static/assets/gameInfo/en_Super Metroid.md

@@ -1,25 +0,0 @@
-# Super Metroid
-
-## Where is the settings page?
-The player settings page for this game is located <a href="../player-settings">here</a>. It contains all the options
-you need to configure and export a config file.
-
-## What does randomization do to this game?
-Items which the player would normally acquire throughout the game have been moved around. Logic remains, so the game
-is always able to be completed, but because of the item shuffle the player may need to access certain areas before
-they would in the vanilla game.
-
-## What items and locations get shuffled?
-All power-ups and ammunition can be shuffled, and all locations in the game which could contain any of those items
-may have their contents changed.
-
-## Which items can be in another player's world?
-Any of the items which can be shuffled may also be placed into another player's world. It is possible to choose to
-limit certain items to your own world.
-
-## What does another world's item look like in Super Metroid?
-A unique item sprite has been added to the game to represent items belonging to another world.
-
-## When the player receives an item, what happens?
-When the player receives an item, a text box will appear to show which item was received, and from whom.
-

WebHostLib/static/assets/gameInfo/en_Timespinner.md

@@ -1,28 +0,0 @@
-# Timespinner
-
-## Where is the settings page?
-The player settings page for this game is located <a href="../player-settings">here</a>. It contains all the options
-you need to configure and export a config file.
-
-## What does randomization do to this game?
-Items which the player would normally acquire throughout the game have been moved around. Logic remains, so the game
-is always able to be completed, but because of the item shuffle the player may need to access certain areas before
-they would in the vanilla game. All rings and spells are also randomized into those item locations, therefor you can no longer craft them at the alchemist
-
-## What is the goal of Timespinner when randomized?
-The goal remains unchanged. Kill the Sandman\Nightmare!
-
-## What items and locations get shuffled?
-All main inventory items, orbs, collectables, and familiers can be shuffled, and all locations in the game which could
-contain any of those items may have their contents changed.
-
-## Which items can be in another player's world?
-Any of the items which can be shuffled may also be placed into another player's world. It is possible to choose to
-limit certain items to your own world.
-
-## What does another world's item look like in Timespinner?
-Items belonging to other worlds are represented by the vanilla item [Elemental Beads](https://timespinnerwiki.com/Use_Items), Elemental Beads have no use in the randomizer
-
-## When the player receives an item, what happens?
-When the player receives an item, the same items popup will be displayed as when you would normally obtain the item
-

WebHostLib/static/assets/glossary.js

@@ -0,0 +1,51 @@
+window.addEventListener('load', () => {
+    const tutorialWrapper = document.getElementById('glossary-wrapper');
+    new Promise((resolve, reject) => {
+        const ajax = new XMLHttpRequest();
+        ajax.onreadystatechange = () => {
+            if (ajax.readyState !== 4) { return; }
+            if (ajax.status === 404) {
+                reject("Sorry, the glossary page is not available in that language yet.");
+                return;
+            }
+            if (ajax.status !== 200) {
+                reject("Something went wrong while loading the glossary.");
+                return;
+            }
+            resolve(ajax.responseText);
+        };
+        ajax.open('GET', `${window.location.origin}/static/assets/faq/` +
+          `glossary_${tutorialWrapper.getAttribute('data-lang')}.md`, true);
+        ajax.send();
+    }).then((results) => {
+        // Populate page with HTML generated from markdown
+        showdown.setOption('tables', true);
+        showdown.setOption('strikethrough', true);
+        showdown.setOption('literalMidWordUnderscores', true);
+        tutorialWrapper.innerHTML += (new showdown.Converter()).makeHtml(results);
+        adjustHeaderWidth();
+
+        // Reset the id of all header divs to something nicer
+        for (const header of document.querySelectorAll('h1, h2, h3, h4, h5, h6')) {
+            const headerId = header.innerText.replace(/\s+/g, '-').toLowerCase();
+            header.setAttribute('id', headerId);
+            header.addEventListener('click', () => {
+                window.location.hash = `#${headerId}`;
+                header.scrollIntoView();
+            });
+        }
+
+        // Manually scroll the user to the appropriate header if anchor navigation is used
+        document.fonts.ready.finally(() => {
+            if (window.location.hash) {
+                const scrollTarget = document.getElementById(window.location.hash.substring(1));
+                scrollTarget?.scrollIntoView();
+            }
+        });
+    }).catch((error) => {
+        console.error(error);
+        tutorialWrapper.innerHTML =
+            `<h2>This page is out of logic!</h2>
+            <h3>Click <a href="${window.location.origin}">here</a> to return to safety.</h3>`;
+    });
+});

WebHostLib/static/assets/lttpMultiTracker.js

@@ -0,0 +1,6 @@
+window.addEventListener('load', () => {
+    $(".table-wrapper").scrollsync({
+        y_sync: true,
+        x_sync: true
+    });
+});

WebHostLib/static/assets/player-settings.js

@@ -6,26 +6,24 @@ window.addEventListener('load', () => {
   // Update game name on page
   document.getElementById('game-name').innerText = gameName;
 
-  Promise.all([fetchSettingData()]).then((results) => {
+  fetchSettingData().then((results) => {
     let settingHash = localStorage.getItem(`${gameName}-hash`);
     if (!settingHash) {
       // If no hash data has been set before, set it now
-      localStorage.setItem(`${gameName}-hash`, md5(results[0]));
+      settingHash = md5(JSON.stringify(results));
+      localStorage.setItem(`${gameName}-hash`, settingHash);
       localStorage.removeItem(gameName);
-      settingHash = md5(results[0]);
     }
 
-    if (settingHash !== md5(results[0])) {
-      const userMessage = document.getElementById('user-message');
-      userMessage.innerText = "Your settings are out of date! Click here to update them! Be aware this will reset " +
-        "them all to default.";
-      userMessage.style.display = "block";
-      userMessage.addEventListener('click', resetSettings);
+    if (settingHash !== md5(JSON.stringify(results))) {
+      showUserMessage("Your settings are out of date! Click here to update them! Be aware this will reset " +
+        "them all to default.");
+      document.getElementById('user-message').addEventListener('click', resetSettings);
     }
 
     // Page setup
-    createDefaultSettings(results[0]);
-    buildUI(results[0]);
+    createDefaultSettings(results);
+    buildUI(results);
     adjustHeaderWidth();
 
     // Event listeners
@@ -38,7 +36,8 @@ window.addEventListener('load', () => {
     const nameInput = document.getElementById('player-name');
     nameInput.addEventListener('keyup', (event) => updateBaseSetting(event));
     nameInput.value = playerSettings.name;
-  }).catch((error) => {
+  }).catch((e) => {
+    console.error(e);
     const url = new URL(window.location.href);
     window.location.replace(`${url.protocol}//${url.hostname}/page-not-found`);
   })
@@ -103,9 +102,15 @@ const buildOptionsTable = (settings, romOpts = false) => {
     // td Left
     const tdl = document.createElement('td');
     const label = document.createElement('label');
+    label.textContent = `${settings[setting].displayName}: `;
     label.setAttribute('for', setting);
-    label.setAttribute('data-tooltip', settings[setting].description);
-    label.innerText = `${settings[setting].displayName}:`;
+
+    const questionSpan = document.createElement('span');
+    questionSpan.classList.add('interactive');
+    questionSpan.setAttribute('data-tooltip', settings[setting].description);
+    questionSpan.innerText = '(?)';
+
+    label.appendChild(questionSpan);
     tdl.appendChild(label);
     tr.appendChild(tdl);
 
@@ -113,6 +118,8 @@ const buildOptionsTable = (settings, romOpts = false) => {
     const tdr = document.createElement('td');
     let element = null;
 
+    const randomButton = document.createElement('button');
+
     switch(settings[setting].type){
       case 'select':
         element = document.createElement('div');
@@ -133,8 +140,21 @@ const buildOptionsTable = (settings, romOpts = false) => {
           }
           select.appendChild(option);
         });
-        select.addEventListener('change', (event) => updateGameSetting(event));
+        select.addEventListener('change', (event) => updateGameSetting(event.target));
         element.appendChild(select);
+
+        // Randomize button
+        randomButton.innerText = '🎲';
+        randomButton.classList.add('randomize-button');
+        randomButton.setAttribute('data-key', setting);
+        randomButton.setAttribute('data-tooltip', 'Toggle randomization for this option!');
+        randomButton.addEventListener('click', (event) => toggleRandomize(event, select));
+        if (currentSettings[gameName][setting] === 'random') {
+          randomButton.classList.add('active');
+          select.disabled = true;
+        }
+
+        element.appendChild(randomButton);
         break;
 
       case 'range':
@@ -149,20 +169,119 @@ const buildOptionsTable = (settings, romOpts = false) => {
         range.value = currentSettings[gameName][setting];
         range.addEventListener('change', (event) => {
           document.getElementById(`${setting}-value`).innerText = event.target.value;
-          updateGameSetting(event);
+          updateGameSetting(event.target);
         });
         element.appendChild(range);
 
         let rangeVal = document.createElement('span');
         rangeVal.classList.add('range-value');
         rangeVal.setAttribute('id', `${setting}-value`);
-        rangeVal.innerText = currentSettings[gameName][setting] ?? settings[setting].defaultValue;
+        rangeVal.innerText = currentSettings[gameName][setting] !== 'random' ?
+          currentSettings[gameName][setting] : settings[setting].defaultValue;
         element.appendChild(rangeVal);
+
+        // Randomize button
+        randomButton.innerText = '🎲';
+        randomButton.classList.add('randomize-button');
+        randomButton.setAttribute('data-key', setting);
+        randomButton.setAttribute('data-tooltip', 'Toggle randomization for this option!');
+        randomButton.addEventListener('click', (event) => toggleRandomize(event, range));
+        if (currentSettings[gameName][setting] === 'random') {
+          randomButton.classList.add('active');
+          range.disabled = true;
+        }
+
+        element.appendChild(randomButton);
+        break;
+
+      case 'special_range':
+        element = document.createElement('div');
+        element.classList.add('special-range-container');
+
+        // Build the select element
+        let specialRangeSelect = document.createElement('select');
+        specialRangeSelect.setAttribute('data-key', setting);
+        Object.keys(settings[setting].value_names).forEach((presetName) => {
+          let presetOption = document.createElement('option');
+          presetOption.innerText = presetName;
+          presetOption.value = settings[setting].value_names[presetName];
+          const words = presetOption.innerText.split("_");
+          for (let i = 0; i < words.length; i++) {
+            words[i] = words[i][0].toUpperCase() + words[i].substring(1);
+          }
+          presetOption.innerText = words.join(" ");
+          specialRangeSelect.appendChild(presetOption);
+        });
+        let customOption = document.createElement('option');
+        customOption.innerText = 'Custom';
+        customOption.value = 'custom';
+        customOption.selected = true;
+        specialRangeSelect.appendChild(customOption);
+        if (Object.values(settings[setting].value_names).includes(Number(currentSettings[gameName][setting]))) {
+          specialRangeSelect.value = Number(currentSettings[gameName][setting]);
+        }
+
+        // Build range element
+        let specialRangeWrapper = document.createElement('div');
+        specialRangeWrapper.classList.add('special-range-wrapper');
+        let specialRange = document.createElement('input');
+        specialRange.setAttribute('type', 'range');
+        specialRange.setAttribute('data-key', setting);
+        specialRange.setAttribute('min', settings[setting].min);
+        specialRange.setAttribute('max', settings[setting].max);
+        specialRange.value = currentSettings[gameName][setting];
+
+        // Build rage value element
+        let specialRangeVal = document.createElement('span');
+        specialRangeVal.classList.add('range-value');
+        specialRangeVal.setAttribute('id', `${setting}-value`);
+        specialRangeVal.innerText = currentSettings[gameName][setting] !== 'random' ?
+          currentSettings[gameName][setting] : settings[setting].defaultValue;
+
+        // Configure select event listener
+        specialRangeSelect.addEventListener('change', (event) => {
+          if (event.target.value === 'custom') { return; }
+
+          // Update range slider
+          specialRange.value = event.target.value;
+          document.getElementById(`${setting}-value`).innerText = event.target.value;
+          updateGameSetting(event.target);
+        });
+
+        // Configure range event handler
+        specialRange.addEventListener('change', (event) => {
+          // Update select element
+          specialRangeSelect.value =
+            (Object.values(settings[setting].value_names).includes(parseInt(event.target.value))) ?
+            parseInt(event.target.value) : 'custom';
+          document.getElementById(`${setting}-value`).innerText = event.target.value;
+          updateGameSetting(event.target);
+        });
+
+        element.appendChild(specialRangeSelect);
+        specialRangeWrapper.appendChild(specialRange);
+        specialRangeWrapper.appendChild(specialRangeVal);
+        element.appendChild(specialRangeWrapper);
+
+        // Randomize button
+        randomButton.innerText = '🎲';
+        randomButton.classList.add('randomize-button');
+        randomButton.setAttribute('data-key', setting);
+        randomButton.setAttribute('data-tooltip', 'Toggle randomization for this option!');
+        randomButton.addEventListener('click', (event) => toggleRandomize(
+            event, specialRange, specialRangeSelect)
+        );
+        if (currentSettings[gameName][setting] === 'random') {
+          randomButton.classList.add('active');
+          specialRange.disabled = true;
+          specialRangeSelect.disabled = true;
+        }
+
+        specialRangeWrapper.appendChild(randomButton);
         break;
 
       default:
-        console.error(`Unknown setting type: ${settings[setting].type}`);
-        console.error(setting);
+        console.error(`Ignoring unknown setting type: ${settings[setting].type} with name ${setting}`);
         return;
     }
 
@@ -175,6 +294,27 @@ const buildOptionsTable = (settings, romOpts = false) => {
   return table;
 };
 
+const toggleRandomize = (event, inputElement, optionalSelectElement = null) => {
+  const active = event.target.classList.contains('active');
+  const randomButton = event.target;
+
+  if (active) {
+    randomButton.classList.remove('active');
+    inputElement.disabled = undefined;
+    if (optionalSelectElement) {
+      optionalSelectElement.disabled = undefined;
+    }
+  } else {
+    randomButton.classList.add('active');
+    inputElement.disabled = true;
+    if (optionalSelectElement) {
+      optionalSelectElement.disabled = true;
+    }
+  }
+
+  updateGameSetting(randomButton);
+};
+
 const updateBaseSetting = (event) => {
   const options = JSON.parse(localStorage.getItem(gameName));
   options[event.target.getAttribute('data-key')] = isNaN(event.target.value) ?
@@ -182,16 +322,25 @@ const updateBaseSetting = (event) => {
   localStorage.setItem(gameName, JSON.stringify(options));
 };
 
-const updateGameSetting = (event) => {
+const updateGameSetting = (settingElement) => {
   const options = JSON.parse(localStorage.getItem(gameName));
-  options[gameName][event.target.getAttribute('data-key')] = isNaN(event.target.value) ?
-      event.target.value : parseInt(event.target.value, 10);
+
+  if (settingElement.classList.contains('randomize-button')) {
+    // If the event passed in is the randomize button, then we know what we must do.
+    options[gameName][settingElement.getAttribute('data-key')] = 'random';
+  } else {
+    options[gameName][settingElement.getAttribute('data-key')] = isNaN(settingElement.value) ?
+      settingElement.value : parseInt(settingElement.value, 10);
+  }
+
   localStorage.setItem(gameName, JSON.stringify(options));
 };
 
 const exportSettings = () => {
   const settings = JSON.parse(localStorage.getItem(gameName));
-  if (!settings.name || settings.name.trim().length === 0) { settings.name = "noname"; }
+  if (!settings.name || settings.name.toLowerCase() === 'player' || settings.name.trim().length === 0) {
+    return showUserMessage('You must enter a player name!');
+  }
   const yamlText = jsyaml.safeDump(settings, { noCompatMode: true }).replaceAll(/'(\d+)':/g, (x, y) => `${y}:`);
   download(`${document.getElementById('player-name').value}.yaml`, yamlText);
 };
@@ -208,21 +357,42 @@ const download = (filename, text) => {
 };
 
 const generateGame = (raceMode = false) => {
+  const settings = JSON.parse(localStorage.getItem(gameName));
+  if (!settings.name || settings.name.toLowerCase() === 'player' || settings.name.trim().length === 0) {
+    return showUserMessage('You must enter a player name!');
+  }
+
   axios.post('/api/generate', {
-    weights: { player: localStorage.getItem(gameName) },
-    presetData: { player: localStorage.getItem(gameName) },
+    weights: { player: settings },
+    presetData: { player: settings },
     playerCount: 1,
+    spoiler: 3,
     race: raceMode ? '1' : '0',
   }).then((response) => {
     window.location.href = response.data.url;
   }).catch((error) => {
-    const userMessage = document.getElementById('user-message');
-    userMessage.innerText = 'Something went wrong and your game could not be generated.';
+    let userMessage = 'Something went wrong and your game could not be generated.';
     if (error.response.data.text) {
-      userMessage.innerText += ' ' + error.response.data.text;
+      userMessage += ' ' + error.response.data.text;
     }
-    userMessage.classList.add('visible');
-    window.scrollTo(0, 0);
+    showUserMessage(userMessage);
     console.error(error);
   });
 };
+
+const showUserMessage = (message) => {
+  const userMessage = document.getElementById('user-message');
+    userMessage.innerText = message;
+    userMessage.classList.add('visible');
+    window.scrollTo(0, 0);
+    userMessage.addEventListener('click', () => {
+      userMessage.classList.remove('visible');
+      userMessage.addEventListener('click', hideUserMessage);
+    });
+};
+
+const hideUserMessage = () => {
+  const userMessage = document.getElementById('user-message');
+  userMessage.classList.remove('visible');
+  userMessage.removeEventListener('click', hideUserMessage);
+};

WebHostLib/static/assets/sc2wolTracker.js

@@ -0,0 +1,49 @@
+window.addEventListener('load', () => {
+  // Reload tracker every 15 seconds
+  const url = window.location;
+  setInterval(() => {
+    const ajax = new XMLHttpRequest();
+    ajax.onreadystatechange = () => {
+      if (ajax.readyState !== 4) { return; }
+
+      // Create a fake DOM using the returned HTML
+      const domParser = new DOMParser();
+      const fakeDOM = domParser.parseFromString(ajax.responseText, 'text/html');
+
+      // Update item tracker
+      document.getElementById('inventory-table').innerHTML = fakeDOM.getElementById('inventory-table').innerHTML;
+      // Update only counters in the location-table
+      let counters = document.getElementsByClassName('counter');
+      const fakeCounters = fakeDOM.getElementsByClassName('counter');
+      for (let i = 0; i < counters.length; i++) {
+        counters[i].innerHTML = fakeCounters[i].innerHTML;
+      }
+    };
+    ajax.open('GET', url);
+    ajax.send();
+  }, 15000)
+
+  // Collapsible advancement sections
+  const categories = document.getElementsByClassName("location-category");
+  for (let i = 0; i < categories.length; i++) {
+    let hide_id = categories[i].id.split('-')[0];
+    if (hide_id == 'Total') {
+      continue;
+    }
+    categories[i].addEventListener('click', function() {
+      // Toggle the advancement list
+      document.getElementById(hide_id).classList.toggle("hide");
+      // Change text of the header
+      const tab_header = document.getElementById(hide_id+'-header').children[0];
+      const orig_text = tab_header.innerHTML;
+      let new_text;
+      if (orig_text.includes("▼")) {
+        new_text = orig_text.replace("▼", "▲");
+      }
+      else {
+        new_text = orig_text.replace("▲", "▼");
+      }
+      tab_header.innerHTML = new_text;
+    });
+  }
+});

WebHostLib/static/assets/supportedGames.js

@@ -0,0 +1,83 @@
+window.addEventListener('load', () => {
+  const gameHeaders = document.getElementsByClassName('collapse-toggle');
+  Array.from(gameHeaders).forEach((header) => {
+    const gameName = header.getAttribute('data-game');
+    header.addEventListener('click', () => {
+      const gameArrow = document.getElementById(`${gameName}-arrow`);
+      const gameInfo = document.getElementById(gameName);
+      if (gameInfo.classList.contains('collapsed')) {
+        gameArrow.innerText = '▼';
+        gameInfo.classList.remove('collapsed');
+      } else {
+        gameArrow.innerText = '▶';
+        gameInfo.classList.add('collapsed');
+      }
+    });
+  });
+
+  // Handle game filter input
+  const gameSearch = document.getElementById('game-search');
+  gameSearch.value = '';
+
+  gameSearch.addEventListener('input', (evt) => {
+    if (!evt.target.value.trim()) {
+      // If input is empty, display all collapsed games
+      return Array.from(gameHeaders).forEach((header) => {
+        header.style.display = null;
+        const gameName = header.getAttribute('data-game');
+        document.getElementById(`${gameName}-arrow`).innerText = '▶';
+        document.getElementById(gameName).classList.add('collapsed');
+      });
+    }
+
+    // Loop over all the games
+    Array.from(gameHeaders).forEach((header) => {
+      const gameName = header.getAttribute('data-game');
+      const gameArrow = document.getElementById(`${gameName}-arrow`);
+      const gameInfo = document.getElementById(gameName);
+
+      // If the game name includes the search string, display the game. If not, hide it
+      if (gameName.toLowerCase().includes(evt.target.value.toLowerCase())) {
+        header.style.display = null;
+        gameArrow.innerText = '▼';
+        gameInfo.classList.remove('collapsed');
+      } else {
+        console.log(header);
+        header.style.display = 'none';
+        gameArrow.innerText = '▶';
+        gameInfo.classList.add('collapsed');
+      }
+    });
+  });
+
+  document.getElementById('expand-all').addEventListener('click', expandAll);
+  document.getElementById('collapse-all').addEventListener('click', collapseAll);
+});
+
+const expandAll = () => {
+  const gameHeaders = document.getElementsByClassName('collapse-toggle');
+  // Loop over all the games
+    Array.from(gameHeaders).forEach((header) => {
+      const gameName = header.getAttribute('data-game');
+      const gameArrow = document.getElementById(`${gameName}-arrow`);
+      const gameInfo = document.getElementById(gameName);
+
+      if (header.style.display === 'none') { return; }
+      gameArrow.innerText = '▼';
+      gameInfo.classList.remove('collapsed');
+    });
+};
+
+const collapseAll = () => {
+  const gameHeaders = document.getElementsByClassName('collapse-toggle');
+  // Loop over all the games
+    Array.from(gameHeaders).forEach((header) => {
+      const gameName = header.getAttribute('data-game');
+      const gameArrow = document.getElementById(`${gameName}-arrow`);
+      const gameInfo = document.getElementById(gameName);
+
+      if (header.style.display === 'none') { return; }
+      gameArrow.innerText = '▶';
+      gameInfo.classList.add('collapsed');
+    });
+};

WebHostLib/static/assets/trackerCommon.js

@@ -1,5 +1,7 @@
 const adjustTableHeight = () => {
     const tablesContainer = document.getElementById('tables-container');
+    if (!tablesContainer)
+        return;
     const upperDistance = tablesContainer.getBoundingClientRect().top;
 
     const containerHeight = window.innerHeight - upperDistance;
@@ -12,12 +14,42 @@ const adjustTableHeight = () => {
     }
 };
 
+/**
+ * Convert an integer number of seconds into a human readable HH:MM format
+ * @param {Number} seconds
+ * @returns {string}
+ */
+const secondsToHours = (seconds) => {
+    let hours   = Math.floor(seconds / 3600);
+    let minutes = Math.floor((seconds - (hours * 3600)) / 60).toString().padStart(2, '0');
+    return `${hours}:${minutes}`;
+};
+
 window.addEventListener('load', () => {
     const tables = $(".table").DataTable({
         paging: false,
         info: false,
         dom: "t",
+        stateSave: true,
+        stateSaveCallback: function(settings, data) {
+            delete data.search;
+            localStorage.setItem(`DataTables_${settings.sInstance}_/tracker`, JSON.stringify(data));
+        },
+        stateLoadCallback: function(settings) {
+            return JSON.parse(localStorage.getItem(`DataTables_${settings.sInstance}_/tracker`));
+        },
+        footerCallback: function(tfoot, data, start, end, display) {
+            if (tfoot) {
+                const activityData = this.api().column('lastActivity:name').data().toArray().filter(x => !isNaN(x));
+                Array.from(tfoot?.children).find(td => td.classList.contains('last-activity')).innerText =
+                  (activityData.length) ? secondsToHours(Math.min(...activityData)) : 'None';
+            }
+        },
         columnDefs: [
+            {
+                targets: 'last-activity',
+                name: 'lastActivity'
+            },
             {
                 targets: 'hours',
                 render: function (data, type, row) {
@@ -30,11 +62,7 @@ window.addEventListener('load', () => {
                     if (data === "None")
                         return data;
 
-                    let hours   = Math.floor(data / 3600);
-                    let minutes = Math.floor((data - (hours * 3600)) / 60);
-
-                    if (minutes < 10) {minutes = "0"+minutes;}
-                    return hours+':'+minutes;
+                    return secondsToHours(data);
                 }
             },
             {
@@ -63,24 +91,57 @@ window.addEventListener('load', () => {
         // the tbody and render two separate tables.
     });
 
-    document.getElementById('search').addEventListener('keyup', (event) => {
-        tables.search(event.target.value);
-        console.info(tables.search());
+    const searchBox = document.getElementById("search");
+    searchBox.value = tables.search();
+    searchBox.focus();
+    searchBox.select();
+    const doSearch = () => {
+        tables.search(searchBox.value);
         tables.draw();
+    };
+    searchBox.addEventListener("keyup", doSearch);
+    window.addEventListener("keydown", (event) => {
+        if (!event.ctrlKey && !event.altKey && event.key.length === 1 && document.activeElement !== searchBox) {
+            searchBox.focus();
+            searchBox.select();
+        }
+        if (!event.ctrlKey && !event.altKey && !event.shiftKey && event.key === "Escape") {
+            if (searchBox.value !== "") {
+                searchBox.value = "";
+                doSearch();
+            }
+            searchBox.blur();
+            if (!document.getElementById("tables-container"))
+                window.scroll(0, 0);
+            event.preventDefault();
+        }
     });
+    const tracker = document.getElementById('tracker-wrapper').getAttribute('data-tracker');
+    const target_second = document.getElementById('tracker-wrapper').getAttribute('data-second') + 3;
+
+    function getSleepTimeSeconds(){
+        // -40 % 60 is -40, which is absolutely wrong and should burn
+        var sleepSeconds = (((target_second - new Date().getSeconds()) % 60) + 60) % 60;
+        return sleepSeconds || 60;
+    }
 
     const update = () => {
         const target = $("<div></div>");
-        const tracker = document.getElementById('tracker-wrapper').getAttribute('data-tracker');
-        target.load("/tracker/" + tracker, function (response, status) {
+        console.log("Updating Tracker...");
+        target.load(location.href, function (response, status) {
             if (status === "success") {
                 target.find(".table").each(function (i, new_table) {
                     const new_trs = $(new_table).find("tbody>tr");
+                    const footer_tr = $(new_table).find("tfoot>tr");
                     const old_table = tables.eq(i);
                     const topscroll = $(old_table.settings()[0].nScrollBody).scrollTop();
                     const leftscroll = $(old_table.settings()[0].nScrollBody).scrollLeft();
                     old_table.clear();
-                    old_table.rows.add(new_trs).draw();
+                    if (footer_tr.length) {
+                        $(old_table.table).find("tfoot").html(footer_tr);
+                    }
+                    old_table.rows.add(new_trs);
+                    old_table.draw();
                     $(old_table.settings()[0].nScrollBody).scrollTop(topscroll);
                     $(old_table.settings()[0].nScrollBody).scrollLeft(leftscroll);
                 });
@@ -90,19 +151,14 @@ window.addEventListener('load', () => {
                 console.log(response);
             }
         })
+        setTimeout(update, getSleepTimeSeconds()*1000);
     }
-
-    setInterval(update, 30000);
+    setTimeout(update, getSleepTimeSeconds()*1000);
 
     window.addEventListener('resize', () => {
         adjustTableHeight();
         tables.draw();
     });
 
-    $(".table-wrapper").scrollsync({
-        y_sync: true,
-        x_sync: true
-    });
-
     adjustTableHeight();
 });

WebHostLib/static/assets/tutorial.js

@@ -14,7 +14,7 @@ window.addEventListener('load', () => {
             }
             resolve(ajax.responseText);
         };
-        ajax.open('GET', `${window.location.origin}/static/assets/tutorial/` +
+        ajax.open('GET', `${window.location.origin}/static/generated/docs/` +
             `${tutorialWrapper.getAttribute('data-game')}/${tutorialWrapper.getAttribute('data-file')}_` +
             `${tutorialWrapper.getAttribute('data-lang')}.md`, true);
         ajax.send();
@@ -23,28 +23,32 @@ window.addEventListener('load', () => {
         showdown.setOption('tables', true);
         showdown.setOption('strikethrough', true);
         showdown.setOption('literalMidWordUnderscores', true);
+        showdown.setOption('disableForced4SpacesIndentedSublists', true);
         tutorialWrapper.innerHTML += (new showdown.Converter()).makeHtml(results);
         adjustHeaderWidth();
 
+        const title = document.querySelector('h1')
+        if (title) {
+            document.title = title.textContent;
+        }
+
         // Reset the id of all header divs to something nicer
-        const headers = Array.from(document.querySelectorAll('h1, h2, h3, h4, h5, h6'));
-        const scrollTargetIndex = window.location.href.search(/#[A-z0-9-_]*$/);
-        for (let i=0; i < headers.length; i++){
-            const headerId = headers[i].innerText.replace(/[ ]/g,'-').toLowerCase()
-            headers[i].setAttribute('id', headerId);
-            headers[i].addEventListener('click', () =>
-                window.location.href = window.location.href.substring(0, scrollTargetIndex) + `#${headerId}`);
+        for (const header of document.querySelectorAll('h1, h2, h3, h4, h5, h6')) {
+            const headerId = header.innerText.replace(/\s+/g, '-').toLowerCase();
+            header.setAttribute('id', headerId);
+            header.addEventListener('click', () => {
+                window.location.hash = `#${headerId}`;
+                header.scrollIntoView();
+            });
         }
 
         // Manually scroll the user to the appropriate header if anchor navigation is used
-        if (scrollTargetIndex > -1) {
-            try{
-                const scrollTarget = window.location.href.substring(scrollTargetIndex + 1);
-                document.getElementById(scrollTarget).scrollIntoView({ behavior: "smooth" });
-            } catch(error) {
-                console.error(error);
+        document.fonts.ready.finally(() => {
+            if (window.location.hash) {
+                const scrollTarget = document.getElementById(window.location.hash.substring(1));
+                scrollTarget?.scrollIntoView();
             }
-        }
+        });
     }).catch((error) => {
         console.error(error);
         tutorialWrapper.innerHTML =

WebHostLib/static/assets/tutorial/Subnautica/setup_en.md

@@ -1,32 +0,0 @@
-# Subnautica Randomizer Setup Guide
-
-## Required Software
-
-- [Subnautica](https://store.steampowered.com/app/264710/Subnautica/)
-- [QModManager4](https://www.nexusmods.com/subnautica/mods/201)
-- [Archipelago Mod for Subnautica](https://github.com/Berserker66/ArchipelagoSubnauticaModSrc/releases)
-
-
-## Installation Procedures
-
-1. Install QModManager4 as per its instructions.
-
-2. The folder you installed QModManager4 into will now have a /QMods directory. It might appear after a start of Subnautica. You can also create this folder yourself.
-
-3. Unpack the Archipelago Mod into this folder, so that Subnautica/QMods/Archipelago/ is a valid path.
-
-4. Start Subnautica. You should see a Connect Menu in the topleft of your main Menu. 
-
-## Troubleshooting
-
-If you don't see the connect window check that you see a qmodmanager_log-Subnautica.txt in Subnautica, if not QModManager4 is not correctly installed, otherwise open it and look for `[Info   :   BepInEx] Loading [Archipelago 1.0.0.0]`, version number doesn't matter. If it doesn't show this, then QModManager4 didn't find the Archipelago mod, so check your paths.
-    
-## Joining a MultiWorld Game
-
-1. In Host, enter the address of the server, such as archipelago.gg:38281, your server host should be able to tell you this.
-
-2. In Password enter the server password if one exists, otherwise leave blank.
-
-3. In PlayerName enter your "name" field from the yaml, or website config.
-
-4. Hit Connect. If it says succesfully authenticated you can now create a new savegame or resume the correct savegame.

WebHostLib/static/assets/tutorial/archipelago/advanced_settings_en.md

@@ -1,160 +0,0 @@
-# Advanced Game Options Guide
-
-
-The Archipelago system generates games using player configuration files as input. Generally these are going to be
-YAML files and each player will have one of these containing their custom settings for the randomized game they want to play.
-On the website when you customize your settings from one of the game player settings pages which you can reach from the
-[supported games page](/games). Clicking on the export settings button at the bottom will provide you with a pre-filled out
-YAML with your options. The player settings page also has an option to download a fully filled out yaml containing every
-option with every available setting for the available options.
-
-## YAML Formatting
-YAML files are a format of <span data-tooltip="Allegedly.">human-readable</span> markup config files. The basic syntax
-of a yaml file will have `root` and then different levels of `nested` text that the generator "reads" in order to determine
-your settings. To nest text, the correct syntax is **two spaces over** from its root option. A YAML file can be edited
-with whatever text editor you choose to use though I personally recommend that you use [Sublime Text](https://www.sublimetext.com/).
-This program out of the box supports the correct formatting for the YAML file, so you will be able to tab and get proper
-highlighting for any potential errors made while editing the file. If using any other text editor such as Notepad or
-Notepad++ whenever you move to nest an option that it is done with two spaces and not tabs. 
-
-Typical YAML format will look as follows:
-```yaml
-root_option:
-  nested_option_one:
-    option_one_setting_one: 1
-    option_one_setting_two: 0
-  nested_option_two:
-    option_two_setting_one: 14
-    option_two_setting_two: 43
-```
-
-In Archipelago YAML options are always written out in full lowercase with underscores separating any words. The numbers
-following the colons here are weights. The generator will read the weight of every option the roll that option that many
-times, the next option as many times as its numbered and so forth. For the above example `nested_option_one` will have
-`option_one_setting_one` 1 time and `option_one_setting_two` 0 times so `option_one_setting_one` is guaranteed to occur.
-For `nested_option_two`, `option_two_setting_one` will be rolled 14 times and `option_two_setting_two` will be rolled 43
-times against each other. This means `option_two_setting_two` will be more likely to occur but it isn't guaranteed adding
-more randomness and "mystery" to your settings. Every configurable setting supports weights.
-
-### Root Options
-Currently there are only a few options that are root options. Everything else should be nested within one of these root
-options or in some cases nested within other nested options. The only options that should exist in root are `description`,
-`name`, `game`, `requires`, `accessibility`, `progression_balancing`, `triggers`, and the name of the games you want 
-settings for.
-* `description` is ignored by the generator and is simply a good way for you to organize if you have multiple files using
-this to detail the intention of the file.
-* `name` is the player name you would like to use and is used for your slot data to connect with most games. This can also
-be filled with multiple names each having a weight to it.
-* `game` is where either your chosen game goes or if you would like can be filled with multiple games each with different
-weights.
-* `requires` details different requirements from the generator for the YAML to work as you expect it to. Generally this
-is good for detailing the version of Archipelago this YAML was prepared for as if it is rolled on an older version may be
-missing settings and as such will not work as expected. If any plando is used in the file then requiring it here to ensure
-it will be used is good practice.
-* `accessibility` determines the level of access to the game the generation will expect you to have in order to reach your
-completion goal. This supports `items`, `locations`, and `none` and is set to `locations` by default.
-  * `items` will guarantee you can acquire all items in your world but may not be able to access all locations. This mostly
-comes into play if there is any entrance shuffle in the seed as locations without items in them can be placed in areas
-that make them unreachable.
-  * `none` will only guarantee that the seed is beatable. You will be guaranteed able to finish the seed logically but
-may not be able to access all locations or acquire all items. A good example of this is having a big key in the big chest
-in a dungeon in ALTTP making it impossible to get and finish the dungeon.
-* `progression_balancing` is a system the Archipelago generator uses to try and reduce "BK mode" as much as possible. This
-primarily involves moving necessary progression items into earlier logic spheres to make the games more accessible so that
-players almost always have something to do. This can be turned `on` or `off` and is `on` by default.
-* `triggers` is one of the more advanced options that allows you to create conditional adjustments. You can read more
-about this [here](/tutorial/archipelago/triggers/en).
-
-### Game Options
-
-One of your root settings will be the name of the game you would like to populate with settings in the format
-`GameName`. since it is possible to give a weight to any option it is possible to have one file that can generate a seed
-for you where you don't know which game you'll play. For these cases you'll want to fill the game options for every game
-that can be rolled by these settings. If a game can be rolled it **must** have a settings section even if it is empty.
-
-#### Universal Game Options
-
-Some options in Archipelago can be used by every game but must still be placed within the relevant game's section.
-Currently, these options are `start_inventory`, `start_hints`, `local_items`, `non_local_items`, `start_location_hints`, 
-`exclude_locations`, and various [plando options](/tutorial/archipelago/plando/en).
-* `start_inventory` will give any items defined here to you at the beginning of your game. The format for this must be
-the name as it appears in the game files and the amount you would like to start with. For example `Rupees(5): 6` which
-will give you 30 rupees.
-* `start_hints` gives you free server hints for the defined item/s at the beginning of the game allowing you to hint for
-the location without using any hint points.
-* `local_items` will force any items you want to be in your world instead of being in another world.
-* `non_local_items` is the inverse of `local_items` forcing any items you want to be in another world and won't be located
-in your own.
-* `start_location_hints` allows you to define a location which you can then hint for to find out what item is located in
-it to see how important the location is.
-* `exclude_locations` lets you define any locations that you don't want to do and during generation will force a "junk"
-item which isn't necessary for progression to go in these locations.
-
-### Example
-
-```yaml
-
-description: An example using various advanced options
-name: Example Player
-game: A Link to the Past
-requires: 
-  version: 0.2.0
-accessibility: none
-progression_balancing: on
-A Link to the Past:
-  smallkey_shuffle:
-    original_dungeon: 1
-    any_world: 1
-  start_inventory:
-    Pegasus Boots: 1
-    Bombs (3): 2
-  start_hints:
-    - Hammer
-  local_items:
-    - Bombos
-    - Ether
-    - Quake
-  non_local_items:
-    - Moon Pearl
-  start_location_hints:
-    - Spike Cave
-  exclude_locations:
-    - Cave 45
-triggers:
-  - option_category: A Link to the Past
-    option_name: smallkey_shuffle
-    option_result: any_world
-    options:
-      A Link to the Past:
-        bigkey_shuffle: any_world
-        map_shuffle: any_world
-        compass_shuffle: any_world
-```
-
-#### This is a fully functional yaml file that will do all the following things:
-* `description` gives us a general overview so if we pull up this file later we can understand the intent.
-* `name` is `Example Player` and this will be used in the server console when sending and receiving items.
-* `game` is set to `A Link to the Past` meaning that is what game we will play with this file.
-* `requires` is set to require release version 0.2.0 or higher.
-* `accesibility` is set to `none` which will set this seed to beatable only meaning some locations and items may be
-completely inaccessible but the seed will still be completable.
-* `progression_balancing` is set on meaning we will likely receive important items earlier increasing the chance of having
-things to do.
-* `A Link to the Past` defines a location for us to nest all the game options we would like to use for our game `A Link to the Past`.
-* `smallkey_shuffle` is an option for A Link to the Past which determines how dungeon small keys are shuffled. In this example
-we have a 1/2 chance for them to either be placed in their original dungeon and a 1/2 chance for them to be placed anywhere
-amongst the multiworld.
-* `start_inventory` defines an area for us to determine what items we would like to start the seed with. For this example
-we have:
-  * `Pegasus Boots: 1` which gives us 1 copy of the Pegasus Boots
-  * `Bombs (3)` gives us 2 packs of 3 bombs or 6 total bombs
-* `start_hints` gives us a starting hint for the hammer available at the beginning of the multiworld which we can use with no cost.
-* `local_items` forces the `Bombos`, `Ether`, and `Quake` medallions to all be placed within our own world, meaning we
-have to find it ourselves.
-* `non_local_items` forces the `Moon Pearl` to be placed in someone else's world, meaning we won't be able to find it.
-* `start_location_hints` gives us a starting hint for the `Spike Cave` location available at the beginning of the multiworld
-that can be used for no cost.
-* `exclude_locations` forces a not important item to be placed on the `Cave 45` location.
-* `triggers` allows us to define a trigger such that if our `smallkey_shuffle` option happens to roll the `any_world`
-result it will also ensure that `bigkey_shuffle`, `map_shuffle`, and `compass_shuffle` are also forced to the `any_world`
-result.

WebHostLib/static/assets/tutorial/archipelago/plando_en.md

@@ -1,180 +0,0 @@
-# Archipelago Plando Guide
-
-## What is Plando?
-The purposes of randomizers is to randomize the items in a game to give a new experience.
-Plando takes this concept and changes it up by allowing you to plan out certain aspects of the game by placing certain 
-items in certain locations, certain bosses in certain rooms, edit text for certain NPCs/signs, or even force certain region
-connections. Each of these options are going to be detailed separately as `item plando`, `boss plando`, `text plando`, 
-and `connection plando`. Every game in archipelago supports item plando but the other plando options are only supported 
-by certain games. Currently, Minecraft and LTTP both support connection plando, but only LTTP supports text and boss plando.
-
-### Enabling Plando
-On the website plando will already be enabled. If you will be generating the game locally plando features must be enabled (opt-in).
-* To opt-in go to the archipelago installation (default: `C:\ProgramData\Archipelago`), open the host.yaml with a text
-editor and find the `plando_options` key. The available plando modules can be enabled by adding them after this such as
-`plando_options: bosses, items, texts, connections`.
-
-## Item Plando
-Item plando allows a player to place an item in a specific location or specific locations, place multiple items into
-a list of specific locations both in their own game or in another player's game. **Note that there's a very good chance that
-cross-game plando could very well be broken i.e. placing on of your items in someone else's world playing a different game.**
-* The options for item plando are `from_pool`, `world`, `percentage`, `force`, and either item and location, or items and locations.
-  * `from_pool` determines if the item should be taken *from* the item pool or *added* to it. This can be true or false
-and defaults to true if omitted.
-  * `world` is the target world to place the item in.
-    * It gets ignored if only one world is generated.
-    * Can be a number, name, true, false, or null. False is the default.
-      * If a number is used it targets that slot or player number in the multiworld.
-      * If a name is used it will target the world with that player name.
-      * If set to true it will be any player's world besides your own.
-      * If set to false it will target your own world.
-      * If set to null it will target a random world in the multiworld.
-  * `force` determines whether the generator will fail if the item can't be placed in the location can be true, false, 
-or silent. Silent is the default.
-    * If set to true the item must be placed and the generator will throw an error if it is unable to do so.
-    * If set to false the generator will log a warning if the placement can't be done but will still generate.
-    * If set to silent and the placement fails it will be ignored entirely.
-  * `percentage` is the percentage chance for the relevant block to trigger. This can be any value from 0 to 100 and if 
-omitted will default to 100.
-  * Single Placement is when you use a plando block to place a single item at a single location.
-    * `item` is the item you would like to place and `location` is the location to place it.
-  * Multi Placement uses a plando block to place multiple items in multiple locations until either list is exhausted.
-    * `items` defines the items to use and a number letting you place multiple of it.
-    * `locations` is a list of possible locations those items can be placed in.
-    * Using the multi placement method, placements are picked randomly.
-
-### Available Items
-* [A Link to the Past](https://github.com/ArchipelagoMW/Archipelago/blob/main/worlds/alttp/Items.py#L52)
-* [Factorio Non-Progressive](https://wiki.factorio.com/Technologies) Note that these use the *internal names*. For example, `advanced-electronics`
-* [Factorio Progressive](https://github.com/ArchipelagoMW/Archipelago/blob/main/worlds/factorio/Technologies.py#L374)
-* [Minecraft](https://github.com/ArchipelagoMW/Archipelago/blob/main/worlds/minecraft/Items.py#L14)
-* [Ocarina of Time](https://github.com/ArchipelagoMW/Archipelago/blob/main/worlds/oot/Items.py#L61)
-* [Risk of Rain 2](https://github.com/ArchipelagoMW/Archipelago/blob/main/worlds/ror2/Items.py#L8)
-* [Slay the Spire](https://github.com/ArchipelagoMW/Archipelago/blob/main/worlds/spire/Items.py#L13)
-* [Subnautica](https://github.com/ArchipelagoMW/Archipelago/blob/main/worlds/subnautica/items.json)
-* [Timespinner](https://github.com/ArchipelagoMW/Archipelago/blob/main/worlds/timespinner/Items.py#L11)
-
-### Available Locations
-* [A Link to the Past](https://github.com/ArchipelagoMW/Archipelago/blob/main/worlds/alttp/Regions.py#L429)
-* [Factorio](https://wiki.factorio.com/Technologies) Same as items
-* [Minecraft](https://github.com/ArchipelagoMW/Archipelago/blob/main/worlds/minecraft/Locations.py#L18)
-* [Ocarina of Time](https://github.com/ArchipelagoMW/Archipelago/blob/main/worlds/oot/LocationList.py#L38)
-* [Risk of Rain 2](https://github.com/ArchipelagoMW/Archipelago/blob/main/worlds/ror2/Locations.py#L17) This is a special
-case. The locations are "ItemPickup[number]" up to the maximum set in the yaml.
-* [Slay the Spire](https://github.com/ArchipelagoMW/Archipelago/blob/main/worlds/spire/Locations.py)
-* [Subnautica](https://github.com/ArchipelagoMW/Archipelago/blob/main/worlds/subnautica/locations.json)
-* [Timespinner](https://github.com/ArchipelagoMW/Archipelago/blob/main/worlds/timespinner/Locations.py#L13)
-
-
-A list of all available items and locations can also be found in the [server's datapackage](/api/datapackage).
-### Examples
-```yaml
-plando_items:
-# example block 1 - Timespinner
-  - item:
-      Empire Orb: 1
-      Radiant Orb: 1
-    location: Starter Chest 1
-    from_pool: true
-    world: true
-    percentage: 50
-    
-# example block 2 - Ocarina of Time
-  - items:
-      Kokiri Sword: 1
-      Biggoron Sword: 1
-      Bow: 1
-      Magic Meter: 1
-      Progressive Strength Upgrade: 3
-      Progressive Hookshot: 2
-    locations:
-      - Deku Tree Slingshot Chest
-      - Dodongos Cavern Bomb Bag Chest
-      - Jabu Jabus Belly Boomerang Chest
-      - Bottom of the Well Lens of Truth Chest
-      - Forest Temple Bow Chest
-      - Fire Temple Megaton Hammer Chest
-      - Water Temple Longshot Chest
-      - Shadow Temple Hover Boots Chest
-      - Spirit Temple Silver Gauntlets Chest
-    world: false
-    
-# example block 3 - Slay the Spire
-  - items:
-      Boss Relic: 3
-    locations:
-      Boss Relic 1
-      Boss Relic 2
-      Boss Relic 3
-
-# example block 4 - Factorio
-  - items:
-      progressive-electric-energy-distribution: 2
-      electric-energy-accumulators: 1
-      progressive-turret: 2
-    locations:
-      military
-      gun-turret
-      logistic-science-pack
-      steel-processing
-    percentage: 80
-    force: true
-```
-1. This block has a 50% chance to occur, and if it does will place either the Empire Orb or Radiant Orb on another player's
-Starter Chest 1 and removes the chosen item from the item pool.
-2. This block will always trigger and will place the player's swords, bow, magic meter, strength upgrades, and hookshots
-in their own dungeon major item chests.
-3. This block will always trigger and will lock boss relics on the bosses.
-4. This block has an 80% chance of occuring and when it does will place all but 1 of the items randomly among the four
-locations chosen here.
-
-## Boss Plando
-As this is currently only supported by A Link to the Past instead of explaining here please refer to the 
-[relevant guide](/tutorial/zelda3/plando/en)
-
-## Text Plando
-As this is currently only supported by A Link to the Past instead of explaining here please refer to the
-[relevant guide](/tutorial/zelda3/plando/en)
-
-## Connections Plando
-This is currently only supported by Minecraft and A Link to the Past. As the way that these games interact with
-their connections is different I will only explain the basics here while more specifics for Link to the Past connection
-plando can be found in its plando guide.
-* The options for connections are `percentage`, `entrance`, `exit`, and `direction`. Each of these options support subweights.
-* `percentage` is the percentage chance for this connection from 0 to 100 and defaults to 100.
-* Every connection has an `entrance` and an `exit`. These can be unlinked like in A Link to the Past insanity entrance shuffle.
-* `direction` can be `both`, `entrance`, or `exit` and determines in which direction this connection will operate.
-
-[Link to the Past connections](https://github.com/ArchipelagoMW/Archipelago/blob/main/worlds/alttp/EntranceShuffle.py#L3852)
-
-[Minecraft connections](https://github.com/ArchipelagoMW/Archipelago/blob/main/worlds/minecraft/Regions.py#L62)
-
-### Examples
-```yaml
-plando_connections:
-# example block 1 - Link to the Past
-  - entrance: Cave Shop (Lake Hylia)
-    exit: Cave 45
-    direction: entrance
-  - entrance: Cave 45
-    exit: Cave Shop (Lake Hylia)
-    direction: entrance
-  - entrance: Agahnims Tower
-    exit: Old Man Cave Exit (West)
-    direction: exit
-    
-# example block 2 - Minecraft
-  - entrance: Overworld Structure 1
-    exit: Nether Fortress
-    direction: both
-  - entrance: Overworld Structure 2
-    exit: Village
-    direction: both
-```
-
-1. These connections are decoupled so going into the lake hylia cave shop will take you to the inside of cave 45 and
-when you leave the interior you will exit to the cave 45 ledge. Going into the cave 45 entrance will then take you to the
-lake hylia cave shop. Walking into the entrance for the old man cave and Agahnim's Tower entrance will both take you to
-their locations as normal but leaving old man cave will exit at Agahnim's Tower.
-2. This will force a nether fortress and a village to be the overworld structures for your game. Note that for the Minecraft
-connection plando to work structure shuffle must be enabled.

WebHostLib/static/assets/tutorial/archipelago/setup_en.md

@@ -1,79 +0,0 @@
-# Archipelago Setup Guide
-
-## Installing the Archipelago software
-The most recent public release of Archipelago can be found [here](https://github.com/ArchipelagoMW/Archipelago/releases).
-Run the exe file, and after accepting the license agreement you will be prompted on which components you would like to install. 
-The generator allows you to generate multiworld games on your computer. The ROM setups are optional but are required if 
-anyone in the game that you generate wants to play any of those games as they are needed to generate the relevant patch 
-files. The server will allow you to host the multiworld on your machine but this also requires you to port forward. The 
-default port for Archipelago is `38281`. If you are unsure how to do this there are plenty of other guides on the internet 
-that will be more suited to your hardware. The `Clients` are what you use to connect your game to the multiworld. If the 
-game/games you plan to play are available here go ahead and install these as well. If the game you choose to play is 
-supported by Archipelago but not listed in the installation check the relevant tutorial.
-
-## Generating a game
-
-### Creating a YAML
-In a multiworld there must be one YAML per world. Any number of players can play on each world using either the game's
-native coop system or using archipelago's coop support. Each world will hold one slot in the multiworld and will have a
-slot name and, if the relevant game requires it, files to associate it with that multiworld. If multiple people plan to
-play in one world cooperatively then they will only need one YAML for their coop world, but if each player is planning on
-playing their own game then they will each need a YAML. These YAML files can be generated by going to the relevant game's
-player settings page, entering the name they want to use for the game, setting the options to what they would like to
-play with and then clicking on the export settings button. This will then download a YAML file that will contain all of
-these options and this can then be given to whoever is going to generate the game.
-
-### Gather all player YAMLS
-All players that wish to play in the generated multiworld must have a YAML file which contains the settings that they wish to play with.
-A YAML is a file which contains human readable markup. In other words, this is a settings file kind of like an INI file or a TOML file. 
-Each player can go to the game's player settings page in order to determine the settings how they want them and then download a YAML file containing these settings.
-After getting the YAML files of each participant for your multiworld game, these can all either be placed together in the 
-`Archipelago\Players` folder or compressed into a ZIP folder to then be uploaded to the [website generator](/generate).
-If rolling locally ensure that the folder is clear of any files you do not wish to include in the game such as the 
-included default player settings files.
-
-#### Changing local host settings for generation
-Sometimes there are various settings that you may want to change before rolling a seed such as enabling race mode, 
-auto-forfeit, plando support, or setting a password. All of these settings plus other options are able to be changed by 
-modifying the `host.yaml` file in the base `Archipelago` folder. The settings chosen here are baked into
-the serverdata file that gets output with the other files after generation so if rolling locally ensure this file is edited
-to your liking *before* rolling the seed.
-
-### Rolling the seed
-
-#### On the Website
-After gathering the YAML files together in one location, select all of the files and compress them into a .zip folder. 
-Next go to the [Start Playing](/start-playing) page and click on `generate a randomized game` to reach the website generator. 
-Here, you can adjust some server settings such as forfeit rules and the cost for a player to use a hint before generation. 
-After adjusting the host settings to your liking click on the Upload File button and using the explorer window that opens, 
-navigate to the location where you zipped the player files and upload this zip. The page will generate your game and refresh
-multiple times to check on completion status. After the generation completes you will be on a Seed Info page that provides
-the seed, the date/time of creation, a link to the spoiler log, if available, and links to any rooms created from this seed.
-To begin playing, click on `Create New Room`, which will take you to the room page. From here you can navigate back to thse
-Seed Info page or to the Tracker page. Sharing the link to this page with your friends will provide them with the
-necessary info and files for them to connect to the multiworld.
-
-#### Rolling using the generation program
-After gathering the YAML files together in the `Archipelago\Players` folder, run the program `ArchipelagoGenerate.exe` 
-in the base `Archipelago` folder. This will then open a console window and either silently close itself or spit out an 
-error. If you receive an error, it is likely due to an error in the YAML file. If the error is unhelpful in figuring 
-out the issue asking in the ***#tech-support*** channel of our Discord for help with finding it is highly recommended. 
-The generator will put a zip folder into your `Archipelago\output` folder with the format `AP_XXXXXXXXX`.zip. 
-This contains the patch files and relevant mods for the players as well as the serverdata for the host.
-
-## Hosting a multiworld
-
-### Uploading the seed to the website
-The easiest and most recommended method is to generate the game on the website which will allow you to create a private
-room with all the necessary files you can share, as well as hosting the game and supporting item trackers for various games. 
-If for some reason the seed was rolled on a machine, then either the resulting zip file or the resulting `AP_XXXXX.archipelago`
-inside the zip file can be uploaded to the [upload page](/uploads). This will give a page with the seed info and have a 
-link to the spoiler if it exists. Click on Create New room and then share the link for the room with the other players 
-so that they can download their patches or mods. The room will also have a link to a Multiworld Tracker and tell you 
-what the players need to connect to from their clients. 
-
-### Hosting a seed locally
-For this we'll assume you have already port forwarding `38281` and have generated a seed that is still in the `outputs` 
-folder. Next, you'll want to run `ArchipelagoServer.exe`. A window will open in order to open the multiworld data for the 
-game. You can either use the generated zip folder or extract the .archipelago file and use it. If everything worked correctly the console window should tell you it's now hosting a game with the IP, port, and password that clients will need in order to connect.
-Extract the patch and mod files then send those to your friends, and you're done!

WebHostLib/static/assets/tutorial/archipelago/triggers_en.md

@@ -1,69 +0,0 @@
-# Archipelago Triggers Guide
-
-## What are triggers?
-Triggers allow you to customize your game settings by allowing you to define certain options or even a variety of 
-settings to occur or "trigger" under certain conditions. These are essentially "if, then statements" for options in your game. 
-A good example of what you can do with triggers is the custom 
-[mercenary mode](https://github.com/alwaysintreble/Archipelago-yaml-dump/blob/main/Snippets/Mercenary%20Mode%20Snippet.yaml) 
-that was created using entirely triggers and plando. For more information on plando you can reference 
-[this guide](/tutorial/archipelago/plando/en) or [this guide](/tutorial/zelda3/plando/en).
-
-## Trigger use
-Triggers have to be defined in the root of the yaml file meaning it must be outside of a game section. 
-The best place to do this is the bottom of the yaml.
-- Triggers comprise of the trigger section and then each trigger must have an `option_category`, `option_name`, and 
-`option_result` from which it will react to and then an `options` section where the definition of what will happen.
-- `option_category` is the defining section from which the option is defined in.
-    - Example: `A Link to the Past`
-    - This is the root category the option is located in. If the option you're triggering off of is in root then you 
-would use `null`, otherwise this is the game for which you want this option trigger to activate.
-- `option_name` is the option setting from which the triggered choice is going to react to.
-    - Example: `shop_item_slots` 
-    - This can be any option from any category defined in the yaml file in either root or a game section except for `game`.
-- `option_result` is the result of this option setting from which you would like to react.
-    - Example: `15`
-    - Each trigger must be used for exactly one option result. If you would like the same thing to occur with multiple 
-results you would need multiple triggers for this.
-- `options` is where you define what will happen when this is detected. This can be something as simple as ensuring 
-another option also gets selected or placing an item in a certain location. 
-    - Example: 
-  ```yaml
-  A Link to the Past:
-    start_inventory: 
-      Rupees (300): 2
-  ```
-This format must be:
-
-  ```yaml
-  root option:
-    option to change:
-      desired result
-  ```
-
-### Examples
-The above examples all together will end up looking like this:
-  ```yaml
-  triggers:
-    - option_category: A Link to the Past
-      option_name: shop_item_slots
-      option_result: 15
-      options:
-        A Link to the Past:
-          start_inventory:
-            Rupees(300): 2
-  ```
-
-For this example if the generator happens to roll 15 shuffled in shop item slots for your game you'll be granted 600 rupees at the beginning.
-These can also be used to change other options.
-
-For example:
-  ```yaml
-  triggers:
-    - option_category: Timespinner
-      option_name: SpecificKeycards
-      option_result: true
-      options:
-        Timespinner:
-          Inverted: true
-  ```
-In this example if your world happens to roll SpecificKeycards then your game will also start in inverted.

WebHostLib/static/assets/tutorial/factorio/setup_en.md

@@ -1,128 +0,0 @@
-# Factorio Randomizer Setup Guide
-
-## Required Software
-##### Players
-- [Factorio](https://factorio.com) - Needed by Players and Hosts
-
-##### Server Hosts
-- [Factorio](https://factorio.com) - Needed by Players and Hosts
-- [Archipelago](https://github.com/ArchipelagoMW/Archipelago/releases) - Needed by Hosts
-
-## Create a Config (.yaml) File
-
-### What is a config file and why do I need one?
-Your config file contains a set of configuration options which provide the generator with information about how it
-should generate your game. Each player of a multiworld will provide their own config file. This setup allows each
-player to enjoy an experience customized for their taste, and different players in the same multiworld can all have
-different options. 
-
-### Where do I get a config file?
-The [Player Settings](/games/Factorio/player-settings) page on the website allows you to configure
-your personal settings and export a config file from them.
-
-### Verifying your config file
-If you would like to validate your config file to make sure it works, you may do so on
-the [YAML Validator](/mysterycheck) page.
-
-## Connecting to Someone Else's Factorio Game
-Connecting to someone else's game is the simplest way to play Factorio with Archipelago. It allows multiple
-people to play in a single world, all contributing to the completion of the seed.
-
-1. Acquire the Archipelago mod for this seed. It should be named `AP_*.zip`, where `*` is the seed number.
-2. Copy the mod file into your Factorio `mods` folder, which by default is located at:  
-`C:\Users\YourName\AppData\Roaming\Factorio\mods`
-3. Get the server address from the person hosting the game you are joining
-4. Launch Factorio
-5. Click on "Multiplayer" in the main menu
-6. Click on "Connect to address"
-7. Enter the address into this box
-8. Click "Connect"
-
-## Prepare to Host Your Own Factorio Game
-
-### Defining Some Terms
-In Archipelago, multiple Factorio worlds may be played simultaneously. Each of these worlds must be hosted by a
-Factorio server, which is connected to the Archipelago Server via middleware.
-
-This guide uses the following terms to refer to the software:
-- **Factorio Client** - The Factorio instance which will be used to play the game.
-- **Factorio Server** - The Factorio instance which will be used to host the Factorio world. Any number of
-Factorio Clients may connect to this server.
-- **Archipelago Client** - The middleware software used to connect the Factorio Server to the Archipelago Server.
-- **Archipelago Server** - The central Archipelago server, which connects all games to each other.
-
-### What a Playable State Looks Like
-- An Archipelago Server
-- The generated Factorio Mod, created as a result of running `ArchipelagoGenerate.exe`
-- One running instance of `ArchipelagoFactorioClient.exe` (the Archipelago Client) per Factorio world
-- A running modded Factorio Server, which should have been started by the Archipelago Client automatically
-- A running modded Factorio Client
-
-### Dedicated Server Setup
-To play Factorio with Archipelago, a dedicated server setup is required. This dedicated Factorio Server must be
-installed separately from your main Factorio Client installation. The recommended way to install two instances
-of Factorio on your computer is to download the Factorio installer file directly from
-[factorio.com](https://factorio.com/download).
-
-#### If you purchased Factorio on Steam, GOG, etc.
-You can register your copy of Factorio on [factorio.com](https://factorio.com/). You will be required to
-create an account, if you have not done so already. As part of that process, you will be able to enter your
-Factorio product code. This will allow you to download the game directly from their website.
-
-#### Download the Standalone Version
-It is recommended to download the standalone version of Factorio for use as a dedicated server. Doing so prevents
-any potential conflicts with your currently-installed version of Factorio. Download the file by clicking on the
-button appropriate to your operating system, and extract the folder to a convenient location (we recommend
-C:\Factorio or similar).<br />
-<img src="/static/assets/tutorial/factorio/factorio-download.png" />
-
-Next, you should launch your Factorio Server by running `factorio.exe`, which is located at: `bin/x64/factorio.exe`.
-You will be asked to log-in to your Factorio account using the same credentials you used on Factorio's website.
-After you have logged in, you may close the game.
-
-#### Configure your Archipelago Installation
-You must modify your `host.yaml` file inside your Archipelago installation directory so that it points to your
-standalone Factorio executable. Here is an example of the appropriate setup, note the double `\\` are required:
-```yaml
-factorio_options:
-  executable:  C:\\factorio\\bin\\x64\\factorio"
-```
-
-With all that complete, you are now able to...
-
-## Host Your Own Factorio Game
-
-1. Obtain the Factorio mod for this Archipelago seed. It should be named `AP_*.zip`, where `*` is the seed number.
-2. Install the mod into your Factorio Server by copying the zip file into the `mods` folder.
-3. Install the mod into your Factorio Client by copying the zip file into the `mods` folder, which is likely located
-at `C:\Users\YourName\AppData\Roaming\Factorio\mods`.
-4. Obtain the Archipelago Server address from the website's host room, or from the server host.
-5. Run your Archipelago Client, which is named `ArchilepagoFactorioClient.exe`. This was installed along with
-Archipelago if you chose to include it during the installation process.
-6. Enter `/connect [server-address]` into the input box at the bottom of the Archipelago Client and press "Enter"
-<br /><img src="/static/assets/tutorial/factorio/connect-to-ap-server.png" />
-7. Launch your Factorio Client
-8. Click on "Multiplayer" in the main menu
-9. Click on "Connect to address"
-10. Enter `localhost` into the server address box
-11. Click "Connect"
-
-For additional client features, issue the `/help` command in the Archipelago Client. Once connected to the AP
-server, you can also issue the `!help` command to learn about additional commands like `!hint`. 
-
-## Allowing Other People to Join Your Game
-1. Ensure your Archipelago Client is running.
-2. Ensure port `34197` is forwarded to the computer running the Archipelago Client.
-3. Obtain your IP address by visiting [this website](https://whatismyip.com/).
-4. Provide your IP address to anyone you want to join your game, and have them follow the steps for
-"Connecting to Someone Else's Factorio Game" above.
-
-## Troubleshooting
-In case any problems should occur, the Archipelago Client will create a file `FactorioClient.txt` in the `/logs`.
-The contents of this file may help you troubleshoot an issue on your own and is vital for requesting help from other
-people in Archipelago.
-
-## Additional Resources
-- [Alternate Tutorial by Umenen](https://docs.google.com/document/d/1yZPAaXB-QcetD8FJsmsFrenAHO5V6Y2ctMAyIoT9jS4)
-- [Factorio Speedrun Guide](https://www.youtube.com/watch?v=ExLrmK1c7tA)
-- [Factorio Wiki](https://wiki.factorio.com/)

WebHostLib/static/assets/tutorial/ff1/multiworld_en.md

@@ -1,114 +0,0 @@
-# Final Fantasy 1 (NES) Multiworld Setup Guide
-
-## Required Software
-- The FF1Client which is bundled with [Archipelago](https://github.com/ArchipelagoMW/Archipelago/releases)
-- The [BizHawk](http://tasvideos.org/BizHawk.html) emulator. Versions 2.3.1 and higher are supported. 
-  Version 2.7 is recommended
-- Your Final Fantasy (USA Edition) ROM file, probably named `Final Fantasy (USA).nes`. Neither Archipelago.gg nor the 
-  Final Fantasy Randomizer Community can supply you with this.
-
-## Installation Procedures
-1. Download and install the latest version of [Archipelago](https://github.com/ArchipelagoMW/Archipelago/releases)
-   1. On Windows, download Setup.Archipelago.<HighestVersion>.exe and run it
-2. Assign Bizhawk version 2.3.1 or higher as your default program for launching `.nes` files.
-    1. Extract your Bizhawk folder to your Desktop, or somewhere you will remember. Below are optional additional
-       steps for loading ROMs more conveniently
-       1. Right-click on a ROM file and select **Open with...**
-       2. Check the box next to **Always use this app to open .nes files**
-       3. Scroll to the bottom of the list and click the grey text **Look for another App on this PC**
-       4. Browse for `EmuHawk.exe` located inside your Bizhawk folder (from step 1) and click **Open**.
-
-## Playing a Multiworld
-Playing a multiworld on Archipelago.gg has 3 key components:
-1. The Server which is hosting a game for all players.
-2. The Client Program. For Final Fantasy 1, it is a standalone program but other randomizers may build it in.
-3. The Game itself, in this case running on Bizhawk, which then connects to the Client running on your computer.
-
-To set this up the following steps are required:
-1. (Each Player) Generate your own yaml file and randomized ROM
-2. (Host Only) Generate a randomized game with you and 0 or more players using Archipelago
-3. (Host Only) Run the Archipelago Server
-4. (Each Player) Run your client program and connect it to the Server
-5. (Each Player) Run your game and connect it to your client program
-6. (Each Player) Play the game and have fun!
-
-### Obtaining your Archipelago yaml file and randomized ROM
-Unlike most other Archipelago.gg games Final Fantasy 1 is randomized by the 
-[main randomizer](https://finalfantasyrandomizer.com/). Generate a game by going to the site and performing the
-following steps:
-1. Select the randomization options (also known as `Flags` in the community) of your choice. If you do not know what 
-you prefer, or it is your first time playing select the "Archipelago" preset on the main page.
-2. Go to the `Beta` tab and ensure `Archipelago` is enabled. Set your player name to any name that represents you.
-3. Upload you `Final Fantasy(USA).nes` (and click `Remember ROM` for the future!)
-4. Press the `NEW` button beside `Seed` a few times
-5. Click `GENERATE ROM`
-
-It should download two files. One is the `*.nes` file which your emulator will run and the other is the yaml file
-required by Archipelago.gg
-
-### Generating the Multiworld and Starting the Server
-The game can be generated locally or by Archipelago.gg.
-
-#### Generating on Archipelago.gg (Recommended)
-1. Gather all yaml files
-2. Create a zip file containing all of the yaml files. Make sure it is a `*.zip` not a `*.7z` or a `*.rar`
-3. Navigate to the [Generate Page](https://archipelago.gg/generate) and click `Upload File`
-   1. For your first game keep `Forfeit Permission` as `Automatic on goal completion`. Forfeiting actually means
-      giving out all of the items remaining in your game in this case so you do not block anyone else.
-   2. For your first game keep `Hint Cost` at 10%
-4. Select your zip file
-
-#### Generating Locally
-1. Navigate to your Archipelago install directory
-2. Empty the `Players` directory then fill it with one yaml per player including your own which you got from the 
-   finalfantasyrandomizer website above
-3. Run `ArchipelagoGenerate.exe` (double-click it in File Explorer)
-4. You will find your generated game in the `output` directory
-
-#### Starting the server
-If you generated on Archipelago.gg click `Create New Room` on the results page to start your server
-If you generated locally simply navigate to the [Host Game Page](https://archipelago.gg/uploads) and upload the file
-in the `output` directory
-
-### Running the Client Program and Connecting to the Server
-1. Navigate to your Archipelago install folder and run `ArchipelagoFF1Client.exe`
-2. Notice the `/connect command` on the server hosting page (It should look like `/connect archipelago.gg:*****` where 
-   ***** are numbers)
-3. Type the connect command into the client OR add the port to the pre-populated address on the top bar (it should
-   already say `archipelago.gg`) and click `connect`
-
-#### Running Your Game and Connecting to the Client Program
-1. Open Bizhawk 2.3.1 or higher and load your ROM OR 
-   click your ROM file if it is already associated with the extension `*.nes`
-2. Click on the Tools menu and click on **Lua Console**
-3. Click the folder button to open a new Lua script. (CTL-O or **Script** -> **Open Script**)
-4. Navigate to the location you installed Archipelago to. Open data/lua/FF1/ff1_connector.lua
-   1. If it gives a `NLua.Exceptions.LuaScriptException: .\socket.lua:13: module 'socket.core' not found:` exception
-   close your emulator entirely, restart it and re-run these steps
-   2. If it says `Must use a version of bizhawk 2.3.1 or higher`, double-check your Bizhawk version by clicking 
-   **Help** -> **About**
-
-### Play the game
-When the client shows both NES and server are connected you are good to go. You can check the connection status of the
-NES at any time by running `/nes`
-
-### Helpful Commands
-Commands are broken into two types: `/` and `!` commands. The difference is that `/commands` are local to your machine
-and game whereas `!` commands ask the server. Most of the time you can use local commands.
-
-#### Local Commands
-- `/connect <address with port number>` connect to the multiworld server
-- `/disconnect` if you accidentally connected to the wrong port run this to disconnect and then reconnect using
-- `/nes` Shows the current status of the NES connection
-- `/received` Displays all the items you have found or been sent
-- `/missing` Displays all the locations along with their current status (checked/missing)
-- Just typing anything will broadcast a message to all players
-
-#### Remote Commands
-- `!hint <item name>` Tells you at which location in whose game your Item is. Note you need to have checked some locations
-to earn a hint. You can check how many you have by just running `!hint`
-- `!forfeit` If you didn't turn on auto-forfeit or you allowed forfeiting prior to goal completion. Remember that
-"forfeiting" actually means sending out your remaining items in your world
-
-#### Host only (on Archipelago.gg)
-`/forfeit <Player Name>` Forfeits someone regardless of settings and game completion status

WebHostLib/static/assets/tutorial/minecraft/minecraft_en.md

@@ -1,58 +0,0 @@
-# Minecraft Randomizer Setup Guide
-
-## Required Software
-
-- [Minecraft Java Edition](https://www.minecraft.net/en-us/store/minecraft-java-edition) (update 1.17.1)
-- [Archipelago](https://github.com/ArchipelagoMW/Archipelago/releases) (select `Minecraft Client` during installation.)
-
-## Configuring your YAML file
-
-### What is a YAML file and why do I need one?
-Your YAML file contains a set of configuration options which provide the generator with information about how
-it should generate your game. Each player of a multiworld will provide their own YAML file. This setup allows
-each player to enjoy an experience customized for their taste, and different players in the same multiworld
-can all have different options.
-
-### Where do I get a YAML file?
-you can customize your settings by visiting the [minecraft player settings](/games/Minecraft/player-settings)
-
-## Joining a MultiWorld Game
-
-### Obtain your Minecraft data file
-**Only one yaml file needs to be submitted per minecraft world regardless of how many players play on it.**
-
-When you join a multiworld game, you will be asked to provide your YAML file to whoever is hosting. Once that
-is done, the host will provide you with either a link to download your data file, or with a zip file containing
-everyone's data files. Your data file should have a `.apmc` extension.
-
-double-click on your `.apmc` file to have the minecraft client auto-launch the installed forge server.
-make sure to leave this window open as this is your server console.
-
-### Connect to the MultiServer
-Using minecraft 1.17.1 connect to the server `localhost`.
-
-Once in game type `/connect <AP-Address> (Port) (Password)` where `<AP-Address>` is the address of the
-Archipelago server. `(Port)` is only required if the Archipelago server is not using the default port of 38281. `(Password)`
-is only required if the Archipleago server you are using has a password set.
-
-### Play the game
-When the console tells you that you have joined the room, you're all set. Congratulations
-on successfully joining a multiworld game! At this point any additional minecraft players may connect to your
-forge server. to star the game once everyone is ready type `/start`. 
-
-### Useful commands
-- `!help` displays a list all server commands
-- `!hint` will display how many hint points you have, along with any hints that have been given that are related to your game.
-- `!hint (item)` will ask the server to tell you where (item) is
-- `!hint_location (location)` will ask the server to tell you what item is on (location)
-
-## Manual Installation
-it is highly recommended to ues the Archipelago installer to handle the installation of the forge server for you.
-support will not be given for those wishing to manually install forge. but for those of you who know how, and wish to
-do so the following links are the versions of the software we use.
-### Manual install Software links
-- [Minecraft Forge](https://files.minecraftforge.net/net/minecraftforge/forge/index_1.17.1.html)
-- [Minecraft Archipelago Randomizer Mod](https://github.com/KonoTyran/Minecraft_AP_Randomizer/releases)
-**DO NOT INSTALL THIS ON YOUR CLIENT**
-- [Java 16](https://docs.aws.amazon.com/corretto/latest/corretto-16-ug/downloads-list.html)
-

WebHostLib/static/assets/tutorial/ror2/setup_en.md

@@ -1,98 +0,0 @@
-# Risk of Rain 2 Setup Guide
-
-## Install using r2modman
-### Install r2modman
-Head on over to the r2modman page on Thunderstore and follow the installation instructions.
-
-[https://thunderstore.io/package/ebkr/r2modman/](https://thunderstore.io/package/ebkr/r2modman/)
-
-### Install Archipelago Mod using r2modman
-You can install the Archipelago mod using r2modman in one of two ways.
-
-[https://thunderstore.io/package/ArchipelagoMW/Archipelago/](https://thunderstore.io/package/ArchipelagoMW/Archipelago/)
-
-One, you can use the Thunderstore website and click on the "Install with Mod Manager" link.
-
-You can also search for the "Archipelago" mod in the r2modman interface.
-The mod manager should automatically install all necessary dependencies as well.
-
-### Running the Modded Game
-Click on the "Start modded" button in the top left in r2modman to start the game with the
-Archipelago mod installed.
-
-## Joining an Archipelago Session
-There will be a menu button on the right side of the screen in the character select menu. 
-Click it in order to bring up the in lobby mod config. 
-From here you can expand the Archipelago sections and fill in the relevant info.
-Keep password blank if there is no password on the server.
-
-Simply check `Enable Archipelago?` and when you start the run it will automatically connect.
-
-## Gameplay
-The Risk of Rain 2 players send checks by causing items to spawn in-game. That means opening chests or killing bosses, generally. 
-An item check is only sent out after a certain number of items are picked up. This count is configurable in the player's YAML.
-
-## YAML Settings
-An example YAML would look like this:
-```yaml
-description: Ijwu-ror2
-name: Ijwu
-
-game:
-  Risk of Rain 2: 1
-
-Risk of Rain 2:
-  total_locations: 15
-  total_revivals: 4
-  start_with_revive: true
-  item_pickup_step: 1
-  enable_lunar: true
-  item_weights:
-    default: 50
-    new: 0
-    uncommon: 0
-    legendary: 0
-    lunartic: 0
-    chaos: 0
-    no_scraps: 0
-    even: 0
-    scraps_only: 0
-  item_pool_presets: true
-  # custom item weights
-  green_scrap: 16
-  red_scrap: 4
-  yellow_scrap: 1
-  white_scrap: 32
-  common_item: 64
-  uncommon_item: 32
-  legendary_item: 8
-  boss_item: 4
-  lunar_item: 16
-  equipment: 32
-```
-
-| Name | Description | Allowed values |
-| ---- | ----------- | -------------- |
-| total_locations | The total number of location checks that will be attributed to the Risk of Rain player. This option is ALSO the total number of items in the item pool for the Risk of Rain player. | 10 - 100 |
-| total_revivals | The total number of items in the Risk of Rain player's item pool (items other players pick up for them) replaced with `Dio's Best Friend`. | 0 - 5 |
-| start_with_revive | Starts the player off with a `Dio's Best Friend`. Functionally equivalent to putting a `Dio's Best Friend` in your `starting_inventory`. | true/false |
-| item_pickup_step | The number of item pickups which you are allowed to claim before they become an Archipelago location check. | 0 - 5 |
-| enable_lunar | Allows for lunar items to be shuffled into the item pool on behalf of the Risk of Rain player. | true/false |
-| item_weights | Each option here is a preset item weight that can be used to customize your generate item pool with certain settings. | default, new, uncommon, legendary, lunartic, chaos, no_scraps, even, scraps_only |
-| item_pool_presets | A simple toggle to determine whether the item_weight presets are used or the custom item pool as defined below | true/false |
-| custom item weights | Each defined item here is a single item in the pool that will have a weight against the other items when the item pool gets generated. These values can be modified to adjust how frequently certain items appear | 0-100|
-
-
-Using the example YAML above: the Risk of Rain 2 player will have 15 total items which they can pick up for other players. (total_locations = 15)
-
-They will have 15 items waiting for them in the item pool which will be distributed out to the multiworld. (total_locations = 15)
-
-They will complete a location check every second item. (item_pickup_step = 1)
-
-They will have 4 of the items which other players can grant them replaced with `Dio's Best Friend`. (total_revivals = 4)
-
-The player will also start with a `Dio's Best Friend`. (start_with_revive = true)
-
-The player will have lunar items shuffled into the item pool on their behalf. (enable_lunar = true)
-
-The player will have the default preset generated item pool with the custom item weights being ignored. (item_weights: default and item_pool_presets: true)

WebHostLib/static/assets/tutorial/secret-of-evermore/multiworld_en.md

@@ -1,119 +0,0 @@
-# Secret of Evermore Setup Guide
-
-## Required Software
-- [SNI](https://github.com/alttpo/sni/releases) v0.0.59 or newer (included in Archipelago 0.2.1 setup)
-- Hardware or software capable of loading and playing SNES ROM files
-    - An emulator capable of connecting to SNI with ROM access
-        - [snes9x-rr](https://github.com/gocha/snes9x-rr/releases) or
-        - [BizHawk](http://tasvideos.org/BizHawk.html) or
-        - [bsnes-plus-nwa](https://github.com/black-sliver/bsnes-plus)
-    - Or SD2SNES, [FXPak Pro](https://krikzz.com/store/home/54-fxpak-pro.html), or other compatible hardware
-- Your Secret of Evermore US ROM file, probably named `Secret of Evermore (USA).sfc`
-
-## Create a Config (.yaml) File
-
-### What is a config file and why do I need one?
-Your config file contains a set of configuration options which provide the generator with information about how
-it should generate your game. Each player of a multiworld will provide their own config file. This setup allows
-each player to enjoy an experience customized for their taste, and different players in the same multiworld
-can all have different options.
-
-### Where do I get a config file?
-The [Player Settings](/games/Secret%20of%20Evermore/player-settings) page on the website allows you to configure your
-personal settings and export a config file from them.
-
-### Verifying your config file
-If you would like to validate your config file to make sure it works, you may do so on the
-[YAML Validator](/mysterycheck) page.
-
-## Generating a Single-Player Game
-Stand-alone "Evermizer" has a way of balancing single-player games, but may not always be on par feature-wise.
-Head over to [evermizer.com](https://evermizer.com) if you want to try the official stand-alone, otherwise read below.
-
-1. Navigate to the [Player Settings](/games/Secret%20of%20Evermore/player-settings) page, configure your options, and
-   click the "Generate Game" button.
-2. You will be presented with a "Seed Info" page.
-3. Click the "Create New Room" link.
-4. You will be presented with a server page, from which you can download your patch file.
-5. Run your patch file through [apbpatch](https://evermizer.com/apbpatch) and load it in your emulator or console.
-
-## Joining a MultiWorld Game
-
-### Obtain your patch file and create your ROM
-When you join a multiworld game, you will be asked to provide your config file to whoever is hosting. Once that
-is done, the host will provide you with either a link to download your patch file, or with a zip file containing
-everyone's patch files. Your patch file should have a `.apsoe` extension.
-
-Put your patch file on your desktop or somewhere convenient, open [apbpatch](https://evermizer.com/apbpatch) and
-generate your ROM from it. Load the ROM file in your emulator or console.
-
-### Connect to SNI
-
-#### With an emulator
-Start SNI either from the Archipelago install folder or the stand-alone version.
-If this is its first time launching, you may be prompted to allow it to communicate through the Windows Firewall.
-
-##### snes9x-rr
-1. Load your ROM file if it hasn't already been loaded.
-2. Click on the File menu and hover on **Lua Scripting**
-3. Click on **New Lua Script Window...**
-4. In the new window, click **Browse...**
-5. Select the `Connector.lua` file from your SNI installation:
-    * `SNI/lua/x86/Connector.lua` for 32bit snes9x-rr or
-    * `SNI/lua/x64/Connector.lua` for "x64" snes9x-rr
-6. Leave the Lua window open while you are playing.
-
-* If the script window complains about missing `socket.dll` make sure it is in the lua directory.
-* If the script window complains about "Bad EXE format", use the other Connector above (x86 <-> x64)
-
-##### BizHawk
-1. Ensure you have the BSNES core loaded. You may do this by clicking on the Tools menu in BizHawk and following
-   these menu options:  
-   `Config --> Cores --> SNES --> BSNES`  
-   Once you have changed the loaded core, you must restart BizHawk.
-2. Load your ROM file if it hasn't already been loaded.
-3. Click on the Tools menu and click on **Lua Console**
-4. Click the button to open a new Lua script.
-5. Select any `Connector.lua` file from your SNI installation
-
-##### bsnes-plus-nwa
-This should automatically connect to SNI.
-If this is its first time launching, you may be prompted to allow it to communicate through the Windows Firewall. 
-
-#### With hardware
-This guide assumes you have downloaded the correct firmware for your device. If you have not
-done so already, please do this now. SD2SNES and FXPak Pro users may download the appropriate firmware
-[here](https://github.com/RedGuyyyy/sd2snes/releases). Other hardware may find helpful information
-[on this page](http://usb2snes.com/#supported-platforms).
-
-1. Copy the ROM file to your SD card.
-2. Load the ROM file from the menu.
-
-### Open the client
-Open [ap-soeclient](http://evermizer.com/apclient) in a modern browser. Do not switch tabs, open it in a new window
-if you want to use the browser while playing. Do not minimize the window with the client.
-
-The client should automatically connect to SNI, the "SNES" status should change to green.
-
-### Connect to the Archipelago Server
-Enter `/connect server:port` in the client's command prompt and press enter. You'll find `server:port` on the same page
-that had the patch file.
-
-### Play the game
-When the game is loaded but not yet past the intro cutscene, the "Game" status is yellow. When the client shows "AP" as
-green and "Game" as yellow, you're ready to play. The intro can be skipped pressing the START button and "Game" should
-change to green. Congratulations on successfully joining a multiworld game!
-
-## Hosting a MultiWorld game
-The recommended way to host a game is to use our [hosting service](/generate). The process is relatively simple:
-
-1. Collect config files from your players.
-2. Create a zip file containing your players' config files.
-3. Upload that zip file to the website linked above.
-4. Wait a moment while the seed is generated.
-5. When the seed is generated, you will be redirected to a "Seed Info" page.
-6. Click "Create New Room". This will take you to the server page. Provide the link to this page to your players,
-   so they may download their patch files from there.
-7. Note that a link to a MultiWorld Tracker is at the top of the room page. The tracker shows the progress of all
-   players in the game. Any observers may also be given the link to this page.
-8. Once all players have joined, you may begin playing.

WebHostLib/static/assets/tutorial/super-metroid/multiworld_en.md

@@ -1,126 +0,0 @@
-# Super Metroid Setup Guide
-
-## Required Software
-- [Super Metroid Client](https://github.com/ArchipelagoMW/SuperMetroidClient/releases)
-- **sniConnector.lua** (located on the client download page)
-- [SNI](https://github.com/alttpo/sni/releases) (Included in the Super Metroid Client)
-- Hardware or software capable of loading and playing SNES ROM files
-    - An emulator capable of connecting to SNI
-      ([snes9x Multitroid](https://drive.google.com/drive/folders/1_ej-pwWtCAHYXIrvs5Hro16A1s9Hi3Jz),
-      [BizHawk](http://tasvideos.org/BizHawk.html))
-    - An SD2SNES, [FXPak Pro](https://krikzz.com/store/home/54-fxpak-pro.html), or other compatible hardware
-- Your Super Metroid ROM file, probably named `Super Metroid (Japan, USA).sfc`
-
-## Installation Procedures
-
-### Windows Setup
-1. Download and install the Super Metroid Client from the link above, making sure to install the most recent version.
-**The file is located in the assets section at the bottom of the version information**.
-2. During setup, you will be asked to locate your base ROM file. This is your Super Metroid ROM file.
-3. If you are using an emulator, you should assign your Lua capable emulator as your default program
-for launching ROM files.
-    1. Extract your emulator's folder to your Desktop, or somewhere you will remember. 
-    2. Right-click on a ROM file and select **Open with...**
-    3. Check the box next to **Always use this app to open .sfc files**
-    4. Scroll to the bottom of the list and click the grey text **Look for another App on this PC**
-    5. Browse for your emulator's `.exe` file and click **Open**. This file should be located inside
-       the folder you extracted in step one.
-
-### Macintosh Setup
-- We need volunteers to help fill this section! Please contact **Farrak Kilhn** on Discord if you want to help.
-
-## Create a Config (.yaml) File
-
-### What is a config file and why do I need one?
-Your config file contains a set of configuration options which provide the generator with information about how
-it should generate your game. Each player of a multiworld will provide their own config file. This setup allows
-each player to enjoy an experience customized for their taste, and different players in the same multiworld
-can all have different options.
-
-### Where do I get a config file?
-The [Player Settings](/games/Super%20Metroid/player-settings) page on the website allows you to configure your
-personal settings and export a config file from them.
-
-### Verifying your config file
-If you would like to validate your config file to make sure it works, you may do so on the
-[YAML Validator](/mysterycheck) page.
-
-## Generating a Single-Player Game
-1. Navigate to the [Player Settings](/games/Super%20Metroid/player-settings) page, configure your options, and click
-   the "Generate Game" button.
-2. You will be presented with a "Seed Info" page.
-3. Click the "Create New Room" link.
-4. You will be presented with a server page, from which you can download your patch file.
-5. Double-click on your patch file, and the Super Metroid Client will launch automatically, create your ROM from
-   the patch file, and open your emulator for you.
-6. Since this is a single-player game, you will no longer need the client, so feel free to close it.
-
-## Joining a MultiWorld Game
-
-### Obtain your patch file and create your ROM
-When you join a multiworld game, you will be asked to provide your config file to whoever is hosting. Once that
-is done, the host will provide you with either a link to download your patch file, or with a zip file containing
-everyone's patch files. Your patch file should have a `.apm3` extension.
-
-Put your patch file on your desktop or somewhere convenient, and double click it. This should automatically
-launch the client, and will also create your ROM in the same place as your patch file.
-
-### Connect to the client
-
-#### With an emulator
-When the client launched automatically, SNI should have also automatically launched in the background.
-If this is its first time launching, you may be prompted to allow it to communicate through the Windows
-Firewall.
-
-##### snes9x Multitroid
-1. Load your ROM file if it hasn't already been loaded.
-2. Click on the File menu and hover on **Lua Scripting**
-3. Click on **New Lua Script Window...**
-4. In the new window, click **Browse...**
-5. Select the `sniConnector.lua` file you downloaded above
-
-##### BizHawk
-1. Ensure you have the BSNES core loaded. You may do this by clicking on the Tools menu in BizHawk and following
-   these menu options:  
-   `Config --> Cores --> SNES --> BSNES`  
-   Once you have changed the loaded core, you must restart BizHawk.
-2. Load your ROM file if it hasn't already been loaded.
-3. Click on the Tools menu and click on **Lua Console**
-4. Click the button to open a new Lua script.
-5. Select the `sniConnector.lua` file you downloaded above
-
-#### With hardware
-This guide assumes you have downloaded the correct firmware for your device. If you have not
-done so already, please do this now. SD2SNES and FXPak Pro users may download the appropriate firmware
-[here](https://github.com/RedGuyyyy/sd2snes/releases). Other hardware may find helpful information
-[on this page](http://usb2snes.com/#supported-platforms).
-
-1. Close your emulator, which may have auto-launched.
-2. Power on your device and load the ROM.
-
-### Connect to the Archipelago Server
-The patch file which launched your client should have automatically connected you to the AP Server.
-There are a few reasons this may not happen however, including if the game is hosted on the website but
-was generated elsewhere. If the client window shows "Server Status: Not Connected", simply ask the host
-for the address of the server, and copy/paste it into the "Server" input field then press enter.
-
-The client will attempt to reconnect to the new server address, and should momentarily show "Server
-Status: Connected".
-
-### Play the game
-When the client shows both SNES Device and Server as connected, you're ready to begin playing. Congratulations
-on successfully joining a multiworld game!
-
-## Hosting a MultiWorld game
-The recommended way to host a game is to use our [hosting service](/generate). The process is relatively simple:
-
-1. Collect config files from your players.
-2. Create a zip file containing your players' config files.
-3. Upload that zip file to the website linked above.
-4. Wait a moment while the seed is generated.
-5. When the seed is generated, you will be redirected to a "Seed Info" page.
-6. Click "Create New Room". This will take you to the server page. Provide the link to this page to your players,
-   so they may download their patch files from there.
-7. Note that a link to a MultiWorld Tracker is at the top of the room page. The tracker shows the progress of all
-   players in the game. Any observers may also be given the link to this page.
-8. Once all players have joined, you may begin playing.

WebHostLib/static/assets/tutorial/timespinner/setup_en.md

@@ -1,60 +0,0 @@
-# Timespinner Randomizer Setup Guide
-
-## Required Software
-
-- [Timespinner (steam)](https://store.steampowered.com/app/368620/Timespinner/) or [Timespinner (drm free)](https://www.humblebundle.com/store/timespinner)
-- [Timespinner Randomizer](https://github.com/JarnoWesthof/TsRandomizer)
-
-## General Concept
-
-The timespinner Randomizer loads Timespinner.exe from the same folder, and alters its state in memory to allow for randomization of the items
-
-## Installation Procedures
-
-Download latest version of [Timespinner Randomizer](https://github.com/JarnoWesthof/TsRandomizer) you can find the .zip files on the releases page, download the zip for your current platform. Then extract the zip to the folder where your Timespinner game is installed. Then just run TsRandomizer.exe instead of Timespinner.exe to start the game in randomized mode, for more info see the [readme](https://github.com/JarnoWesthof/TsRandomizer)
-    
-## Joining a MultiWorld Game
-
-1. Run TsRandomizer.exe
-2. Select "New Game"
-3. Switch "<< Select Seed >>" to "<< Archiplago >>" by pressing left on the controller or keyboard 
-4. Select "<< Archiplago >>" to open a new menu where you can enter your Archipelago login credentails
-	* NOTE: the input fields support Ctrl + V pasting of values
-5. Select "Connect"
-6. If all went well you will be taken back the difficulty selection menu and the game will start as soon as you select a difficulty
-
-## YAML Settings
-An example YAML would look like this:
-```yaml
-description: Default Timespinner Template
-name: Lunais{number} # Your name in-game. Spaces will be replaced with underscores and there is a 16 character limit
-game:
-  Timespinner: 1
-requires:
-  version: 0.1.8
-Timespinner:
-  StartWithJewelryBox: # Start with Jewelry Box unlocked
-    false: 50
-    true: 0
-  DownloadableItems: # With the tablet you will be able to download items at terminals
-    false: 50
-    true: 50
-  FacebookMode: # Requires Oculus Rift(ng) to spot the weakspots in walls and floors
-    false: 50
-    true: 0
-  StartWithMeyef: # Start with Meyef, ideal for when you want to play multiplayer
-    false: 50
-    true: 50
-  QuickSeed: # Start with Talaria Attachment, Nyoom!
-    false: 50
-    true: 0
-  SpecificKeycards: # Keycards can only open corresponding doors
-    false: 0
-    true: 50
-  Inverted: # Start in the past
-    false: 50
-    true: 50
-```
-* All Options are either enabled or not, if values are specified for both true & false the generator will select one based on weight
-* The Timespinner Randomizer option "StinkyMaw" is currently always enabled for Archipelago generated seeds
-* The Timespinner Randomizer options "ProgressiveVerticalMovement" & "ProgressiveKeycards" are currently not supported on Archipelago generated seeds

WebHostLib/static/assets/tutorial/tutorials.json

@@ -1,346 +0,0 @@
-[
-  {
-    "gameTitle": "Archipelago",
-    "tutorials": [
-      {
-        "name": "Multiworld Setup Tutorial",
-        "description": "A guide to setting up the Archipelago software to generate and host multiworld games on your computer and using the website.",
-        "files": [
-          {
-            "language": "English",
-            "filename": "archipelago/setup_en.md",
-            "link": "archipelago/setup/en",
-            "authors": [
-              "alwaysintreble"
-            ]
-          }
-        ]
-      },
-      {
-        "name": "Using Advanced Settings",
-        "description": "A guide to reading yaml files and editing them to fully customize your game.",
-        "files": [
-          {
-            "language": "English",
-            "filename": "archipelago/advanced_settings_en.md",
-            "link": "archipelago/advanced_settings/en",
-            "authors": [
-              "alwaysintreble"
-            ]
-          }
-        ]
-      },
-      {
-        "name": "Archipelago Triggers Guide",
-        "description": "A guide to setting up and using triggers in your game settings.",
-        "files": [
-          {
-            "language": "English",
-            "filename": "archipelago/triggers_en.md",
-            "link": "archipelago/triggers/en",
-            "authors": [
-              "alwaysintreble"
-            ]
-          }
-        ]
-      },
-      {
-        "name": "Archipelago Plando Guide",
-        "description": "A guide to understanding and using plando for your game.",
-        "files": [
-          {
-            "language": "English",
-            "filename": "archipelago/plando_en.md",
-            "link": "archipelago/plando/en",
-            "authors": [
-              "alwaysintreble"
-            ]
-          }
-        ]
-      }
-    ]
-  },
-  {
-    "gameTitle": "The Legend of Zelda: A Link to the Past",
-    "tutorials": [
-      {
-        "name": "Multiworld Setup Tutorial",
-        "description": "A guide to setting up the Archipelago ALttP software on your computer. This guide covers single-player, multiworld, and related software.",
-        "files": [
-          {
-            "language": "English",
-            "filename": "zelda3/multiworld_en.md",
-            "link": "zelda3/multiworld/en",
-            "authors": [
-              "Farrak Kilhn"
-            ]
-          },
-          {
-            "language": "Deutsch",
-            "filename": "zelda3/multiworld_de.md",
-            "link": "zelda3/multiworld/de",
-            "authors": [
-              "Fischfilet"
-            ]
-          },
-          {
-            "language": "Español",
-            "filename": "zelda3/multiworld_es.md",
-            "link": "zelda3/multiworld/es",
-            "authors": [
-              "Edos"
-            ]
-          },
-          {
-            "language": "Français",
-            "filename": "zelda3/multiworld_fr.md",
-            "link": "zelda3/multiworld/fr",
-            "authors": [
-              "Coxla"
-            ]
-          }
-        ]
-      },
-      {
-        "name": "MSU-1 Setup Tutorial",
-        "description": "A guide to setting up MSU-1, which allows for custom in-game music.",
-        "files": [
-          {
-            "language": "English",
-            "filename": "zelda3/msu1_en.md",
-            "link": "zelda3/msu1/en",
-            "authors": [
-              "Farrak Kilhn"
-            ]
-          },
-          {
-            "language": "Español",
-            "filename": "zelda3/msu1_es.md",
-            "link": "zelda3/msu1/es",
-            "authors": [
-              "Edos"
-            ]
-          },
-          {
-            "language": "Français",
-            "filename": "msu1_fr.md",
-            "link": "zelda3/msu1/fr",
-            "authors": [
-              "Coxla"
-            ]
-          }
-        ]
-      },
-      {
-        "name": "Plando Tutorial",
-        "description": "A guide to creating Multiworld Plandos",
-        "files": [
-          {
-            "language": "English",
-            "filename": "zelda3/plando_en.md",
-            "link": "zelda3/plando/en",
-            "authors": [
-              "Berserker"
-            ]
-          }
-        ]
-      }
-    ]
-  },
-  {
-    "gameTitle": "The Legend of Zelda: Ocarina of Time",
-    "tutorials": [
-      {
-        "name": "Multiworld Setup Tutorial",
-        "description": "A guide to setting up the Archipelago Ocarina of Time software on your computer.",
-        "files": [
-          {
-            "language": "English",
-            "filename": "zelda5/setup_en.md",
-            "link": "zelda5/setup/en",
-            "authors": [
-              "Edos"
-            ]
-          },
-          {
-            "language": "Spanish",
-            "filename": "zelda5/setup_es.md",
-            "link": "zelda5/setup/es",
-            "authors": [
-              "Edos"
-            ]
-          }
-        ]
-      }
-    ]
-  },
-  {
-    "gameTitle": "Factorio",
-    "tutorials": [
-      {
-        "name": "Multiworld Setup Tutorial",
-        "description": "A guide to setting up the Archipelago Factorio software on your computer.",
-        "files": [
-          {
-            "language": "English",
-            "filename": "factorio/setup_en.md",
-            "link": "factorio/setup/en",
-            "authors": [
-              "Berserker",
-              "Farrak Kilhn"
-            ]
-          }
-        ]
-      }
-    ]
-  },
-  {
-    "gameTitle": "Minecraft",
-    "tutorials": [
-      {
-        "name": "Multiworld Setup Tutorial",
-        "description": "A guide to setting up the Archipelago Minecraft software on your computer. This guide covers single-player, multiworld, and related software.",
-        "files": [
-          {
-            "language": "English",
-            "filename": "minecraft/minecraft_en.md",
-            "link": "minecraft/minecraft/en",
-            "authors": [
-              "Kono Tyran"
-            ]
-          },
-          {
-            "language": "Spanish",
-            "filename": "minecraft/minecraft_es.md",
-            "link": "minecraft/minecraft/es",
-            "authors": [
-              "Edos"
-            ]
-          },
-          {
-            "language": "Swedish",
-            "filename": "minecraft/minecraft_sv.md",
-            "link": "minecraft/minecraft/sv",
-            "authors": [
-              "Albinum"
-            ]
-          }
-        ]
-      }
-    ]
-  },
-  {
-    "gameTitle": "Risk of Rain 2",
-    "tutorials": [
-      {
-        "name": "Multiworld Setup Guide",
-        "description": "A guide to setting up the Risk of Rain 2 integration for Archipelago multiworld games.",
-        "files": [
-          {
-            "language": "English",
-            "filename": "ror2/setup_en.md",
-            "link": "ror2/setup/en",
-            "authors": [
-              "Ijwu"
-            ]
-          }
-        ]
-      }
-    ]
-  },
-  {
-    "gameTitle": "Timespinner",
-    "tutorials": [
-      {
-        "name": "Multiworld Setup Guide",
-        "description": "A guide to setting up the Timespinner randomizer connected to an Archipelago Multiworld",
-        "files": [
-          {
-            "language": "English",
-            "filename": "timespinner/setup_en.md",
-            "link": "timespinner/setup/en",
-            "authors": [
-              "Jarno"
-            ]
-          }
-        ]
-      }
-    ]
-  },
-  {
-    "gameTitle": "Subnautica",
-    "tutorials": [
-      {
-        "name": "Multiworld Setup Guide",
-        "description": "A guide to setting up the Subnautica randomizer connected to an Archipelago Multiworld",
-        "files": [
-          {
-            "language": "English",
-            "filename": "Subnautica/setup_en.md",
-            "link": "Subnautica/setup/en",
-            "authors": [
-              "Berserker"
-            ]
-          }
-        ]
-      }
-    ]
-  },
-  {
-    "gameTitle": "Super Metroid",
-    "tutorials": [
-      {
-        "name": "Multiworld Setup Guide",
-        "description": "A guide to setting up the Super Metroid Client on your computer. This guide covers single-player, multiworld, and related software.",
-        "files": [
-          {
-            "language": "English",
-            "filename": "super-metroid/multiworld_en.md",
-            "link": "super-metroid/multiworld/en",
-            "authors": [
-              "Farrak Kilhn"
-            ]
-          }
-        ]
-      }
-    ]
-  },
-  {
-    "gameTitle": "Secret of Evermore",
-    "tutorials": [
-      {
-        "name": "Multiworld Setup Guide",
-        "description": "A guide to playing Secret of Evermore randomizer. This guide covers single-player, multiworld and related software.",
-        "files": [
-          {
-            "language": "English",
-            "filename": "secret-of-evermore/multiworld_en.md",
-            "link": "secret-of-evermore/multiworld/en",
-            "authors": [
-              "Black Sliver"
-            ]
-          }
-        ]
-      }
-    ]
-  },
-  {
-    "gameTitle": "Final Fantasy",
-    "tutorials": [
-      {
-        "name": "Multiworld Setup Guide",
-        "description": "A guide to playing Final Fantasy multiworld. This guide only covers playing multiworld.",
-        "files": [
-          {
-            "language": "English",
-            "filename": "ff1/multiworld_en.md",
-            "link": "ff1/multiworld/en",
-            "authors": [
-              "jat2980"
-            ]
-          }
-        ]
-      }
-    ]
-  }
-]

WebHostLib/static/assets/tutorial/zelda3/msu1_en.md

@@ -1,77 +0,0 @@
-# MSU-1 Setup Guide
-
-## What is MSU-1?
-MSU-1 allows for the use of custom in-game music. It works on original hardware, the SuperNT, and certain emulators.
-This guide will explain how to find custom music packages, often called MSU packs, and how to configure
-them for use with original hardware, the SuperNT, and the snes9x emulator.
-
-## Where to find MSU Packs
-MSU packs are constantly in development. You can find a list of completed packs, as well as in-development packs on
-[this Google Spreadsheet](https://docs.google.com/spreadsheets/d/1XRkR4Xy6S24UzYkYBAOv-VYWPKZIoUKgX04RbjF128Q).
-
-## What an MSU pack should look like
-MSU packs contain many files, most of which are the music files which will be used when playing the game. These files
-should be named similarly, with a hyphenated number at the end, and with a `.pcm` extension. It does not matter what
-each music file is named, so long as they all follow the same pattern. The most popular filename you will find is
-`alttp_msu-X.pcm`, where X is replaced by a number.
-
-There is one other type of file you should find inside an MSU pack's folder. This file indicates to the hardware or
-to the emulator that MSU should be enabled for this game. This file should be named similarly to the other files in
-the folder, but will have a `.msu` extension and be 0 KB in size.
-
-A short example of the contents of an MSU pack folder are as follows:
-```
-List of files inside an MSU pack folder:
-alttp_msu.msu
-alttp_msu-1.pcm
-alttp_msu-2.pcm
-...
-alttp_msu-34.pcm
-```
-
-## How to use an MSU Pack
-In all cases, you must rename your ROM file to match the pattern of names inside your MSU pack's folder, then place
-your ROM file inside that folder.
-
-This will cause the folder contents to look like the following:
-```
-List of files inside an MSU pack folder:
-alttp_msu.msu
-alttp_msu.sfc    <-- Add your ROM file
-alttp_msu-1.pcm
-alttp_msu-2.pcm
-...
-alttp_msu-34.pcm
-```
-
-### With snes9x
-1. Load the ROM file from snes9x.
-
-### With SD2SNES / FXPak on original hardware
-1. Load the MSU pack folder onto your SD2SNES / FXPak.
-2. Navigate into the MSU pack folder and load your ROM.
-
-### With SD2SNES / FXPak on SuperNT
-1. Load the MSU pack folder onto your SD2SNES / FXPak.
-2. Power on your SuperNT and navigate to the `Settings` menu.
-3. Enter the `Audio` settings.
-4. Check the box marked `Cartridge Audio Enable.`
-5. Navigate back to the previous menu.
-6. Choose `Save/Clear Settings`.
-7. Choose `Save Settings`.
-8. Choose `Run Cartridge` from the main menu.
-9. Navigate into your MSU pack folder and load your ROM.
-
-## A word of caution to streamers
-Many MSU packs use copyrighted music which is not permitted for use on platforms like Twitch and YouTube.
-If you choose to stream music from an MSU pack, please ensure you have permission to do so. If you stream
-music which has not been licensed to you, or licensed for use in a stream in general, your VOD may be muted. 
-In the worst case, you may receive a DMCA take-down notice. Please be careful to only stream music for which
-you have the rights to do so.
-
-##### Stream-safe MSU packs
-Below is a list of MSU packs which, so far as we know, are safe to stream. More will be added to this list as
-we learn of them. If you know of any we missed, please let us know!
-- Vanilla Game Music
-- [Smooth McGroove](https://drive.google.com/open?id=1JDa1jCKg5hG0Km6xNpmIgf4kDMOxVp3n)
-- Zelda community member Amarith assembled the following list for the purpose of competitive restreams.  While we have not ourselves verified this list, all submissions required VoD proof they were not muted.  Generally speaking, MSU-1 packs are less safe if they contain lyrics at any point.  This list was only tested on Twitch and results for other platforms may vary. [Restream-Safe List](https://tinyurl.com/MSUsApprovedForLeagueChannels)

WebHostLib/static/assets/tutorial/zelda3/multiworld_en.md

@@ -1,128 +0,0 @@
-# A Link to the Past Randomizer Setup Guide
-
-## Required Software
-- [Z3Client](https://github.com/ArchipelagoMW/Z3Client/releases) or the SNIClient included with
-[Archipelago](https://github.com/ArchipelagoMW/Archipelago/releases)
-    - If installing Archipelago, make sure to check the box for SNIClient -> A Link to the Past Patch Setup during install, or SNI will not be included
-- [SNI](https://github.com/alttpo/sni/releases) (Included in both Z3Client and SNIClient)
-- Hardware or software capable of loading and playing SNES ROM files
-    - An emulator capable of connecting to SNI
-      ([snes9x Multitroid](https://drive.google.com/drive/folders/1_ej-pwWtCAHYXIrvs5Hro16A1s9Hi3Jz),
-      [BizHawk](http://tasvideos.org/BizHawk.html))
-    - An SD2SNES, [FXPak Pro](https://krikzz.com/store/home/54-fxpak-pro.html), or other compatible hardware
-- Your Japanese v1.0 ROM file, probably named `Zelda no Densetsu - Kamigami no Triforce (Japan).sfc`
-
-## Installation Procedures
-1. Download and install your preferred client from the link above, making sure to install the most recent version.
-**The installer file is located in the assets section at the bottom of the version information**.
-    - During setup, you will be asked to locate your base ROM file. This is your Japanese Link to the Past ROM file.
-
-2. If you are using an emulator, you should assign your Lua capable emulator as your default program
-for launching ROM files.
-    1. Extract your emulator's folder to your Desktop, or somewhere you will remember. 
-    2. Right-click on a ROM file and select **Open with...**
-    3. Check the box next to **Always use this app to open .sfc files**
-    4. Scroll to the bottom of the list and click the grey text **Look for another App on this PC**
-    5. Browse for your emulator's `.exe` file and click **Open**. This file should be located inside
-       the folder you extracted in step one.
-
-## Create a Config (.yaml) File
-
-### What is a config file and why do I need one?
-Your config file contains a set of configuration options which provide the generator with information about how
-it should generate your game. Each player of a multiworld will provide their own config file. This setup allows
-each player to enjoy an experience customized for their taste, and different players in the same multiworld
-can all have different options.
-
-### Where do I get a config file?
-The [Player Settings](/games/A%20Link%20to%20the%20Past/player-settings) page on the website allows you to configure
-your personal settings and export a config file from them.
-
-### Verifying your config file
-If you would like to validate your config file to make sure it works, you may do so on the
-[YAML Validator](/mysterycheck) page.
-
-## Generating a Single-Player Game
-1. Navigate to the [Player Settings](/games/A%20Link%20to%20the%20Past/player-settings) page, configure your options,
-   and click the "Generate Game" button.
-2. You will be presented with a "Seed Info" page.
-3. Click the "Create New Room" link.
-4. You will be presented with a server page, from which you can download your patch file.
-5. Double-click on your patch file, and the Z3Client will launch automatically, create your ROM from
-   the patch file, and open your emulator for you.
-6. Since this is a single-player game, you will no longer need the client, so feel free to close it.
-
-## Joining a MultiWorld Game
-
-### Obtain your patch file and create your ROM
-When you join a multiworld game, you will be asked to provide your config file to whoever is hosting. Once that
-is done, the host will provide you with either a link to download your patch file, or with a zip file containing
-everyone's patch files. Your patch file should have a `.apbp` extension.
-
-Put your patch file on your desktop or somewhere convenient, and double click it. This should automatically
-launch the client, and will also create your ROM in the same place as your patch file.
-
-### Connect to the client
-
-#### With an emulator
-When the client launched automatically, SNI should have also automatically launched in the background.
-If this is its first time launching, you may be prompted to allow it to communicate through the Windows
-Firewall.
-
-##### snes9x Multitroid
-1. Load your ROM file if it hasn't already been loaded.
-2. Click on the File menu and hover on **Lua Scripting**
-3. Click on **New Lua Script Window...**
-4. In the new window, click **Browse...**
-5. Select the connector lua file included with your client
-     - Z3Client users should download `sniConnector.lua` from the client download page
-     - SNIClient users should look in their Archipelago folder for `/sni/lua`
-
-##### BizHawk
-1. Ensure you have the BSNES core loaded. You may do this by clicking on the Tools menu in BizHawk and following
-   these menu options:  
-   `Config --> Cores --> SNES --> BSNES`  
-   Once you have changed the loaded core, you must restart BizHawk.
-2. Load your ROM file if it hasn't already been loaded.
-3. Click on the Tools menu and click on **Lua Console**
-4. Click Script -> Open Script...
-5. Select the `Connector.lua` file you downloaded above
-     - Z3Client users should download `sniConnector.lua` from the client download page
-     - SNIClient users should look in their Archipelago folder for `/sni/lua`
-6. Run the script by double-clicking it in the listing
-
-#### With hardware
-This guide assumes you have downloaded the correct firmware for your device. If you have not
-done so already, please do this now. SD2SNES and FXPak Pro users may download the appropriate firmware
-[here](https://github.com/RedGuyyyy/sd2snes/releases). Other hardware may find helpful information
-[on this page](http://usb2snes.com/#supported-platforms).
-
-1. Close your emulator, which may have auto-launched.
-2. Power on your device and load the ROM.
-
-### Connect to the Archipelago Server
-The patch file which launched your client should have automatically connected you to the AP Server.
-There are a few reasons this may not happen however, including if the game is hosted on the website but
-was generated elsewhere. If the client window shows "Server Status: Not Connected", simply ask the host
-for the address of the server, and copy/paste it into the "Server" input field then press enter.
-
-The client will attempt to reconnect to the new server address, and should momentarily show "Server
-Status: Connected".
-
-### Play the game
-When the client shows both SNES Device and Server as connected, you're ready to begin playing. Congratulations
-on successfully joining a multiworld game!
-
-## Hosting a MultiWorld game
-The recommended way to host a game is to use our [hosting service](/generate). The process is relatively simple:
-
-1. Collect config files from your players.
-2. Create a zip file containing your players' config files.
-3. Upload that zip file to the website linked above.
-4. Wait a moment while the seed is generated.
-5. When the seed is generated, you will be redirected to a "Seed Info" page.
-6. Click "Create New Room". This will take you to the server page. Provide the link to this page to your players,
-   so they may download their patch files from there.
-7. Note that a link to a MultiWorld Tracker is at the top of the room page. The tracker shows the progress of all
-   players in the game. Any observers may also be given the link to this page.
-8. Once all players have joined, you may begin playing.

WebHostLib/static/assets/tutorialLanding.js

@@ -23,6 +23,7 @@ window.addEventListener('load', () => {
       games.forEach((game) => {
         const gameTitle = document.createElement('h2');
         gameTitle.innerText = game.gameTitle;
+        gameTitle.id = `${encodeURIComponent(game.gameTitle)}`;
         tutorialDiv.appendChild(gameTitle);
 
         game.tutorials.forEach((tutorial) => {
@@ -65,7 +66,16 @@ window.addEventListener('load', () => {
       showError();
       console.error(error);
     }
+
+    // Check if we are on an anchor when coming in, and scroll to it.
+    const hash = window.location.hash;
+    if (hash) {
+      const offset = 128;  // To account for navbar banner at top of page.
+      window.scrollTo(0, 0);
+      const rect = document.getElementById(hash.slice(1)).getBoundingClientRect();
+      window.scrollTo(rect.left, rect.top - offset);
+    }
   };
-  ajax.open('GET', `${window.location.origin}/static/assets/tutorial/tutorials.json`, true);
+  ajax.open('GET', `${window.location.origin}/static/generated/tutorials.json`, true);
   ajax.send();
 });

WebHostLib/static/assets/userContent.js

@@ -6,6 +6,7 @@ window.addEventListener('load', () => {
         "order": [[ 3, "desc" ]],
         "info": false,
         "dom": "t",
+        "stateSave": true,
     });
   $("#seeds-table").DataTable({
         "paging": false,
@@ -13,5 +14,6 @@ window.addEventListener('load', () => {
         "order": [[ 2, "desc" ]],
         "info": false,
         "dom": "t",
+        "stateSave": true,
     });
 });

WebHostLib/static/static/backgrounds/LICENSE

@@ -1,4 +1,3 @@
-Copyright 2020 Berserker66 (Fabian Dill)
-Copyright 2020 LegendaryLinux (Chris Wilson)
+Copyright 2022 LegendaryLinux (Chris Wilson)
 
 All rights reserved.