# 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 |
| `check_updates` | true | at start-up, say in the log if a newer Emberwild is out (and whether its protocol differs, so new players couldn't join) |
| `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`.