M2.7: Host Game, backups, launchd/systemd samples, hosting and Tailscale guide

docs/HOSTING.md

@@ -0,0 +1,136 @@
+# Hosting a game
+
+Three ways to run a server, from easiest:
+
+1. **Host Game** on the title screen. A server runs on your computer while
+   you play, and stops when you leave. Good for an evening with friends.
+2. **A dedicated server** on a spare computer (like the home server Mac):
+   `server/run_server.sh`, or as a service that starts on boot. Good for a
+   world that's always there.
+3. **A small cloud server** (Linux): the same as 2, using the systemd file.
+
+Whichever you use, friends need to reach your computer on **UDP port
+24242** (or the one you pick). On the same Wi-Fi that just works. From
+elsewhere, use **Tailscale** (recommended) or port forwarding (below).
+
+## 1. Host Game (from the title screen)
+- Title screen > **Host Game**. Pick a server name, the rules (co-op,
+  friendly rivals or adversarial), an optional password, the port, and
+  (the first time) a seed. **Start**.
+- The game starts a windowless copy of itself as the server, then joins it.
+  You're its first player, so you're its **admin** (`T` then `/help`).
+- When you're in, a message says the addresses friends can join at: your
+  local network address (192.168.x.x) and, if Tailscale is running, your
+  100.x address.
+- **Leaving** (Disconnect, or quitting the game) saves the island and
+  stops the server. Next time, Host Game carries on with the same island
+  (the seed field is locked once it exists).
+- Its files: `~/Library/Application Support/Godot/app_userdata/Emberwild/host/`
+  (macOS; `%APPDATA%\Godot\app_userdata\Emberwild\host\` on Windows):
+  `server.json`, `server.log`, and the world in `worlds/server-world/`.
+- macOS may ask once whether Godot may accept incoming network
+  connections: say **Allow**, or friends can't connect.
+
+## 2. A dedicated server
+On the machine that will run it (it needs Godot 4.7 or newer and a copy of
+the game, e.g. a git clone):
+```bash
+server/run_server.sh                              # settings from server.json
+server/run_server.sh --server-name "Paul's island" --password secret
+```
+It checks Godot's version, imports a fresh copy the first time, and starts
+the server with no window. **You can type admin commands into its terminal**
+(the same as in chat, without the `/`): `players`, `rules`,
+`set pvp true`, `time 08:00`, `backup`, `say hello`... Stop it with Ctrl+C.
+
+The first player to join a new server becomes its admin (so join it
+yourself before telling friends the address). More admins: `/admin <name>`.
+
+**As a service** (starts on boot, restarts if it stops):
+- **macOS:** `server/com.emberwild.server.plist`: edit the paths in it,
+  then `cp server/com.emberwild.server.plist ~/Library/LaunchAgents/` and
+  `launchctl load -w ~/Library/LaunchAgents/com.emberwild.server.plist`.
+  It runs while you're logged in (set the Mac to log in automatically for an
+  always-on server). Log: `~/Library/Logs/emberwild-server.log`.
+- **Linux:** `server/emberwild-server.service`: the steps are in the file
+  (`sudo systemctl enable --now emberwild-server`; logs with
+  `journalctl -u emberwild-server -f`).
+
+As a service there's no terminal to type commands into: use chat in game,
+or edit `server.json` and restart.
+
+## Settings and rules
+`server.json` (made with defaults on first run; its path is printed at
+start-up). Admins can change the rules in game with `/set` (they're saved
+to the file). The full list is in `docs/MULTIPLAYER_PLAN.md` §4 and §6;
+the ones you'll want first:
+
+| Setting | Default | |
+|---|---|---|
+| `server_name`, `motd`, `password` | | what players see; a password keeps strangers out |
+| `port` | 24242 | UDP |
+| `max_players` | 8 | |
+| `pvp`, `raiding` | false, false | can players hurt each other / take down others' builds |
+| `locks` | owner_and_friends | who can open your chests and doors (`/friend <name>`) |
+| `death_penalty` | grave | or `keep`, or `drop_all` |
+| `difficulty` | normal | easy / normal / hard |
+| `sleep` | all_online | or `half`, `anyone`, `off` |
+| `backups_kept`, `backup_hours` | 10, 6 | see below |
+| `allowlist`, `banned`, `admins` | | player ids (use `/ban`, `/admin` rather than editing) |
+
+## Backups
+The server copies the world (the island and every player's character) to
+`worlds/<world>/backups/<date_time>/`:
+- when it starts (the state it's about to load),
+- every `backup_hours` while it runs,
+- whenever an admin types `/backup` (`/backups` lists them).
+
+It keeps the newest `backups_kept`. **To restore one:** stop the server,
+copy the files from the backup folder (`meta.json`, `world.json` and the
+`players` folder) into `worlds/<world>/`, replacing what's there, and start
+it again.
+
+The world also saves within 10 seconds of any change and when a player
+leaves, so stopping it with Ctrl+C loses at most a few seconds.
+
+## Letting friends in from outside your home
+
+### Tailscale (recommended)
+Tailscale puts your devices and your friends' on a private network, with
+nothing opened to the internet and no router settings.
+1. Install Tailscale on the server computer ([tailscale.com/download](https://tailscale.com/download))
+   and sign in.
+2. Share the server with each friend: in the Tailscale admin console,
+   **Machines** > the server's **...** menu > **Share**, and send them the
+   link. (Or invite them to your tailnet.)
+3. They install Tailscale, sign in and accept the share.
+4. In the game they **Join** with the server's Tailscale address,
+   `100.x.y.z` (shown in Tailscale, and in the game when you host), or its
+   machine name (with MagicDNS on), e.g. `home-mac`.
+
+To check it works: `tailscale ping <server name>` from the friend's
+computer.
+
+### Port forwarding
+On your router, forward **UDP 24242** to the server computer's local
+address (give that computer a fixed local address first). Friends join
+with your public IP address. It needs no extra software, but your home IP
+and that port are public, so set a `password`.
+
+### A cloud server
+Any small Linux server works (it needs little: a couple of GB of memory).
+Install Godot, clone the game, use the systemd file, and open UDP 24242 in
+the provider's firewall.
+
+## Troubleshooting
+- **"Different game version":** the server and the player are on different
+  versions of the game. Update both (`git pull`), and restart the server.
+- **"No answer from the server":** wrong address, the server isn't running,
+  or a firewall is in the way (macOS: allow incoming connections for Godot;
+  Tailscale: is it connected on both ends?).
+- **"Port 24242 is already in use":** another server is running on this
+  computer (a dedicated one, or a Host Game that didn't stop). Stop it, or
+  host on another port.
+- **The server says the game's scripts didn't load:** it's a fresh copy
+  that hasn't been imported, or Godot is older than 4.7. `run_server.sh`
+  handles both; see `docs/SETUP_ON_NEW_MACHINE.md`.

docs/MULTIPLAYER_PLAN.md

@@ -363,7 +363,7 @@ player" or "this player":
 | **M2.4** *(done)* | intents as RPCs; per-player inventory, stats, diet, death and graves; per-player saves and migration | two players craft, eat, die and loot their own graves; an old single-player save loads |
 | **M2.5** *(done)* | wildlife and wolves server-side, projectiles, fishing, sleeping with the rule | a pack hunts two players at once; arrows hit on both screens |
 | **M2.6** *(done)* | server rules: PvP, raiding, locks and friends, death penalty, difficulty; admin console and chat | each preset (co-op, rivals, adversarial) behaves as described in §4 |
-| **M2.7** | hosting polish: "Host game" button, systemd and launchd samples, backups, a Tailscale how-to in the docs | Paul runs it on the home server, and a friend joins over Tailscale and plays for an hour |
+| **M2.7** *(done, see docs/HOSTING.md)* | hosting polish: "Host game" button, systemd and launchd samples, backups, a Tailscale how-to in the docs | Paul runs it on the home server, and a friend joins over Tailscale and plays for an hour |
 
 ## 10. Testing
 - **Headless multi-process tests:** a script starts a headless server and

docs/ROADMAP.md

@@ -59,6 +59,7 @@ phases M2.0-M2.7).
 - [x] Per-player inventory, stats, death, graves and saves on the server *(M2.4)*
 - [x] Animals, wolves, hunting, fishing and sleeping on the server *(M2.5)*
 - [x] Server rules (PvP, raiding, locks and friends, death penalty, difficulty, wolf grace), chat and admin commands, server console *(M2.6)*
+- [x] Host Game from the title screen, backups, launchd and systemd samples, hosting and Tailscale guide (`docs/HOSTING.md`) *(M2.7)*
 - **Done when:** a friend joins your self-hosted server and you build together.
 
 ## M3 — Addon SDK + sandbox · ~2–3 months

docs/SETUP_ON_NEW_MACHINE.md

@@ -45,7 +45,9 @@ The shared island is saved in `worlds/server-world/` in that same folder,
 within 10 seconds of any change (and when someone leaves). Stop it with
 Ctrl+C. Players join with **Join Game** on the title screen. Over
 Tailscale, use the server machine's 100.x address or its machine name. See
-`docs/MULTIPLAYER_PLAN.md` for all the options.
+`docs/MULTIPLAYER_PLAN.md` for all the options, and `docs/HOSTING.md` for
+hosting from the title screen, running it as a service, backups and
+Tailscale.
 
 ## Tests
 Run everything (fails on any failed check or script error):