Architecture

How Storia works

Storia is four programs that work together. A single Storia server is a complete Minecraft server; add Storia Proxy for a network, and Storia Workers with a Storia Relay to run one world on several machines. This page explains what each one does, where it runs and what travels between them.

Overview of a Storia ClusterPlayers connect to Storia Proxy, which listens on port 25565. Storia Proxy sends each player to the Storia Worker that runs the part of the world they are in, using modern forwarding. Each worker runs one part of the shared world. When a player crosses into another worker's part, Storia Proxy moves them without a loading screen. The workers and the proxy connect to Storia Relay, which listens on port 25590, stores the world and decides who runs what. All of it is encrypted. NetworkWorkersCoordinator PlayersMC Storia Proxy:25565modern forwarding Worker Apart of the worldWorker Bpart of the worldWorker Cpart of the worldencrypted Storia Relaythe world · :25590 Overview of a Storia ClusterPlayers connect to Storia Proxy, which listens on port 25565. Storia Proxy sends each player to the Storia Worker that runs the part of the world they are in, using modern forwarding. Each worker runs one part of the shared world. When a player crosses into another worker's part, Storia Proxy moves them without a loading screen. The workers and the proxy connect to Storia Relay, which listens on port 25590, stores the world and decides who runs what. All of it is encrypted. PlayersMC Storia Proxy:25565modern forwarding Worker AWorker BWorker Cencrypted Storia Relaythe world · :25590
  1. Players connect to Storia Proxy, which listens on port 25565.
  2. Storia Proxy sends each player to the Storia Worker that runs the part of the world they are in, using modern forwarding.
  3. Each worker runs one part of the shared world. When a player crosses into another worker's part, Storia Proxy moves them without a loading screen.
  4. The workers and the proxy connect to Storia Relay, which listens on port 25590, stores the world and decides who runs what. All of it is encrypted.

The four programs

Each program has one job. Together they run one world on as many machines as your players need.

Storia

The game server

What it does
Runs a world: players, mobs, redstone, farms, chunks. Built on Folia, so different areas of the world tick on different CPU cores.
What it does not do
Does not need the other three. On its own it is a complete Minecraft server.
Runs on
Your main machine (or one per game mode behind a proxy).
Needs
Java 25, RAM for the world (RAM world) plus the heap.
Ports
25565 for players (or a private port behind the proxy).
Configuration
storia.yml, plus the usual Paper and Folia files.
Read the docs

Storia Proxy

The front door

What it does
Accepts every player on one address and sends them to the right server or worker. In a cluster it switches players between workers without a loading screen. Shows the server list MOTD, a live tab list and network-wide messages, built from 50 placeholders.
What it does not do
Does not run any world, so it needs very little CPU. Plugins for it are Velocity plugins.
Runs on
Any small machine, often next to the servers.
Needs
Java 21+, about 512 MB of RAM.
Ports
25565 for players.
Configuration
velocity.toml, storia-proxy.toml.
Read the docs

Storia Worker

One server of a cluster

What it does
Runs the part of the shared world where its players are: chunks, mobs, redstone and the players themselves. Add workers when your players outgrow one machine.
What it does not do
Cannot be added to a single Storia server: it needs Storia Relay. Keeps no world of its own; chunks, player data and shared data are read from and written to the relay.
Runs on
Any machine that could run a Storia server.
Needs
Java 25, about the CPU and RAM of a normal Storia server. No world copy: it fetches the world settings from the relay.
Ports
25565 for the proxy (keep it private).
Configuration
storia.yml (cluster.*).
Read the docs

Storia Relay

The coordinator

What it does
Stores the world, gives every part of it to one worker at a time, puts players who meet on the same worker, balances busy workers and tells the proxy when to move a player.
What it does not do
Runs no part of the world itself and needs no Minecraft server.
Runs on
One reachable machine with disk space for the world; can be the proxy's machine.
Needs
Java 21+, about 512 MB of RAM, disk for the world.
Ports
25590 for workers and the proxy.
Configuration
relay.properties.
Read the docs

Inside every Storia server

These layers run in a single Storia server and in every worker of a cluster.

Regions

Folia groups nearby chunks into regions. Each region ticks on its own CPU core, so a busy base on one side of the world does not slow down a player on the other side.

Tick guard

When a region gets too slow, mobs in crowded chunks think less often. Players standing there are not limited, and redstone is never touched.

Player budget

Only players who add load by themselves, such as flying fast with elytra, get a shorter view distance while their region is busy.

RAM world

On a single server, worlds live in RAM and are written to disk in the background, so saving and loading chunks never waits for the disk.

Pregeneration

Generates terrain ahead of time using every spare core, so exploring only loads chunks that already exist.

Cluster client

In a worker, reads and writes chunks through the relay, keeps writes on disk while the relay is away, and hands players over when they move.

The journey of a player between workers

What happens when Bob, on worker B, flies toward Alice, who is on worker A.

  1. Storia Worker

    Every second, each worker tells the relay which parts of the world its players can see.

  2. Storia Relay

    Bob's view is about to touch Alice's area. The relay decides they belong on one worker: the one with more players there, A.

  3. Storia Relay

    The relay asks worker B to hand Bob over. B saves his inventory, advancements, statistics and position, and reports ready.

  4. Storia Proxy

    Storia Proxy connects Bob to worker A in the background with the same entity id, then switches his connection over: no login, no respawn, no loading screen.

  5. Storia Worker

    Worker A reads Bob's data from the relay; the cells B was running are released and A takes them over from their saved state.

  6. Storia Worker

    Bob keeps flying. His client never noticed that the server behind it changed.

The journey of a player

  1. Server list

    The player's client pings the proxy's address. Storia Proxy answers with the MOTD from storia-proxy.toml, with placeholders such as {online} filled in.

  2. Login

    The proxy authenticates the player with Mojang. In a cluster it asks the relay which worker runs the place they logged out, and connects them there.

  3. Forwarding

    Modern forwarding passes the player's UUID and skin to the server, signed with the forwarding secret, so the server can trust it.

  4. Playing

    The tab list refreshes every second with placeholders about the player and the network. Join, leave and switch messages go to everyone.

  5. Moving

    Crossing into another worker's part of the world moves the player without a loading screen. Moving to another server of a network (lobby, minigames) is a normal switch.

What travels over each connection

ConnectionCarriesProtection
Player ↔ Storia ProxyThe Minecraft protocol: movement, chat, chunks, everything the game needs.Minecraft's own encryption (online mode).
Storia Proxy ↔ Storia server or workerThe same Minecraft traffic, plus the forwarded player identity.Signed with the forwarding secret. Keep servers and workers off the public internet.
Storia Worker ↔ Storia RelayChunks, entities, player data, advancements, statistics, maps, the scoreboard, and who runs which part of the world.AES-256-GCM with keys derived from your shared secret, which is never sent.
Storia Proxy ↔ Storia RelayWhich worker a player should join, and when to move a player.The same encryption, with its own keys per connection.

When something stops

If this stopsWhat happens
A worker, with /stopIt first moves its players to the other workers, then saves and stops. Nobody is kicked.
A worker that crashesThe proxy sends its players to another worker. Within 15 seconds the relay gives its part of the world to another worker, from the last saved state.
The relayWorkers keep running and keep their writes on disk until it is back. New players cannot join and nobody is moved in the meantime.
The proxyPlayers cannot join through it until it is back. Servers, workers and their world keep running and nothing is lost.
A single server's machineWith the RAM world, changes since the last sync (5 minutes by default) are lost; if only the server process dies, the RAM copy is recovered on the next start.

Three common setups

Start with the first one and add programs as your server grows.

1

Single server

For most servers. Everything on one machine.

PlayersStoria

Storia only

2

Network

Several game modes behind one address, with a shared tab list and messages.

PlayersProxyStoria ×2

Storia Proxy + Storia

3

Cluster

One big world on several machines. Add workers as players grow.

PlayersProxyWorker ×NRelay

Storia Proxy + Storia Worker + Storia Relay

Requirements at a glance

ProgramJavaMemoryPortFiles it needs
Storia25Heap + the world in RAM25565The world
Storia Proxy21+~512 MB25565None
Storia Worker25Like a Storia server25565 (private)None: fetches the world settings from the relay
Storia Relay21+~512 MB + disk25590The world

Every port can be changed. All four programs come in every release on the downloads page.

Download all four