Server Guide
This guide covers building, running, and administering a Rawframe dedicated server. You host your own server, you own it — the platform never hosts games. For game development, see the Creating Games 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 your game from game/, and enter the main loop.
To stop the server, type quit in the console or press Ctrl+C.
Working Directory
The server looks for game/ 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
-portvalue (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.
Game Loading
The server loads your game — and every Asset Store package it uses — from game/ at startup.
What Gets Loaded
The server loads shared scripts and server-side scripts from the game and each installed asset package. Client-only scripts are skipped.
Load Process
- The loader reads
game/place.jsonand the manifests of installed asset packages. - Manifests are parsed and validated.
- Packages are sorted by dependency order (topological sort) — assets load before the game that uses them.
- For each package: shared scripts execute first, then server scripts.
- Script failures are logged but do not prevent other packages 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-Package VM Isolation and Hot-Reload
Your game and each installed asset package run in their own isolated Luau VMs. This means:
- Crash isolation: A buggy asset cannot corrupt your game's state.
- Memory tracking: Each package's memory usage is tracked independently.
- Clean hot-reload: Reloading a package destroys and recreates only its VM.
Hot-Reload
During development, script packages can be hot-reloaded without restarting the server:
- File changes are automatically detected.
- The package's VM is destroyed and recreated with fresh state.
- Other packages 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.
Game Not Loading
If game/ does not exist, the server starts an empty world. Check that:
- The
game/directory exists in your working directory. - The game has a valid
place.json. - Check the server log for parse errors.