Cinderwild/docs/HOSTING.md

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):

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) 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.