How elytrium/shipmc works
Project Type and Purpose
• ShipMC is a C++-based Minecraft protocol library combined with a proxy server (and “limbo” server) tool.
• It provides raw network abstractions (compression, framing), a full protocol parser/serializer (packets, data types, NBT, entities), and an executable proxy that sits between a Minecraft client and a real server.
File Structure Analysis
• Top level
• CMakeLists.txt, .gitignore, .clang-format → build and formatting
• .gitmodules → external submodule (lib/ShipNet)
• README.md, LICENSE
• lib/ShipNet
• A submodule providing foundational networking (socket wrappers, async I/O)
• src/Launcher.cpp
• Entry point for the proxy/limbo server
• src/main/proxy
• Proxy.cpp/.hpp → coordinates client⇄server connections
• client/Client.cpp/.hpp → represents the inbound Minecraft client connection
• handlers/… → per-packet handler classes (Connect, Status, Proxy)
• src/network/pipe
• CompressionPipe, MinecraftFramedBytePacketPipe → I/O pipeline layers: decompress/compress, frame split, raw packet I/O
• src/protocol
• MinecraftProtocol → high-level encode/decode orchestration
• ProtocolUtils → helpers for reading/writing primitives
• data/** → definitions of all in-game data structures (entities, items, world, NBT, particle, profile)
• handler/server → handshake/auth handlers for server-side protocol
• packet/** → all packet definitions for handshake, login, play, status, prepared
• registry → mapping between packet IDs and types
• src/utils
• ShipUtils, MinecraftOrdinalRegistry → miscellanous utilities and registries
Key Components
• Executable Layer
• Launcher (CLI application)
• Proxy module (accepts client sockets, spawns Client and Server sessions)
• Networking Layer (lib/ShipNet + src/network/pipe)
• TCP sockets
• CompressionPipe
• MinecraftFramedBytePacketPipe
• Raw byte ↔ Packet buffer
• Protocol Layer (src/protocol)
• PacketRegistry → determines packet type by ID
• Packet serializers/deserializers
• Data classes (Entity, ItemStack, NBT, etc.)
• Packet handlers (StatusPing, Handshake, LoginStart, Game packets)
• External Services
• Upstream Minecraft server (the real target)
• Downstream Minecraft client
Relationships and Data Flow
• Client <--TCP/connects to Launcher/Proxy Listener
• Proxy Listener hands off to a ClientSession object
• ClientSession I/O pipeline:
Socket → CompressionPipe → FramingPipe → Packet buffer → Protocol layer
• Protocol layer invokes appropriate PacketHandler
• e.g. HandshakePacketHandler → authenticates or redirects
• StatusPacketHandler → responds to pings
• ProxyPacketHandler → tunnels play-stage packets
• After decode and optional modification, packets are forwarded through the same pipeline back to client or upstream server.
Architectural Patterns and Principles
• Layered I/O pipeline (Decorator pattern): allows chaining compression, framing, byte-packet conversion
• Registry/Factory for packet IDs → PacketRegistry decouples ID lookup from class instantiation
• Handler pattern: each packet type has a handler class, making protocol extension modular
• Clear separation between networking, protocol parsing/serialization, and application logic
Final Advice
• Be exhaustive: include all major sub-systems (lib/ShipNet, network pipes, protocol handlers, data models).
• Both control flow (which component calls which handler) and data flow (how bytes travel).