# bulletmc/bullet architecture

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

- Interactive diagram: https://gitdiagram.com/bulletmc/bullet
- Repository: https://github.com/bulletmc/bullet

## Overview

##### Project Type & Purpose
- Bullet is designed as a specialized, high‑performance Minecraft server aimed at overcoming the limitations of vanilla servers (high RAM consumption, single-threaded design, and limited extensibility).
- Its purpose is to efficiently handle the game logic, player interactions, and network communication while also supporting familiar patterns for people coming from Spigot or Paper servers.

##### Analyzing the File Structure
- The project follows a modular design with clearly segregated directories for commands, entity management, network packets, events, storage, world handling, and various data types.
- There is a strong emphasis on packet handling (input/output for handshake, login, play, status packets) which reflects the network communication backbone of a Minecraft server.
- Subdirectories like “commands/commands” and “packets” hint at the Command Processing and Packet Handling layers, while “storage”, “world”, and “entity” indicate underlying subsystems for data management, world simulation, and in‑game objects.

##### Key Components
a. Core Server Component:
- "Bullet Core" (or Server Bootstrap) which initiates the server, sets up configurations, and acts as the central orchestrator.

b. Networking & Packet Handling:
- Packet Registry: Responsible for mapping packet types.
- Packet Handlers/Receivers: Incoming network data (e.g., handshake, login, play, status packets) is processed here.

c. Command System:
- Command Manager: Oversees command parsing and execution.
- Command Implementations: Each command (such as BanCommand, KickCommand, TeleportCommand) can be represented as nodes under the command system.
- Data & Suggestion Components: Supporting classes like GraphCommandNode and PlayerSuggestions provide context-sensitive command assistance.

d. Event & Session Management:
- Event Manager & Event Listeners: Illustrate how events (player actions, game state changes) propagate through the system.
- ClientSession: Manages individual player sessions.

e. Game World & Entity Management:
- World Management: Represented by the World module which handles world state, time, blocks, and in‑game environment (see directory “world” with blocks, data, and items).
- Entity System: Differentiate between living (player, mob) and non‑living entities with associated management components (BossBarManager, Inventory, etc.).

f. Storage Subsystem:
- Disk Storage: Illustrate components such as DiskServerStorage and DiskWorldStorage for persisting data.
- World & Player Data Persistence: Show how data flows between in‑memory game state and the disk storage.

g. Data Types & Serialization:
- Data-type abstractions under “datatypes” (Angle, BlockPositionType, etc.) and custom serializers, especially for UUIDs, ensuring that data is correctly formatted and transmitted.

##### Relationships & Interactions
- How the Event Manager interacts with various subsystems like Commands or Entity management to coordinate actions.
- Underline multi‑threading by noting that some components (e.g., packet processing, event handling) may operate concurrently across multiple CPU cores.

##### Architectural Patterns and Principles
- The design leans toward modularity, separating concerns into isolated subsystems for network operations, commands, events, and world management.
- The event-driven architecture is evident in the presence of an Event Manager and listeners.
- The pattern of command registration and handling reflects common design patterns (like Command Pattern) for extensibility.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Bullet Minecraft Server Architecture"
        BC("Bullet Core"):::core

        subgraph "Networking Subsystem"
            CC("Client Connection"):::network
            PR("Packet Receiver"):::network
            PG("Packet Registry"):::network
            PH("Packet Handler"):::network
        end

        subgraph "Command Subsystem"
            CM("Command Manager"):::command
            CI("Command Implementations"):::command
            GCN("Graph Command Node"):::command
            PS("Player Suggestions"):::command
        end

        subgraph "Event & Session Subsystem"
            EM("Event Manager"):::event
            EL("Event Listener"):::event
            CSN("Client Session"):::event
        end

        subgraph "World & Entity Subsystem"
            WM("World Manager"):::world
            GE("General Entity"):::world
            LE("Living Entities"):::world
            PM("Player Management"):::world
        end

        subgraph "Storage Subsystem"
            SM("Storage Manager"):::storage
            AS("Abstract Storage"):::storage
            DS("Disk Storage"):::storage
            WD("World Data Persistence"):::storage
        end

        subgraph "Data Types & Serialization"
            DT("Data-type Abstractions"):::datatype
            CustSer("Custom Serializers"):::datatype
        end
    end

    MT("Multi-threading & Performance Optimizations"):::note

    %% Networking Connections
    CC --> PR
    PR --> PH
    PG --> PH
    PH -->|"feeds"| BC

    %% Core to Subsystems
    BC -->|"invokes"| CM
    BC -->|"invokes"| EM
    BC -->|"invokes"| WM
    BC -->|"invokes"| SM
    BC -->|"utilizes"| DT
    BC --> GE

    %% Command Subsystem Connections
    CM --> CI
    CM --> GCN
    CM --> PS

    %% Event Subsystem Connections
    EM --> EL
    EM --> CSN
    EM -->|"triggers"| CM
    EM -->|"triggers"| GE

    %% World & Entity Connections
    GE --> LE
    LE --> PM
    WM -->|"persists state to"| SM

    %% Storage Subsystem Connections
    SM --> AS
    SM --> DS
    SM --> WD

    %% Data Types & Serialization Connection
    DT --> CustSer

    %% Annotation for multi-threading
    BC -.-> MT

    %% Click Events
    click BC "https://github.com/bulletmc/bullet/blob/main/src/main/kotlin/Bullet.kt"
    click PG "https://github.com/bulletmc/bullet/blob/main/src/main/kotlin/packets/PacketRegistry.kt"
    click PH "https://github.com/bulletmc/bullet/blob/main/src/main/kotlin/packets/PacketHandler.kt"
    click PR "https://github.com/bulletmc/bullet/blob/main/src/main/kotlin/packets/PacketReceiver.kt"
    click CM "https://github.com/bulletmc/bullet/blob/main/src/main/kotlin/commands/CommandManager.kt"
    click CI "https://github.com/bulletmc/bullet/tree/main/src/main/kotlin/commands/commands"
    click GCN "https://github.com/bulletmc/bullet/tree/main/src/main/kotlin/commands/data"
    click PS "https://github.com/bulletmc/bullet/blob/main/src/main/kotlin/commands/commands/suggestions/PlayerSuggestions.kt"
    click EM "https://github.com/bulletmc/bullet/blob/main/src/main/kotlin/events/EventManager.kt"
    click EL "https://github.com/bulletmc/bullet/blob/main/src/main/kotlin/events/EventListener.kt"
    click CSN "https://github.com/bulletmc/bullet/blob/main/src/main/kotlin/ClientSession.kt"
    click WM "https://github.com/bulletmc/bullet/blob/main/src/main/kotlin/world/World.kt"
    click GE "https://github.com/bulletmc/bullet/blob/main/src/main/kotlin/entity/Entity.kt"
    click LE "https://github.com/bulletmc/bullet/tree/main/src/main/kotlin/entity/livingentity"
    click PM "https://github.com/bulletmc/bullet/tree/main/src/main/kotlin/entity/player"
    click SM "https://github.com/bulletmc/bullet/blob/main/src/main/kotlin/storage/StorageManager.kt"
    click AS "https://github.com/bulletmc/bullet/blob/main/src/main/kotlin/storage/AbstractServerStorage.kt"
    click DS "https://github.com/bulletmc/bullet/tree/main/src/main/kotlin/storage/disk"
    click WD "https://github.com/bulletmc/bullet/tree/main/src/main/kotlin/storage/world"
    click DT "https://github.com/bulletmc/bullet/tree/main/src/main/kotlin/datatypes"
    click CustSer "https://github.com/bulletmc/bullet/blob/main/src/main/kotlin/serialization/UUIDSerializer.kt"

    %% Styles
    classDef core fill:#ef9a9a,stroke:#e57373,stroke-width:2px;
    classDef network fill:#fff59d,stroke:#fbc02d,stroke-width:2px;
    classDef command fill:#90caf9,stroke:#42a5f5,stroke-width:2px;
    classDef event fill:#90caf9,stroke:#42a5f5,stroke-width:2px;
    classDef world fill:#a5d6a7,stroke:#66bb6a,stroke-width:2px;
    classDef storage fill:#ffcc80,stroke:#ffa726,stroke-width:2px;
    classDef datatype fill:#ce93d8,stroke:#ab47bc,stroke-width:2px;
    classDef note fill:#eeeeee,stroke:#bdbdbd,stroke-dasharray: 5 5,stroke-width:2px;
```
