flayerproxy/README.md

🎮 FlayerProxy

A seamless Minecraft Bot-to-Proxy handoff bridge. Keep your Minecraft character online 24/7, and instantly take control from a standard client whenever you join.

  _____ _                       ____                      
 |  ___| | __ _ _   _  ___ _ _|  _ \ _ __ _____  ___   _ 
 | |_  | |/ _` | | | |/ _ \ '__| |_) | '__/ _ \ \/ / | | |
 |  _| | | (_| | |_| |  __/ |  |  __/| | | (_) >  <| |_| |
 |_|   |_|\__,_|\__, |\___|_|  |_|   |_|  \___/_/\_\\__, |
                |___/                                |___/ 

FlayerProxy bridges Mineflayer (a powerful Minecraft bot framework) and minecraft-protocol. It connects to a target Minecraft server, maintains a persistent online session, runs anti-AFK tasks, caches the surrounding world state, and lets you connect using a standard Minecraft client to take control of your character on the fly—without disconnecting from the server.

---

🚀 How It Works

FlayerProxy operates as a stateful proxy between your client and the target server. The lifecycle revolves around four major states:

stateDiagram-v2
    [*] --> INIT : Start Application
    INIT --> BOT_MODE : Connects to Server
    BOT_MODE --> HANDOFF : Proxy Client Connects
    HANDOFF --> CLIENT_MODE : State Replayed & Teleport Confirmed
    CLIENT_MODE --> BOT_MODE : Proxy Client Disconnects
    CLIENT_MODE --> INIT : Server Disconnects
    BOT_MODE --> INIT : Server Disconnects

1. INIT

• The bot initiates a connection to the upstream target server.
• The local proxy server begins listening for incoming client connections.

2. BOT_MODE

• No human player is connected.
• The bot holds the session, runs anti-AFK behavior (if configured), and handles physics.
• State Caching: The proxy continuously captures and updates a local cache of the world (chunks, entities, inventory, scoreboards, player position, etc.).

3. HANDOFF

• A standard Minecraft client connects to the proxy.
• Bot AI/physics are immediately disabled to prevent conflict.
• State Replay: The StateReplayer sends the cached world state sequentially to the client, reproducing the exact state of the environment without reloading.
• The client is synchronized to the bot's coordinates and confirms the teleport.

4. CLIENT_MODE

• The handoff is completed.
• A bidirectional ClientBridge is established to pipe raw network packets directly between your client and the target server.
• You play normally with low latency, while the cache continues to monitor updates in the background.
• When you disconnect, the proxy reverts to BOT_MODE, re-enabling the bot's anti-AFK AI.

---

🛠️ State Cache System

To make the client transition seamless and prevent loading/rendering glitches, FlayerProxy caches a comprehensive set of packet states:

Cache Component	Monitored Packets & Data	Eviction / Strategy
Chunks	map_chunk, update_light, unload_chunk, block_change, multi_block_change	LRU cache (default max 1024 chunks); block and light updates merged into cached map_chunk columns.
Entities	spawn_entity, entity_metadata, entity_equipment, entity_effect, set_passengers, entity_destroy, relative movements / teleports	Tracks positions, gear, mounts, and status effects.
Player State	login, position, update_health, experience, abilities, difficulty, respawn	Caches player attributes to sync client UI and positioning.
Inventory	window_items, set_slot, held_item_slot, set_player_inventory, set_cursor_item	Captures open container, inventory contents, and hand slots.
Misc / Environment	update_time, game_state_change, initialize_world_border, player_info (tab list), scoreboard_*, teams, boss_bar, tags	Keeps track of scoreboard rankings, player lists, time of day, world borders, and registry tags.

---

⚙️ Configuration

Copy the template structure and configure your parameters in config.json in the root directory:

{
  "server": {
    "host": "192.168.178.58",
    "port": 25565,
    "version": "1.21.10"
  },
  "auth": {
    "username": "FlayerBot",
    "auth": "microsoft"
  },
  "proxy": {
    "host": "0.0.0.0",
    "port": 25566,
    "onlineMode": false,
    "maxClients": 1
  },
  "bot": {
    "antiAfk": true,
    "antiAfkInterval": 30000,
    "viewDistance": 10
  },
  "cache": {
    "maxChunks": 1024,
    "trackEntities": true
  }
}

Config Options Reference

• server: Upstream Minecraft server details. version must match the server version.
• auth: Credentials. auth can be set to "microsoft" or "offline".
• proxy: Local proxy server settings.
  • onlineMode: If true, proxy checks Mojang authentication for incoming clients (requires client to match bot username or have appropriate credentials depending on target server configuration). Set to false for simple local offline-mode connections.
• bot: Bot behavior settings.
  • antiAfk: When no client is connected, randomly turns, sneaks, and swings so the bot stays active.
  • antiAfkMinInterval / antiAfkMaxInterval: Milliseconds between idle actions (default 1500–6000).
• spectator: Watch-only proxy (default port 25568). Multiple clients can connect; they receive spectator gamemode and a live view of the bot (bot mode / idle) or the controlling player (client mode). No movement or interaction is forwarded upstream.
  • enabled, port, onlineMode, maxClients (default 20).
• cache: Memory usage controls for caching the world.

---

📁 Project Structure

├── config.json             # Configuration settings
├── codebase_map.md         # Comprehensive function & class map
├── package.json            # Dependencies and scripts
└── src
    ├── index.js            # Entry point; boots session and handles process signals
    ├── config.js           # Configuration loader & validator
    ├── constants/          # Constants, e.g. packets requiring raw forwarding
    ├── proxy/
    │   ├── ProxyServer.js  # Wrapper for minecraft-protocol server
    │   └── ClientBridge.js # Pipes client-to-server & server-to-client packets
    ├── session/
    │   ├── SessionManager.js # Orchestrates states (BOT_MODE <-> CLIENT_MODE)
    │   ├── ServerConnection.js # Wraps Mineflayer bot and captures raw packets
    │   ├── ChunkAckManager.js # Intercepts and controls chunk acks
    │   ├── MovementRelay.js # Syncs client and bot coordinates
    │   └── handoffFlow.js  # Step-by-step handoff sequence runner
    ├── state/
    │   ├── WorldStateCache.js # Main caching coordinator
    │   ├── ChunkCache.js   # Map chunks, lights, and block edits (LRU)
    │   ├── EntityCache.js  # Track mobs, players, metadata, and positions
    │   ├── InventoryCache.js # Items, equipment slots, and cursor items
    │   ├── PlayerStateCache.js # XP, health, spawning details, and coords
    │   ├── JoinSyncCache.js # Recipes and advancements sent at login
    │   ├── MiscCache.js    # Scoreboards, world borders, time, and headers
    │   ├── ScoreboardCache.js # Tracks scoreboard entries and teams
    │   └── WorldBorderCache.js # Tracks world border constraints
    ├── replay/
    │   ├── StateReplayer.js # Replays cached packets to clients on handoff
    │   ├── replayChunks.js # Streams chunk and light packets
    │   └── replayHelpers.js # Replay yielding and wait conditions
    ├── sniffer/            # Packet sniffer & MITM interception tool
    │   ├── index.js        # Sniffer launcher and entry point
    │   ├── MitmProxy.js    # Decrypts/parses both legs (Mitm mode)
    │   ├── TransparentProxy.js # Transparent TCP proxy (Transparent mode)
    │   ├── StreamTap.js    # Unmodified stream frame parser
    │   ├── PacketLog.js    # Structured JSONL log writer
    │   └── mitm*.js        # Login, encryption, gate, relay and session logic
    └── utils/
        ├── logger.js       # Structured logging utility
        ├── angles.js       # Minecraft rotation & angle utility functions
        ├── chatRelay.js    # Chat re-signing for the bot connection
        ├── clientDisconnect.js # Safe error-handling disconnect wrappers
        ├── handoffSync.js  # Temporary play-phase socket relay helper
        └── positionSync.js # Coordinates and confirms client positioning

---

🚦 Getting Started

Prerequisites

• Node.js (v18 or higher recommended)
• A valid Minecraft account (if connecting to online-mode servers)

Installation

1. Clone the repository:

   git clone <repository-url>
   cd flayerproxy
   

2. Install dependencies:

   npm install
   

Running the Proxy

1. Create and customize your config.json in the root.
2. Start the proxy server:

   npm start
   

3. Open Minecraft, click Direct Connection (or Add Server), and connect to localhost:25566 (or whichever port you configured).

---

🧪 Technical Notes & Packet Handling

• Config-Phase Capture: During the server's handshake/configuration phase, FlayerProxy intercept registry_data and metadata packets. These are later passed verbatim to your joining client so that custom blocks, biomes, and registry configurations match the target server exactly.
• Keep-Alive Filtering: The Mineflayer bot automatically responds to upstream keep_alive checks. The proxy blocks keep_alive packets from being sent to/from the local client to prevent sequence mismatches that would trigger an immediate kick.
• Position Synchronization: During the handoff, the client must be instantly moved to the exact coords of the bot. The proxy writes a position packet to the client, pauses packet forwarding, waits for the client to return a teleport_confirm packet, and then opens the bidirectional stream. This ensures you spawn safely in the world without falling or glitching.

---

📜 License

This project is licensed under the ISC License.