Add documentation:

- README.md: Updated with information on how to get started using a pre-built release. Updated the steps for building from source. Added information about how the purpose of each NuGet package dependency. - Added quickstart documents to assist users on getting started. One for from scratch, and another for those that already have a zone running ASSS. - Added the user manual (still a work in progress, missing many parts).
gigamon-dev · Jul 1, 2023 · 93dce50 · 93dce50
1 parent 2b11d9a
commit 93dce50
Show file tree

Hide file tree

Showing 4 changed files with 569 additions and 20 deletions.
diff --git a/README.md b/README.md
@@ -4,28 +4,41 @@ A zone server for the multiplayer game Subspace based on *A Small Subspace Serve
 ## About
 This is a cross-platform server written in C#.  It was developed based on the *A Small Subspace Server* (*ASSS*) open-source project and can be considered a derivative.  As such, the modular design closely resembles that of *ASSS* and is meant to be extended in very much the same ways. 
 
-This project aims to match the core functionality of *ASSS*. Contrary to its name, *ASSS* is not "small". Porting over everything in *ASSS* is not a realistic goal, therefore a choice had to be made on what is considered essential. Nearly everything needed to run a zone is available. See [asss-equivalents](./doc/asss-equivalents.md) for a more detailed listing. Also, see [additional-features](./doc/additional-features.md) for information about features that this server adds, which are not in *ASSS*.
-
-For guidance on how to extend the server, see the [Developer Guide](./doc/developer-guide.md).
-
-## Setup / Use
-1. Open and build the solution: `"src/SubspaceServer.sln"`.
-2. Setup the Zone
-   1. Copy **Continuum.exe** (currently 0.40) into the zone's **'clients'** folder: `"src/SubspaceServer/Zone/clients"`.
-   2. Configure it much like you would for *ASSS*.
-      - arenas
-      - conf
-      - maps
-      - news.txt
-3. Run it.  
-*Note: The working directory needs to be the **'Zone'** folder.*
+This project provides everything needed to host a zone. It has all of the essential functionality from *ASSS* and also many of the extras. 
+
+- See [asss-equivalents](./doc/asss-equivalents.md) for a detailed listing and comparison of included parts.
+- Also, see [additional-features](./doc/additional-features.md) for information about features that this server adds, which are not in *ASSS*.
+
+## Get Started
+
+[Download](./releases) the latest release.
+
+- Follow the [Quickstart](./doc/quickstart.md) for instructions on how to get up and running from scratch.
+   - If you already have a zone running using *ASSS*, see [Quickstart from ASSS](./doc/quickstart-from-asss.md) instead. It has instructions on how to use your existing files.
+- Read the [User Manual](./doc/user-manual.md) for more information.
+
+## Build and Extend
+
+The built-in functionality of the server is more than enough to host a zone. It's highly configurable and supports all the regular gameplay modes. However, the true power of this project is in how it can be extended by writing plugins.
+
+For guidance on how to develop your own plugins to extend the server, see the [Developer Guide](./doc/developer-guide.md).
+
+To build the server,
+- Get the code:
+
+   ```
+   git clone https://github.com/gigamon-dev/SubspaceServer.git
+   ````
+
+- Open the solution: `"src/SubspaceServer.sln"` to build and run it.
+- Remember to place a copy of **Continuum.exe** (currently 0.40) into the zone's **'clients'** folder: `"src/SubspaceServer/Zone/clients"` before running.
 
 ## Dependencies
-- [Google.Protobuf](https://www.nuget.org/packages/Google.Protobuf)
-- [Iconic.Zlib.Netstandard](https://www.nuget.org/packages/Iconic.Zlib.Netstandard)
-- [Microsoft.Extensions.ObjectPool](https://www.nuget.org/packages/Microsoft.Extensions.ObjectPool)
-- [SixLabors.ImageSharp](https://www.nuget.org/packages/SixLabors.ImageSharp)
-- [System.Data.SQLite.Core](https://www.nuget.org/packages/System.Data.SQLite.Core)
+- [Google.Protobuf](https://www.nuget.org/packages/Google.Protobuf) - for serializing data
+- [Iconic.Zlib.Netstandard](https://www.nuget.org/packages/Iconic.Zlib.Netstandard) - for zlib and crc32
+- [Microsoft.Extensions.ObjectPool](https://www.nuget.org/packages/Microsoft.Extensions.ObjectPool) - object pooling to reduce the need to garbage collect
+- [SixLabors.ImageSharp](https://www.nuget.org/packages/SixLabors.ImageSharp) - for creating images of maps
+- [System.Data.SQLite.Core](https://www.nuget.org/packages/System.Data.SQLite.Core) - embedded database for persisting player and arena data
 
 ## License
 GNU GPLv2, since that's what *A Small Subspace Server* uses and much of this can be considered as being a derivative of it.

diff --git a/doc/quickstart-from-asss.md b/doc/quickstart-from-asss.md
@@ -0,0 +1,104 @@
+# Subspace Server .NET Quickstart from ASSS
+
+### Contents
+
+[Prerequisites](#prerequisites)<br>
+[Installation](#installation)<br>
+[Transition to Modules.config](#transition-to-modulesconfig)<br>
+[Modules Attached to Arenas](#modules-attached-to-arenas)<br>
+[Run the server](#run-the-server)<br>
+[Take it further](#take-it-further)<br>
+
+This article provides instructions on how to quickly get *Subspace Server .NET* up and running for those that already have a zone using *ASSS* and would like to try to hosting it using *Subspace Server .NET*.
+
+If you don't already have a zone running *ASSS*, see [Quickstart](./quickstart.md) instead for instructions on how to set up from scratch.
+
+## Prerequisites
+
+The server requires that .NET be installed. If you don't already have it, you can get it from: https://dotnet.microsoft.com. (Currently .NET 7)
+
+The server can technically be run on any system supported by .NET. However, pre-built binaries are only being provided for Linux x64 and Windows x64.
+
+> You are free to download the source code and build it for other platforms/architectures, but be aware of these known limitations:
+> - The System.Data.SQLite NuGet package doesn't include native binaries for ARM64. To work around this, either build your own ARM64 binary for SQLite or do not use the persist modules (`SS.Core.Modules.PersistSQLite` and `SS.Core.Modules.Persist`).
+> - The Continuum Encryption native binaries (closed source) are currently only available for Linux x64 and Windows x64. In the future, macOS and ARM64 binaries may be considered.
+
+## Installation
+
+Download the latest [release](../releases) and extract it to the location of your choice.
+
+Copy files from your ASSS zone including:
+- The `clients` folder (which should contain the Continuum.exe client)
+- The `maps` folder
+- The `arenas` folder
+- `news.txt`
+- `obscene.txt`
+- `conf/passwd.conf`
+- `conf/staff.conf`
+- any additional .conf files under `conf/` that your arenas #include
+
+## Transition to Modules.config
+
+ASSS uses the `conf/modules.conf` file to determine the which modules to load and the order to load them in. Subspace Server .NET uses `conf/Modules.config`, which is similar, but is an XML file.
+
+Module names are slightly different in Subspace Server .NET. It should be relatively obvious which modules you'll want to load compared to those being  loaded for your existing ASSS zone. In fact, the default load order is more or less the same. If in doubt, see [asss-equivalents](asss-equivalents.md) for a mapping of ASSS modules to Subspace Server .NET modules.
+
+## Modules Attached to Arenas
+
+In an arena.conf file, the `Modules:AttachModules` setting is used to attach modules to the arena. The value of this setting differs slightly, so you'll need to edit each of the arena.conf files that includes this setting.
+
+In ASSS the setting looks like:
+```INI
+[ Modules ]
+AttachModules = \
+	points_kill \
+	points_flag \
+	points_goal \
+	buy
+```
+
+The setting is similar in Subspace Server .NET, except that the module names are different. Here's the equivalent of the above for Subspace Server .NET:
+```INI
+[ Modules ]
+AttachModules = \
+	SS.Core.Modules.Scoring.KillPoints \
+	SS.Core.Modules.Scoring.FlagGamePoints \
+	SS.Core.Modules.Scoring.BallGamePoints \
+	SS.Core.Modules.Buy
+```
+
+Notice the modules differ slightly in name, and they include the full namespace. See [asss-equivalents](asss-equivalents.md) for a mapping of ASSS modules to Subspace Server .NET modules.
+
+## Run the server
+
+To run the server, use the included startup script which is located in the zone's root folder.
+
+#### Linux and macOS
+
+The script is named: `run-server.sh`. From the shell, `cd` to the folder you installed the server to, and run it:
+
+```
+./run-server.sh
+```
+
+#### Windows
+
+The script is named: `run-server.cmd`. Run it from File Explorer, or from the command line `cd` to the folder you installed the server to, and run it.
+
+```
+run-server.cmd
+```
+
+#### PowerShell
+
+Alternatively, a PowerShell script, `run-server-ps1` is also included, in case that is your preference.
+
+```
+./run-server.ps1
+```
+
+## Take it further
+
+For more information about the server, see the [User Manual](./user-manual.md). 
+
+To learn how to create your own plugin modules, see the [Developer Guide](./developer-guide.md).
diff --git a/doc/quickstart.md b/doc/quickstart.md
@@ -0,0 +1,96 @@
+# Subspace Server .NET Quickstart
+
+### Contents
+
+[Prerequisites](#prerequisites)<br>
+[Installation](#installation)<br>
+[Run the server](#run-the-server)<br>
+[Connect to your zone](#connect-to-your-zone)<br>
+[Take it further](#take-it-further)<br>
+
+This article provides instructions on how to quickly get *Subspace Server .NET* up and running from scratch.
+
+If you already have a zone running *ASSS*, see [Quickstart from ASSS](quickstart-from-asss.md) instead for instructions on how to use your existing *ASSS* files.
+
+## Prerequisites
+
+The server requires that .NET be installed. If you don't already have it, you can get it from: https://dotnet.microsoft.com. (Currently .NET 7)
+
+The server can technically be run on any system supported by .NET. However, pre-built binaries are only being provided for Linux x64 and Windows x64.
+
+> You are free to download the source code and build it for other platforms/architectures, but be aware of these known limitations:
+> - The System.Data.SQLite NuGet package doesn't include native binaries for ARM64. To work around this, either build your own ARM64 binary for SQLite or do not use the persist modules (`SS.Core.Modules.PersistSQLite` and `SS.Core.Modules.Persist`).
+> - The Continuum Encryption native binaries (closed source) are currently only available for Linux x64 and Windows x64. In the future, macOS and ARM64 binaries may be considered.
+
+## Installation
+
+1. Download the latest [release](../releases) and extract it to the location of your choice.
+
+2. In the folder you extracted to, find the folder named `clients`. Copy `Continuum.exe` from your Continuum client's folder into the `clients` folder.
+
+At this point, the server can technically be run and you'd be able to connect to it on port 5000. However, you'll likely want to change that.
+
+## Configure the endpoint to Listen on
+
+Open the `conf/global.conf` file and find the `[Listen]` section. It should look something like:
+
+```ini
+[ Listen ]
+Port = 5000
+BindAddress = 
+```
+
+The `Port` setting tells the server which UDP port to listen on for game requests. It also determines which port to listen on for ping requests, which is always implicitly the `Port` number + 1. Therefore, in this example, it listens for game requests on port 5000 and for ping requests on port 5001.
+
+The `BindAddress` setting tells the server which IP address to listen on. By default, this setting is empty, meaning listen on all available network interfaces.
+
+## Run the server
+
+To run the server, use the included startup script which is located in the zone's root folder.
+
+#### Linux and macOS
+
+The script is named: `run-server.sh`. From the shell, `cd` to the folder you installed the server to, and run it:
+
+```
+./run-server.sh
+```
+
+#### Windows
+
+The script is named: `run-server.cmd`. Run it from File Explorer, or from command line `cd` to the folder you installed the server to, and run it.
+
+```
+run-server.cmd
+```
+
+#### PowerShell
+
+Alternatively, a PowerShell script, `run-server-ps1` is also included, in case that is your preference.
+
+```
+./run-server.ps1
+```
+
+> To shut the server down gracefully, use: `Ctrl + C`
+
+## Connect to your zone
+
+Start the Continuum client. On the main screen, click the **Zones** button to open the **Add/Update Zones** window. Alternatively, it can be opened by navigating on the menu bar to: **View** --> **Zones...**
+
+On the **Add/Update Zones** window, click the "**Add Custom...**" button and fill out the fields. Fill in the **Zone Name** with a name of your choice. Fill in the **IP Address** of the server. If you're running it locally, you can use 127.0.0.1 to specify localhost. The **Port** should be the value you configured earlier, or 5000 if you skipped that step.
+
+Confirm you choices and your zone should appear on list and you should be able to connect to it.
+
+## Take it further
+
+Now that you have your server running, what you do with it is up to you. 
+
+For more information about the server, see the [User Manual](./user-manual.md). 
+
+Here are a few topics that might be of interest:
+- [How to initially set yourself up as sysop](./user-manual.md#how-to-initially-set-yourself-up-as-sysop)
+- [List your zone on directory servers](./user-manual.md#list-your-zone-on-directory-servers)
+- [Connect your zone to a billing server](./user-manual.md#connect-your-zone-to-a-billing-server)
+
+If you would like to learn how to create your own plugins, see the [Developer Guide](./developer-guide.md).