Server Guide

This guide covers building, running, and administering a Rawframe dedicated server. For mod development, see the Modding Guide.

---

Building the Server

The dedicated server is a headless binary (no window, no renderer, no audio). It is built automatically alongside the client on desktop platforms.

Windows

mkdir build && cd build
cmake .. -G "Visual Studio 18 2026" -DCMAKE_EXPORT_COMPILE_COMMANDS=ON
cmake --build . --config Release

The server binary will be at build/bin/rawframe_server.exe.

Linux / macOS

mkdir build && cd build
cmake .. -DCMAKE_BUILD_TYPE=Release -DCMAKE_EXPORT_COMPILE_COMMANDS=ON
cmake --build . -j$(nproc)

To skip building tests for a faster build:

cmake .. -DRAWFRAME_BUILD_TESTS=OFF -DCMAKE_BUILD_TYPE=Release

---

Running

Launch the server from the build output directory:

# Default settings (port 27015, 32 players, 20 Hz tick rate)
./rawframe_server

# Custom settings
./rawframe_server -port 27015 -maxplayers 16 -tickrate 30 -name "My Server"

# With RCON enabled
./rawframe_server -name "My Server" -rcon_password "secretpass"

The server will initialize the ECS world (headless), create the network server, load mods from mods/, and enter the main loop.

To stop the server, type quit in the console or press Ctrl+C.

Working Directory

The server looks for mods/ relative to the current working directory. Make sure to run from the project root:

./build/bin/rawframe_server

---

Command-Line Arguments

Argument	Default	Description
-port <N>	27015	Server listen port (UDP).
-maxplayers <N>	32	Maximum simultaneous connections.
-tickrate <N>	20	Entity snapshot broadcast frequency (Hz).
-name "<str>"	"Rawframe Server"	Server name (shown in browser).
-map "<str>"	"default"	Map name (metadata).
-rcon_password "<str>"	""	RCON password. Empty disables RCON.
-help	—	Show help text and exit.

Examples

# Basic public server
./rawframe_server -port 27015 -name "Public FFA" -maxplayers 24

# Private server with RCON
./rawframe_server -name "Private" -rcon_password "s3cure!" -maxplayers 8

# High tick rate for competitive play
./rawframe_server -tickrate 64 -maxplayers 10 -name "Competitive"

# Multiple servers on one machine
./rawframe_server -port 27020 -name "Server 2"

Port Requirements

• Game port: The -port value (default 27015). UDP.
• LAN discovery port: Game port + 1 (default 27016). UDP broadcast for auto-discovery.

Ensure both ports are open in your firewall.

---

Console Commands

The server reads commands from stdin. Type a command and press Enter.

Command	Description
quit / exit	Gracefully shut down.
status	Server info: name, map, players, tick rate, uptime.
kick <peer_id>	Kick a connected client.
ban <peer_id>	Ban and kick a client (persistent, IP-based).
unban <ip>	Remove an IP from the ban list.
help	List available commands.

Example Session

> status
Server: My Server | Map: default | Players: 3/32 | Tick: 20 Hz | Uptime: 142s

> kick 2
Kicked peer 2

> ban 5
Banned and kicked peer 5

> quit
Server shutting down...

---

RCON (Remote Console)

RCON allows administrators to execute server commands from a connected client.

Enabling

./rawframe_server -rcon_password "my_rcon_password"

If the password is empty (default), RCON is disabled.

Security

• Choose a strong password. RCON commands go through the same handler as local console input.
• Do not share the password with untrusted players — anyone with it can execute any command.
• Future versions will add libsodium encryption for all network traffic.

---

Mod Loading

The server loads mods from mods/ at startup.

What Gets Loaded

The server loads shared scripts and server-side scripts from each mod. Client-only scripts are skipped.

Load Process

1. ModLoader scans mods/ for subdirectories containing mod.json.
2. Manifests are parsed and validated.
3. Mods are sorted by dependency order (topological sort).
4. For each mod: shared scripts execute first, then server scripts.
5. Script failures are logged but do not prevent other mods from loading.

Server-Side API Availability

API	Available	Notes
entity.* (entities, transforms)	Yes	Full CRUD and transform access.
hook.Add("Think", key, fn)	Yes	Tick callbacks work on server.
net.* (Send, Broadcast, Receive)	Yes	Full server-side networking.
physics.raycast(...)	Yes	Physics raycasting available.
Audio functions	No	No-ops (return 0 or do nothing).
Input functions	No	Return false/0 (no input on server).

---

Per-Mod VM Isolation and Hot-Reload

Each mod runs in its own isolated Luau VM. This means:

• Crash isolation: A buggy mod cannot corrupt another mod’s state.
• Memory tracking: Each mod’s memory usage is tracked independently.
• Clean hot-reload: Reloading a mod destroys and recreates only its VM.

Hot-Reload

During development, mods can be hot-reloaded without restarting the server:

• File changes are automatically detected.
• The mod’s VM is destroyed and recreated with fresh state.
• Other mods are unaffected.

This makes iteration fast — edit a script, save, and see changes immediately.

---

Performance Tuning

Tick Rate

Tick Rate	Interval	Use Case
10 Hz	100 ms	Low bandwidth, casual games
20 Hz (default)	50 ms	General purpose, good balance
30 Hz	~33 ms	Smoother movement replication
64 Hz	~16 ms	Competitive/fast-paced games

Higher tick rates provide smoother entity movement but consume more bandwidth.

Max Players

Server Hardware	Max Players	Tick Rate
Low-end VPS (1 core)	8-16	20 Hz
Mid-range (2-4 cores)	16-32	20-30 Hz
Dedicated (4+ cores)	32-64	30-64 Hz

Delta Time Clamping

The server clamps delta time to 0.1 seconds (100 ms). If a frame takes longer, the simulation advances by at most 0.1s to prevent physics jumps.

---

Docker Deployment

Rawframe ships with Docker support for easy server deployment:

# Build the image
docker build -t rawframe-server -f deploy/Dockerfile .

# Run a server
docker run -p 27015:27015/udp rawframe-server

# With custom settings
docker run -p 27015:27015/udp rawframe-server \
  -name "Docker Server" -maxplayers 16 -tickrate 30

For multi-server setups, use the provided docker-compose.yml in the deploy/ directory.

---

Troubleshooting

Server Won’t Start

Symptom: Failed to create network server

Causes:

• Another process is using the port. Check with netstat -an | grep 27015.
• The port number is invalid (0 or >65535).

Fix: Use a different port with -port <N>, or stop the conflicting process.

Clients Can’t Connect

• Ensure the game port and discovery port (port+1) are open in your firewall.
• For internet hosting, forward both UDP ports on your router.
• Symmetric NAT is not supported — use a VPS or port forwarding.

No Mods Loading

If mods/ does not exist, the server continues without mods. Check that:

• The mods/ directory exists in your working directory.
• Each mod has a valid mod.json.
• Check the server log for parse errors.