Architecture

How Storia works

Storia is four programs that work together. Only the server is required; the others add a network, more CPU for terrain, or both. This page explains what each one does, where it runs and what travels between them.

Overview of a full Storia network Players connect to Storia Proxy on port 25565. Storia Proxy forwards each player to one of the Storia servers (for example lobby and survival), using modern forwarding. A Storia server sends terrain work, encrypted, to Storia Relay on port 25590. Storia Relay hands each piece of work to one of the Storia Workers, which send the terrain back the same way. Network Game servers Terrain helpers Players MC Storia Proxy:25565 modern forwarding Storia · lobbyFolia Storia · survivalFolia AES-GCM Storia Relay:25590 Worker Aterrain noiseWorker Bterrain noiseWorker Cterrain noise
  1. Players connect to Storia Proxy on port 25565.
  2. Storia Proxy forwards each player to one of the Storia servers (for example lobby and survival), using modern forwarding.
  3. A Storia server sends terrain work, encrypted, to Storia Relay on port 25590.
  4. Storia Relay hands each piece of work to one of the Storia Workers, which send the terrain back the same way.

The four programs

Each program has one job. Together they form a network where no single busy place can slow everyone down.

Storia

The game server

What it does
Runs the 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. Shows the server list MOTD, a live tab list and network-wide join and switch 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

Extra CPU for terrain

What it does
Computes the heaviest step of terrain generation (the shape of the land, caves and aquifers) for a Storia server, and sends the result back.
What it does not do
Opens no player port, never stores or changes your world, never sees players, chat or inventories.
Runs on
Any spare machine: an old PC, a second server, a cloud VM.
Needs
Java 25, a copy of the world folder without its chunks (level.dat, datapacks, data).
Ports
25590 when listening; none when it connects out to a relay.
Configuration
storia.yml (offload.mode: worker).
Read the docs

Storia Relay

The dispatcher

What it does
Sits between servers and workers and hands each piece of terrain work to the least busy worker whose terrain matches exactly. Workers can join and leave at any time.
What it does not do
Does no terrain work itself and needs no Minecraft files.
Runs on
One reachable machine; can be the proxy's machine.
Needs
Java 21+, about 256 MB of RAM.
Ports
25590 for servers and workers.
Configuration
relay.properties.
Read the docs

Inside the Storia server

The server is where the world lives. These layers work together to keep every player's experience smooth.

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

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.

Offload client

Sends the noise step of new chunks to workers, and generates locally whenever a worker is busy, slow or gone.

The journey of a new chunk

What happens when a player walks into land that has never been generated, with a relay and workers set up.

  1. Storia server

    A player reaches the edge of the generated world. The server needs new chunks.

  2. Storia server

    The server places structure starts and biomes. These depend on the whole world, so they stay local.

  3. Storia server

    For the noise step, it picks a connection with free capacity and sends a request: the chunk position, the dimension and the outlines of nearby structures.

  4. Storia Relay

    The relay forwards the request to the least busy worker that produced identical probe chunks for this dimension.

  5. Storia Worker

    The worker computes the terrain shape, caves and aquifers, and sends back the blocks and heightmaps.

  6. Storia server

    The server checks the answer and applies it. If no answer arrives in time, it generates the chunk itself instead.

  7. Storia server

    The server adds surface blocks, caves, trees, ores and light, then sends the finished chunk to the player.

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, then connects them to the first server in its try list.

  3. Forwarding

    Modern forwarding passes the player's UUID and skin to the Storia 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. Switching

    When the player moves to another server, the proxy keeps the connection and moves it. If a server stops unexpectedly, the proxy sends its players to another one.

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 serverThe same Minecraft traffic, plus the forwarded player identity.Signed with the forwarding secret. Keep servers off the public internet.
Storia server ↔ Relay or WorkerChunk positions, the dimension and nearby structure outlines one way; terrain blocks and heightmaps the other. Never players, chat or inventories.AES-256-GCM with keys derived from your shared secret, which is never sent.
Relay ↔ WorkerThe same terrain requests and answers, passed through.The same encryption, with its own keys per connection.

When something stops

If this stopsWhat happens
A workerIts unfinished requests go to another worker, or back to the server, which generates those chunks itself. At most, those chunks take a moment longer.
The relayServers generate all terrain locally and reconnect automatically when the relay is back.
A Storia serverThe proxy moves its players to another server in the try list. The other servers keep running.
The proxyPlayers cannot join through it until it is back. Servers and their worlds keep running and nothing is lost.
The machine running a serverWith 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.

Four common setups

Start with the first one and add programs as your server grows. Nothing needs to be reinstalled.

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

Server with helpers

A busy exploration or pregeneration server with one or two spare machines.

PlayersStoriaWorker ×2

Storia + Storia Worker

4

Full network

Many servers sharing a pool of workers that can come and go.

PlayersProxyStoria ×3RelayWorker ×N

all four

Requirements at a glance

ProgramJavaMemoryPortFiles it needs
Storia25Heap + the world in RAM25565The world
Storia Proxy21+~512 MB25565None
Storia Worker252–4 GB25590 (or none with a relay)The world folder without region, entities, poi
Storia Relay21+~256 MB25590None

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

Download all four