From 6165f214b5617c4a913187e99ac42eaaf7c76adf Mon Sep 17 00:00:00 2001
From: alexion <contact@alexion.dev>
Date: Thu, 10 Sep 2026 08:20:07 -0400
Subject: [PATCH] docs: document SteamCMD server workflow

---
 docs/02 notes/steamcmd servers.md | 71 +++++++++++++++++++++++++++++++
 1 file changed, 71 insertions(+)
 create mode 100644 docs/02 notes/steamcmd servers.md

diff --git a/docs/02 notes/steamcmd servers.md b/docs/02 notes/steamcmd servers.md
new file mode 100644
index 0000000..b8b46d5
--- /dev/null
+++ b/docs/02 notes/steamcmd servers.md	
@@ -0,0 +1,71 @@
+# SteamCMD servers
+
+Use `modules.services.steamcmd` as the low-level runner for one SteamCMD server.
+Create a game module under `configs/nixos/modules/services/games/` for each game.
+
+The game module owns game-specific defaults and command-line flags.
+The host owns deployment-specific paths, names, secrets, and network placement.
+
+## Create a game module
+
+1. Create `configs/nixos/modules/services/games/<game>.nix`.
+2. Define options under `modules.services.games.<game>`.
+3. Expose only values the host must choose.
+4. Map those values to `modules.services.steamcmd`.
+5. Set the Steam dedicated-server app ID in the game module.
+6. Set the server executable in the game module.
+7. Generate game-specific arguments in the game module.
+8. Open the game's documented UDP ports in the game module.
+
+Keep `modules.services.steamcmd` focused on shared SteamCMD behavior.
+Do not put game-specific flags or port rules there.
+
+## Configure a host
+
+During validation, enable the game module directly on a host.
+
+```nix
+modules.services.games.valheim = {
+  enable = true;
+  steamDir = "/pikachu/data/steamcmd";
+  installDir = "/pikachu/data/servers/valheim/main";
+  stateDir = "/pikachu/media/games/servers/valheim/main";
+  serverName = "main";
+  password = "foobarbaz";
+};
+```
+
+Use host paths for direct host deployment.
+Use guest paths after the server moves into a guest.
+
+## Deploy and test
+
+1. Evaluate the host configuration.
+
+   ```sh
+   nix eval .#nixosConfigurations.<host>.config.system.build.toplevel.drvPath --raw
+   ```
+
+2. Deploy the host.
+
+   ```sh
+   deploy-to <host>
+   ```
+
+3. Check the game service.
+
+   ```sh
+   sudo systemctl status <game>.service
+   sudo journalctl -u <game>.service -n 200 --no-pager
+   ```
+
+4. Check UDP listeners.
+
+   ```sh
+   sudo ss -lunp | grep -E '<port>|<port-plus-one>|<game>'
+   ```
+
+5. Connect from the game client.
+
+The Valheim server is ready after the log contains `Game server connected`.
+It can spend time generating a new world before it accepts connections.