Architecture · Helix docs

This page explains how the engine is built. The full, binding design is in API_DESIGN.md; when the two disagree, that file wins.

Rule zero: one-to-one with BDS

Vanilla behaviour matches BDS exactly, not “close enough”: world generation, redstone, every other vanilla mechanic and the world storage format. Where parallel work could change a vanilla result, such as redstone update order or scheduled ticks, Helix follows BDS’s order inside a region.

The performance target is no felt lag, even with 400 players in one spot: no tick over 50 ms, checked with a benchmark of 400 fake players.

Layers

The engine is built in layers, and each piece is an interface with a default implementation you can swap on its own:

Core: ticking, networking, chunks and players.
Systems: physics, AI, pathfinding, inventories, world generation and storage.
Vanilla content: blocks, items, mobs and mechanics, built only on the public API.
Your server’s own code.

Two presets are planned: vanilla (everything on, for survival) and minimal (core only, for Skyblock and minigames).

Registry

Vanilla, built-in features and plugins all register content through one Setup builder at boot. There is no back door.

Frozen at boot: what the client is told once when it joins, such as blocks and their states, items, biomes and entity types.
Changeable while running: recipes, the creative inventory, commands, and server-only data such as loot, trades and spawn rules.
Registering an existing name overrides it, and the log says which plugin replaced what.
Every block state is a dense number with its properties in one flat table. Behaviour is a set of small optional hooks; plugins can replace a behaviour or wrap it to run code before or after vanilla’s, even while the server runs.

World in memory

Each player has two zones around them:

The simulation zone (BDS’s tick distance) is fully loaded and ticked.
The view zone (BDS’s view distance) is loaded or generated on worker threads, sent to the player, then released.

Memory follows the area being simulated, not the size of the world or the view distance. As on BDS, the client draws distant vanilla terrain itself, which cuts the number of chunk packets by about 3.3 times.

Regions and ticking

The world is split into regions that tick in parallel at 20 ticks per second, merging when players come together and splitting when they move apart.

Inside a crowded region, every player’s own input and mob AI’s thinking run in parallel; anything that changes the shared world is applied afterwards in a fixed order, so results are the same on any number of cores.
Each entity update is encoded once per tick and the same bytes go to every viewer.
A region never waits on loading or saving.

Players

A player is three parts:

The session: the connection, identity and what the client has been sent.
The entity: position, health, inventory and game mode, owned by the region it stands in.
The profile: permissions and server-wide facts.

Which entities a player sees and the packets sent on join follow BDS. Anti-cheat is an optional module, off by default.

Events

Priorities are named by when they run: First, Early, Normal, Late, Last, then Monitor, which only reads.
Almost every event can be cancelled or changed.
An event nobody listens to is never built, and firing one allocates nothing.

Storage

By default each world is one LevelDB, exactly like BDS, with every key and format the same, so any BDS world opens in Helix and any Helix world opens in BDS.
Storage is pluggable: the world store and player store are separate, so a network can keep players in one shared database.
Each plugin gets its own namespaced key-value store.