From c06d7bdc704301137ba9beeda3eeda6b6db0a34c Mon Sep 17 00:00:00 2001 From: Martin Michelsen Date: Wed, 11 May 2022 16:49:46 -0700 Subject: [PATCH] update readme --- README.md | 95 +++++++++++++++++++++++-------------------------------- 1 file changed, 39 insertions(+), 56 deletions(-) diff --git a/README.md b/README.md index 8d89a501..dd6c85b2 100644 --- a/README.md +++ b/README.md @@ -16,16 +16,17 @@ Current known issues / missing features: - Test all the communication features (info board, simple mail, card search, etc.) - The trade window isn't implemented yet. - PSO PC and PSOBB are not well-tested and likely will disconnect when clients try to use unimplemented features. Only GC is known to be stable and mostly complete. -- Add all the chat commands that khyller used to have. (Most, but not all, currently exist in newserv.) ## Usage -Currently this code should build on macOS and Ubuntu. It will likely work on other Linux flavors too, but probably will not work on Windows. +Currently this code 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 - the build process could be very manual. -So, you've read all of the above and you want to try it out? Here's what you do: -- Make sure you have CMake and libevent installed. +There is a probably-not-too-old macOS release on the newserv GitHub repository (look in the right sidebar). + +If you're running Linux or want to build newserv yourself, here's what you do: +- Make sure you have CMake and libevent installed. (`brew install libevent` on macOS, `sudo apt-get install cmake libevent-dev` on most Linuxes) - Build and install phosg (https://github.com/fuzziqersoftware/phosg). -- Run `cmake . && make`. +- Run `cmake . && make` on the newserv directory. - In the system/ directory, make a copy of config.example.json named config.json, and edit it appropriately. - 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. - Use the interactive shell to add a license. Run `help` in the shell to see how to do this. @@ -36,14 +37,14 @@ newserv automatically finds quests in the system/quests directory. To install yo There are multiple PSO quest formats out there; newserv supports most of them. Specifically, newserv can use quests in any of the following formats: - bin/dat format: These quests consist of two files with the same base name, a .bin file and a .dat file. -- Unencrypted GCI format: These quests also consist of a .bin and .dat file, but an encoding is applied on top of them. The filenames should end in .bin.gci and .dat.gci. +- Unencrypted GCI format: These quests also consist of a .bin and .dat file, but an encoding is applied on top of them. The filenames should end in .bin.gci and .dat.gci. (Note that there also exists an encrypted GCI format, which newserv does not support.) - Encrypted DLQ format: These quests also consist of a .bin and .dat file, but downlaod quest encryption is applied on top of them. The filenames should end in .bin.dlq and .dat.dlq. - QST format: These quests consist of only a .qst file, which contains both the .bin and .dat files within it. Standard quest file names should be like `q###-CATEGORY-VERSION.EXT`; battle quests should be named like `b###-VERSION.EXT`, and challenge quests should be named like `c###-VERSION.EXT`. The fields in each filename are: - `###`: quest number (this doesn't really matter; it should just be unique for the 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 +- `VERSION`: d1 = Dreamcast v1, dc = Dreamcast v2, pc = PC, gc = GameCube Episodes 1 & 2, gc3 = Episode 3, bb = Blue Burst - `EXT`: file extension (bin, dat, bin.gci, dat.gci, bin.dlq, dat.dlq, or qst) When newserv indexes the quests during startup, it will warn (but not fail) if any quests are corrupt or in unrecognized formats. @@ -59,63 +60,62 @@ The server's shell supports a variety of administration commands. If the interac newserv also supports a variety of commands players can use via the chat interface. These commands work on the game server (that is, in lobbies and games hosted by newserv); they do not work on the proxy server. The chat commands are: * Information commands - * `$li`: Show basic information about the lobby or game you're in. - * `$what`: Show the type, name, and stats of the nearest item on the ground. + * `$li`: Shows basic information about the lobby or game you're in. + * `$what`: Shows the type, name, and stats of the nearest item on the ground. * Personal state commands - * `$arrow `: Change your lobby arrow color. - * `$secid `: Set 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. + * `$arrow `: Changes your lobby arrow color. + * `$secid `: 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. * Blue Burst player commands - * `$bbchar <1-4>`: If the username and password are correct, convert the current character to BB format and save it on the server in the given slot. - * `$changebank `: Switch to another bank. - * `$edit `: Modify your character data. - * `$item `: Set the next item to be dropped from an enemy or box. + * `$bbchar <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. + * `$edit `: Modifies your character data. + * `$item `: Sets the next item to be dropped from an enemy or box. * Game state commands - * `$maxlevel `: Set the maximum level for players to join the current game. - * `$minlevel `: Set the minimum level for players to join the current game. - * `$password `: Set the game's join password. To unlock the game, run `$password` with nothing after it. + * `$maxlevel `: Sets the maximum level for players to join the current game. + * `$minlevel `: Sets the minimum level for players to join the current game. + * `$password `: Sets the game's join password. To unlock the game, run `$password` with nothing after it. * Cheat mode commands - * `$cheat`: Enable or disable cheat mode for the current game. All other cheat mode commands do nothing if cheat mode is disabled. - * `$infhp` / `$inftp`: Enable or disable infinite HP or TP mode. Applies to only you. In infinite HP mode, one-hit KO attacks will still kill you. - * `$warp `: Warp yourself to the given area. - * `$next`: Warp yourself to the next area. - * `$swa`: Enable or disable switch assist. When enabled, the server will attempt to automatically unlock two-player doors in solo games if you step on both switches sequentially. + * `$cheat`: Enables or disables cheat mode for the current game. All other cheat mode commands do nothing if cheat mode is disabled. + * `$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 `: Warps yourself to the given area. + * `$next`: Warps yourself to the next area. + * `$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. * Configuration commands - * `$event ` / `$allevent `: Set the current holiday event in the current lobby, or in all lobbies. Holiday events are documented in the "Using $event" item in the information menu. - * `$song `: Play a specific song in the current lobby (Episode 3 only). + * `$event ` / `$allevent `: Sets the current holiday event in the current lobby, or in all lobbies. Holiday events are documented in the "Using $event" item in the information menu. + * `$song `: Plays a specific song in the current lobby (Episode 3 only). * Administration commands - * `$ann `: Send an announcement message. The message text is sent to all players in all games and lobbies. - * `$ax `: Send a message to the server's terminal. This cannot be used to run server shell commands; it only prints text to stderr. - * `$silence `: Silence a player (remove their ability to chat) or unsilence a player. The identifier may be the player's name or guild card number. - * `$kick `: Disconnect a player. The identifier may be the player's name or guild card number. - * `$ban `: Ban a player. The identifier may be the player's name or guild card number. + * `$ann `: Sends an announcement message. The message text is sent to all players in all games and lobbies. + * `$ax `: Sends a message to the server's terminal. This cannot be used to run server shell commands; it only prints text to stderr. + * `$silence `: Silences a player (remove their ability to chat) or unsilences a player. The identifier may be the player's name or guild card number. + * `$kick `: Disconnects a player. The identifier may be the player's name or guild card number. + * `$ban `: Bans a player. The identifier may be the player's name or guild card number. ### Using newserv as a proxy -If you want to play online on remote servers rather than running your own server, newserv also includes a PSO proxy. Currently this works with PSO GC and may work with PC, but not with BB. +If you want to play online on remote servers rather than running your own server, newserv also includes a PSO proxy. Currently this works with PSO GC and may work with PC; it also works with some BB clients in specific situations. To use the proxy, add an entry to the ProxyDestinations dictionary in config.json, then run newserv and connect to it as normal (see below). You'll see a "Proxy server" option in the main menu, and you can pick which remote server to connect to. A few things to be aware of when using the proxy server: -- There are shell commands that affect clients on the proxy (run 'help' in the shell to see what they are). All proxy commands in the 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 to affect. -- The remote server will probably try to assign you a guild card number that doesn't match the one you have on newserv. The proxy server rewrites the commands on the fly 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. This number is printed to the terminal at the time it's assigned, but is not (yet) shown to the client in any way. - On PC and GC, using the Change Ship or Change Block actions from the lobby counter will bring you back to newserv's main menu, not the remote server's ship select. You can go back to the server you were just on by choosing it from newserv's proxy server menu again. +- The remote server will probably try to assign you a guild card number that doesn't match the one you have on newserv. The proxy server rewrites the commands on the fly 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 connect to the remote server. - The proxy server blocks chat commands that look like newserv commands by default, but you can change this with the `set-chat-safety off` shell command if needed. +- There are shell commands that affect clients on the proxy (run 'help' in the shell to see what they are). All proxy commands in the 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 to affect. ### Connecting local clients -If you're running PSO on a real GameCube, you can make it connect to newserv by setting its default gateway and DNS server addresses to newserv's address. Note that newserv's DNS server is disabled by default; you'll have to enable it in config.json. +If you're running PSO on a real GameCube, you can make it connect to newserv by setting its default gateway and DNS server addresses to newserv's address. newserv's DNS server must be running on port 53 and accessible. -If you have PSO Plus or Episode III, it won't want to connect to a server on the same local network as the GameCube itself, as determined by the GC's IP address and subnet mask. In the old days, one way to get around this was to create a fake network adapter on the server (or use an existing real one) that has an IP address on a different subnet, tell the GameCube that the server is the default gateway, and have the server reply to the DNS request with its non-local IP address. To do this with newserv, just set LocalAddress in the config file to a different interface. For example, if the GameCube is on the 192.168.0.x network and your other adapter has address 10.0.1.6, set newserv's LocalAddress to 10.0.1.6 and set PSO's DNS server and default gateway addresses to the server's 192.168.0.x address. This may not work on modern systems or on non-Windows machines - I haven't tested it in many years. +If you have PSO Plus or Episode III, it won't want to connect to a server on the same local network as the GameCube itself, as determined by the GameCube's IP address and subnet mask. In the old days, one way to get around this was to create a fake network adapter on the server (or use an existing real one) that has an IP address on a different subnet, tell the GameCube that the server is the default gateway, and have the server reply to the DNS request with its non-local IP address. To do this with newserv, just set LocalAddress in the config file to a different interface. For example, if the GameCube is on the 192.168.0.x network and your other adapter has address 10.0.1.6, set newserv's LocalAddress to 10.0.1.6 and set PSO's DNS server and default gateway addresses to the server's 192.168.0.x address. This may not work on modern systems or on non-Windows machines - I haven't tested it in many years. If you're emulating PSO 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. This works for all PSO versions, including Plus and Episode III, without the trickery described above. To do this: -- Set the BBA type to tapserver (Config -> GameCube -> SP1). -- Enable the IP stack simulator according to the comments in config.json, and start newserv. You do not need to install or run tapserver. +- Set Dolphin's BBA type to tapserver (Config -> GameCube -> SP1). +- Enable newserv's IP stack simulator according to the comments in config.json, and start newserv. You do not need to install or run tapserver. - 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` @@ -126,23 +126,6 @@ If you're emulating PSO using a version of Dolphin with tapserver support (curre ### Connecting external clients -If you want to accept connections from outside your local network, you'll need to set ExternalAddress to your public IP address in the configuration file, and you'll likely need to open some ports in your router's NAT configuration. You'll need to open the following ports depending on which client versions you want to be able to connect: +If you want to accept connections from outside your local network, you'll need to set ExternalAddress to your public IP address in the configuration file, and you'll likely need to open some ports in your router's NAT configuration - specifically, all the TCP ports listed in PortConfiguration in config.json. - PSO PC 9100, 9300, 9420, 10000 - PSO GC 1.0 JP 9000, 9421 - PSO GC 1.1 JP 9001, 9421 - PSO GC Ep3 JP 9003, 9421 - PSO GC 1.0 US 9100, 9421 - PSO GC Ep3 US 9103, 9421 - PSO GC 1.0 EU 9200, 9421 - PSO GC 1.1 EU 9201, 9421 - PSO GC Ep3 EU 9203, 9421 - PSO BB 9422, 11000, 12000, 12004, 12005, 12008 - -If you want to allow external clients to use the proxy server, you'll need to open more ports: - - PSO PC 9520 - PSO GC (all versions) 9521 - PSO BB 9522 - -For GC clients, you'll have to use newserv's built-in DNS server or set up your own DNS server as well. Remote players can connect to your server by entering your DNS server's IP address in their client's network configuration. If you use newserv's built-in DNS server, you'll also need to forward UDP port 53 to your newserv instance. +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.