206 lines
10 KiB
Markdown
206 lines
10 KiB
Markdown
# 🎮 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).
|