Genesis
This commit is contained in:
sebseb7
202
README.md
Normal file
202
README.md
Normal file
@@ -0,0 +1,202 @@
|
||||
# 🎮 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) with active block change overlays. |
|
||||
| **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`: Keeps the bot moving or performing minor actions so it doesn't get kicked for inactivity.
|
||||
* **`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).
|
||||
Reference in New Issue
Block a user