Add environment and database documentation

astro.config.mjs

@@ -3,6 +3,7 @@ import { defineConfig } from "astro/config";
 
 import createFaviconsIntegration from "astro-favicons";
 import robotsTxt from "astro-robots-txt";
+import starlightLinksValidator from "starlight-links-validator";
 
 // https://astro.build/config
 export default defineConfig({
@@ -45,6 +46,12 @@ export default defineConfig({
           },
         },
       ],
+      plugins: [
+        starlightLinksValidator({
+          errorOnRelativeLinks: false,
+        }),
+      ],
+      customCss: ["./src/styles/custom.css"],
     }),
     robotsTxt(),
     createFaviconsIntegration({

package.json

@@ -16,6 +16,7 @@
     "astro-favicons": "^2.0.2",
     "astro-robots-txt": "^1.0.0",
     "sharp": "^0.32.5",
+    "starlight-links-validator": "^0.5.1",
     "typescript": "^5.3.3"
   }
 }

src/content/docs/reference/External Services/mongo.md

@@ -0,0 +1,51 @@
+---
+title: MongoDB
+---
+
+We use [MongoDB](https://www.mongodb.com/docs/) to store player profiles and permissions.
+
+## Connection Logic
+
+When a game server starts up, it attempts to connect to Mongo using the hostname specified in the [Environment](/reference/environment).
+
+## The Player Model
+
+| Property       | BSON Type                         | Description                                                     |
+| -------------- | --------------------------------- | --------------------------------------------------------------- |
+| `_id`          | String                            | Dashed UUID                                                     |
+| `username`     | String                            | Username                                                        |
+| `coins`        | Int32                             | Current coin balance                                            |
+| `experience`   | Int32                             | Network experience (used to calculate level)                    |
+| `punishments`  | Array ([Punishment](#punishment)) | List of active and past punishments                             |
+| `achievements` | Array (empty)                     | List of earned achievements (not implemented yet)               |
+| `statistics`   |                                   | List of tracked statistics                                      |
+| `cosmetics`    | Array ([Cosmetic](#cosmetic))     | List of owned cosmetics and whether they are currently equipped |
+| `lastJoinDate` | Int64                             | The last time the player's data was loaded as a Unix timestamp  |
+
+## Supplemental Structure Types
+
+### `Punishment`
+
+Represents an active or expired punishment.
+
+| Property    | BSON Type | Description                                                                                |
+| ----------- | --------- | ------------------------------------------------------------------------------------------ |
+| `type`      | String    | Either `BAN` or `MUTE`                                                                     |
+| `id`        | String    | A UUID (with dashes) that uniquely identifies the punishment                               |
+| `issuedAt`  | Int64     | The time the punishment was issued, represented as a Unix timestamp                        |
+| `expiresAt` | Int64     | The time the punishment will expire/has expired, represented as a Unix timestamp           |
+| `moderator` | String    | The UUID of the player which enacted the punishment                                        |
+| `reason`    | String    | A short string description of why the punishment was enacted, provided by the `moderator`. |
+| `active`    | Bool      | A boolean representing whether the punishment is currently effective                       |
+
+The `active` field allows a manual override of the punishment. Even if `active` is set to `true` on a punishment,
+the expiration date should be checked. If the has passed, the punishment should not affect the player.
+
+### `Cosmetic`
+
+Represents a cosmetic that a player owns.
+
+| Property | BSON Type | Description                             |
+| -------- | --------- | --------------------------------------- |
+| `id`     | String    | A string identifier for the cosmetic    |
+| `active` | String    | Whether the cosmetic is equipped or not |

src/content/docs/reference/commands.md

@@ -1,7 +1,7 @@
 ---
 title: Server Commands
 ---
-Just like in vanilla Minecraft, the [BlueDragonMC/Server](/reference/subprojects/server-core/) Minestom instance relies on commands for important interactions. Each command has its own permission, and **no permissions are granted by default**. This document references a few different permission levels, but these are for illustrative purposes only, and do not represent specific requirements.
+Just like in vanilla Minecraft, the [BlueDragonMC/Server](https://github.com/BlueDragonMC/Server) Minestom instance relies on commands for important interactions. Each command has its own permission, and **no permissions are granted by default**. This document references a few different permission levels, but these are for illustrative purposes only, and do not represent specific requirements.
 
 ## Selectors
 Just like on vanilla servers, BlueDragon supports the use of the following selectors in place of player names:

src/content/docs/reference/environment.md

@@ -0,0 +1,39 @@
+---
+title: Environment
+---
+
+The BlueDragonMC/Server project loads several environment configuration options at startup that influence its interaction with other services.
+
+## Development and Production Modes
+
+The server is determined to be in "Dev" or "Prod" modes by looking at the `BLUEDRAGON_ENV_TYPE` environment variable. If it's set to "DEV", the server is assumed to be in development mode, and if not, the server will be set to production mode.
+
+If the `BLUEDRAGON_ENV_TYPE` is not set, the fallback is to check for a directory called `/server` at the file system root. If it exists, then production mode is used; if not, development mode.
+
+## Environment Variable Reference
+
+| Environment variable            | Defaults                                                              | Description                                                                                                        |
+| ------------------------------- | --------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
+| `BLUEDRAGON_QUEUE_TYPE`         | **Dev**: `TEST`<br>**Prod**: `IPC`                                    | Use "IPC" to connect to Puffin for queueing, or "TEST" for a fully-local/single-instance queue                     |
+| `BLUEDRAGON_MONGO_HOSTNAME`     | **Dev**: `localhost:27017`<br>**Prod**: `mongo:27017`                 | The hostname that resolves to a MongoDB instance                                                                   |
+| `BLUEDRAGON_PUFFIN_HOSTNAME`    | **Dev**: `localhost`<br>**Prod**: `puffin`                            | The hostname that resolves to a Puffin instance                                                                    |
+| `BLUEDRAGON_LUCKPERMS_HOSTNAME` | **Dev**: `http://localhost:8080`<br>**Prod**: `http://luckperms:8080` | The hostname that resolves to a [standalone LuckPerms](https://luckperms.net/) instance                            |
+| `BLUEDRAGON_DEFAULT_GAME`       | `lobby`                                                               | The game to automatically create on startup. Typically used to immediately initialize a lobby on each game server. |
+| `BLUEDRAGON_AGONES_DISABLED`    | _Not set_                                                             | If this environment variable is present with any value, Agones integration will be disabled.                       |
+
+_[View ConfiguredEnvironment source code](https://github.com/BlueDragonMC/Server/blob/b05b09ad229ccf85da20130510c9c1cdf90bbeed/src/main/kotlin/com/bluedragonmc/server/queue/environments.kt#L23) for more details about server environment configuration._
+
+## Other Environment Information
+
+- The `Environment` class also stores version information handled by the [Blossom](https://github.com/KyoriPowered/blossom/) Gradle plugin. See [`GitVersionInfo`](https://github.com/BlueDragonMC/Server/blob/b05b09ad229ccf85da20130510c9c1cdf90bbeed/src/main/kotlin/com/bluedragonmc/server/GitVersionInfo.kt#L8) for more details.
+- The environment contains a list of all registered games obtained from the [`GameLoader`](https://github.com/BlueDragonMC/Server/blob/b05b09ad229ccf85da20130510c9c1cdf90bbeed/src/main/kotlin/com/bluedragonmc/server/queue/GameLoader.kt#L15).
+
+## Server Naming
+
+Every game server **must** have a unique name to interact properly with other services. The default [`ConfiguredEnvironment`](https://github.com/BlueDragonMC/Server/blob/b05b09ad229ccf85da20130510c9c1cdf90bbeed/src/main/kotlin/com/bluedragonmc/server/queue/environments.kt#L23) goes through the following process for determining a server's name:
+
+1. If the `HOSTNAME` environment variable is set, its value will be used as the server name.
+2. If the server is in development mode _or_ Agones integration is disabled, a random string will be created and used.
+3. If the server is in production mode _and_ Agones integration is enabled, a gRPC request will be sent to get the server name from the Agones [gRPC API](https://agones.dev/site/docs/guides/client-sdks/#gameserver).
+
+The result is then cached for future lookups.

src/styles/custom.css

@@ -0,0 +1,4 @@
+/* See https://github.com/withastro/starlight/issues/1321 */
+.sl-markdown-content :is(th, td):not(:where(.not-content *)) > code {
+  overflow-wrap: normal;
+}