# luanti-org/luanti architecture

> Architecture diagram of the GitHub repository luanti-org/luanti, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/luanti-org/luanti
- Repository: https://github.com/luanti-org/luanti

## Overview

#### Purpose and entry points
Luanti is a C++ voxel game engine that runs an interactive client, a dedicated server, or local singleplayer; games and mods are Lua content. Process startup and mode selection originate in `src/main.cpp`, with client launch/game control in `src/client/clientlauncher.cpp` and authoritative server lifecycle in `src/server.cpp`. CMake defines the native build graph at `CMakeLists.txt` and `src/CMakeLists.txt`.

#### Core simulation and world model
The engine’s shared domain model represents voxel maps, nodes, entities, players, inventories, crafting, collision, lighting, and serialization. Persistent/in-memory map structures center on `src/map.cpp`, `src/mapblock.cpp`, and `src/environment.cpp`. Server specialization adds world ownership, active objects, player state, rollback, and inventory mutation through `src/servermap.cpp`, `src/serverenvironment.cpp`, and `src/server/activeobjectmgr.cpp`.

#### Server, generation, and persistence
The server simulates the world, invokes gameplay callbacks, generates/emerges map blocks, and persists data. Emerge/map-generation is separated from runtime map management in `src/emerge.cpp`, `src/mapgen/mapgen.cpp`, and generator variants such as `src/mapgen/mapgen_v7.cpp`. Database adapters provide a replaceable persistence boundary: files, SQLite3, LevelDB, PostgreSQL, and Redis under `src/database/database.cpp`, `src/database/database-sqlite3.cpp`, and `src/database/database-postgresql.cpp`.

#### Multiplayer protocol boundary
Client and server exchange engine protocol packets over the networking layer. Packet definitions, opcode dispatch, connection handling, and the transport implementation reside in `src/network/networkprotocol.cpp`, `src/network/connection.cpp`, and `src/network/mtp/impl.cpp`; server-side client/session management is `src/server/clientiface.cpp`. This is the principal trust boundary between remote clients and server-authoritative state.

#### Client runtime and rendering
The client receives replicated world/media state, maintains client-side environment and map meshes, processes input/UI, and renders through the bundled Irrlicht-derived graphics stack. Core gameplay loop is `src/client/game.cpp`; world replication/model is `src/client/client.cpp` and `src/client/clientenvironment.cpp`; asynchronous mesh construction is `src/client/mesh_generator_thread.cpp`. Rendering pipeline and effects are organized in `src/client/render/pipeline.cpp`, `src/client/renderingengine.cpp`, and GLSL assets such as `client/shaders/nodes_shader/opengl_fragment.glsl`. The graphics runtime is vendored in `irr/`, including SDL device support and OpenGL/GLES drivers.

#### Lua content and scripting boundary
Lua is the extension boundary for games, server mods, client mods, menus, mapgen, and restricted server-sent client-side mods. C++ Lua bindings and context-specific script hosts are in `src/script/lua_api/`, `src/script/scripting_server.cpp`, and `src/script/scripting_client.cpp`. Built-in Lua establishes standard engine behavior and UI: `builtin/game/init.lua`, `builtin/mainmenu/init.lua`, and `builtin/client/init.lua`. Installed game/mod content is discovered and configured via `src/content/mods.cpp` and `src/content/subgames.cpp`; `games/devtest/` is the bundled engine-validation game.

#### Platform and external dependencies
Native targets use CMake and run across desktop platforms plus Android. Android wraps the native engine with Java/SDL activities in `android/app/src/main/java/net/minetest/minetest/GameActivity.java` and Gradle builds. Material dependencies include SDL, OpenGL/OpenGLES, Lua or LuaJIT, OpenAL/Vorbis, curl/HTTP, gettext, and optional database backends; discovery modules are under `cmake/Modules/`. Docker supports server deployment via `Dockerfile`.

Main entry points: [`src/server.cpp`](https://github.com/luanti-org/luanti/blob/master/src/server.cpp) (Server lifecycle), [`src/main.cpp`](https://github.com/luanti-org/luanti/blob/master/src/main.cpp) (Process startup), [`src/script/scripting_server.cpp`](https://github.com/luanti-org/luanti/blob/master/src/script/scripting_server.cpp) (Lua script hosts), [`src/servermap.cpp`](https://github.com/luanti-org/luanti/blob/master/src/servermap.cpp) (Server world state)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_native["Native engine"]
  node_startup(("Process startup<br/>C++ entry point<br/>[main.cpp]"))
  node_shared_world["Shared world model<br/>map and simulation<br/>[map.cpp]"]
  node_protocol["Network protocol<br/>packet definitions"]
  node_transport["Network transport<br/>MTP connection<br/>[impl.cpp]"]
end

subgraph group_server["Authoritative server"]
  node_server_lifecycle["Server lifecycle<br/>authoritative runtime<br/>[server.cpp]"]
  node_server_world["Server world state<br/>world ownership<br/>[servermap.cpp]"]
  node_emerge["Emerge and mapgen<br/>world generation<br/>[emerge.cpp]"]
  node_mapgen["Map generator<br/>generator variants<br/>[mapgen.cpp]"]
  node_database[("Persistence adapters<br/>database boundary<br/>[database.cpp]")]
  node_server_sessions["Server sessions<br/>client interface<br/>[clientiface.cpp]"]
end

subgraph group_client["Client and graphics"]
  node_launcher["Client launcher<br/>launch control<br/>[clientlauncher.cpp]"]
  node_client_game["Client game loop<br/>interactive runtime<br/>[game.cpp]"]
  node_client_world["Client world replica<br/>replicated environment<br/>[client.cpp]"]
  node_mesh_worker["Mesh generation worker<br/>async meshing"]
  node_rendering["Rendering pipeline<br/>graphics pipeline<br/>[pipeline.cpp]"]
  node_graphics_runtime["Irrlicht graphics runtime<br/>vendored graphics"]
end

subgraph group_content["Lua content"]
  node_script_hosts{{"Lua script hosts<br/>C++ scripting boundary"}}
  node_builtin_lua["Built-in Lua behavior<br/>Lua runtime content<br/>[init.lua]"]
  node_games_mods["Games and mods<br/>Lua content discovery<br/>[mods.cpp]"]
end

subgraph group_platform["Build and platform"]
  node_cmake["Native build graph<br/>CMake build<br/>[CMakeLists.txt]"]
  node_android["Android wrapper<br/>Java SDL activity<br/>[GameActivity.java]"]
end

node_startup -->|"starts client"| node_launcher
node_startup -->|"starts server"| node_server_lifecycle
node_launcher -->|"launches"| node_client_game
node_server_lifecycle -->|"owns"| node_server_world
node_server_world -->|"specializes"| node_shared_world
node_server_lifecycle -->|"requests blocks"| node_emerge
node_emerge -->|"generates"| node_mapgen
node_server_world -->|"persists world"| node_database
node_server_lifecycle -->|"manages clients"| node_server_sessions
node_server_sessions -->|"dispatches packets"| node_protocol
node_protocol -->|"uses"| node_transport
node_transport -->|"replicates state"| node_client_world
node_client_game -->|"updates"| node_client_world
node_client_world -->|"schedules meshes"| node_mesh_worker
node_mesh_worker -->|"provides mesh data"| node_rendering
node_rendering -->|"draws through"| node_graphics_runtime
node_server_lifecycle -->|"invokes callbacks"| node_script_hosts
node_client_game -->|"runs client scripts"| node_script_hosts
node_script_hosts -->|"loads"| node_builtin_lua
node_script_hosts -->|"executes content"| node_games_mods
node_cmake -->|"builds"| node_startup
node_android -->|"hosts native engine"| node_startup

click node_startup "https://github.com/luanti-org/luanti/blob/master/src/main.cpp"
click node_launcher "https://github.com/luanti-org/luanti/blob/master/src/client/clientlauncher.cpp"
click node_shared_world "https://github.com/luanti-org/luanti/blob/master/src/map.cpp"
click node_server_lifecycle "https://github.com/luanti-org/luanti/blob/master/src/server.cpp"
click node_server_world "https://github.com/luanti-org/luanti/blob/master/src/servermap.cpp"
click node_emerge "https://github.com/luanti-org/luanti/blob/master/src/emerge.cpp"
click node_mapgen "https://github.com/luanti-org/luanti/blob/master/src/mapgen/mapgen.cpp"
click node_database "https://github.com/luanti-org/luanti/blob/master/src/database/database.cpp"
click node_server_sessions "https://github.com/luanti-org/luanti/blob/master/src/server/clientiface.cpp"
click node_protocol "https://github.com/luanti-org/luanti/blob/master/src/network/networkprotocol.cpp"
click node_transport "https://github.com/luanti-org/luanti/blob/master/src/network/mtp/impl.cpp"
click node_client_game "https://github.com/luanti-org/luanti/blob/master/src/client/game.cpp"
click node_client_world "https://github.com/luanti-org/luanti/blob/master/src/client/client.cpp"
click node_mesh_worker "https://github.com/luanti-org/luanti/blob/master/src/client/mesh_generator_thread.cpp"
click node_rendering "https://github.com/luanti-org/luanti/blob/master/src/client/render/pipeline.cpp"
click node_script_hosts "https://github.com/luanti-org/luanti/blob/master/src/script/scripting_server.cpp"
click node_builtin_lua "https://github.com/luanti-org/luanti/blob/master/builtin/game/init.lua"
click node_games_mods "https://github.com/luanti-org/luanti/blob/master/src/content/mods.cpp"
click node_cmake "https://github.com/luanti-org/luanti/blob/master/CMakeLists.txt"
click node_android "https://github.com/luanti-org/luanti/blob/master/android/app/src/main/java/net/minetest/minetest/GameActivity.java"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_startup,node_shared_world,node_protocol,node_transport toneBlue
class node_server_lifecycle,node_server_world,node_emerge,node_mapgen,node_database,node_server_sessions toneAmber
class node_launcher,node_client_game,node_client_world,node_mesh_worker,node_rendering,node_graphics_runtime toneMint
class node_script_hosts,node_builtin_lua,node_games_mods toneRose
class node_cmake,node_android toneIndigo
```

## Components

### Native engine

- [Process startup](https://github.com/luanti-org/luanti/blob/master/src/main.cpp): C++ entry point · Selects client, dedicated-server, or local-play mode. · `src/main.cpp`
- [Shared world model](https://github.com/luanti-org/luanti/blob/master/src/map.cpp): map and simulation · Maps, blocks, environment, entities, and serialization. · `src/map.cpp`
- [Network protocol](https://github.com/luanti-org/luanti/blob/master/src/network/networkprotocol.cpp): packet definitions · `src/network/networkprotocol.cpp`
- [Network transport](https://github.com/luanti-org/luanti/blob/master/src/network/mtp/impl.cpp): MTP connection · `src/network/mtp/impl.cpp`

### Authoritative server

- [Server lifecycle](https://github.com/luanti-org/luanti/blob/master/src/server.cpp): authoritative runtime · `src/server.cpp`
- [Server world state](https://github.com/luanti-org/luanti/blob/master/src/servermap.cpp): world ownership · Owns active objects, players, rollback, and inventories. · `src/servermap.cpp`
- [Emerge and mapgen](https://github.com/luanti-org/luanti/blob/master/src/emerge.cpp): world generation · `src/emerge.cpp`
- [Map generator](https://github.com/luanti-org/luanti/blob/master/src/mapgen/mapgen.cpp): generator variants · `src/mapgen/mapgen.cpp`
- [Persistence adapters](https://github.com/luanti-org/luanti/blob/master/src/database/database.cpp): database boundary · Replaceable file, SQL, LevelDB, PostgreSQL, and Redis storage. · `src/database/database.cpp`
- [Server sessions](https://github.com/luanti-org/luanti/blob/master/src/server/clientiface.cpp): client interface · `src/server/clientiface.cpp`

### Client and graphics

- [Client launcher](https://github.com/luanti-org/luanti/blob/master/src/client/clientlauncher.cpp): launch control · `src/client/clientlauncher.cpp`
- [Client game loop](https://github.com/luanti-org/luanti/blob/master/src/client/game.cpp): interactive runtime · `src/client/game.cpp`
- [Client world replica](https://github.com/luanti-org/luanti/blob/master/src/client/client.cpp): replicated environment · `src/client/client.cpp`
- [Mesh generation worker](https://github.com/luanti-org/luanti/blob/master/src/client/mesh_generator_thread.cpp): async meshing · `src/client/mesh_generator_thread.cpp`
- [Rendering pipeline](https://github.com/luanti-org/luanti/blob/master/src/client/render/pipeline.cpp): graphics pipeline · Renders meshes and effects through the Irrlicht-derived runtime. · `src/client/render/pipeline.cpp`
- **Irrlicht graphics runtime**: vendored graphics · SDL device and OpenGL/GLES drivers.

### Lua content

- [Lua script hosts](https://github.com/luanti-org/luanti/blob/master/src/script/scripting_server.cpp): C++ scripting boundary · Context-specific server and client Lua hosts. · `src/script/scripting_server.cpp`
- [Built-in Lua behavior](https://github.com/luanti-org/luanti/blob/master/builtin/game/init.lua): Lua runtime content · `builtin/game/init.lua`
- [Games and mods](https://github.com/luanti-org/luanti/blob/master/src/content/mods.cpp): Lua content discovery · Discovers installed games and mods. · `src/content/mods.cpp`

### Build and platform

- [Native build graph](https://github.com/luanti-org/luanti/blob/master/CMakeLists.txt): CMake build · `CMakeLists.txt`
- [Android wrapper](https://github.com/luanti-org/luanti/blob/master/android/app/src/main/java/net/minetest/minetest/GameActivity.java): Java SDL activity · `android/app/src/main/java/net/minetest/minetest/GameActivity.java`

## Connections

- Process startup → Client launcher: starts client
- Process startup → Server lifecycle: starts server
- Client launcher → Client game loop: launches
- Server lifecycle → Server world state: owns
- Server world state → Shared world model: specializes
- Server lifecycle → Emerge and mapgen: requests blocks
- Emerge and mapgen → Map generator: generates
- Server world state → Persistence adapters: persists world
- Server lifecycle → Server sessions: manages clients
- Server sessions → Network protocol: dispatches packets
- Network protocol → Network transport: uses
- Network transport → Client world replica: replicates state
- Client game loop → Client world replica: updates
- Client world replica → Mesh generation worker: schedules meshes
- Mesh generation worker → Rendering pipeline: provides mesh data
- Rendering pipeline → Irrlicht graphics runtime: draws through
- Server lifecycle → Lua script hosts: invokes callbacks
- Client game loop → Lua script hosts: runs client scripts
- Lua script hosts → Built-in Lua behavior: loads
- Lua script hosts → Games and mods: executes content
- Native build graph → Process startup: builds
- Android wrapper → Process startup: hosts native engine
