fix initial lobby position commands across NTE/proto boundary

Should probably ask Flycast to do this automatically with zero values.

.clang-format

@@ -0,0 +1,28 @@
+Standard: c++20
+BasedOnStyle: LLVM
+IndentWidth: 2
+ColumnLimit: 0
+AccessModifierOffset: -2
+NamespaceIndentation: None
+BreakBeforeBraces: Custom
+PointerAlignment: Left
+IndentCaseLabels: true
+PackConstructorInitializers: CurrentLine
+BraceWrapping:
+  AfterEnum: false
+  AfterStruct: false
+  AfterClass: false
+  SplitEmptyFunction: false
+  AfterControlStatement: false
+  AfterNamespace: false
+  AfterFunction: false
+  AfterUnion: false
+  AfterExternBlock: false
+  BeforeCatch: false
+  BeforeElse: false
+  SplitEmptyRecord: false
+  SplitEmptyNamespace: false
+AlignTrailingComments: false
+AlignAfterOpenBracket: DontAlign
+AlignOperands: DontAlign
+AlignEscapedNewlines: Left

.gitignore

@@ -15,13 +15,15 @@ Testing
 
 # Files modified by the user and/or server that don't have defaults
 system/config.json
+system/ep3/battle-records/*.mzrd
 system/ep3/tournament-state.json
-system/ep3/maps-free/*.bind
-system/ep3/maps-quest/*.bind
 system/licenses.nsi
-system/players/player_*
-system/players/account_*
-system/players/bank_*
+system/licenses/*.json
+system/players/*.psochar
+system/players/*.psosys
+system/players/*.psocard
+system/players/*.nsc
+system/players/*.nsa
 system/patch-pc/.metadata-cache.json
 system/patch-bb/.metadata-cache.json
 
@@ -29,7 +31,6 @@ system/patch-bb/.metadata-cache.json
 # repository
 files
 make_release.py
-notes
 old-khyller
 old-newserv
 release

CMakeLists.txt

@@ -33,75 +33,100 @@ set (LIBEVENT_LIBRARIES
         ${LIBEVENT_CORE})
 
 find_package(phosg REQUIRED)
+find_package(Iconv REQUIRED)
 find_package(resource_file QUIET)
 
 
 
 # Executable definition
 
-add_executable(newserv
-  src/CatSession.cc
-  src/Channel.cc
-  src/ChatCommands.cc
-  src/Client.cc
-  src/Compression.cc
-  src/DNSServer.cc
-  src/Episode3/AssistServer.cc
-  src/Episode3/BattleRecord.cc
-  src/Episode3/Card.cc
-  src/Episode3/CardSpecial.cc
-  src/Episode3/DataIndex.cc
-  src/Episode3/DeckState.cc
-  src/Episode3/MapState.cc
-  src/Episode3/PlayerState.cc
-  src/Episode3/PlayerStateSubordinates.cc
-  src/Episode3/RulerServer.cc
-  src/Episode3/Server.cc
-  src/Episode3/Tournament.cc
-  src/FileContentsCache.cc
-  src/FunctionCompiler.cc
-  src/GSLArchive.cc
-  src/IPFrameInfo.cc
-  src/IPStackSimulator.cc
-  src/Items.cc
-  src/LevelTable.cc
-  src/License.cc
-  src/Lobby.cc
-  src/Loggers.cc
-  src/Main.cc
-  src/Map.cc
-  src/Menu.cc
-  src/NetworkAddresses.cc
-  src/PatchFileIndex.cc
-  src/Player.cc
-  src/ProxyCommands.cc
-  src/ProxyServer.cc
-  src/PSOEncryption.cc
-  src/PSOGCObjectGraph.cc
-  src/PSOProtocol.cc
-  src/Quest.cc
-  src/RareItemSet.cc
-  src/ReceiveCommands.cc
-  src/ReceiveSubcommands.cc
-  src/ReplaySession.cc
-  src/SendCommands.cc
-  src/Server.cc
-  src/ServerShell.cc
-  src/ServerState.cc
-  src/Shell.cc
-  src/StaticGameData.cc
-  src/Text.cc
-  src/Version.cc
+set(SOURCES
+    src/AFSArchive.cc
+    src/BattleParamsIndex.cc
+    src/BMLArchive.cc
+    src/CatSession.cc
+    src/Channel.cc
+    src/ChatCommands.cc
+    src/Client.cc
+    src/CommonItemSet.cc
+    src/Compression.cc
+    src/DCSerialNumbers.cc
+    src/DNSServer.cc
+    src/EnemyType.cc
+    src/Episode3/AssistServer.cc
+    src/Episode3/BattleRecord.cc
+    src/Episode3/Card.cc
+    src/Episode3/CardSpecial.cc
+    src/Episode3/DataIndexes.cc
+    src/Episode3/DeckState.cc
+    src/Episode3/MapState.cc
+    src/Episode3/PlayerState.cc
+    src/Episode3/PlayerStateSubordinates.cc
+    src/Episode3/RulerServer.cc
+    src/Episode3/Server.cc
+    src/Episode3/Tournament.cc
+    src/FileContentsCache.cc
+    src/FunctionCompiler.cc
+    src/GSLArchive.cc
+    src/GVMEncoder.cc
+    src/IPFrameInfo.cc
+    src/IPStackSimulator.cc
+    src/ItemCreator.cc
+    src/ItemData.cc
+    src/ItemNameIndex.cc
+    src/ItemParameterTable.cc
+    src/Items.cc
+    src/LevelTable.cc
+    src/License.cc
+    src/Lobby.cc
+    src/Loggers.cc
+    src/Main.cc
+    src/Map.cc
+    src/Menu.cc
+    src/NetworkAddresses.cc
+    src/PatchFileIndex.cc
+    src/Player.cc
+    src/PlayerSubordinates.cc
+    src/ProxyCommands.cc
+    src/ProxyServer.cc
+    src/PSOEncryption.cc
+    src/PSOGCObjectGraph.cc
+    src/PSOProtocol.cc
+    src/Quest.cc
+    src/QuestScript.cc
+    src/RareItemSet.cc
+    src/ReceiveCommands.cc
+    src/ReceiveSubcommands.cc
+    src/ReplaySession.cc
+    src/SaveFileFormats.cc
+    src/SendCommands.cc
+    src/Server.cc
+    src/ServerShell.cc
+    src/ServerState.cc
+    src/Shell.cc
+    src/StaticGameData.cc
+    src/TeamIndex.cc
+    src/Text.cc
+    src/TextArchive.cc
+    src/UnicodeTextSet.cc
+    src/Version.cc
+    src/WordSelectTable.cc
 )
-target_include_directories(newserv PUBLIC ${LIBEVENT_INCLUDE_DIR})
-target_link_libraries(newserv phosg ${LIBEVENT_LIBRARIES} pthread)
 
 if(resource_file_FOUND)
-  target_compile_definitions(newserv PUBLIC HAVE_RESOURCE_FILE)
-  target_link_libraries(newserv resource_file)
-  message(STATUS "libresource_file found; enabling patch support")
+    set(SOURCES ${SOURCES} src/ARCodeTranslator.cc)
+endif()
+
+add_executable(newserv ${SOURCES})
+target_include_directories(newserv PUBLIC ${LIBEVENT_INCLUDE_DIR} ${Iconv_INCLUDE_DIRS})
+target_link_libraries(newserv phosg ${LIBEVENT_LIBRARIES} ${Iconv_LIBRARIES} pthread)
+
+if(resource_file_FOUND)
+    target_compile_definitions(newserv PUBLIC HAVE_RESOURCE_FILE)
+    target_link_libraries(newserv resource_file)
+    message(STATUS "libresource_file found; enabling patch support")
 else()
-  message(WARNING "libresource_file not found; disabling patch support")
+    message(WARNING "libresource_file not found; disabling patch support")
 endif()
 
 
@@ -110,21 +135,23 @@ endif()
 
 enable_testing()
 
-file(GLOB TestCases ${CMAKE_SOURCE_DIR}/tests/*.test.txt)
+file(GLOB LogTestCases ${CMAKE_SOURCE_DIR}/tests/*.test.txt)
 
-foreach(TestCase IN ITEMS ${TestCases})
-  add_test(
-      NAME ${TestCase}
-      WORKING_DIRECTORY ${CMAKE_SOURCE_DIR}
-      COMMAND ${CMAKE_BINARY_DIR}/newserv replay-log ${TestCase} --config=${CMAKE_SOURCE_DIR}/tests/config.json --require-password=password --require-access-key=111111111111)
+foreach(LogTestCase IN ITEMS ${LogTestCases})
+    add_test(
+        NAME ${LogTestCase}
+        WORKING_DIRECTORY ${CMAKE_SOURCE_DIR}
+        COMMAND ${CMAKE_BINARY_DIR}/newserv --replay-log=${LogTestCase} --config=${CMAKE_SOURCE_DIR}/tests/config.json)
 endforeach()
 
-add_test(
-    NAME compression
-    WORKING_DIRECTORY ${CMAKE_SOURCE_DIR}
-    COMMAND ${CMAKE_SOURCE_DIR}/test-compression.sh ${CMAKE_BINARY_DIR}/newserv)
-
+file(GLOB ScriptTestCases ${CMAKE_SOURCE_DIR}/tests/*.test.sh)
 
+foreach(ScriptTestCase IN ITEMS ${ScriptTestCases})
+    add_test(
+        NAME ${ScriptTestCase}
+        WORKING_DIRECTORY ${CMAKE_SOURCE_DIR}
+        COMMAND ${ScriptTestCase} ${CMAKE_BINARY_DIR}/newserv)
+endforeach()
 
 # Installation configuration
 

README.md

@@ -1,12 +1,34 @@
 # newserv <img align="right" src="s-newserv.png" />
 
-newserv is a game server and proxy for Phantasy Star Online (PSO).
+newserv is a game server, proxy, and reverse-engineering tool for Phantasy Star Online (PSO).
 
 This project includes code that was reverse-engineered by the community in ages long past, and has been included in many projects since then. It also includes some game data from Phantasy Star Online itself, which was originally created by Sega.
 
+* Background
+    * [History](#history)
+    * [Future (and to-do list)](#future)
+* [Compatibility](#compatibility)
+* Setup
+    * [Configuration](#configuration)
+    * [Installing quests](#installing-quests)
+    * [Episode 3 features](#episode-3-features)
+    * [Client patch directories for PC and BB](#client-patch-directories)
+    * [Memory patches and DOL files for GC](#memory-patches-and-dol-files)
+    * [Using newserv as a proxy](#using-newserv-as-a-proxy)
+    * [Chat commands](#chat-commands)
+* How to connect
+    * Connecting local clients
+        * [PSO DC](#pso-dc)
+        * [PSO DC on Flycast](#pso-dc-on-flycast)
+        * [PSO PC](#pso-pc)
+        * [PSO GC on a real GameCube](#pso-gc-on-a-real-gamecube)
+        * [PSO GC on Dolphin](#pso-gc-on-dolphin)
+    * [Connecting external clients](#connecting-external-clients)
+* [Non-server features](#non-server-features)
+
 ## History
 
-The history of this project essentially mirrors my development as a software engineer from the beginning of my hobby until now. If you don't care about the story, skip to the "Compatibility" or "Usage" sections below.
+The history of this project essentially mirrors my development as a software engineer from the beginning of my hobby until now. If you don't care about the story, skip to the "Compatibility" or "Setup" sections below.
 
 I originally purchased PSO GC when I heard about PSUL, and wanted to play around with running homebrew on my GameCube. This pathway eventually led to [GCARS-CS](https://github.com/fuzziqersoftware/gcars-cs), but that's another story.
 
@@ -28,144 +50,154 @@ newserv is many things - a server, a proxy, an encryption and decryption tool, a
 
 With that said, I offer no guarantees on how or when this project will advance. Feel free to submit GitHub issues if you find bugs or have feature requests; I'd like to make the server as stable and complete as possible, but I can't promise that I'll respond to issues in a timely manner. If you feel like contributing to newserv yourself, pull requests are welcome as well.
 
-Current known issues / missing features / things to do:
-- Episode 3 battles are implemented but are not well-tested.
-    - Fix behavior when joining a spectator team after the beginning of a battle.
-- PSOBB is not well-tested and likely will disconnect or misbehave when clients try to use unimplemented features.
-    - Enemy indexes also desync slightly in most games, often in later areas, leading to incorrect EXP values being given for killed enemies.
-- Fix some edge cases on the BB proxy server (e.g. make sure Change Ship does the right thing, which is not the same as what it should do on V2/V3).
-- PSOX is not tested at all.
-- Memory patches currently are platform-specific but not version-specific. This makes them quite a bit harder to write and use properly.
-- Find a way to silence audio in RunDOL.s. Some old DOLs don't reset audio systems at load time and it's annoying to hear the crash buzz when the GC hasn't actually crashed.
-- Implement private and overflow lobbies.
-- Enforce client-side size limits (e.g. for 60/62 commands) on the server side as well. (For 60/62 specifically, perhaps transform them to 6C/6D if needed.)
-- Encapsulate BB server-side random state and make replays deterministic.
-- VMS decoding doesn't work. Complete this reverse-engineering project.
-- Code style
-    - The internal menu abstraction is ugly and hard to work with. Rewrite it.
-    - Add default values for all commands (like we use for Episode 3 battle commands).
-    - Clean up the way proxy session options are passed to the session from the client object (and add user-settable options for e.g. chat filter, which currently doesn't appear in the menu).
-- Episode 3 bugs
-    - Disconnecting during a match turns you into a COM if there are other humans in the match, even if the match is part of a tournament. This may be incorrect behavior for tournaments.
-    - Disconnecting during a tournament when there are no other humans in the match simply cancels the match (so it can be replayed) instead of forfeiting, which is almost certainly incorrect behavior. (Then again, no one likes losing tournaments to COMs...)
-    - Tournament deck restrictions aren't enforced when populating COMs at tournament start time. This can cause weird behavior if, for example, a COM deck contains assist cards and the tournament rules forbid them.
-    - There is a rare failure mode during battles that causes one of the clients to be disconnected.
+See TODO.md for a list of known issues and future work.
 
 ## Compatibility
 
 newserv supports several versions of PSO. Specifically:
-| Version              | Basic commands | Lobbies       | Games         | Proxy         |
-|----------------------|----------------|---------------|---------------|---------------|
-| Dreamcast Trial      | Partial (6)    | Not supported | Not supported | Not supported |
-| Dreamcast V1         | Supported (1)  | Supported     | Supported     | Supported     |
-| Dreamcast V2         | Supported (1)  | Supported     | Supported     | Supported     |
-| PC                   | Supported      | Supported     | Supported     | Supported     |
-| GameCube Ep1&2 Trial | Untested (2)   | Untested (2)  | Untested (2)  | Untested (2)  |
-| GameCube Ep1&2       | Supported      | Supported     | Supported     | Supported     |
-| GameCube Ep1&2 Plus  | Supported      | Supported     | Supported     | Supported     |
-| GameCube Ep3 Trial   | Supported      | Supported     | Supported (3) | Supported     |
-| GameCube Ep3         | Supported      | Supported     | Supported (3) | Supported     |
-| XBOX Ep1&2           | Untested (4)   | Untested (4)  | Untested (4)  | Untested (4)  |
-| Blue Burst           | Supported      | Supported     | Partial (5)   | Supported     |
+| Version        | Login        | Lobbies      | Games        | Proxy        |
+|----------------|--------------|--------------|--------------|--------------|
+| DC Trial       | Yes          | Yes          | Yes          | No           |
+| DC 11/2000     | Yes          | Yes          | Yes          | No           |
+| DC 12/2000     | Yes          | Yes          | Yes          | Yes          |
+| DC 01/2001     | Yes          | Yes          | Yes          | Yes          |
+| DC V1          | Yes          | Yes          | Yes          | Yes          |
+| DC 08/2001     | Untested (1) | Untested (1) | Untested (1) | Untested (1) |
+| DC V2          | Yes          | Yes          | Yes          | Yes          |
+| PC             | Yes          | Yes          | Yes          | Yes          |
+| GC Ep1&2 Trial | Untested (1) | Untested (1) | Untested (1) | Untested (1) |
+| GC Ep1&2       | Yes          | Yes          | Yes          | Yes          |
+| GC Ep1&2 Plus  | Yes          | Yes          | Yes          | Yes          |
+| GC Ep3 Trial   | Yes          | Yes          | Partial (3)  | Yes          |
+| GC Ep3         | Yes          | Yes          | Yes          | Yes          |
+| Xbox Ep1&2     | Yes          | Yes          | Yes          | Yes          |
+| BB (vanilla)   | Yes          | Yes          | Yes (2)      | Yes          |
+| BB (Tethealla) | Yes          | Yes          | Yes (2)      | Yes          |
 
 *Notes:*
-1. *DC support has only been tested with the US versions of PSO DC. Other versions probably don't work, but will be easy to add. Please submit a GitHub issue if you have a non-US DC version, and can provide a log from a connection attempt.*
-2. *This version only supports the modem adapter, which Dolphin does not currently emulate, so it's difficult to test.*
-3. *See the following section about Episode 3 functionality.*
-4. *newserv's implementation of PSOX is based on disassembly of the client executable; it has never been tested with a real client and most likely doesn't work.*
-5. *Some basic features are not implemented in Blue Burst games, so the games are not very playable. A lot of work has to be done to get BB games to a playable state.*
-6. *Support for PSO Dreamcast Trial Edition is very incomplete and probably never will be complete. This is really just exploring a curiosity that sheds some light on early network engineering done by Sega, not an actual attempt at supporting this version of the game.*
+1. *newserv's implementations of these versions are based on disassembly of the client executables and have never been tested.*
+2. *BB games are mostly playable, but there are still some unimplemented features (for example, some quests that use rare commands may not work). Please submit a GitHub issue if you find something that doesn't work.*
+3. *Creating a game works and battle setup behaves mostly normally, but starting a battle doesn't work.*
 
-### Episode 3
+## Setup
 
-The following Episode 3 features are well-tested and work normally:
-* Downloading quests.
-* Creating and joining games.
-* Trading cards.
-* Participating in card auctions. (The auction contents must be configured in config.json.)
-* Tournaments. (See below)
+### Configuration
 
-The following Episode 3 features are implemented, but only partially tested:
-* CARD battles. If you find a feature or card ability that doesn't work, please make a GitHub issue and describe the situation (including the attacking card(s), defending card(s), and ability that didn't work).
-* Spectator teams are partially implemented, but are not well-tested. There is a known issue that prevents viewing battles unless you're in the spectator team when the battle begins.
-* Battle replays sometimes cause the client to crash during the replay. Using the $playrec command is therefore not recommended.
-
-Tournaments work differently than they did on Sega's servers. Tournaments can be created with the `create-tournament` shell command, which enables players to register for them. (Use `help` to see all the arguments - there are many!) The `start-tournament` shell command starts the tournament, but this doesn't schedule any matches. Instead, players who are ready to play their next match can all stand at the rightmost 4-player battle table in the same CARD lobby, and the tournament match will start automatically. (This also means that, for example, not all matches in round 1 must be complete before round 2 can begin - only the matches preceding each individual match must be complete for that match to be playable.)
-
-Because newserv gives all players 1000000 meseta, there is no reward for winning a tournament. This may change in the future.
-
-Episode 3 state and game data is stored in the system/ep3 directory. The files in there are:
-* card-definitions.mnr: Compressed card definition list, sent to Episode 3 clients at connect time. Card stats and abilities can be changed by editing this file.
-* card-definitions.mnrd: Decompressed version of the above. If present, newserv will use this instead of the compressed version, since this is easier to edit.
-* card-text.mnr: Compressed card text archive. Generally only used for debugging.
-* com-decks.json: COM decks used in tournaments. The default decks in this file come from logs from Sega's servers, so the file doesn't include every COM deck Sega ever made - the rest are probably lost to time.
-* maps-free/ and maps-quest/: Online free battle and quest maps (.mnm/.bin/.mnmd/.bind files). Free battle and quest files have exactly the same format; the only difference between the files in these directories is which section of the menu they will appear in on the client.
-* tournament-state.json: State of all active tournaments. This file is automatically written when any tournament changes state for any reason (e.g. a tournament is created/started/deleted or a match is resolved).
-
-## Usage
-
-Currently newserv should build on macOS and Ubuntu. It will likely work on other Linux flavors too. It should work on Windows as well, but I haven't tested it recently - the build process could be very manual. Cygwin is likely the easiest Windows environment in which to build newserv.
+Currently newserv works on macOS, Windows, and Ubuntu Linux. It will likely work on other Linux flavors too.
 
 There is a fairly recent macOS ARM64 release on the newserv GitHub repository. You may need to install libevent manually even if you use this release (run `brew install libevent`).
 
-If you're using an older AMD64 Mac, you're running Linux, or you just want to build newserv yourself, here's what you do:
-1. Make sure you have CMake and libevent installed. (`brew install cmake libevent` on macOS, `sudo apt-get install cmake libevent-dev` on most Linuxes)
-2. Build and install phosg (https://github.com/fuzziqersoftware/phosg).
-3. Optionally, install resource_dasm (https://github.com/fuzziqersoftware/resource_dasm). This will enable newserv to send memory patches and load DOL files on PSO GC clients. PSO GC clients can play PSO normally on newserv without this.
-4. Run `cmake . && make` in the newserv directory.
+There is a fairly recent Windows release on the newserv GitHub repository also. It's built with Cygwin, and all the necessary DLL files should be included. That said, I've only tested it on my own machine and there is no CI for Windows builds like there is for macOS and Linux, so if it doesn't work for you, please open a GitHub issue to let me know.
+
+If you're not using a release from the GitHub repository, do this to build newserv:
+1. If you're on Windows, install Cygwin. While doing so, install the `cmake`, `gcc-core`, `gcc-g++`, `git`, `libevent2.1_7`, `make`, `libiconv`, and `zlib` packages. Do the rest of these steps inside a Cygwin shell (not a Windows cmd shell or PowerShell).
+2. Make sure you have CMake, libevent, and libiconv installed. (On macOS, `brew install cmake libevent libiconv`; on most Linuxes, `sudo apt-get install cmake libevent-dev`; on Windows, you already did this in step 1.)
+3. Build and install phosg (https://github.com/fuzziqersoftware/phosg).
+4. Optionally, install resource_dasm (https://github.com/fuzziqersoftware/resource_dasm). This will enable newserv to send memory patches and load DOL files on PSO GC clients. PSO GC clients can play PSO normally on newserv without this.
+5. Run `cmake . && make` in the newserv directory.
 
 After building newserv or downloading a release, do this to set it up and use it:
 1. In the system/ directory, make a copy of config.example.json named config.json, and edit it appropriately.
-2. If you plan to play PSO Blue Burst on newserv, set up the patch directory appropriately. See the "Client patch directories" section below.
+2. If you plan to play PSO Blue Burst on newserv, set up the patch directory. See the "Client patch directories" section below.
 3. Run `./newserv` in the newserv directory. This will start the game server and run the interactive shell. You may need `sudo` if newserv's built-in DNS server is enabled.
-4. Use the interactive shell to add a license. Run `help` in the shell to see how to do this.
+4. If you set AllowUnregisteredUsers to false in config.json, use the interactive shell to add your license. Run `help` in the shell to see how to do this.
 5. Set your client's network settings appropriately and start an online game. See the "Connecting local clients" or "Connecting remote clients" section to see how to get your game client to connect.
 
 To use newserv in other ways (e.g. for translating data), see the end of this document.
 
 ### Installing quests
 
-newserv automatically finds quests in the system/quests/ directory. To install your own quests, or to use quests you've saved using the proxy's set-save-files option, just put them in that directory and name them appropriately.
+newserv automatically finds quests in the subdirectories of the system/quests/ directory. To install your own quests, or to use quests you've saved using the proxy's Save Files option, just put them in one of the subdirectories there and name them appropriately. The subdirectories and their behaviors (e.g. in which game modes they should appear and for which PSO versions) is defined in the QuestCategories field in config.json.
 
-Standard quest files should be named like `q###-CATEGORY-VERSION.EXT`, battle quests should be named like `b###-VERSION.EXT`, challenge quests should be named like `c###-VERSION.EXT`, and Episode 3 download quests should be named like `e###-gc3.EXT`. The fields in each filename are:
-- `###`: quest number (this doesn't really matter; it should just be unique for the PSO version)
-- `CATEGORY`: ret = Retrieval, ext = Extermination, evt = Events, shp = Shops, vr = VR, twr = Tower, gov = Government (BB only), dl = Download (these don't appear during online play), 1p = Solo (BB only)
-- `VERSION`: d1 = Dreamcast v1, dc = Dreamcast v2, pc = PC, gc = GameCube Episodes 1 & 2, gc3 = Episode 3, bb = Blue Burst
+Within the category directories, quest files should be named like `q###-VERSION-LANGUAGE.EXT` (although the `q` is ignored, and can be any letter). The fields in each filename are:
+- `###`: quest number (this doesn't really matter; it should just be unique across the PSO version)
+- `VERSION`: dn = Dreamcast NTE, dp = Dreamcast 11/2000 prototype, d1 = Dreamcast v1, dc = Dreamcast v2, pc = PC, gcn = GameCube Trial Edition, gc = GameCube Episodes 1 & 2, gc3 = Episode 3 (see below), xb = Xbox, bb = Blue Burst
+- `LANGUAGE`: j = Japanese, e = English, g = German, f = French, s = Spanish
 - `EXT`: file extension (see table below)
 
-For example, the GameCube version of Lost HEAT SWORD is in two files named `q058-ret-gc.bin` and `q058-ret-gc.dat`. newserv knows these files are quests because they're in the system/quests/ directory, it knows they're for PSO GC because the filenames contain `-gc`, and it puts them in the Retrieval category because the filenames contain `-ret`.
+For .dat files, the `LANGUAGE` token may be omitted. If it's present, then that .dat file will only be used for that language of the quest; if omitted, then that .dat file will be used for all languages of the quest.
 
-There are multiple PSO quest formats out there; newserv supports most of them. It can also decode any known format to standard .bin/.dat format. Specifically:
+Some quests (mostly battle and challenge mode quests) have additional JSON metadata files that describe how the server should handle them. These metadata files are generally named similarly to their .bin and .dat counterparts, except the `VERSION` token may also be omitted if the metadata applies to all versions of the quest on all PSO versions.
 
-| Format                    | Extension             | Supported     | Decode action    |
-|---------------------------|-----------------------|---------------|------------------|
-| Compressed                | .bin and .dat         | Yes           | None (1)         |
-| Compressed Ep3            | .bin or .mnm          | Yes (4)       | None (1)         |
-| Uncompressed              | .bind and .datd       | Yes           | compress-prs (2) |
-| Uncompressed Ep3          | .bind or .mnmd        | Yes (4)       | compress-prs (2) |
-| Unencrypted GCI           | .bin.gci and .dat.gci | Yes           | decode-gci       |
-| Encrypted GCI with key    | .bin.gci and .dat.gci | Yes           | decode-gci       |
-| Encrypted GCI without key | .bin.gci and .dat.gci | No            | decode-gci (3)   |
-| Ep3 GCI                   | .bin.gci or .mnm.gci  | Download only | decode-gci       |
-| Encrypted DLQ             | .bin.dlq and .dat.dlq | Yes           | decode-dlq       |
-| Ep3 DLQ                   | .bin.dlq or .mnm.dlq  | Download only | decode-dlq       |
-| Online QST                | .qst                  | Yes           | decode-qst       |
-| Download QST              | .qst                  | Yes           | decode-qst       |
+Some quests may also include a .pvr file, which contains an image used in the quest. These files are named similarly to their .bin and .dat counterparts.
+
+For example, the GameCube version of Lost HEAT SWORD is in two files named `q058-gc-e.bin` and `q058-gc.dat`. newserv knows these files are quests because they're in the system/quests/ directory, it knows they're for PSO GC because the filenames contain `-gc`, it knows this is the English version of the quest because the .bin filename ends with `-e` (even though the .dat filename does not), and it puts them in the Retrieval category because the files are within the retrieval/ directory within system/quests/.
+
+The GameCube and Xbox quest formats are very similar, but newserv treats them as different. If you want to use the same quest file for GameCube and Xbox clients, you can make one a symbolic link to the other.
+
+There are multiple PSO quest formats out there; newserv supports all of them. It can also decode any known format to standard .bin/.dat format. Specifically:
+
+| Format           | Extension             | Supported  | Decode action    |
+|------------------|-----------------------|------------|------------------|
+| Compressed       | .bin and .dat         | Yes        | None (1)         |
+| Compressed Ep3   | .bin or .mnm          | Yes (4)    | None (1)         |
+| Uncompressed     | .bind and .datd       | Yes        | compress-prs (2) |
+| Uncompressed Ep3 | .bind or .mnmd        | Yes (4)    | compress-prs (2) |
+| VMS (DCv1)       | .bin.vms and .dat.vms | Yes        | decode-vms       |
+| VMS (DCv2)       | .bin.vms and .dat.vms | Decode (3) | decode-vms (3)   |
+| GCI (decrypted)  | .bin.gci and .dat.gci | Yes        | decode-gci       |
+| GCI (with key)   | .bin.gci and .dat.gci | Yes        | decode-gci       |
+| GCI (no key)     | .bin.gci and .dat.gci | Decode (3) | decode-gci (3)   |
+| GCI (Ep3)        | .bin.gci or .mnm.gci  | Yes        | decode-gci       |
+| GCI (Ep3 Trial)  | .bin.gci or .mnm.gci  | Decode (3) | decode-gci (3)   |
+| DLQ              | .bin.dlq and .dat.dlq | Yes        | decode-dlq       |
+| DLQ (Ep3)        | .bin.dlq or .mnm.dlq  | Yes        | decode-dlq       |
+| QST (online)     | .qst                  | Yes        | decode-qst       |
+| QST (download)   | .qst                  | Yes        | decode-qst       |
 
 *Notes:*
 1. *This is the default format. You can convert these to uncompressed format by running `newserv decompress-prs FILENAME.bin FILENAME.bind` (and similarly for .dat -> .datd)*
 2. *Similar to (1), to compress an uncompressed quest file: `newserv compress-prs FILENAME.bind FILENAME.bin` (and likewise for .datd -> .dat)*
-3. *If you know the encryption seed (serial number), pass it in as a hex string with the `--seed=` option. If you don't know the encryption seed, newserv will find it for you, which will likely take a long time.*
-4. *Episode 3 online quests don't go in the system/quests directory; they instead go in the system/ep3/maps-free or system/ep3/maps-quest directory. If you want an Episode 3 quest to be available for both online play and for downloading, the file must exist in both system/quests and in one of the map directories in system/ep3.*
+3. *Use the decode action to convert these quests to .bin/.dat format before putting them into the server's quests directory. If you know the encryption seed (serial number), pass it in as a hex string with the `--seed=` option. If you don't know the encryption seed, newserv will find it for you, which will likely take a long time.*
+4. *Episode 3 quests don't go in the system/quests directory. See the Episode 3 section below.*
 
-Episode 3 download quests consist only of a .bin file - there is no corresponding .dat file. Episode 3 download quest files may be named with the .mnm extension instead of .bin, since the format is the same as the standard map files (in system/ep3/). These files can be encoded in any of the formats described above, except .qst. There are no encrypted Episode 3 GCI formats because the game doesn't encrypt quests saved to the memory card, unlike Episodes 1&2.
+Episode 3 download quests consist only of a .bin file - there is no corresponding .dat file. Episode 3 download quest files may be named with the .mnm extension instead of .bin, since the format is the same as the standard map files (in system/ep3/). These files can be encoded in any of the formats described above, except .qst.
 
 When newserv indexes the quests during startup, it will warn (but not fail) if any quests are corrupt or in unrecognized formats.
 
-If you've changed the contents of the quests directory, you can re-index the quests without restarting the server by running `reload quests` in the interactive shell. The new quests will be available immediately, but any games with quests already in progress will continue using the old versions of the quests until those quests end.
+Quest contents are cached in memory, but if you've changed the contents of the quests directory, you can re-index the quests without restarting the server by running `reload quests` in the interactive shell. The new quests will be available immediately, but any games with quests already in progress will continue using the old versions of the quests until those quests end.
 
 All quests, including those originally in GCI or DLQ format, are treated as online quests unless their filenames specify the dl category. newserv allows players to download all quests, even those in non-download categories.
 
+### Episode 3 features
+
+newserv supports many features unique to Episode 3:
+* CARD battles. Not every combination of abilities has been tested yet, so if you find a feature or card ability that doesn't work like it's supposed to, please make a GitHub issue and describe the situation (the attacking card(s), defending card(s), and ability or condition that didn't work).
+* Spectator teams.
+* Tournaments. (But they work differently than Sega's tournaments did - see below)
+* Downloading quests.
+* Trading cards.
+* Participating in card auctions. (The auction contents must be configured in config.json.)
+* Decorations in lobbies. Currently only images are supported; the game also supports loading custom 3D models in lobbies, but newserv does not implement this (yet).
+
+#### Battle records
+
+After playing a battle, you can save the record of the battle with the $saverec command. You can then replay the battle later by using the $playrec command in a lobby - this will create a spectator team and play the recording of the battle as if it were happening in realtime. Note that there is a bug in older versions of Dolphin that seems to be frequently triggered when playing battle records, which causes the emulator to crash with the message `QObject::~QObject: Timers cannot be stopped from another thread`. To avoid this, use the latest version of Dolphin.
+
+#### Tournaments
+
+Tournaments work differently than they did on Sega's servers. Tournaments can be created with the `create-tournament` shell command, which enables players to register for them. (Use `help` to see all the arguments - there are many!) The `start-tournament` shell command starts the tournament (and prevents further registrations), but this doesn't schedule any matches. Instead, players who are ready to play their next match can all stand at the 4-player battle table near the lobby warp in the same CARD lobby, and the tournament match will start automatically.
+
+These tournament semantics mean that there can be multiple matches in the same tournament in play simultaneously, and not all matches in a round must be complete before the next round can begin - only the matches preceding each individual match must be complete for that match to be playable.
+
+The Meseta rewards for winning tournament matches can be configured in config.json.
+
+#### Episode 3 files
+
+Episode 3 state and game data is stored in the system/ep3 directory. The files in there are:
+* card-definitions.mnr: Compressed card definition list, sent to Episode 3 clients at connect time. Card stats and abilities can be changed by editing this file.
+* card-definitions.mnrd: Decompressed version of the above. If present, newserv will use this instead of the compressed version, since this is easier to edit.
+* card-text.mnr: Compressed card text archive. Generally only used for debugging.
+* card-text.mnrd: Decompressed card text archive; same format as TextCardE.bin. Generally only used for debugging.
+* com-decks.json: COM decks used in tournaments. The default decks in this file come from logs from Sega's servers, so the file doesn't include every COM deck Sega ever made - the rest are probably lost to time.
+* maps/: Online free battle and quest maps (.mnm/.bin/.mnmd/.bind files). newserv comes with all the original online and offline maps, including Story Mode quests. If you don't want the offline maps and quests to be playable online, delete the .bind files system/ep3/maps.
+* maps-download/: Download maps and quests (.mnm/.bin/.mnmd/.bind files). There are two subcategories by default (download maps and Trial Edition download maps), but you can add more by editing QuestCategories in config.json. Categories that have flag 0x40 (Ep3 download) set are indexed from this directory; all others are indexed from system/quests/. Files in maps-download/ subdirectories have the same format as those in the maps/ directory, but should be named like `e###-gc3-LANGUAGE.EXT` (similar to how non-Episode 3 quests are named in the system/quests/ directory). If you want a map to be available for online play and for downloading, the file must exist in both maps/ and in a maps-download/ subdirectory (a symbolic link is acceptable).
+* tournament-state.json: State of all active tournaments. This file is automatically written when any tournament changes state for any reason (e.g. a tournament is created/started/deleted or a match is resolved).
+
+There is no public editor for Episode 3 maps and quests, but the format is described fairly thoroughly in src/Episode3/DataIndexes.hh (see the MapDefinition structure). You'll need to use `newserv decompress-prs ...` to decompress .bin or .mnm files before editing them, but you don't need to compress the files again to use them - just put the .bind or .mnmd file in the maps directory and newserv will make it available.
+
+Like quests, Episode 3 card definitions, maps, and quests are cached in memory. If you've changed any of these files, you can run `reload ep3` in the interactive shell to make the changes take effect without restarting the server.
+
 ### Client patch directories
 
 If you're not playing PSO Blue Burst on newserv, you can skip these steps.
@@ -178,6 +210,8 @@ For BB clients, newserv reads some files out of the patch data to implement game
 
 Specifically, the patch-bb directory should contain at least the data.gsl file and all map_*.dat files from the version of PSOBB that you want to play on newserv. You can copy these files out of the client's data directory from a clean installation, and put them in system/patch-bb/data.
 
+Patch directory contents are cached in memory. If you've changed any of these files, you can run `reload patches` in the interactive shell to make the changes take effect without restarting the server.
+
 ### Memory patches and DOL files
 
 Everything in this section requires resource_dasm to be installed, so newserv can use the PowerPC assembler and disassembler from its libresource_file library. If resource_dasm is not installed, newserv will still build and run, but these features will not be available.
@@ -193,6 +227,8 @@ You can put memory patches in the system/ppc directory with filenames like Patch
 
 You can also put DOL files in the system/dol directory, and they will appear in the Programs menu. Selecting a DOL file there will load the file into the GameCube's memory and run it, just like the old homebrew loaders (PSUL and PSOload) did. For this to work, ReadMemoryWord.s, WriteMemory.s, and RunDOL.s must be present in the system/ppc directory. This has been tested on Dolphin but not on a real GameCube, so results may vary.
 
+Like other kinds of data, functions and DOL files are cached in memory. If you've changed any of these files, you can run `reload functions` or `reload dol-files` in the interactive shell to make the changes take effect without restarting the server.
+
 I mainly built the DOL loading functionality for documentation purposes. By now, there are many better ways to load homebrew code on an unmodified GameCube, but to my knowledge there isn't another open-source implementation of this method in existence.
 
 ### Using newserv as a proxy
@@ -205,24 +241,49 @@ To use the proxy for PSO BB, set the ProxyDestination-BB entry in config.json. I
 
 When you're on PSO DC, PC, or GC and are connected to a remote server through newserv's proxy, choosing the Change Ship or Change Block action from the lobby counter will send you back to newserv's main menu instead of the remote server's ship or block select menu. You can go back to the server you were just on by choosing it from the proxy server menu again.
 
+There are many options available when starting a proxy session. All options are off by default unless otherwise noted. The options are:
+* **Chat commands**: enables chat commands in the proxy session (on by default).
+* **Chat filter**: enables escape sequences in chat messages and info board (on by default).
+* **Player notifications**: shows a message when any player joins or leaves the game or lobby you're in.
+* **Block pings**: blocks automatic pings sent by the client, and responds to ping commands from the server automatically. This works around a bug in Sylverant's login server.
+* **Infinite HP**: automatically heals you whenever you get hit. An attack that kills you in one hit will still kill you, however.
+* **Infinite TP**: automatically restores your TP whenever you use any technique.
+* **Switch assist**: attempts to unlock doors that require two players in a one-player game.
+* **Infinite Meseta** (Episode 3 only): gives you 1,000,000 Meseta, regardless of the value sent by the remote server.
+* **Block events**: disables holiday events sent by the remote server.
+* **Block patches**: prevents any B2 (patch) commands from reaching the client.
+* **Save files**: saves copies of several kinds of files when they're sent by the remote server. The files are written to the current directory (which is usually the directory containing the system/ directory). These kinds of files can be saved:
+    * Online quests and download quests (saved as .bin/.dat files)
+    * GBA games (saved as .gba files)
+    * Patches (saved as .bin files, and disassembled into PowerPC assembly if newserv is built with patch support)
+    * Player data from BB sessions (saved as .bin files, which are not the same format as .nsc files)
+    * Episode 3 online quests and maps (saved as .mnmd files)
+    * Episode 3 download quests (saved as .mnm files)
+    * Episode 3 card definitions (saved as .mnr files)
+    * Episode 3 media updates (saved as .gvm, .bml, or .bin files)
+
 The remote server will probably try to assign you a Guild Card number that doesn't match the one you have on newserv. On PSO DC, PC and GC, the proxy server rewrites the commands in transit to make it look like the remote server assigned you the same Guild Card number as you have on newserv, but if the remote server has some external integrations (e.g. forum or Discord bots), they will use the Guild Card number that the remote server believes it has assigned to you. The number assigned by the remote server is shown to you when you first connect to the remote server, and you can retrieve it in lobbies or during games with the $li command.
 
-Some chat commands (see below) have the same basic function on the proxy server but have different effects or conditions. In addition, there are some server shell commands that affect clients on the proxy (run 'help' in the shell to see what they are). All proxy commands in the server shell only work when there's exactly one client connected through the proxy, since there isn't (yet) a way to say via the shell which session you want the command to apply to.
+Some chat commands (see below) have the same basic function on the proxy server but have different effects or conditions. In addition, there are some server shell commands that affect clients on the proxy (run `help` in the shell to see what they are). If there's only one proxy session open, the shell's proxy commands will affect that session. Otherwise, you'll have to specify which session to affect with the `on` prefix - to send a chat message in LinkedSession:17205AE4, for example, you would run `on 17205AE4 chat ...`.
 
 ### Chat commands
 
-The server's shell supports a variety of administration commands. If the interactive shell is enabled, you can enter these commands at any time, even if the prompt isn't visible. Run `help` in the server's shell to see all of the commands and how to use them.
-
-newserv also supports a variety of commands players can use via the chat interface. Any chat message that begins with `$` is treated as a chat command. (If you actually want to send a chat message starting with `$`, type `$$` instead.)
+newserv supports a variety of commands players can use by chatting in-game. Any chat message that begins with `$` is treated as a chat command. (If you actually want to send a chat message starting with `$`, type `$$` instead.)
 
 Some commands only work on the game server and not on the proxy server. The chat commands are:
 
 * Information commands
     * `$li`: Shows basic information about the lobby or game you're in. If you're on the proxy server, shows information about your connection instead (remote Guild Card number, client ID, etc.).
+    * `$ping` (game server only): Shows round-trip ping time from the server to you.
     * `$what` (game server only): Shows the type, name, and stats of the nearest item on the ground.
+    * `$matcount` (game server only): Shows how many of each type of material you've used.
 
 * Debugging commands
-    * `$dbgid` (game server only): Enable or disable high ID preference. When enabled, you'll be placed into the latest available slot in lobbies and games instead of the earliest. Can be useful for finding commands for which newserv doesn't handle client IDs properly.
+    * `$debug` (game server only): Enable or disable debug. You need the DEBUG permission in your user license to use this command. When debug is enabled, you'll see in-game messages from the server when you take certain actions. You'll also be placed into the highest available slot in lobbies and games instead of the lowest, which is useful for finding commands for which newserv doesn't handle client IDs properly. This setting also disables certain safeguards and allows you to do some things that might crash your client.
+    * `$quest <number>`: Load a quest by quest number. Can be used to load battle or challenge quests with only one player present.
+    * `$qcall <function-id>`: Call a quest function on your client.
+    * `$qset <flag-num>` or `$qclear <flag-num>`: Set or clear a global quest flag for everyone in the game.
+    * `$qsync <reg-num> <value>`: Set a quest register's value on your client. `<reg-num>` should be either rXX (e.g. r60) or fXX (e.g. f60); if the latter, `<value>` is parsed as a floating-point value instead of as an integer.
     * `$gc` (game server only): Send your own Guild Card to yourself.
     * `$persist` (game server only): Enable or disable persistence for the current lobby or game. This determines whether the lobby/game is deleted when the last player leaves. You need the DEBUG permission in your user license to use this command because there are no game state checks when you do this. For example, if you make a game persistent, start a quest, then leave the game, the game can't be joined by anyone but also can't be deleted.
     * `$sc <data>`: Send a command to yourself.
@@ -230,30 +291,42 @@ Some commands only work on the game server and not on the proxy server. The chat
 
 * Personal state commands
     * `$arrow <color-id>`: Changes your lobby arrow color.
-    * `$secid <section-id>`: Sets your override section ID. After running this command, any games you create will use your override section ID for rare drops instead of your character's actual section ID. To revert to your actual section id, run `$secid` with no name after it.
-    * `$rand <seed>`: Sets your override random seed (specified as a 32-bit hex value). This will make any games you create use the given seed for rare enemies. This also makes item drops deterministic in Blue Burst games hosted by newserv. On the proxy server, this command can cause desyncs with other players in the same game, since they will not see the overridden random seed. To remove the override, run `$rand` with no arguments.
-    * `$exit`: If you're in a lobby, sends you to the main menu (which ends your proxy session, if you're in one). If you're in an Episode 3 game or spectator team, sends you to the lobby (but does not end your proxy session if you're in one).
+    * `$secid <section-id>`: Sets your override section ID. After running this command, any games you create will use your override section ID for rare drops instead of your character's actual section ID. To revert to your actual section id, run `$secid` with no name after it. On the proxy server, this will not work if the remote server controls item drops (e.g. on BB, or on Schtserv with server drops enabled). If the server does not allow cheat mode anywhere (that is, "CheatModeBehavior" is "Off" in config.json), this command does nothing.
+    * `$rand <seed>`: Sets your override random seed (specified as a 32-bit hex value). This will make any games you create use the given seed for rare enemies. This also makes item drops deterministic in Blue Burst games hosted by newserv. On the proxy server, this command can cause desyncs with other players in the same game, since they will not see the overridden random seed. To remove the override, run `$rand` with no arguments. If the server does not allow cheat mode anywhere (that is, "CheatModeBehavior" is "Off" in config.json), this command does nothing.
+    * `$ln [name-or-type]`: Sets the lobby number. Visible only to you. This command exists because some non-lobby maps can be loaded as lobbies with invalid lobby numbers. See the "GC lobby types" and "Ep3 lobby types" entries in the information menu for acceptable values here. Note that non-lobby maps do not have a lobby counter, so there's no way to exit the lobby without using either `$ln` again or `$exit`. On the game server, `$ln` reloads the lobby immediately; on the proxy server, it doesn't take effect until you load another lobby yourself (which means you'll like have to use `$exit` to escape). Run this command with no argument to return to the default lobby.
+    * `$exit`: If you're in a lobby, sends you to the main menu (which ends your proxy session, if you're in one). If you're in a game or spectator team, sends you to the lobby (but does not end your proxy session if you're in one). Does nothing if you're in a non-Episode 3 game and no quest is in progress.
     * `$patch <name>`: Run a patch on your client. `<name>` must exactly match the name of a patch on the server.
 
 * Blue Burst player commands (game server only)
     * `$bbchar <username> <password> <1-4>`: Use this command when playing on a non-BB version of PSO. If the username and password are correct, this command converts your current character to BB format and saves it on the server in the given slot. Any character already in that slot is overwritten.
-    * `$edit <stat> <value>`: Modifies your character data.
+    * `$edit <stat> <value>`: Modifies your character data. If the server does not allow cheat mode anywhere (that is, "CheatModeBehavior" is "Off" in config.json), this command does nothing.
+    * `$save`: Saves your character, system, and Guild Card data immediately. (By default, your character is saved every 60 seconds while online, and your account and Guild Card data are saved whenever they change.)
 
 * Game state commands (game server only)
-    * `$maxlevel <level>`: Sets the maximum level for players to join the current game.
+    * `$maxlevel <level>`: Sets the maximum level for players to join the current game. (This only applies when joining; if a player joins and then levels up past this level during the game, they are not kicked out, but won't be able to rejoin if they leave.)
     * `$minlevel <level>`: Sets the minimum level for players to join the current game.
     * `$password <password>`: Sets the game's join password. To unlock the game, run `$password` with nothing after it.
-    * `$spec`: Toggles the allow spectators flag. If any players are spectating when this flag is disabled, they will be sent back to the lobby.
-    * `$saverec <name>`: Save the recording of the last Episode 3 battle.
-    * `$playrec <name>`: Play a battle recording. This command creates a spectator team and replays the specified battle log within it. There is a known issue which causes spectators to crash in some cases, so use of this command is currently not recommended.
+    * `$itemtable`: Switches between using the client's or the server's drop table. No effect on BB (the server's drop table is always used). The server's rare tables are defined in JSON files in the system/item-tables directory.
+    * `$drop`: Enables or disables all item drops from boxes and enemies in the current game.
+
+* Episode 3 commands (game server only)
+    * `$spec`: Toggles the allow spectators flag for Episode 3 games. If any players are spectating when this flag is disabled, they will be sent back to the lobby.
+    * `$inftime`: Toggles infinite-time mode. Must be used before starting a battle. If infinite-time mode is enabled, the overall and per-phase time limits will be disabled regardless of the values chosen during battle setup. After completing a battle, infinite-time mode is reset to the server's default value (which can be set in Episode3BehaviorFlags in config.json).
+    * `$defrange <min>-<max>`: Sets the DEF dice range for the next battle. If this is used, the dice range set during battle rules setup will apply only to ATK dice; DEF dice will use this range instead. Assist cards and other dice effects will still apply. Dice exchange also still applies if it is enabled.
+    * `$stat <what>`: Shows a statistic about your player or team in the current battle. `<what>` can be `duration`, `fcs-destroyed`, `cards-destroyed`, `damage-given`, `damage-taken`, `opp-cards-destroyed`, `own-cards-destroyed`, `move-distance`, `cards-set`, `fcs-set`, `attack-actions-set`, `techs-set`, `assists-set`, `defenses-self`, `defenses-ally`, `cards-drawn`, `max-attack-damage`, `max-combo`, `attacks-given`, `attacks-taken`, `sc-damage`, `damage-defended`, or `rank`.
+    * `$surrender`: Causes your team to immediately lose the current battle.
+    * `$saverec <name>`: Saves the recording of the last battle.
+    * `$playrec <name>`: Plays a battle recording. This command creates a spectator team and replays the specified battle log within it. There is a bug in Dolphin that makes use of this command unstable in emulation (see the "Battle records" section above).
 
 * Cheat mode commands
-    * `$cheat`: Enables or disables cheat mode for the current game. All other cheat mode commands do nothing if cheat mode is disabled. This command does nothing on the proxy server - cheat commands are always available there.
+    * `$cheat`: Enables or disables cheat mode for the current game. All other cheat mode commands do nothing if cheat mode is disabled. By default, cheat mode is off in new games but can be enabled; there is an option in config.json that allows you to disable cheat mode entirely, or set it to on by default in new games.
     * `$infhp` / `$inftp`: Enables or disables infinite HP or TP mode. Applies to only you. In infinite HP mode, one-hit KO attacks will still kill you.
-    * `$warp <area-id>`: Warps yourself to the given area.
-    * `$next`: Warps yourself to the next area.
+    * `$warpme <floor-id>`: Warps yourself to the given floor.
+    * `$warpall <floor-id>`: Warps everyone in the game to the given floor. You must be the leader to use this command, unless you're on the proxy server.
+    * `$next`: Warps yourself to the next floor.
     * `$swa`: Enables or disables switch assist. When enabled, the server will attempt to automatically unlock two-player doors in solo games if you step on both switches sequentially.
-    * `$item <data>` (or `$i <data>`): Create an item. Item codes are 16 hex bytes; at least 2 bytes must be specified, and all unspecified bytes are zeroes. If you are on the proxy server, you must not be using Blue Burst for this command to work. On the game server, this command works for all versions.
+    * `$item <desc>` (or `$i <desc>`): Create an item. `desc` may be a description of the item (e.g. "Hell Saber +5 0/10/25/0/10") or a string of hex data specifying the item code. Item codes are 16 hex bytes; at least 2 bytes must be specified, and all unspecified bytes are zeroes. If you are on the proxy server, you must not be using Blue Burst for this command to work. On the game server, this command works for all versions.
+    * `$unset <index>`: In an Episode 3 battle, removes one of your set cards from the field. `<index>` is the index of the set card as it appears on your screen - 1 is the card next to your SC's icon, 2 is the card to the right of 1, etc. This does not cause a Hunters-side SC to lose HP, as they normally do when their items are destroyed.
 
 * Configuration commands
     * `$event <event>`: Sets the current holiday event in the current lobby. Holiday events are documented in the "Using $event" item in the information menu. If you're on the proxy server, this applies to all lobbies and games you join, but only you will see the new event - other players will not.
@@ -275,18 +348,25 @@ Some versions of PSO DC will connect to a private server if you just set their D
 
 If you're emulating PSO DC or have a disc image, you can patch the appropriate files within the disc image to make it connect to any address you want. Creating such a patch is also beyond the scope of this document.
 
-Finally, if you're emulating PSO DC, you can modify the loaded executable in memory to make it connect anywhere you want. There is a script included with newserv that can do this for Flycast. The script only works on macOS because it uses memwatch, which is specifically for macOS, but a similar technique could be done manually using scanmem on Linux or Cheat Engine on Windows. (The script is fairly short, and what it does should be easy to understand so you can duplicate its effects with scanmem or Cheat Engine.)
+#### PSO DC on Flycast
 
-To use the script, do this:
+If you're emulating PSO DC, all versions will connect to newserv by setting the following options in Flycast's `emu.cfg` file under `[network]`:
+- DNS = Your newserv's server address (newserv's DNS server must be running on port 53)
+- EmulateBBA = yes
+- Enable = yes
+
+It is also necessary to save any DNS information to the flash memory of the Dreamcast to use the BBA - the easiest way to do this is to use the website option in USv2 and then choose the save to flash option.
+
+Once set up, the EU and US versions will work without any extra set up (other than the HL Check Disable code for USv2), while the JP versions require HL Check Disable codes to be running.
+
+If the server is running on the same machine as Flycast, this might not work, even if you point Flycast's DNS queries at your local IP address (instead of 127.0.0.1). In this case, you can modify the loaded executable in memory to make it connect anywhere you want. There is a script included with newserv that can do this on macOS; a similar technique could be done manually using scanmem on Linux or Cheat Engine on Windows. To use the script, do this:
 1. Build and install memwatch (https://github.com/fuzziqersoftware/memwatch).
-2. Start Flycast and run PSO. (You must run the script below after PSO is loaded - it won't work if you run it before loading the game.)
+2. Start Flycast and run PSO. (You must start PSO before running the script; it won't work if you run the script before loading the game.)
 3. Run `sudo patch_flycast_memory.py <original-destination>`. Replace `<original-destination>` with the hostname that PSO wants to connect to (you can find this out by using Wireshark and looking for DNS queries). The script may take up to a minute; you can continue using Flycast while it runs, but don't start an online game until the script is done.
 4. Run newserv and start an online game in PSO.
 
 If you use this method, you'll have to run the script every time you start PSO in Flycast, but you won't have to run it again if you start another online game without restarting emulation.
 
-Finally, the script takes an optional second argument that allows you to redirect the connection elsewhere (instead of the local machine). THis allows you to connect directly to remote servers if desired.
-
 #### PSO PC
 
 The version of PSO PC I have has the server addresses starting at offset 0x29CB34 in pso.exe. Using a hex editor, change those to "localhost" (without quotes) if you just want to connect to a locally-running newserv instance. Alternatively, you can add an entry to the Windows hosts file (C:\Windows\System32\drivers\etc\hosts) to redirect the connection to 127.0.0.1 (localhost) or any other IP address.
@@ -299,17 +379,14 @@ If you have PSO Plus or Episode III, it won't want to connect to a server on the
 
 #### PSO GC on Dolphin
 
-If you have BBA support via a tap interface, you may be able to just set the DNS server address (as you would on a real GameCube, above) and it may work. This does not work on macOS, but you can use the tapserver interface instead (below).
+If you're using the HLE BBA type, set the BBA's DNS server address to newserv's IP address and it should work. (If newserv is on the same machine as Dolphin, try your local IP address or 127.0.0.1.) In PSO, use the example values below in PSO's network configuration.
 
-If you're using a version of Dolphin with tapserver support (currently only the macOS version), you can make it connect to a newserv instance running on the same machine via the tapserver interface. You do not need to install or run tapserver, and this works for all PSO versions without any of the dual-interface trickery described above. To do this:
+If you're using the TAP BBA type, you'll have to set PSO's network settings appropriately for your tap interface. Set the DNS server address in PSO's network settings to newserv's IP address.
+
+If you're using a version of Dolphin with tapserver support, you can make it connect to a newserv instance running on the same machine via the tapserver interface. You do not need to install or run tapserver. To do this:
 1. Set Dolphin's BBA type to tapserver (Config -> GameCube -> SP1).
 2. Enable newserv's IP stack simulator according to the comments in config.json and start newserv.
-3. In PSO, you have to configure the network settings manually (DHCP doesn't work), but the actual values don't matter as long as they're valid IP addresses. Example values:
-  - IP address: `10.0.1.5`
-  - Subnet mask: `255.255.255.0`
-  - Default gateway: `10.0.1.1`
-  - DNS server address 1: `10.0.1.1`
-  - Leave everything else blank
+3. In PSO's network settings, enable DHCP ("Automatically obtain an IP address"), set DNS server address to "Automatic", and leave DHCP Hostname as "Not set". Leave the proxy server settings blank.
 4. Start an online game.
 
 ### Connecting external clients
@@ -318,17 +395,25 @@ If you want to accept connections from outside your local network, you'll need t
 
 For GC clients, you'll have to use newserv's built-in DNS server or set up your own DNS server as well. If you want external clients to be able to use your DNS server, you'll have to forward UDP port 53 to your newserv instance. Remote players can then connect to your server by entering your DNS server's IP address in their client's network configuration.
 
-### Non-server usage
+### Non-server features
 
-newserv has many CLI options, which can be used to access functionality other than the game/proxy server. Run `newserv help` to see these options and how to use them. The non-server things newserv can do are:
+newserv has many CLI options, which can be used to access functionality other than the game and proxy server. Run `newserv help` to see these options and how to use them. The non-server things newserv can do are:
 
-* Compress or decompress data in the PRS and BC0 formats
-* Compute the decompressed size of compressed PRS data without decompressing it
-* Encrypt or decrypt data using any PSO version's network encryption scheme
-* Encrypt or decrypt data using Episode 3's trivial scheme
-* Run a brute-force search for a decryption seed
-* Decode Shift-JIS text to UTF-16
-* Convert quests in .gci, .dlq, or .qst format to .bin/.dat format
-* Extract the contents of a .gsl archive
-* Connect to another PSO server and pretend to be a client
-* Format Episode 3 game data in a human-readable manner
+* Compress or decompress data in PRS, PR2, or BC0 format (`compress-prs`, `compress-pr2`, `compress-bc0`, `decompress-prs`, `decompress-pr2`, `decompress-bc0`)
+* Compute the decompressed size of compressed PRS data without decompressing it (`prs-size`)
+* Encrypt or decrypt data using any PSO version's network encryption scheme (`encrypt-data`, `decrypt-data`)
+* Encrypt or decrypt data using Episode 3's trivial scheme (`encrypt-trivial-data`, `decrypt-trivial-data`)
+* Encrypt or decrypt data using the Challenge Mode text algorithm (`encrypt-challenge-data`, `decrypt-challenge-data`)
+* Encrypt or decrypt PSO GC save data (.gci files) (`encrypt-gci-save`, `decrypt-gci-save`)
+* Convert a PSO GC or Episode 3 snapshot file to a BMP image (`decode-gci-snapshot`)
+* Find the likely round1 or round2 seed for a corrupt save file (`salvage-gci`)
+* Run a brute-force search for a decryption seed (`find-decryption-seed`)
+* Convert quests in .gci, .vms, .dlq, or .qst format to .bin/.dat format (`decode-gci`, `decode-vms`, `decode-dlq`, `decode-qst`)
+* Convert quests in .bin/.dat to .qst format (`encode-qst`)
+* Convert text archives (e.g. TextEnglish.pr2) to JSON and vice versa (`decode-text-archive`, `encode-text-archive`)
+* Disassemble quest scripts (`disassemble-quest-script`)
+* Format Episode 3 game data in a human-readable manner (`show-ep3-maps`, `show-ep3-cards`)
+* Convert item data to a human-readable description, or vice versa (`describe-item`, `encode-item`)
+* Connect to another PSO server and pretend to be a client (`cat-client`)
+* Replay a session log for testing (`replay-log`)
+* Extract the contents of a .gsl or .bml archive (`extract-gsl`, `extract-bml`)

TODO.md

@@ -0,0 +1,41 @@
+## General
+
+- Find a way to silence audio in RunDOL.s
+- Encapsulate BB server-side random state and make replays deterministic
+- Implement choice search
+- Write a simple status API
+- Implement per-game logging
+- Build an exception-handling abstraction in ChatCommands that shows formatted error messages in all cases
+- Make reloading happen on separate threads so compression doesn't block active clients
+- Implement decrypt/encrypt actions for VMS files
+- Make UI strings localizable (e.g. entries in menus, welcome message, etc.)
+- Figure out what causes the corruption message on PC proxy sessions and fix it
+- Make $edit for DC/PC
+- Add an idle connection timeout for proxy sessions
+
+## Episode 3
+
+- Make disconnecting during a tournament match cause you to forfeit the match
+- Enforce tournament deck restrictions (e.g. rank checks, No Assist option) when populating COMs at tournament start time
+- It may be possible to send spectators back to the waiting room after a non-tournament battle by sending 6xB4x05 with environment 0x19, then 6xB4x3B again; try this
+- Add support for recording battles on the proxy server (both in primary and spectator teams)
+- When `reload ep3` happens and the defs file is changed, send the new defs file to all connected players who aren't in a game (if this even works - when exactly does the client decompress the defs file from the server?)
+- Make `reload licenses` not vulnerable to online players' licenses overwriting licenses on disk somehow
+- Implement ranks (based on total Meseta earned)
+
+## PSO XBOX
+
+- Fix receiving Guild Cards from non-Xbox players
+- Make the Guild Card description field in SavedPlayerDataBB longer to accommodate XB descriptions (0x200 bytes)
+
+## PSOBB
+
+- Find any remaining mismatches in enemy indexes / experience
+- Fix some edge cases on the BB proxy server (e.g. Change Ship)
+- Implement less-common subcommands
+    - 6xD8: Add S-rank weapon special
+- Test team commands
+    - Test all EA subcommands (a few are still not implemented)
+    - 6xC1, 6xC2, 6xCD, 6xCE: Team invites/administration (not implemented)
+    - Fix invite member menu
+- Implement story progress flags for unlocking quests

notes/AITalk.bin-format.txt

@@ -0,0 +1,16 @@
+struct AITalkBin {
+  be_uint32_t num_scs;
+  be_uint32_t sc_offsets[num_scs];
+
+  struct SCDialogueEntry {
+    be_uint32_t num_entries;
+    be_uint32_t unknown_a1;
+    be_uint32_t size; // in bytes
+    struct WhenEntry {
+      be_uint32_t when;
+      be_uint32_t percent_chance; // 0-100
+      be_uint32_t count;
+      be_uint32_t string_ids[count];
+    } __attribute__((packed));
+  } __attribute__((packed));
+} __attribute__((packed));

notes/ar-codes.txt

@@ -0,0 +1,266 @@
+(Ep1&2 USA) Unlock all songs in BGM test
+(Note: sadly, there are no secret/unused ones)
+04368960 38600001
+04368964 4E800020
+
+(Ep1&2 USA v1.01) Play lobby (and event) music on Pioneer 2 also
+0417E0F0 60000000
+
+(Ep3 USA) Play lobby (and event) music in Morgue also
+040B7028 60000000
+
+(Ep3 USA) Skip white logo screens during startup
+0409D774 38000007
+(Episodes 1&2 USA v1.01) Skip white logo screens during startup
+0413F190 38000007
+
+(Ep3 USA) Skip agreement prompts before online game
+041B50C8 38000003
+(Episodes 1&2 USA v1.01) Skip agreement prompt before online game
+04327D80 38000003
+
+(Ep3 USA) Disable rate limit for pressing A during loading screens
+042F9B30 38000000
+
+(Ep3 USA) Auto-press A as fast as possible during loading screens
+042F9AC0 60000000
+
+(Ep3 USA) Replace loading screen A button sounds with random sounds
+042F9B18 4804BB19
+042F9B1C 5463063E
+042F9B20 60631400
+042F9B24 64630005
+042F9B28 38800000
+
+(Ep3 USA) Change color of loading screens
+(Replace AA, RR, GG, BB appropriately)
+042FA704 3CC0AARR
+042FA708 60C6GGBB
+
+(Ep3 USA) Use 16:9 aspect ratio
+04383DC8 4BC87F99
+0400BD60 C042DED0
+0400BD64 EC5D00B2
+0400BD68 4E800020
+
+(Ep3 USA) Disable darkening effect during battle details mode
+042F951C 4E800020
+
+(Ep3 USA) Unlock all COM decks
+042CA908 38600001
+
+(Ep3 USA) Enable all lobby counter options in non-CARD lobbies
+04096A8C 480000C0
+04096B4C 38800007
+04096BFC 4BFFFF2C
+
+(Ep3 USA) Change HUD color mask
+0438CA8C 3C00RRGG
+0438CA90 6000BBAA
+
+(Ep3 USA) Disable lobby event music (but keep the visuals)
+040B705C 38000000
+
+(Ep3 USA) Enable Pinz's Shop Super Card Capsule Machine as a fourth option
+043101C0 38800004
+04310238 2C1D0004
+04487E8C 000000C8
+
+(Ep3 USA) Change color of pulsing orange text (e.g. card ability names)
+0457EE18 RRRRRRRR  // Phase 1 (long) red component as 32-bit float (0.0-255.0)
+0457EE20 GGGGGGGG  // Phase 1 (long) green component as 32-bit float (0.0-255.0)
+0457EE10 BBBBBBBB  // Phase 1 (long) blue component as 32-bit float (0.0-255.0)
+0457EE1C RRRRRRRR  // Phase 2 (short) red component as 32-bit float (0.0-255.0)
+0457EE24 GGGGGGGG  // Phase 2 (short) green component as 32-bit float (0.0-255.0)
+0457EE14 BBBBBBBB  // Phase 2 (short) blue component as 32-bit float (0.0-255.0)
+
+(Ep3 USA) Change color of pulsing orange text to be random every frame
+04155D78 7CA802A6
+04155D7C 7C661B78
+04155D80 481EF8B1
+04155D84 7C671B78
+04155D88 481EF8A9
+04155D8C 50677822
+04155D90 64E7FF00
+04155D94 90E60024
+04155D98 7CA803A6
+04155D9C 4E800020
+
+(Ep3 USA) Enable color and symbol codes in info board text
+(Use codes like e.g. $CG to change text colors, as described in CommandFormats.hh)
+040F2E80 4BF0D41D
+040F0274 4BF10025
+040EFC58 4BF10641
+04000298 38810008
+0400029C 38C3FFFF
+040002A0 8CA60001
+040002A4 28050024
+040002A8 4082000C
+040002AC 38000009
+040002B0 98060000
+040002B4 28050000
+040002B8 4082FFE8
+040002BC 7C633050
+040002C0 4E800020
+
+(Ep3 USA) Unlock all offline free battle maps
+042CAA00 38600001
+(This unlocks ALL maps, including a bunch of maps with garbage names that crash if you try to play them)
+
+(Ep3 USA) Talk to auction counter offline to get all cards
+042F5D18 4BD160E8
+0400BE00 9421FFE0
+0400BE04 7C0802A6
+0400BE08 90010024
+0400BE0C 93E10010
+0400BE10 93C10014
+0400BE14 93A10018
+0400BE18 9381001C
+0400BE1C 3C60802A
+0400BE20 60631BAC
+0400BE24 7C6903A6
+0400BE28 38600000
+0400BE2C 4E800421
+0400BE30 7C7F1B78
+0400BE34 3C60802A
+0400BE38 606315BC
+0400BE3C 7C6903A6
+0400BE40 7FE3FB78
+0400BE44 4E800421
+0400BE48 3F80802A
+0400BE4C 639C17AC
+0400BE50 3BC00001
+0400BE54 3BA00063
+0400BE58 7FE3FB78
+0400BE5C 7FC4F378
+0400BE60 7F8903A6
+0400BE64 4E800421
+0400BE68 3BBDFFFF
+0400BE6C 281D0000
+0400BE70 4082FFE8
+0400BE74 3BDE0001
+0400BE78 281E02F0
+0400BE7C 4081FFD8
+0400BE80 3C60802A
+0400BE84 6063160C
+0400BE88 7C6903A6
+0400BE8C 7FE3FB78
+0400BE90 4E800421
+0400BE94 83E10010
+0400BE98 83C10014
+0400BE9C 83A10018
+0400BEA0 8381001C
+0400BEA4 80010024
+0400BEA8 38210020
+0400BEAC 7C0803A6
+0400BEB0 482E9FC0
+
+(Episodes 1&2 USA v1.01) Press L for enemy debug; enable various other debug messages
+040FD9D8 38600001  # Various enemy debug messages
+00153E53 00000001  # Poison fog debug 1
+00153E4B 00000001  # Poison fog debug 2
+040FDA18 60000000  # TObjRoomId
+025CB6AA 00000000
+4A588EA0 00000040
+025CB6AA 00000001
+TODO: Figure out more debug message conditionals (vars/functions) and add them here
+
+(Episode 3 USA) Able to find VIP cards offline (but they're still rare)
+042C0B20 4800000C
+
+(Ep3 USA) Hold L when starting battle to enter debug menu
+042C5460 4BD3AF78
+040003D8 3C60804A
+040003DC 60630518
+040003E0 3C800002
+040003E4 480C9F35
+040003E8 2C030000
+040003EC 4082000C
+040003F0 8801001A
+040003F4 48000008
+040003F8 3800001A
+040003FC 482C5068
+
+(Ep3 USA) Dressing room always accessible
+041A16FC 38600001
+
+(Ep3 USA) Full dressing room v1
+Can't change your class, but you start with your existing appearance
+Go online with this code on after using the dressing room to fully save changes
+0418EB5C 60000000
+042A0184 389D0370
+042A0188 387E2120
+
+(Ep3 USA) Full dressing room v2
+Can change your class, but you start with the default appearance
+Go online with this code on after using the dressing room to fully save changes
+04186ECC 4BFFFFD8
+042A0184 389D0370
+042A0188 387E2120
+
+(Ep3 USA) Replace Options menu with debug menu
+04149E70 38600019
+
+(Ep3 USA) Jukebox is free
+0430D1DC 48000024
+
+(Ep3 USA) Use own character in battle (online only)
+041FFAB0 4800001C
+042A54D8 4BD5B0F9
+04200A34 4BDFFB9D
+041FFA9C 4BE00B35
+040005D0 38600000
+040005D4 3CA08049
+040005D8 80A54160
+040005DC 2805000F
+040005E0 41820008
+040005E4 481E8E24
+040005E8 80ADA448
+040005EC 7C042800
+040005F0 41820008
+040005F4 481E8E14
+040005F8 38600001
+040005FC 4E800020
+
+(Ep3 USA) Disable chat smut filter
+0412F8B8 7D0802A6
+0412F8BC 7C661B78
+0412F8C0 7C872378
+0412F8C4 48217285
+0412F8C8 38A30001
+0412F8CC 7CE33B78
+0412F8D0 7CC43378
+0412F8D4 7D0803A6
+0412F8D8 4BEDEBF4
+
+(Ep3 USA) Metal tiles don't appear in Simulator map
+04296904 4E800020
+
+(Ep3 USA) Enable Boooo and Laughter soundchat sounds
+Note: Without a TextEnglish.pr2/pr3 patch, the menu items for these sounds will be blank (but they will still work)
+0430B734 38800029
+0430B770 2C1F0029
+0430B59C 2C030029
+0430B5A8 5460083C
+0430B5B4 7C63022E
+0442B690 80258026
+0442B694 8227852D
+0442B698 80308031
+0442B69C 8A3F8532
+0442B6A0 8A408533
+0442B6A4 8A418A28
+0442B6A8 8A388A29
+0442B6AC 8A39852E
+0442B6B0 802F853D
+0442B6B4 85348535
+0442B6B8 853B8536
+0442B6BC 8537852B
+0442B6C0 853A853C
+0442B6C4 853E8044
+0442B6C8 80458046
+0442B6CC 80478048
+0442B6D0 8049804A
+0442B6D4 804B804C
+0442B6D8 804D804E
+0442B6DC 804F802A
+0442B6E0 802C0000

notes/dc-proto-connection-addresses.txt

@@ -0,0 +1,5 @@
+DC NTE: pso02.dricas.ne.jp
+Nov 2000 proto: test1.st-pso.games.sega.net
+Dec 2000 proto: sg107634.csrd.sega.co.jp OR master.pso.dream-key.com
+Jan 2001 proto: master.pso.dream-key.com
+Aug 2001 proto (v2): ???

notes/ep3-card-corrections.txt

@@ -0,0 +1,45 @@
+Ep3 card text corrections (from THG Discord):
+- AP Absorption: Does not block Tech attacks, instead they deal 2 extra damage.
+- Assault: Adds 5 AP minus the number of FCs on your field, not in your deck.
+- Assist Return: If this replaces an Assist card that was not in its owner's own Assist slot, that card gets re-played in to that slot.
+- Barble: His "Unfilial" ability does 3 damage, not 1.
+- Berdysh: Equip requirements are Hunter and Humanoid, not either one.
+- Black King Bar: "Machine Influence" doesn't need the opponent to be an attacker.
+- Blade Dance: "Insanity" doesn't exist. Has "Steady Damage".
+- Combo/Explosion: Adds +(# of Combo cards played in phase squared) AP, but the effect only applies once per attacker.
+- EGM: "Timed EXP Sacrifice" gives 9 EXP, not 6.
+- Fix: Sets all FC attacks to 2 damage, not FC attackers to 2 AP.
+- Flatland: Allows summoning in any space on the board, not summoning for free.
+- Ghost Blast: Damage added is 1/3 death count, not 1x.
+- Gibbles +: Curse' sets MV to 1 for 6 turns, not permanently.
+- Govulmer: His "AP Silence" reduces AP by 3, not to 0.
+- Guil Shark: +2 damage per Guil for the "Group" ability, not +1.
+- Gulgus: His "Copy" ability gives full AP and TP, not 1/2.
+- Holy Ray: Doesn't have the "Enemy Bonus" ability.
+- Kaladbolg: "Attack AC Unable" was a lie.
+- Lock on 3: Also has the ability "DEF Cost 4 Disable".
+- Mighty Knuckle: Adds 1.5x points spent as damage, not those points +1.
+- Migium: Gains TP from it's "Combo" ability, not AP.
+- Orland: "Sword AP Count" looks at your team, not the whole field.
+- Pofuilly Slime: His "Copy" ability gives 1/2 AP and TP, not full.
+- Rainbow Baton: Correctly reads as Tech OK.
+- Red Slicer: "Native Influence" doesn't need the opponent to be an attacker.
+- Rufina: She doubles the AP of action cards used, not her own.
+- Unit Blow: Adds +3 AP per Unit Blow played in the entire Combat Phase, but the effect only applies once per attacker.
+
+List of changes Sega made to Ep3 cards online (from THG Discord):
+- Rebalanced Vanilla Cards (E rank is gone, so some cards nerfed b/c they aren’t locked to 1x)
+- Meteor Cudgel: [Cost]5 ---> [Cost]4
+- Frozen Shooter: Frozen Target now only freezes self for 2 Turns, on a 20% chance.
+- Snow Queen: Frozen Target now only freezes self for 2 Turns, on a 25% chance.
+- Hand Break: Hand Disruptor added (old card description is now accurate)
+- Rush: [Cost]6 [AP]+0 ---> [Cost]4 [AP]+1
+- Explosion: [Cost]5 ---> [Cost]4
+- Resta: Range changed to Anti’s range (hits all ally SCs and FCs)
+- Dice Half: [Cost]5 ---> [Cost]4
+- Resistance: [Cost]5 ---> [Cost]4
+- Independant: [Cost]4 ---> [Cost]3
+- Dreamaga: [Cost]1 ---> [Cost]2
+- Dengeki: [Cost]1 ---> [Cost]2
+- EGM: [Cost]1 ---> [Cost]2
+- Beat: [AP]+5 ---> [AP]+4

notes/ep3-text-color-codes.txt

@@ -0,0 +1,127 @@
+
+0457EE18 437F0000  CG_color_r_phase1
+0457EE20 00000000  CG_color_g_phase1
+0457EE10 00000000  CG_color_b_phase1
+0457EE1C 00000000  CG_color_r_phase2
+0457EE24 437F0000  CG_color_g_phase2
+0457EE14 00000000  CG_color_b_phase2
+
+437F0000 == 255.0f
+
+
+
+
+
+(Ep3 USA) Change color of pulsing orange text (e.g. card ability names)
+0457EE18 RRRRRRRR  // Phase 1 (long) red component as 32-bit float (0.0-255.0)
+0457EE20 GGGGGGGG  // Phase 1 (long) green component as 32-bit float (0.0-255.0)
+0457EE10 BBBBBBBB  // Phase 1 (long) blue component as 32-bit float (0.0-255.0)
+0457EE1C RRRRRRRR  // Phase 2 (short) red component as 32-bit float (0.0-255.0)
+0457EE24 GGGGGGGG  // Phase 2 (short) green component as 32-bit float (0.0-255.0)
+0457EE14 BBBBBBBB  // Phase 2 (short) blue component as 32-bit float (0.0-255.0)
+
+(Ep3 USA) Change color of pulsing orange text to be random every frame
+04155D78 7CA802A6
+04155D7C 7C661B78
+04155D80 481EF8B1
+04155D84 7C671B78
+04155D88 481EF8A9
+04155D8C 50677822
+04155D90 64E7FF00
+04155D94 90E60024
+04155D98 7CA803A6
+04155D9C 4E800020
+
+
+
+color codes in info board
+
+patch 800F2E80 48253CC9     bl         strlen
+./m68kdasm --assemble-ppc32 --ppc32 --start-address=800F2E80
+bl      [8000029C]
+040F2E80 4BF0D41D  bl        -0x000F2BE4 /* 8000029C */
+
+patch/preserve 800f0274 38810008 addi       param_2,r1,0x8
+./m68kdasm --assemble-ppc32 --ppc32 --start-address=800F0274
+bl      [80000298]
+040F0274 4BF10025  bl        -0x000EFFDC /* 80000298 */
+
+patch/preserve 800efc58 38810008 addi       r4,r1,0x8
+./m68kdasm --assemble-ppc32 --ppc32 --start-address=800EFC58
+bl      [80000298]
+040EFC58 4BF10641  bl        -0x000EF9C0 /* 80000298 */
+
+./m68kdasm --assemble-ppc32 --ppc32 --start-address=80000298
+entry_from_send_61_and_send_98:
+addi    r4, r1, 8
+entry_from_send_D8:
+subi    r6, r3, 1
+again:
+lbzu    r5, [r6 + 1]
+cmplwi  r5, 0x24
+bne     skip_char
+li      r0, 0x09
+stb     [r6], r0
+skip_char:
+cmplwi  r5, 0
+bne     again
+sub     r3, r6, r3
+blr
+04000298 38810008  addi      r4, r1, 0x0008
+0400029C 38C3FFFF  subi      r6, r3, 0x0001
+040002A0 8CA60001  lbzu      r5, [r6 + 0x0001]
+040002A4 28050024  cmplwi    r5, 36
+040002A8 4082000C  bne       +0x0000000C /* 800002B4 */
+040002AC 38000009  li        r0, 0x0009
+040002B0 98060000  stb       [r6], r0
+040002B4 28050000  cmplwi    r5, 0
+040002B8 4082FFE8  bne       -0x00000018 /* 800002A0 */
+040002BC 7C633050  subf      r3, r3, r6
+040002C0 4E800020  blr
+
+
+
+Ep1&2 v1.01 version of the above code
+
+send_D9
+./m68kdasm --assemble-ppc32 --ppc32 --start-address=801DA398
+bl  [800002D4]
+041DA398 4BE25F3D  bl        -0x001DA0C4 /* 800002D4 */
+
+send_61
+./m68kdasm --assemble-ppc32 --ppc32 --start-address=801DC2AC
+bl  [800002D0]
+041DC2AC 4BE24025  bl        -0x001DBFDC /* 800002D0 */
+
+send_98
+./m68kdasm --assemble-ppc32 --ppc32 --start-address=801DC144
+bl  [800002D0]
+041DC144 4BE2418D  bl        -0x001DBE74 /* 800002D0 */
+
+./m68kdasm --assemble-ppc32 --ppc32 --start-address=800002D0
+entry_from_send_61_and_send_98:
+addi    r4, r1, 8
+entry_from_send_D8:
+subi    r6, r3, 1
+again:
+lbzu    r5, [r6 + 1]
+cmplwi  r5, 0x24
+bne     skip_char
+li      r0, 0x09
+stb     [r6], r0
+skip_char:
+cmplwi  r5, 0
+bne     again
+sub     r3, r6, r3
+blr
+040002D0 38810008  addi      r4, r1, 0x0008
+040002D4 38C3FFFF  subi      r6, r3, 0x0001
+040002D8 8CA60001  lbzu      r5, [r6 + 0x0001]
+040002DC 28050024  cmplwi    r5, 36
+040002E0 4082000C  bne       +0x0000000C /* 800002EC */
+040002E4 38000009  li        r0, 0x0009
+040002E8 98060000  stb       [r6], r0
+040002EC 28050000  cmplwi    r5, 0
+040002F0 4082FFE8  bne       -0x00000018 /* 800002D8 */
+040002F4 7C633050  subf      r3, r3, r6
+040002F8 4E800020  blr

notes/psobb/jpbb-resources/help_city_ja.lst

@@ -0,0 +1,3 @@
+.\data\help2-0-ja.png
+.\data\help0-4-ja.png
+.\data\help0-5-ja.png

notes/psobb/jpbb-resources/help_lobby_ja.lst

@@ -0,0 +1,6 @@
+.\data\help2-0-ja.png
+.\data\help0-0-ja.png
+.\data\help0-1-ja.png
+.\data\help0-2-ja.png
+.\data\help0-3-ja.png
+.\data\help0-7-ja.png

notes/psobb/jpbb-resources/help_prompt_city_ja.lst

@@ -0,0 +1 @@
+.\data\help1-1-ja.png

notes/psobb/jpbb-resources/help_prompt_lobby_ja.lst

@@ -0,0 +1 @@
+.\data\help1-0-ja.png

notes/psobb/psobb-notes.txt

@@ -0,0 +1,39 @@
+PSOBB SUPPORT FILES, NOTES & RESOURCES
+
+--------------------------------------------------------------------------------
+CLIENT LOCALIZATION
+
+By default PSOBB loads everything in Japanese so it requires some extra files
+to properly implement the English localization from SOA, these files are offered
+here inside the usbb-resources folder for your convenience they are the same ones
+from the old official USBB client
+
+To use them, you just need to drag and drop all its contents into your client's 
+data folder. Then if the client's internal lang flag is set correctly to English 
+will load all the correct texts from these files.
+
+In case you want to play in Japanese, just use the default Tethealla client and 
+delete all the files including _e or _eng in the names and then the game will 
+default everything to its original Japanese language.
+
+Just in case, there's the jpbb-resources folder with the latest localization 
+changes made on the official JPBB for an extra backup.
+
+---------------------------------------------------------------------------------
+PSOBB EP1,2,4 ORIGINAL VANILLA DROP TABLES/RATES
+
+Included in the vanilla-tables folder I placed the original files I created for the
+Schtserv vanilla for backup purposes as they are already implemented into the main
+newserv logic. 
+
+These tables will offer you the experience as close as possible to the original SEGA
+servers for PSOBB JP up to the latest patch before the servers shutdown, so besides a 
+fully functional Episode IV experience, the tables also include the latest special items
+which where added to some Episode 1 and Episode 2 in Ultimate for certain section ID's
+
+Vanilla Tables and rates are the same ones as the Schtserv Wiki for reference:
+https://bbwiki.schtserv.com/index.php/Drops-ep1
+https://bbwiki.schtserv.com/index.php/Drops-ep2
+https://bbwiki.schtserv.com/index.php/Drops-ep4
+
+

notes/psobb/usbb-resources/help_city_en.lst

@@ -0,0 +1,3 @@
+.\data\help2-0-en.png
+.\data\help0-4-en.png
+.\data\help0-5-en.png

notes/psobb/usbb-resources/help_lobby_en.lst

@@ -0,0 +1,6 @@
+.\data\help2-0-en.png
+.\data\help0-0-en.png
+.\data\help0-1-en.png
+.\data\help0-2-en.png
+.\data\help0-3-en.png
+.\data\help0-7-en.png

notes/psobb/usbb-resources/help_prompt_city_en.lst

@@ -0,0 +1 @@
+.\data\help1-1-en.png

notes/psobb/usbb-resources/help_prompt_lobby_en.lst

@@ -0,0 +1 @@
+.\data\help1-0-en.png

notes/star-value-tables.txt

@@ -0,0 +1,11 @@
+star value tables
+
+psobb [B1-437]
+00010203 04090909 01020304 05090909 01020304 05090909 01020304 05090909 01020304 05090909 00010203 04090909 01020304 05090909 01020304 05090909 01020304 05090909 00010203 09090901 02030409 09090102 03040909 09090A0A 090A0A09 0A0A090C 0B0A0A0A 0A0A0A0B 0A090A0A 0A0A0A09 0A0A0A0A 0A0A0A0A 0A0A0B0A 0C0C0B0A 0A090A09 090A0A0A 0A0C090C 0B0A090A 090C0A0B 0A0A0A0A 0A0A0A0B 0B0A0A0A 09090A09 0C0A0A0A 0B0A0B09 0A0A090A 0A0B090B 0A0B0B0A 090A090A 0B090A0A 0A0A0A0A 0A0A0A09 090C0C0C 0C0C0C0C 0C0C0C0C 0C0C0C0C 0C0C0C0C 0C0C0C0C 0C0C0009 0A0A0A0B 090A0A09 0A0A0B0A 0A0A0A0A 0A0A0A0A 0A0A0A0A 0A0A0A0A 0A0A0A0A 0B0B0B0B 0B0B0B0B 0B0B0B0A 0C0A0C0B 0A0A0A0A 0A0B0A0B 0B0B0B0B 0A0A090A 0A0A090B 0B0B0B0C 0C0C0C0C 0A0A0C0A 090A0C09 0A0B0A0A 0A0A0C0A 0A0A0A09 0A0C0A09 0A0A0A0A 0A090C0B 09090909 09090909 09090909 09090909 0909090B 0A0C0A0B 0B0C0A0A 0A090A0A 0A0A0B0A 0A0A0A0A 0909090A 0A090C0A 0C0C0C0C 0C0C0C0C 0C0C0C0C 0C0C0C0C 0C0C0C0C 0C0C0C0C 0C0C0C0C 0C0C0102 03040102 03040203 04020304 01020304 01020304 01020304 01020304 01020304 01020304 03040000 00010102 02030304 04050506 06070707 07080808 08080809 09090A0A 0A0A0A0A 0B0C0A0A 0A0A0A0A 0B0B0B0A 0B0B0C0B 0B0B0B0B 0A0A0A0A 0A0A0C09 0909090A 0A0B0C09 0B0A0A0A 0A0A0A0A 0A0A0A0B 0A0A0A0A 0A0A0A00 00010203 03040405 05050606 07070808 08080808 0A0A0A0A 0A0A0909 090A0A0A 0A0A0A0A 0A0A0B0A 0A0B0A09 0909090A 0B0B0000 0B000000 00080808 08080808 09080808 09080808 09070707 07070909 090C0909 09090909 09090909 09090909 09090909 09090909 09090909 09090909 09090909 09090909 09090909 09090909 09090909 0A0A0B0A 0B0A0909 0B0B0B0C 0A0A0A09 0A0A0A0A 090A0A0A 0A0A0A0A 0A0A0A0A 0203050B 0203050B 0203050B 0203050B 0204060B 0204060B 0203050B 080B080A 0B020305 02030502 03050304 06030405 07080B04 06090406 09040609 06090B06 090B0909 09090909 0A0B0B0B 0B0B0B0B 0B0B0B0B 0B0B0B0B 0B0B0B0B 0A0B0B0B 0B0B0B0B
+
+psogc [94-2F7]
+00010203 04090909 01020304 05090909 01020304 05090909 01020304 05090909 01020304 05090909 00010203 04090909 01020304 05090909 01020304 05090909 01020304 05090909 00010203 09090901 02030409 09090102 03040909 09090A0A 090A0A09 0A0A090C 0B0A0A0A 0A0A0A0B 0A090A0A 0A0A0A09 0A0A0A0A 0A0A0A0A 0A0A0B0A 0C0C0B0A 0A090A09 090A0A0A 0A0C090C 0B0A090A 090C0A0B 0A0A0A0A 0A0A0A0B 0B0A0A0A 09090A09 0C0A0A0A 0B0A0B09 0A0A090A 0A0B090B 0A0B0B0A 090A090A 0B090A0A 0A0A0A0A 0A0A0A09 090C0C0C 0C0C0C0C 0C0C0C0C 0C0C0C0C 0C0C0C0C 0C0C0C0C 0C0C0009 0A0A0A0B 090A0A09 0A0A0B0A 0A0A0A0A 0A0A0A0A 0A0A0A0A 0A0A0A0A 0A0A0A0A 0B0B0B0B 0B0B0B0B 0B0B0B0A 0C0A0C0B 0A0A0A0A 0A0B0A0B 0B0B0B0B 0A0A090A 0A0A090B 0B0B0B0C 0C0C0C0C 01020304 01020304 02030402 03040102 03040102 03040102 03040102 03040102 03040102 03040304 00000001 01020203 03040405 05060607 07070708 08080808 08090909 0A0A0A0A 0A0A0B0C 0A0A0A0A 0A0A0B0B 0B0A0B0B 0C0B0B0B 0B0B0000 01020303 04040505 05060607 07080808 0808080A 0A0A0A0A 0A090909 0A0A0A0A 0A0A0A0A 0A0B0A0A 0B0A0909 09090A0B 0B000000 00000000 08080808 08080809 08080809 08080809 07070707 07090909 0C090909 09090909 09090909 09090909 09090909 09090909 09090909 09090909 09090909 09090909 09090909 09090909 09090902 03050B02 03050B02 03050B02 03050B02 04060B02 04060B02 03050B08 0B080A0B 02030502 03050203 05030406 03040507 080B0406 09040609 04060906 090B0609 0B090909 090909
+
+
+
+0203050B0203050B0203050B0203050B

src/AFSArchive.cc

@@ -0,0 +1,86 @@
+#include "AFSArchive.hh"
+
+#include <stdio.h>
+#include <string.h>
+
+#include <phosg/Encoding.hh>
+#include <phosg/Filesystem.hh>
+#include <phosg/Strings.hh>
+
+using namespace std;
+
+AFSArchive::AFSArchive(shared_ptr<const string> data)
+    : data(data) {
+  struct FileHeader {
+    be_uint32_t magic;
+    le_uint32_t num_files;
+  } __attribute__((packed));
+
+  struct FileEntry {
+    le_uint32_t offset;
+    le_uint32_t size;
+  } __attribute__((packed));
+
+  StringReader r(*this->data);
+  const auto& header = r.get<FileHeader>();
+  if (header.magic != 0x41465300) { // 'AFS\0'
+    throw runtime_error("file is not an AFS archive");
+  }
+
+  while (this->entries.size() < header.num_files) {
+    const auto& entry = r.get<FileEntry>();
+    this->entries.emplace_back(Entry{.offset = entry.offset, .size = entry.size});
+  }
+}
+
+pair<const void*, size_t> AFSArchive::get(size_t index) const {
+  const auto& entry = this->entries.at(index);
+  if (entry.offset > this->data->size()) {
+    throw out_of_range("entry begins beyond end of archive");
+  }
+  if (entry.offset + entry.size > this->data->size()) {
+    throw out_of_range("entry extends beyond end of archive");
+  }
+
+  return make_pair(this->data->data() + entry.offset, entry.size);
+}
+
+string AFSArchive::get_copy(size_t index) const {
+  auto ret = this->get(index);
+  return string(reinterpret_cast<const char*>(ret.first), ret.second);
+}
+
+StringReader AFSArchive::get_reader(size_t index) const {
+  auto ret = this->get(index);
+  return StringReader(ret.first, ret.second);
+}
+
+string AFSArchive::generate(const vector<string>& files, bool big_endian) {
+  return big_endian ? AFSArchive::generate_t<true>(files) : AFSArchive::generate_t<false>(files);
+}
+
+template <bool IsBigEndian>
+string AFSArchive::generate_t(const vector<string>& files) {
+  using U32T = typename std::conditional<IsBigEndian, be_uint32_t, le_uint32_t>::type;
+
+  StringWriter w;
+  w.put_u32b(0x41465300); // 'AFS\0'
+  w.put<U32T>(files.size());
+
+  // It seems entries are aligned to 0x800-byte boundaries, and the file's
+  // header is always 0x80000 (!) bytes, most of which is unused
+  uint32_t data_offset = 0x80000;
+  for (const auto& file : files) {
+    w.put<U32T>(data_offset);
+    w.put<U32T>(file.size());
+    data_offset = (data_offset + file.size() + 0x7FF) & (~0x7FF);
+  }
+
+  w.extend_to(0x80000);
+  for (const auto& file : files) {
+    w.write(file);
+    w.extend_to((w.size() + 0x7FF) & (~0x7FF));
+  }
+
+  return std::move(w.str());
+}

src/AFSArchive.hh

@@ -0,0 +1,36 @@
+#pragma once
+
+#include <stdint.h>
+
+#include <memory>
+#include <phosg/Filesystem.hh>
+#include <phosg/Strings.hh>
+#include <string>
+#include <unordered_map>
+
+class AFSArchive {
+public:
+  AFSArchive(std::shared_ptr<const std::string> data);
+  ~AFSArchive() = default;
+
+  struct Entry {
+    uint64_t offset;
+    uint32_t size;
+  };
+  inline const std::vector<Entry>& all_entries() const {
+    return this->entries;
+  }
+
+  std::pair<const void*, size_t> get(size_t index) const;
+  std::string get_copy(size_t index) const;
+  StringReader get_reader(size_t index) const;
+
+  static std::string generate(const std::vector<std::string>& files, bool big_endian);
+
+private:
+  template <bool IsBigEndian>
+  static std::string generate_t(const std::vector<std::string>& files);
+
+  std::shared_ptr<const std::string> data;
+  std::vector<Entry> entries;
+};

src/ARCodeTranslator-Stub.hh

@@ -0,0 +1,8 @@
+#pragma once
+
+#include <stdexcept>
+#include <string>
+
+inline void run_ar_code_translator(const std::string&, const std::string&, const std::string&) {
+  throw std::runtime_error("resource_file is not available; install it and rebuild newserv");
+}

src/ARCodeTranslator.cc

@@ -0,0 +1,154 @@
+#include "ARCodeTranslator.hh"
+
+#include <phosg/Filesystem.hh>
+#include <phosg/Strings.hh>
+#include <resource_file/ExecutableFormats/DOLFile.hh>
+
+using namespace std;
+
+void run_ar_code_translator(const std::string& initial_directory, const std::string& use_file, const std::string& command) {
+  string directory = initial_directory;
+  while (ends_with(directory, "/")) {
+    directory.resize(directory.size() - 1);
+  }
+  PrefixedLogger log("[ar-trans] ");
+
+  unordered_map<string, shared_ptr<DOLFile>> files;
+  for (const auto& filename : list_directory(directory)) {
+    if (ends_with(filename, ".dol")) {
+      string name = filename.substr(0, filename.size() - 4);
+      string path = directory + "/" + filename;
+      files.emplace(name, new DOLFile(path.c_str()));
+      log.info("Loaded %s", name.c_str());
+    }
+  }
+
+  string source_filename;
+  shared_ptr<DOLFile> source_file;
+  auto find_match = [&](std::shared_ptr<DOLFile> target_file, uint32_t source_address) -> uint32_t {
+    const DOLFile::Section* source_section = nullptr;
+    for (const auto& sec : source_file->sections) {
+      if (source_address >= sec.address && source_address < sec.address + sec.data.size()) {
+        source_section = &sec;
+        break;
+      }
+    }
+    if (!source_section) {
+      throw runtime_error("source address not within any section");
+    }
+    size_t source_offset = source_address - source_section->address;
+    size_t source_bytes_available_after = source_section->data.size() - source_offset;
+    log.info("(find_match) Source offset = %08zX with %08zX bytes available after", source_offset, source_bytes_available_after);
+
+    for (size_t match_length = 4;
+         match_length < min<size_t>(source_bytes_available_after, 0x100);
+         match_length += 4) {
+      size_t num_matches = 0;
+      size_t last_match_address = 0;
+      StringReader source_r(source_section->data.data() + source_offset, match_length);
+      for (const auto& target_section : target_file->sections) {
+        for (size_t target_section_offset = 0;
+             target_section_offset + match_length <= target_section.data.size();
+             target_section_offset += 4) {
+          source_r.go(0);
+          StringReader target_r(target_section.data.data() + target_section_offset, match_length);
+          size_t z;
+          for (z = 0; z < match_length; z += 4) {
+            if (source_section->is_text) {
+              uint32_t source_opcode = source_r.get_u32b();
+              uint32_t target_opcode = target_r.get_u32b();
+              uint32_t source_class = source_opcode & 0xFC000000;
+              if (source_class != (target_opcode & 0xFC000000)) {
+                break;
+              }
+              if (source_class == 0x48000000) {
+                source_opcode &= 0xFC000003;
+                target_opcode &= 0xFC000003;
+              } else if (source_class == 0x40000000) {
+                source_opcode &= 0xFFFF0003;
+                target_opcode &= 0xFFFF0003;
+              }
+              if (source_opcode != target_opcode) {
+                break;
+              }
+            } else {
+              if (source_r.get_u32l() != target_r.get_u32l()) {
+                break;
+              }
+            }
+          }
+          if (z == match_length) {
+            num_matches++;
+            last_match_address = target_section.address + target_section_offset;
+          }
+        }
+      }
+      log.info("(find_match) For match length %zX, %zu matches found", match_length, num_matches);
+      if (num_matches == 1) {
+        return last_match_address;
+      } else if (num_matches == 0) {
+        throw runtime_error("did not find exactly one match");
+      }
+    }
+    throw runtime_error("scan field too long; too many matches");
+  };
+
+  auto handle_command = [&](const string& command) -> void {
+    auto tokens = split(command, ' ');
+    if (tokens.empty()) {
+      throw runtime_error("no command given");
+    }
+    strip_trailing_whitespace(tokens[tokens.size() - 1]);
+
+    if (tokens[0] == "use") {
+      source_filename = tokens.at(1);
+      source_file = files.at(source_filename);
+    } else if (tokens[0] == "match") {
+      if (!source_file) {
+        throw runtime_error("no source file selected");
+      }
+
+      uint32_t source_addr = stoul(tokens.at(1), nullptr, 16);
+      for (const auto& it : files) {
+        if (it.second == source_file) {
+          log.info("(%s) %08" PRIX32, it.first.c_str(), source_addr);
+        } else {
+          try {
+            uint32_t match_addr = find_match(it.second, source_addr);
+            log.info("(%s) %08" PRIX32, it.first.c_str(), match_addr);
+          } catch (const exception& e) {
+            log.error("(%s) failed: %s", it.first.c_str(), e.what());
+          }
+        }
+      }
+    } else if (!tokens[0].empty()) {
+      throw runtime_error("unknown command");
+    }
+  };
+
+  if (!use_file.empty()) {
+    source_filename = use_file;
+    source_file = files.at(source_filename);
+  }
+
+  if (!command.empty()) {
+    handle_command(command);
+  } else {
+    while (!feof(stdin)) {
+      if (!source_filename.empty()) {
+        fprintf(stdout, "ar-trans:%s/%s> ", directory.c_str(), source_filename.c_str());
+      } else {
+        fprintf(stdout, "ar-trans:%s> ", directory.c_str());
+      }
+      fflush(stdout);
+
+      string command = fgets(stdin);
+      try {
+        handle_command(command);
+      } catch (const exception& e) {
+        log.error("Failed: %s", e.what());
+      }
+    }
+    fputc('\n', stdout);
+  }
+}