# elytrium/limboapi architecture

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

- Interactive diagram: https://gitdiagram.com/elytrium/limboapi
- Repository: https://github.com/elytrium/limboapi

## Overview

##### Project Type and Purpose
- This is a Java-based library/plugin for the Velocity Minecraft proxy.
- It consists of two Gradle modules:
- api – compile-time only interfaces, factories, session handlers, and abstractions for virtual worlds, chunks, players, packets, etc.
- plugin – the actual Velocity plugin implementation that injects into the Netty pipeline, loads world files, maps block/item data, and drives the virtual server (“Limbo”) behavior.

##### File Structure
- Top-level:
- api/… – Java packages under net.elytrium.limboapi.api defining the public contract.
- plugin/… – net.elytrium.limboapi implementation classes, mapping JSON/NBT resources, file loaders.
- config/, build scripts, templates (code generation for API constants).
- Key patterns:
- Modularization: API vs Implementation.
- Event-driven & injection (numerous Listener classes under plugin/src/main/java/.../injection).
- Resource-driven world mapping (plugin/src/main/resources/mapping).
- External deps configured in build.gradle: mcprotocollib, ViaVersion/ProtocolSupport for block mappings.

##### Extract Insights from the README
- Core functionality: intercept login/play events, spin up a lightweight “virtual server” session (Limbo), load a world, stream chunk & entity data, then hand off to a real server.
- Usage: consumers compile-only depend on limboapi-api; plugin module implements the API at runtime.
- References to packet control, chunk loading, world file formats (.schematic, .nbt).

a. External System
- Velocity Proxy (host application)
- Player TCP Connections
b. LimboAPI Modules
- API Module (interfaces): LimboFactory, LimboSessionHandler, VirtualWorld, VirtualChunk, etc.
- Plugin Module (implementation):
- Injection Handlers (LoginListener, DisconnectListener, PacketHooks)
- VirtualServer Manager (LimboImpl, LimboSessionHandlerImpl)
- World Loader (WorldFileTypeRegistry, MCEditSchematicFile, StructureNbtFile)
- Packet Generator (PacketFactoryImpl wrapping mcprotocollib)
- Mapping Resources (JSON/NBT under resources/mapping)
c. External Libraries
- mcprotocollib (low-level packet abstraction)
- ProtocolSupport / ViaVersion (legacy ↔ modern ID mapping)

##### Relationships & Interactions
- Velocity → Plugin’s Injection Handlers: intercept login, channel registration.
- Injection Handlers → VirtualServer Manager: invoke LimboFactory to create LimboImpl & session handler.
- VirtualServer Manager → World Loader: load world/chunk data from files and mapping resources.
- VirtualServer Manager → Packet Generator (mcprotocollib): build and send chunk, block, item, chat, title packets to the Player connection.
- Packet Generator ↔ External Libraries: pull ID mappings, abstract packet formats.
- VirtualServer Manager → Velocity: after the “limbo” sequence, forwards the player connection onward to the target real server.

##### Architectural Patterns & Principles
- Layered Separation: API (contract) vs Implementation (plugin) vs External libs.
- Event-Driven & Hook Architecture: uses Velocity’s event loop and Netty pipeline injection for login/play events.
- Adapter/Facade: PacketFactoryImpl wraps mcprotocollib into higher-level API.
- Resource-Driven Code Generation: API BuildConstants template and mapping JSON/NBT to drive behavior.
- Extensibility: other plugins (LimboAuth, LimboFilter) subscribe to API events.

- Blue for API module
- Green for Plugin subcomponents
- Orange for External libraries/systems
- Gray for resource files
- From Velocity Proxy → Injection Handlers (“Player Connection”)
- From Handlers → VirtualServer Manager (“LimboFactory.createSession()”)
- From Manager → World Loader (“loadWorld(…)”)
- From Manager → Packet Generator (“generate/send packets”)
- From Packet Generator → Player Connection (“ChunkData, Title, Chat…”)
- From VirtualServer Manager → Velocity Proxy (“forwardToRealServer()”)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Proxy Layer
    subgraph "Proxy Layer"
        VP["Velocity Proxy"]:::external
        PC["Player Connection"]:::external
    end

    VP -->|"Player Connection"| PC

    %% Plugin Layer
    subgraph "LimboAPI Plugin Layer"
        %% API Module
        subgraph "API Module"
            LF["LimboFactory"]:::api
            LSH["LimboSessionHandler"]:::api
            VW["VirtualWorld"]:::api
            VC["VirtualChunk"]:::api
        end

        %% Implementation
        subgraph "Plugin Implementation"
            EP["LimboAPI (Plugin Entry)"]:::plugin

            %% Injection Handlers
            subgraph "Injection Handlers"
                IL["LoginListener"]:::plugin
                DL["DisconnectListener"]:::plugin
                PH["PacketHooks"]:::plugin
                TL["RewritingVelocityTabList"]:::plugin
            end

            %% Virtual Server Manager
            subgraph "VirtualServer Manager"
                LI["LimboImpl"]:::plugin
                LS["LimboSessionHandlerImpl"]:::plugin
            end

            %% World Loader
            subgraph "World Loader"
                WF["WorldFileTypeRegistry"]:::plugin
                MSF["MCEditSchematicFile"]:::plugin
                SNF["StructureNbtFile"]:::plugin
            end

            %% Packet Generator
            subgraph "Packet Generator"
                PF["PacketFactoryImpl"]:::plugin
            end

            MR["Mapping Resources"]:::resource
        end
    end

    %% External Libraries
    subgraph "External Layer"
        MC["mcprotocollib"]:::external
        VV["ViaVersion/ProtocolSupport"]:::external
    end

    %% Connections
    VP --> EP
    EP --> IL
    EP --> DL
    EP --> PH
    EP --> TL

    PC -->|"login event"| IL
    PC -->|"disconnect event"| DL
    PC -->|"packet flow"| PH

    IL -->|"calls createSession()"| LF
    DL -->|"calls createSession()"| LF
    PH -->|"calls createSession()"| LF
    TL -->|"calls createSession()"| LF

    LF -->|"returns LimboImpl"| LI
    LF -->|"returns HandlerImpl"| LS

    LI -->|"loadWorld()"| WF
    WF -->|"instantiates"| MSF
    WF -->|"instantiates"| SNF
    WF -->|"reads data from"| MR

    LI -->|"generate/send packets"| PF
    PF -->|"uses"| MC
    PF -->|"uses"| VV
    PF -->|"sends packets to"| PC

    LI -->|"forwardToRealServer()"| VP

    %% Click Events
    click LF "https://github.com/elytrium/limboapi/blob/master/api/src/main/java/net/elytrium/limboapi/api/LimboFactory.java"
    click LSH "https://github.com/elytrium/limboapi/blob/master/api/src/main/java/net/elytrium/limboapi/api/LimboSessionHandler.java"
    click VW "https://github.com/elytrium/limboapi/blob/master/api/src/main/java/net/elytrium/limboapi/api/chunk/VirtualWorld.java"
    click VC "https://github.com/elytrium/limboapi/blob/master/api/src/main/java/net/elytrium/limboapi/api/chunk/VirtualChunk.java"
    click EP "https://github.com/elytrium/limboapi/blob/master/plugin/src/main/java/net/elytrium/limboapi/LimboAPI.java"
    click IL "https://github.com/elytrium/limboapi/blob/master/plugin/src/main/java/net/elytrium/limboapi/injection/login/LoginListener.java"
    click DL "https://github.com/elytrium/limboapi/blob/master/plugin/src/main/java/net/elytrium/limboapi/injection/disconnect/DisconnectListener.java"
    click PH "https://github.com/elytrium/limboapi/tree/master/plugin/src/main/java/net/elytrium/limboapi/injection/packet/"
    click TL "https://github.com/elytrium/limboapi/blob/master/plugin/src/main/java/net/elytrium/limboapi/injection/tablist/RewritingVelocityTabList.java"
    click LI "https://github.com/elytrium/limboapi/blob/master/plugin/src/main/java/net/elytrium/limboapi/server/LimboImpl.java"
    click LS "https://github.com/elytrium/limboapi/blob/master/plugin/src/main/java/net/elytrium/limboapi/server/LimboSessionHandlerImpl.java"
    click WF "https://github.com/elytrium/limboapi/blob/master/plugin/src/main/java/net/elytrium/limboapi/file/WorldFileTypeRegistry.java"
    click MSF "https://github.com/elytrium/limboapi/blob/master/plugin/src/main/java/net/elytrium/limboapi/file/MCEditSchematicFile.java"
    click SNF "https://github.com/elytrium/limboapi/blob/master/plugin/src/main/java/net/elytrium/limboapi/file/StructureNbtFile.java"
    click PF "https://github.com/elytrium/limboapi/blob/master/plugin/src/main/java/net/elytrium/limboapi/protocol/packets/PacketFactoryImpl.java"
    click MR "https://github.com/elytrium/limboapi/tree/master/plugin/src/main/resources/mapping/"

    %% Styles
    classDef api fill:#ADD8E6,stroke:#000
    classDef plugin fill:#90EE90,stroke:#000
    classDef external fill:#FFA500,stroke:#000
    classDef resource fill:#D3D3D3,stroke:#000
```
