System architecture — Fig. 01

Daystar

A meeting space in orbit around a shared sun, where every person is a glowing star or planet. Browsers ask one agent where to play, then talk to a game server over a live connection; game servers mirror shared rooms to each other so people on different servers still see one another.

Data Control Zone Control center
● Users — browser
Platform — one container (Bun)
Planned — not built yet
Web app · any browser
daystar.ptnn.dev

Game Client

  • Lobby: pick a name, a kind of body and a color
  • Space, sun and glowing players drawn in code with PixiJS (no images)
  • Your own moves show instantly; the server double-checks them
  • Other players are smoothed 100 ms behind so motion looks fluid
  • Chat panel plus speech bubbles above heads
  • Moves to another server by itself when asked, or when its server disappears
PixiJS WebSocket Binary messages
Hosting · in front of everything

Cloudflare → Coolify

  • Encrypts every connection (HTTPS / secure WebSocket)
  • daystar.ptnn.dev reaches the agent
  • talk-s1 … s4.ptnn.dev reach the game servers
TLS Docker
Control center · single instance · port 3000

Agent

  • Serves the web app and answers "where should I play?"
  • Keeps a room on one server, spilling onto another only when it gets busy
  • Hands out a signed ticket (valid 30 s) and gives every player a room-unique id
  • Watches load every second and asks busy servers to move some players
  • Only one agent today: if it stops, nobody new can join
Placement Tickets Load watch
Game server · s1 … s4 · ports 3001–3004

Game Server

  • Holds each room's players and the world's limits
  • Checks every move: not too fast, not into the sun, not past the edge
  • Sends each room an update 20 times a second, only for players who moved
  • One call reaches everyone in a room (Bun pub/sub)
Bun 20 Hz Ticket check
Replicated ×4identical code
Server ↔ server

Mesh

  • Every pair of servers is directly linked
  • Mirrors rooms that span servers
  • Passes a player over during a move
Process manager · container entry point

Supervisor  starts the agent and the four servers, and restarts any that crash.

Storage

Chat history service

Today a server keeps no chat history. A separate database service will store it.

Messaging

Message bus

Redis Streams or Kafka instead of direct server links, once there are more servers or machines.

Availability

Several agents

More than one agent behind a load balancer, so the agent is no longer a single point of failure.

Bandwidth

Area of interest

Send each player only the people near them, cutting traffic in very large rooms.

1Where do I play?
Ticket + address
2Play · live
3Please move
Joins · leaves · load
Move orders
Sync
Starts · restarts every process
Invariant 01

The server is the referee

Your screen moves you right away, but every position is checked against speed and the world's limits. A move that does not add up is corrected back.

Invariant 02

Only what changed is sent

Twenty times a second a room sends just the players who moved, packed in 7 bytes each. People standing still cost nothing.

Invariant 03

No ticket, no entry

A game server only accepts a connection that carries a ticket the agent signed for that exact server and room, used within 30 seconds.

Update rate
20 / second

Room updates; your own movement is sent at the same pace while you walk.

Per moving player
7 bytes

Position and facing in each update, instead of 12 bytes before the binary protocol.

One server process
~5,000 players

Measured in rooms of 1,000 with 20% of people walking, keeping delays under 50 ms.

Bandwidth
~1 Gbps

Outgoing traffic for those 5,000 players; the network, not the CPU, is the next limit.

Word

Room

One shared map at /r/<name>. Everyone with the same link is together.

Word

Tick

A server heartbeat, 20 per second, when a room sends out what changed.

Word

Ticket

A short-lived pass from the agent naming your room, your server and your player id.

Word

Mesh

The direct links between game servers that keep a shared room identical on each of them.

Word

Migration

Moving a player to a less busy server without them leaving the room or losing their spot.

Cluster version (branch scale-out). Without cluster settings the same image runs as a single game server that also plays the agent's role. Numbers measured on a development machine; see docs/cluster.md for the technical design.