# 🎮 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.

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

**FlayerProxy** bridges [Mineflayer](https://github.com/PrismarineJS/mineflayer) (a powerful Minecraft bot framework) and [minecraft-protocol](https://github.com/PrismarineJS/node-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:

```mermaid
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:

```json
{
  "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

```text
├── 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](https://nodejs.org/) (v18 or higher recommended)
* A valid Minecraft account (if connecting to online-mode servers)

### Installation
1. Clone the repository:
   ```bash
   git clone <repository-url>
   cd flayerproxy
   ```
2. Install dependencies:
   ```bash
   npm install
   ```

### Running the Proxy
1. Create and customize your `config.json` in the root.
2. Start the proxy server:
   ```bash
   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](LICENSE).