Files

sebseb7 db2edb66ff Genesis

2026-05-20 18:20:59 +02:00

33 KiB

Raw Blame History

🗺️ FlayerProxy Codebase Map

This document provides a comprehensive mapping of all the classes, functions, and files in the src/ directory of FlayerProxy, along with Mermaid diagrams showing how the components interact during different modes of operation.

📑 Table of Contents

Architecture & Interaction Diagrams
Detailed File Mapping
- Root Scripts & Configuration — src/index.js, src/config.js
- session — Session State Machine — SessionManager, ServerConnection, ChunkAckManager, MovementRelay, handoffFlow
- proxy — Client Connection Proxy — ProxyServer, ClientBridge
- state — World State Caching — WorldStateCache, ChunkCache, EntityCache, PlayerStateCache, InventoryCache, MiscCache, JoinSyncCache, WorldBorderCache, ScoreboardCache
- replay — Client Handoff Replay — StateReplayer, replayChunks, replayHelpers
- utils — Helper Utilities — angles, chatRelay, clientDisconnect, handoffSync, logger, positionSync
- sniffer — MITM Packet Sniffer — MitmProxy, TransparentProxy, StreamTap, PacketLog, and relay modules

🏗️ Architecture & Interaction Diagrams

1. High-Level Core System Diagram

This diagram shows how the core components of FlayerProxy (SessionManager, ProxyServer, ServerConnection, WorldStateCache, StateReplayer, and ClientBridge) cooperate to manage the proxy's dual-mode lifecycle.

graph TD
    classDef main fill:#d4e1f5,stroke:#1a5f7a,stroke-width:2px;
    classDef helper fill:#f5f0d4,stroke:#7a6b1a,stroke-width:1px;
    classDef external fill:#e1d5e7,stroke:#9673a6,stroke-width:1px;

    Client["Minecraft Client (Port 25566)"]:::external
    Server["Target Minecraft Server"]:::external

    subgraph FlayerProxy ["FlayerProxy Core"]
        SM["[SessionManager]"]:::main
        SC["[ServerConnection]"]:::main
        PS["[ProxyServer]"]:::main
        WSC["[WorldStateCache]"]:::main
        SR["[StateReplayer]"]:::main
        CB["[ClientBridge]"]:::main
    end

    SM -->|Orchestrates| SC
    SM -->|Orchestrates| PS
    SM -->|Orchestrates| WSC
    SM -->|Orchestrates| SR
    SM -->|Coordinates Handoff| CB

    SC -->|Holds session with| Bot["Mineflayer Bot"]:::external
    Bot -->|Connects to| Server
    SC -->|Captures play packets to| WSC
    PS -->|Listens for incoming| Client
    SR -->|Replays cache from WSC to| Client
    CB -->|Pipes C2S / S2C play packets| Client
    CB -->|Pipes C2S / S2C play packets| SC

2. Client Handoff Flow Diagram

This sequence diagram shows the step-by-step handoff process when a standard Minecraft client connects to the proxy, disabling the bot's AI, replaying the cached state, and establishing the packet-forwarding bridge.

sequenceDiagram
    autonumber
    actor Player as Minecraft Client
    participant PS as ProxyServer
    participant SM as SessionManager
    participant SC as ServerConnection
    participant WSC as WorldStateCache
    participant SR as StateReplayer
    participant Server as Upstream Server

    Note over SM,SC: State: BOT_MODE (Bot AI holds session)
    Player->>PS: Connect to Proxy (Port 25566)
    PS->>SM: _onClientConnect(client)
    Note over SM: State -> HANDOFF
    SM->>SC: setBotControl(false) [Disable Bot physics/AI]
    SM->>SM: _primeChunksNearBot() [Confirm position & await chunks]
    SM->>SR: replay(client)
    SR->>Player: Send 'login' packet (join_game)
    SR->>Player: Send difficulty, abilities, permission level
    SR->>Player: Send early misc packets (tags, commands, server_data, time)
    SR->>Player: Send recipe & advancement sync packets
    SR->>Player: Send initial 'position' teleport packet
    Player-->>SR: Send 'teleport_confirm' packet
    SR->>Player: Send tab list (player_info)
    SR->>Player: Send level info (world border, spawn, time)
    SR->>Player: Send chunks (chunk_batch_start, map_chunks, light, block_changes, chunk_batch_finished)
    SR->>Player: Send spawned entities (metadata, equipment, effects, passengers)
    SR->>Player: Send experience, health, and status effects
    SR->>Player: Send inventory snapshot (window_items, set_slot, held_item_slot)
    Note over SR: State replay complete
    SM->>SC: syncProxyClientPosition(client) [Final snap]
    SC->>Player: Send updated 'position' + 'update_view_position'
    Player-->>SC: Send 'teleport_confirm'
    SM->>SC: confirmServerPosition() [Confirm to Server]
    SC->>Server: Send serverbound 'position_look'
    SM->>Server: Send 'player_loaded' (hasClientLoaded)
    Note over SM: State -> CLIENT_MODE
    SM->>CB: Start ClientBridge(client, serverConn, worldState)
    Note over CB: Bidirectional Packet Piping Active

3. MITM Sniffer Architecture Diagram

The Packet Sniffer has two modes of operation:

MitmProxy: Decrypts both the client leg and the server leg using custom negotiated encryption keys to print and inspect packet structures in real time.
TransparentProxy: Pipes TCP streams directly without decryption, using a non-disruptive StreamTap to record unencrypted packets (like status handshakes or offline logins).

graph LR
    classDef sniffer fill:#d4f5d4,stroke:#1a7a1a,stroke-width:2px;
    classDef external fill:#e1d5e7,stroke:#9673a6,stroke-width:1px;

    Client["Minecraft Client (Port 25567)"]:::external
    Server["Target Minecraft Server"]:::external

    subgraph MitmProxyApp ["MitmProxy (Packet Sniffer)"]
        MProxy["MitmProxy (mc.createServer)"]:::sniffer
        PacketLog["PacketLog (JSONL log file)"]:::sniffer
        StreamTap["StreamTap (C2S & S2C frame parsing)"]:::sniffer
    end

    Client -->|connects| MProxy
    MProxy -->|initiates upstream client| UpstreamClient["mc.createClient"]:::sniffer
    UpstreamClient -->|connects| Server

    MProxy -->|logs packets| PacketLog
    MProxy -->|taps packets for state tracking| StreamTap

🗂️ Detailed File Mapping

1. Root Scripts & Configuration

📄 src/index.js

The main entry point for the application. Loads system config and handles errors, starts the core SessionManager, hooks process event signals (SIGINT, SIGTERM) for a graceful shutdown, and captures uncaughtException / unhandledRejection warnings.

Function	Description
`shutdown(signal)`	Gracefully stops the proxy and exits the node process.

📄 src/config.js

Handles configuration loading, validation, and parsing.

Function	Description
`loadConfig()`	Synchronously reads `config.json`, validates host, port, version, and auth configuration, applies default options, and returns the configuration object.

2. session — Session State Machine

🧩 SessionManager `class`

Orchestrates the dual-mode proxy state machine: INIT ↔ BOT_MODE ↔ HANDOFF ↔ CLIENT_MODE.

Method	Description
`constructor(config)`	Initializes state machine with configuration.
`start()`	Establishes connections to the upstream Minecraft server and starts the proxy server.
`_scheduleReconnect(delaySec)`	Schedules a timed reconnect sequence if the connection is lost.
`_setupServerEvents()`	Hooks upstream server events (`connected`, `disconnected`, `kicked`, `error`, `death`, `respawn`).
`_primeChunksNearBot()`	Triggers server movement packets to verify that the chunk cache is loaded near the bot before handing off.
`_refreshClientAfterBotRespawn()`	Re-aligns position and client view in case the bot respawns while a client is connected.
`_onClientConnect(client)`	Initiates the handoff sequence to transition from `BOT_MODE` to `CLIENT_MODE`.
`_cleanupClient()`	Stops the packet bridge and cleans up client-related event listeners.
`_transitionTo(newState)`	Transitions the machine state and logs status summaries.
`stop()`	Gracefully halts all services.

🧩 ServerConnection `class` extends `EventEmitter`

Manages the persistent Mineflayer bot connection to the target server.

Method	Description
`constructor(config, worldState)`	Initializes bot connection manager with config and world state reference.
`connect()`	Spawns the bot connection via Mineflayer.
`_setupConfigCapture()`	Caches configuration-phase registry data and tags.
`_setupPacketCapture()`	Hooks play packets and routes them directly to the state cache.
`_setupBotEvents()`	Listens for bot lifecycle events (`spawn`, `end`, `kicked`, `error`, `death`, and chat logging).
`setBotControl(enabled)`	Enables/disables physics and AI on the Mineflayer bot.
`setClientDrivesChunkBatchAck(clientDrives)`	Delegates chunk batch acknowledgement control between client and Mineflayer.
`flushChunkBatchAck()`	Unblocks the server chunk sender.
`refreshProxyClientPermissions(client)`	Sends player permissions status packets.
`syncProxyClientPosition(client)`	Snaps client position coordinates to the bot.
`confirmServerPosition()`	Confirms final block coordinates back to the server.
`setProxyClientChunkAck(enabled)`	Configures the ChunkAckManager.
`relayClientMovement(name, data)`	Translates Notchian/mineflayer coordinates and forwards client movements upstream.
`writeToServer(name, data)`	Writes raw packets directly upstream.
`disconnect()`	Safely disconnects the bot.

🧩 ChunkAckManager `class`

Intercepts Mineflayer's chunk batch acknowledgement listeners to prevent double-acknowledging packets during the client session.

Method	Description
`constructor()`	Initializes acknowledgement state.
`disable(rawClient)`	Disables auto-acknowledgement on the client stream.
`restore(rawClient)`	Restores Mineflayer auto-acknowledgement.
`flush(rawClient)`	Sends a manual chunk batch received acknowledgement packet.

📄 MovementRelay.js `functions`

Function	Description
`relayClientMovement(bot, rawClient, name, data)`	Applies client movement packets to the bot entity structure and writes updates upstream.
`syncProxyClientPosition(bot, worldState, client)`	Sends a teleport/position packet to the client and awaits a matching `teleport_confirm`.
`confirmServerPosition(bot, rawClient, connected)`	Writes a `position_look` verification packet to the upstream server.

📄 handoffFlow.js `functions`

Function	Description
`performHandoff({...})`	Coordinates the sequential handoff sequence: installs temporary upstream forwarding rules, primes nearby chunks, triggers the StateReplayer, aligns player coordinates/permissions, and spawns the ClientBridge.

3. proxy — Client Connection Proxy

🧩 ProxyServer `class`

Listens for connection attempts from standard Minecraft Java clients.

Method	Description
`constructor(config, onClientConnect, worldState)`	Initializes proxy server with config, client callback, and world state.
`start()`	Initializes the local minecraft-protocol server (`mc.createServer`), configures pre-login listeners to replay raw config packets, and registers joining players.
`updateRegistryCodec(codec)`	Replaces the registry codec object in the protocol handler options.
`stop()`	Halts client listening sockets.

🧩 ClientBridge `class`

Manages bidirectional packet pipelines when in CLIENT_MODE.

Method	Description
`constructor(client, serverConn, worldState)`	Initializes bridge with client, server connection, and world state references.
`_getViewDistance()`	Resolves the view distance from configuration or state records.
`_syncClientViewFromBlockCoords(blockX, blockZ)`	Computes chunk coordinates and updates client view center position.
`_syncClientViewFromBot()`	Aligns client view center with the bot entity position.
`_playerBlockCoordsForView()`	Returns coordinates representing the client player's view anchor.
`_ensureViewIncludesChunk(chunkX, chunkZ)`	Ensures the client's view includes target coordinates prior to sending map chunks.
`enableMovement()`	Authorizes client movement and syncs view center alignment.
`start()`	Sets up packet intercept listeners to route packets between legs, excluding blocked elements (e.g. `keep_alive`, `teleport_confirm`, `message_acknowledgement`) and re-signing client chat events.
`_shouldForwardPlayerInfo(data)`	Filters latency updates for unknown players.
`stop()`	Tears down the forwarding pipe.

4. state — World State Caching

🧩 WorldStateCache `class`

Master coordinator for world cache segments. Integrates and clears sub-caches on server switches.

Method	Description
`constructor(config)`	Initializes all sub-caches from configuration.
`handleConfigPacket(name, data)`	Caches parsed config-phase packets.
`buildRegistryCodec()`	Combines cached config packets to build a custom Minecraft registry codec.
`handleRawConfigPacket(name, buffer)`	Appends raw configuration buffers.
`getRawConfigPacketsForReplay()`	Filters and returns config-phase buffers for client replay.
`hasRawConfigPackets()`	Returns `true` if raw configuration buffers are cached.
`handleServerPacket(name, data, buffer)`	Evaluates incoming play packets and routes them to sub-caches.
`getSummary()`	Returns cache sizing info for log monitoring.
`clear()`	Wipes all cached structures.

🧩 ChunkCache `class`

Manages loaded map chunks, light maps, and block overlays using an LRU cache.

Method	Description
`constructor(maxChunks)`	Initializes chunk storage with LRU capacity limit.
`_key(x, z)`	Computes string key for map lookups.
`handleMapChunk(data, rawBuffer)`	Caches chunk data and marks it as active in the LRU tracking queue.
`handleUpdateLight(data, rawBuffer)`	Caches light updates.
`handleUnloadChunk(data)`	Evicts chunk records from cache.
`handleBlockChange(data)`	Appends single block changes as an overlay.
`handleMultiBlockChange(data)`	Appends multiblock edits as an overlay.
`_buildChunkEntry(chunkData)`	Assembles raw data, block edits, and light arrays.
`getChunksForReplay(centerChunkX, centerChunkZ, viewDistance)`	Returns cached chunks sorting closest-first.
`hasChunkAtBlock(x, z)`	Verifies if a chunk is loaded.
`clear()`	Wipes chunk maps.

🧩 EntityCache `class`

Tracks entities, positions, gear, and status effects.

Method	Category	Description
`constructor()`	—	Initializes entity tracking maps.
`handleSpawnEntity(data)`	Lifecycle	Instantiates a new tracked entity.
`handleEntityDestroy(data)`	Lifecycle	Removes entities.
`handleEntityMetadata(data)`	State	Updates metadata flags.
`handleEntityEquipment(data)`	State	Caches equipment items.
`handleEntityEffect(data)`	State	Adds status effects.
`handleRemoveEntityEffect(data)`	State	Removes status effects.
`handleSetPassengers(data)`	State	Caches passenger mounting structures.
`handleEntityPosition(data)`	Movement	Updates entity coordinates.
`handleSyncEntityPosition(data)`	Movement	Translates and maps sync positions.
`handleRelEntityMove(data)`	Movement	Applies relative move differentials.
`handleEntityMoveLook(data)`	Movement	Applies move and rotation differentials.
`handleEntityTeleport(data)`	Movement	Sets absolute coordinates.
`getAllEntities()`	Query	Returns sanitized entity arrays.
`removePlayerEntity(entityId)`	Query	Excludes own entity.
`clear()`	—	Clears entity maps.

🧩 PlayerStateCache `class`

Caches player-specific attributes.

Method	Description
`constructor()`	Initializes player state storage.
`handleLogin(data)`	Stores the initial login join_game packet.
`handlePosition(data)`	Stores coordinate positions.
`handleUpdateHealth(data)`	Stores health/hunger levels.
`handleExperience(data)`	Caches XP level values.
`handleAbilities(data)`	Caches flight capabilities and speeds.
`handleEntityStatus(data)`	Caches permissions status.
`handleSpawnPosition(data)`	Caches spawn points.
`handleDifficulty(data)`	Caches difficulty levels.
`handleGameStateChange(data)`	Captures gamemode updates.
`handleRespawn(data)`	Resets active position, health, and status values on player respawn.
`handleEntityEffect(data)`	Caches player status effects.
`handleRemoveEntityEffect(data)`	Evicts player status effects.
`getState()`	Returns all active player data.
`clear()`	Wipes player state.

🧩 InventoryCache `class`

Caches slot lists, inventories, and held items.

Method	Description
`constructor()`	Initializes inventory storage.
`handleWindowItems(data)`	Caches full item lists.
`handleSetSlot(data)`	Caches individual slot updates.
`handleHeldItemSlot(data)`	Stores current hotbar slot index.
`handleSetPlayerInventory(data)`	Stores inventory slots.
`handleSetCursorItem(data)`	Stores cursor items.
`getReplayPackets()`	Assembles sequence of inventory packet states.
`clear()`	Clears inventory states.

🧩 MiscCache `class`

Coordinates world data, tab lists, scoreboards, tags, and bossbars.

Method	Category	Description
`constructor()`	—	Initializes miscellaneous state storage.
`handleUpdateTime(data)`	World	Caches time variables.
`handleGameStateChange(data)`	World	Tracks weather triggers.
`handleSimulationDistance(data)`	World	Caches simulation distance settings.
`handleUpdateViewDistance(data)`	World	Caches view distance settings.
`handleUpdateViewPosition(data)`	World	Caches view position markers.
`handlePlayerInfo(data)`	Tab list	Tracks player additions.
`handlePlayerRemove(data)`	Tab list	Tracks player removals.
`handlePlayerListHeader(data)`	Tab list	Caches tab list headers.
`handleBossBar(data)`	UI	Caches bossbar indicators.
`handleTags(data)`	Registry	Caches server tag structures.
`handleServerData(data)`	Registry	Caches server description parameters.
`handleDeclareCommands(data)`	Registry	Caches commands registry.
`getReplayPackets()`	Replay	Compiles time, weather, border, teams, scoreboard, and bossbar packets.
`getPlayerInfoReplayPackets()`	Replay	Compiles player_info packets.
`getKnownPlayerUuids()`	Query	Identifies player UUIDs.
`clear()`	—	Clears variables.

🧩 JoinSyncCache `class`

Holds configuration elements that are typically sent only once at login, such as advancement criteria and recipe lists.

Method	Description
`constructor()`	Initializes join-sync storage.
`handlePacket(name, data)`	Identifies and caches advancements and recipe book packets.
`getReplayPackets()`	Returns advancement and recipe packets.
`clear()`	Clears variables.

🧩 WorldBorderCache `class`

Caches world border coordinates and warn margins.

Method	Description
`constructor()`	Initializes border state storage.
`handleInitWorldBorder(data)`	Caches initial world border packet.
`handleWorldBorderCenter(data)`	Caches center coordinates.
`handleWorldBorderSize(data)`	Caches border size.
`handleWorldBorderLerpSize(data)`	Caches border interpolation size.
`handleWorldBorderWarningDelay(data)`	Caches warning delay.
`handleWorldBorderWarningReach(data)`	Caches warning reach distance.
`getReplayPackets()`	Returns border initialization packets.
`clear()`	Resets variables.

🧩 ScoreboardCache `class`

Caches teams, scores, objectives, and scoreboard layouts.

Method	Description
`constructor()`	Initializes scoreboard storage.
`handleScoreboardObjective(data)`	Caches objective structures.
`handleScoreboardDisplayObjective(data)`	Caches display positions.
`handleScoreboardScore(data)`	Caches score updates.
`handleResetScore(data)`	Removes score records.
`handleTeams(data)`	Caches teams.
`getReplayPackets()`	Aggregates objectives, displays, scores, and teams.
`clear()`	Clears variables.

5. replay — Client Handoff Replay

🧩 StateReplayer `class`

Replays the cached world state to a connecting client.

Method	Description
`constructor(worldState, serverConn)`	Initializes replayer with world state and server connection references.
`replay(client)`	Coordinates sequential packet delivery (see replay sequence below).

replay() sequence:

Step	Packets sent
1	`login` packet (join_game)
2	Difficulty, abilities, and permission level
3	Pre-level metadata
4	Active hotbar selection
5	Recipe books and advancements
6	Teleport client player → await `teleport_confirm`
7	Tab list names
8	Time, spawn, world border, weather, view distance
9	Chunk loading start → replay chunks
10	Spawned entities (metadata, passengers, effects)
11	XP, health, and status effects
12	Full inventory (`window_items`)

📄 replayChunks.js `functions`

Function	Description
`replayChunks(write, writeRaw, chunks, center, totalCached)`	Loops through chunk arrays, sending raw chunk/light buffers and block overlay edits, and issues a final `chunk_batch_finished` packet.

📄 replayHelpers.js `functions`

Function	Description
`yieldEventLoop()`	Yields the event loop using `setImmediate`.
`replayPacketData(client, name, data)`	Overrides `enforcesSecureChat` to `false` for clients connecting without secure Mojang keys.
`getPlayerChunkCenter(playerState, misc, bot)`	Resolves chunk coordinates for position center checks.
`splitMiscReplayPackets(packets)`	Splits misc packets into early configurations, level coordinates, and weather variables.
`waitForClientTeleportConfirm(client)`	Awaits the client's `teleport_confirm` packet.

6. utils — Helper Utilities

📄 angles.js `functions`

Function	Description
`toByteAngle(value)`	Converts float degrees to i8 byte angles.
`sanitizeSpawnEntity(spawnData)`	Normalizes angle properties of entity spawn packets.

📄 chatRelay.js `functions`

Function	Description
`disableInboundChatValidation(client)`	Removes message acknowledgement checks to prevent chat validation kicks.
`extractChatText(name, data)`	Extracts text string parameter values from chat packets.
`relayClientChatAsUpstream(serverConn, name, data, log)`	Re-signs and forwards client messages using the bot's credentials.

📄 clientDisconnect.js `functions`

Function	Description
`disconnectReasonText(reason)`	Formats error reason arguments into plain text strings.
`wrapClientEnd(client)`	Wraps connection end methods to prevent formatting exceptions.
`safeEndClient(client, reason)`	Disconnects client sockets.

📄 handoffSync.js `functions`

Function	Description
`installHandoffUpstreamRelay(client, serverConn, log)`	Pipes chunk batch and player loaded packets directly to the server connection during handoff.
`removeHandoffUpstreamRelay(client, handler)`	Removes the handoff forwarding pipe.
`sendPermissionStatusToClient(client, permissionStatus, log)`	Sends the player's OP status packet to the client.

📄 logger.js `functions`

Function	Description
`createLogger(module)`	Returns console logging utilities formatted with module tags and colors.

📄 positionSync.js `functions`

Function	Description
`buildClientboundPositionPacket(bot, teleportId)`	Creates a player teleport packet from the bot's current coordinates.
`waitForClientTeleportConfirm(client, timeoutMs, log)`	Awaits the client's position confirmation.
`movementFlags(onGround, hasHorizontalCollision)`	Builds movement flags objects.
`buildServerboundPositionLook(bot)`	Creates a serverbound player position verification packet.
`distanceSq(a, b)`	Computes squared distance.
`chunkCoordsFromBlock(x, z)`	Resolves block coordinates to chunk coordinates.
`isChunkWithinViewDistance(centerChunkX, centerChunkZ, chunkX, chunkZ, viewDistance)`	Checks if a chunk lies within view distance limits.
`updateClientViewPosition(client, chunkX, chunkZ, lastView)`	Sends `update_view_position` to the client.
`ensureClientViewIncludesChunk(client, playerBlockX, playerBlockZ, chunkX, chunkZ, viewDistance, lastView)`	Snaps the client view center forward if a target chunk is about to load outside of its radius.

7. sniffer — MITM Packet Sniffer

📄 src/sniffer/index.js

Main launcher file for the sniffer tool. Parses arguments, applies default configurations for local hosting and logging directory, launches the MitmProxy engine, and sets up shutdown listeners.

🧩 MitmProxy `class`

Configures an interception proxy that decrypts packet bytes on both connections.

Method	Description
`constructor(config)`	Initializes the MITM proxy with configuration.
`start()`	Initializes the server.
`_onConnection(client)`	Sets up packet listeners, configures log files, and spawns the upstream server client.
`_startUpstream(session, cleanup)`	Begins the upstream connection flow.
`_tryBeginJavaCrypto(session, cleanup)`	Checks state before negotiating encryption.
`_doJavaCrypto(session, cleanup)`	Sets up local encryption filters.
`stop()`	Shuts down proxy services.

🧩 TransparentProxy `class`

Transparently forwards TCP bytes between the client and server while feeding a copy to the StreamTap to extract and log packets.

Method	Description
`constructor(config)`	Initializes transparent proxy with configuration.
`start()`	Binds the transparent port listener.
`_onClientConnect(clientSocket, targetHost, targetPort, sniffer)`	Pipes client and server sockets together and hooks up stream taps.
`stop()`	Shuts down socket handlers.

🧩 StreamTap `class`

Parses packet streams without modifying the underlying bytes.

Method	Description
`constructor(dir, version, packetLog, hooks)`	Initializes stream tap with direction, version, logger, and hooks.
`feed(chunk)`	Passes byte chunks to the framer/splitter.
`_syncState()`	Aligns state variables.
`_parser()`	Creates deserializers.
`_parseFrame(frame)`	Decompresses frame data.
`_onFrame(frame)`	Parses parameters, extracts compression settings and login handshakes, and writes entries to logs.
`_setState(next)`	Sets protocol states.
`_advanceState(name, data)`	Advances states.

🧩 PacketLog `class`

Formats and writes packet data into JSONL logs.

Method	Description
`constructor(opts)`	Initializes log output streams.
`writeMeta(record)`	Writes metadata entries.
`logUnparsed(dir, state, frame, message)`	Logs parser errors.
`logOpaque(dir, bytes, extra)`	Summarizes encrypted play traffic volume.
`logPacket(dir, meta, data, rawBuffer, extra)`	Records details for parsed packets.
`close(reason)`	Safely closes output write streams.

📄 mitmEncryption.js `functions`

Function	Description
`enableJavaEncryption(client, server, options)`	Negotiates the encryption phase on the client connection.

📄 mitmGate.js `functions`

Packet gating logic — controls buffering, ordering, and flushing of packets during connection state transitions.

Function	Category	Description
`canRelayC2S(session, meta)`	C2S	Checks if a client packet should be sent upstream.
`c2sForwardLabel(session, meta)`	C2S	Labels C2S traffic.
`classifyS2C(session, meta)`	S2C	Classifies S2C traffic.
`shouldBufferS2C(session, meta)`	S2C	Checks if S2C packets should be buffered.
`queueBufferedS2C(session, data, meta, buffer)`	S2C	Appends packets to buffer arrays.
`queueHeldS2C(session, data, meta, buffer)`	S2C	Queues packets while encryption is pending.
`isStalePlayS2C(meta)`	S2C	Filters out stale packets.
`flushQueue(session, queue)`	Flush	Flushes a packet queue to the client.
`flushPendingConfig(session)`	Flush	Flushes configuration packets.
`flushPendingPlay(session)`	Flush	Flushes play packets to client.
`sortPlayPending(pending)`	Ordering	Sorts play-phase packets to match join sequence requirements.
`partitionAfterCrypto(pendingS2C)`	Ordering	Partitions packets by state.
`hasPendingSuccess(session)`	State	Checks if a login success packet is waiting.
`onJavaLoginAcknowledged(session)`	State	Shifts connection states to `CONFIGURATION`.
`onJavaFinishConfiguration(session, packetLog)`	State	Shifts connection states to `PLAY`.

📄 mitmLogin.js `functions`

Function	Description
`applyLoginStartIdentity(client, packet, server, options)`	Verifies Mojang public key signatures.

📄 mitmRelay.js `functions`

Handles low-level packet relay, compression synchronization, and raw buffer forwarding decisions.

Function	Description
`shouldWriteRaw(meta, buffer)`	Decides if a packet should be written as a raw buffer.
`relayPacket(target, meta, data, buffer)`	Writes a packet parsed or raw.
`syncCompression(target, name, data)`	Synchronizes compression threshold.
`sortLoginPending(pending)`	Sorts login packets.
`relayLoginCompressToJava(client, meta, data, buffer)`	Writes compression setting.
`relayToJava(client, meta, data, buffer)`	Safely writes packets to Java.

📄 mitmSession.js `functions`

Function	Description
`createMitmSession(client, packetLog)`	Initializes a sniffer session.
`createSessionCleanup(session, packetLog, proxy)`	Returns a session cleanup function.

📄 mitmUpstream.js `functions`

Function	Description
`startStatusPipe(session, config, packetLog, proxy)`	Pipes status pings at the TCP socket layer.
`startUpstream(session, config, cleanup, callbacks)`	Starts the upstream server connection.

33 KiB Raw Blame History

🗺️ FlayerProxy Codebase Map

📑 Table of Contents

🏗️ Architecture & Interaction Diagrams

1. High-Level Core System Diagram

2. Client Handoff Flow Diagram

3. MITM Sniffer Architecture Diagram

🗂️ Detailed File Mapping

1. Root Scripts & Configuration

📄 src/index.js

📄 src/config.js

2. session — Session State Machine

🧩 SessionManager class

🧩 ServerConnection class extends EventEmitter

🧩 ChunkAckManager class

📄 MovementRelay.js functions

📄 handoffFlow.js functions

3. proxy — Client Connection Proxy

🧩 ProxyServer class

🧩 ClientBridge class

4. state — World State Caching

🧩 WorldStateCache class

🧩 ChunkCache class

🧩 EntityCache class

🧩 PlayerStateCache class

🧩 InventoryCache class

🧩 MiscCache class

🧩 JoinSyncCache class

🧩 WorldBorderCache class

🧩 ScoreboardCache class

5. replay — Client Handoff Replay

🧩 StateReplayer class

📄 replayChunks.js functions

📄 replayHelpers.js functions