# minestom/minestom architecture

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

- Interactive diagram: https://gitdiagram.com/minestom/minestom
- Repository: https://github.com/minestom/minestom
- Video tour (about a minute): https://gitdiagram.com/minestom/minestom/video

## Overview

##### Main Components
b. Core Engine/API – The “src/main/java/net/minestom” and especially subpackages under “server” form the backbone of the API. This includes key classes like “MinecraftServer”, “ServerProcess”, and “Tickable”. Include components that manage game state, world tick, scheduling, and multithreading.
c. Networking – The “net/minestom/server/network” package handles all client–server communications. It includes packet parsing and writing, connection management, and player protocol handling. Represent this as a separate yet interconnected module.
d. World & Instance Management – The “net/minestom/server/instance” package manages world instances (the “instance system”). It covers chunks, lighting, block management, and collision detection. This module is architected to be multi-threaded and scalable.
e. Entities, Blocks, and Game Objects – Packages like “net/minestom/server/entity”, “block”, “item”, “inventory” and “component” define the behavior of game objects (entities, interactive blocks, inventories) and include systems like AI, command handling, and physics.
f. Command and Event Handling – Within “net/minestom/server/command” and “net/minestom/server/event”, the command system (with builder patterns) and the event dispatch/listening mechanism are defined.
g. Utilities and Threading – The “net/minestom/server/utils”, “thread” and “timer” packages encapsulate aspects such as asynchronous processing, scheduled tasks, and helper functionalities.
h. Tests and Benchmarks – Modules like “jcstress-tests”, “jmh-benchmarks”, and “testing” provide integration, concurrency, and performance testing. These can be treated as peripheral components that interact with the core modules for continuous validation.

- Code Generation flow (from code-generators to autogenerated source) as an input process that feeds into the core API.
– Networking module ↔ Event Dispatcher
– Event Dispatcher → Command Module and Entity Module (processing player commands or state changes)
– World/Instance Manager ↔ Collision and Lighting modules
– Utilities (threading/timer) are used by almost every core module.

##### Notable Architectural Patterns
- Layered Architecture: Separate low-level infrastructure (utilities, networking) from business logic (game instances, entities, commands).
- Event-Driven Design: Emphasize the event-handling system where changes in player actions or world states trigger events handled by listeners across modules.
- Code Generation: Highlight that many constants and helper classes are automatically generated to maintain consistency and reduce manual coding.
- Modularity: Each major package (entity, instance, command, network) functions as an independent component that communicates through well-defined APIs.

– “API Core” (Minestom Server) in the center.
– Surround that with “Game Modules” (Instances, Entities, Blocks, Inventories, Commands) shown as components that the API exposes.
– “Networking” should be drawn at the edge, representing external connections to clients.
– “Code Generation” feeds into the “API Core” and “Game Modules.”

##### Extra Elements
- Also denote “Tests & Benchmarks” as ancillary components that validate performance and functionality.

Happy diagramming!

## Diagram (Mermaid)

```mermaid
graph TD
    %% Code Generation Layer
    subgraph "Code Generation Layer"
        CodeGen["Code Generation"]:::generator
    end

    %% Core Engine Layer
    subgraph "Core Engine Layer"
        Core["API Core"]:::core
    end

    %% Game Modules
    subgraph "Game Modules"
        Net["Networking"]:::network
        WIM["World & Instance Management"]:::world
        Ent["Entities"]:::entity
        Blk["Blocks"]:::block
        Itm["Items"]:::item
        Cmd["Command System"]:::command
        Evnt["Event Handling"]:::event
    end

    %% Infrastructure & Utilities
    subgraph "Infrastructure & Utilities"
        Util["Utilities"]:::util
        Thd["Threading"]:::thread
        Tmr["Timer"]:::timer
    end

    %% Ancillary
    subgraph "Ancillary"
        Test["Tests & Benchmarks"]:::test
        Demo["Demo Application"]:::demo
    end

    %% Relationships
    CodeGen -->|"generates"| Core
    Core -->|"routes calls"| Net
    Core -->|"manages"| WIM
    Core -->|"updates"| Ent
    Core -->|"invokes"| Cmd
    Core -->|"emits"| Evnt

    Net -->|"sends"| Evnt
    Evnt -->|"triggers"| Cmd
    WIM <-->|"integrates"| Blk

    Util -->|"supports"| Core
    Util -->|"supports"| Net
    Util -->|"supports"| WIM
    Util -->|"supports"| Ent
    Util -->|"supports"| Cmd
    Util -->|"supports"| Evnt

    Thd -->|"enables"| Util
    Tmr -->|"schedules"| Util

    Core -->|"example usage"| Demo
    Test -->|"validates"| Core

    %% Click Events
    click CodeGen "https://github.com/minestom/minestom/tree/master/code-generators"
    click Core "https://github.com/minestom/minestom/tree/master/src/main/java/net/minestom/server"
    click Net "https://github.com/minestom/minestom/tree/master/src/main/java/net/minestom/server/network"
    click WIM "https://github.com/minestom/minestom/tree/master/src/main/java/net/minestom/server/instance"
    click Ent "https://github.com/minestom/minestom/tree/master/src/main/java/net/minestom/server/entity"
    click Blk "https://github.com/minestom/minestom/tree/master/src/main/java/net/minestom/server/instance/block"
    click Itm "https://github.com/minestom/minestom/tree/master/src/main/java/net/minestom/server/item"
    click Cmd "https://github.com/minestom/minestom/tree/master/src/main/java/net/minestom/server/command"
    click Evnt "https://github.com/minestom/minestom/tree/master/src/main/java/net/minestom/server/event"
    click Util "https://github.com/minestom/minestom/tree/master/src/main/java/net/minestom/server/utils"
    click Thd "https://github.com/minestom/minestom/tree/master/src/main/java/net/minestom/server/thread"
    click Tmr "https://github.com/minestom/minestom/tree/master/src/main/java/net/minestom/server/timer"
    click Test "https://github.com/minestom/minestom/tree/master/src/test"
    click Demo "https://github.com/minestom/minestom/tree/master/demo"

    %% Styles
    classDef generator fill:#FFCCCC,stroke:#333,stroke-width:2px;
    classDef core fill:#CCE5FF,stroke:#333,stroke-width:2px;
    classDef network fill:#CCFFCC,stroke:#333,stroke-width:2px;
    classDef world fill:#FFF2CC,stroke:#333,stroke-width:2px;
    classDef entity fill:#FCE5CD,stroke:#333,stroke-width:2px;
    classDef block fill:#F8CBAD,stroke:#333,stroke-width:2px;
    classDef item fill:#F4B084,stroke:#333,stroke-width:2px;
    classDef command fill:#D9EAD3,stroke:#333,stroke-width:2px;
    classDef event fill:#D0E0E3,stroke:#333,stroke-width:2px;
    classDef util fill:#DDEBF7,stroke:#333,stroke-width:2px;
    classDef thread fill:#D9D2E9,stroke:#333,stroke-width:2px;
    classDef timer fill:#EAD1DC,stroke:#333,stroke-width:2px;
    classDef test fill:#FFF2CC,stroke:#333,stroke-width:2px;
    classDef demo fill:#C9DAF8,stroke:#333,stroke-width:2px;
```
