Skip to main content

Local development

The SDK is designed so the exact same server code runs on GameFlow and on your machine. No #if, no separate build, just run your binary locally and it works.

How mode detection works​

When you connect, the SDK picks a transport automatically:

  • Running on GameFlow: the platform injects the runtime environment; the SDK connects to it (with retries) and fails hard if it cannot, so broken servers are visible instead of silently degraded. This is sidecar mode.
  • Running anywhere else: the SDK logs one line and enters local mode. Lifecycle calls are simulated, player tracking works against an in-memory list, and the watch/payload streams emit synthetic updates. No network, no configuration.

You can force a mode when you need to (for example, to exercise the sidecar path against a local fixture) with the GAMEFLOW_SDK_MODE environment variable:

GAMEFLOW_SDK_MODE=local    # or: sidecar

The connect option in code wins over the env var, and both win over auto-detection.

Simulating platform behavior​

Local mode reads a few environment variables so you can exercise real scenarios without deploying:

# Simulate the assigned port (otherwise use your own fallback)
GAMEFLOW_DEFAULT_PORT=7777 \
# Simulate max players (connecting beyond it returns a "server full" error)
GAMEFLOW_MAX_PLAYERS=8 \
# Simulate a launch payload returned by payload()
GAMEFLOW_PAYLOAD='{"match":"test-1"}' \
./your-server

GAMEFLOW_MAX_PLAYERS=0 simulates a game with player tracking disabled, which is what happens in production when "Max Players per Server" is 0. Unset means unlimited capacity.

These knobs are identical across every SDK (TypeScript, Godot, Rust, Go, Unity, Unreal).

Checklist before uploading a build​

  • ready() is called only after the server is listening.
  • Players are reported on every join and leave. Idle servers (zero reported players) are shut down after your organization's idle timeout.
  • SIGTERM triggers a drain plus shutdown() within 45 seconds.
  • The server listens on the platform-assigned port (GAMEFLOW_DEFAULT_PORT) when present.

When all four hold locally, the same build will behave the same way on GameFlow. Next: Creating a Game to upload it.