How elytrium/limboapi works
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()”)