Server Architecture Overview

PlayRen runs games in Docker containers distributed across multiple cloud servers. This page explains how the pieces fit together.

Architecture at a Glance

The platform consists of three main components:

1. Platform Server — the Next.js application that handles user accounts, game catalog, and session orchestration. This is the brain of the operation.
2. Game Servers — Linux machines that run Docker containers with actual game instances. Each server runs a pool agent that manages containers locally.
3. Storage Servers — hosts game file archives (tar.gz) uploaded by partners. Game servers download from storage when caching a new title.

The Pool Agent

Every game server runs a pool agent — a lightweight FastAPI service (Python) that exposes a local API for container management.

The pool agent handles:

• Creating containers — launching a Docker container with the correct game, save slot, and configuration.
• Stopping containers — shutting down a game session and collecting resource metrics.
• Health reporting — reporting CPU load, memory usage, disk space, and active container count.
• Keepalive — extending session lifetime when the user is actively playing.
• Cache management — downloading and extracting game archives from storage servers.

The pool agent listens on port 9100 and is managed by systemd (xgame9-agent service).

The Server Scheduler

When a user launches a game, the platform's server scheduler selects the best game server. The selection algorithm considers:

1. Cache locality — prefer servers that already have the game cached. This avoids the delay of downloading the game archive.
2. Current load — choose the server with the most available capacity (CPU and memory headroom).
3. Resource profile — each game has a tracked CPU and memory profile (exponential moving average from past sessions). The scheduler ensures the selected server has enough capacity.

If no server has the game cached, the scheduler picks the least-loaded server and triggers a cache download in the background.

Game Caching

Game files are distributed on-demand using a pull-based caching model:

1. A user requests to play a game.
2. The scheduler checks the GameCacheEntry database table to see which servers have the game.
3. If the selected server has a cache miss, the pool agent downloads the archive from the partner's storage server.
4. The archive is extracted to the server's local game directory.
5. A GameCacheEntry record is created so future launches skip the download.

Download URLs are constructed from the partner's serverUrl and apiKey fields.

Session Lifecycle

A game session follows this path:

1. Launch request — user clicks Play; the API creates a session record with status starting.
2. Server selection — the scheduler picks the best server.
3. Cache check — if needed, the game is downloaded (up to 60-second timeout).
4. Container launch — the pool agent starts a Docker container with the game and mounts the user's save directory.
5. Status: running — the session record is updated and the play page begins polling.
6. Stream connection — the user's browser establishes a WebRTC connection to the container's Neko instance.
7. Keepalive — periodic keepalive requests prevent idle timeout.
8. Stop — the user stops the session (or it times out). Container CPU/memory stats are collected and the game's resource profile is updated.

Next Steps

• Prerequisites — Hardware and OS requirements for game servers.
• Installation — Set up a new game server.
• Configuration — Configure the pool agent, firewall, and Nginx.
• Monitoring — Health checks and metrics.