Architecture Overview

Void is built with a modular, layered architecture that emphasizes separation of concerns and type safety.

For the full detailed architecture documentation, see the Architecture Reference.

System Architecture

graph TD
    Client[Minecraft Client] -->|TCP| Net[void-net: Async TCP Socket Wrapper<br/>Tokio-based networking]
    Net --> Codec[void-codec: Binary Serialization/Deserialization<br/>Encode/Decode Traits]
    Codec --> Protocol[void-protocol: Minecraft Protocol Definitions<br/>Packets by state and direction]
    Protocol --> Core[void: Core Server Application<br/>Client handling, game logic, state management]

Dual-Threaded Model

Void runs on two threads:

Network thread — A Tokio multi-threaded runtime that handles TCP connections, packet I/O, and per-client async tasks.
Game thread — A Bevy ECS application that runs the game loop, processes packets, updates world state, and sends responses.

The two threads communicate exclusively through flume channels. See the full architecture reference for channel details and the complete packet flow diagram.

Crate Structure

Crate	Description
`void`	Core server framework — ECS components, systems, handlers, commands, world generation, and the public API.
`void-net`	Low-level TCP socket abstraction (accept, read, write framed packets).
`void-protocol`	Minecraft protocol definitions — serverbound/clientbound packet enums and data types.
`void-codec`	Binary `Encode`/`Decode` traits and primitive type implementations.
`void-codec-macros`	Derive macros (`#[derive(Encode, Decode)]`) and field attributes for codec automation.

Connection State Machine

Minecraft connections flow through predefined states:

Handshake -> Status (server list ping)
          -> Login -> Configuration -> Play

See Networking & Protocol for the full connection lifecycle and packet handling pipeline.

Key Reference Pages

Architecture Details — Dual-threaded model, tick loop, plugin system, packet flow
Configuration — ServerBuilder API, ServerConfig fields, defaults
ECS Components & Resources — All components, resources, and entity lifecycle
Events — Semantic events, packet events, observer pattern
Networking & Protocol — Protocol states, connection lifecycle, keep-alive
Command System — CommandBuilder, argument parsers, flags, default commands
World & Chunks — Chunk system, dimensions, streaming, world generators
Player Management — Join/quit flow, visibility, position broadcasting
Binary Codec — Encode/Decode traits, derive macros, field attributes
Registry System — RegistryDataStore API, default registries, customization

ON THIS PAGE

Architecture Overview#

System Architecture#

Dual-Threaded Model#

Crate Structure#