Loading client…

0

Headless Minecraft client framework

Next tick0protocol 777 · mc 26.3

Vanilla-exact protocol. Tick-exact physics. A human input layer.

On
wire

Framing, compression, encryption, packets and Microsoft login, written from scratch.

On
tick

Movement, collision and timing ported from vanilla, then verified against test vectors.

What it does

rapidbot reimplements the Java client from the network up. Mojang’s code is used only as a reference, and everything here is written from scratch.

Wire protocol

A full connection stack, byte-exact with the vanilla client.

  • VarInt, strings and UUID wire types
  • Framing, compression and encryption
  • Packet IDs and packets
  • Network NBT with Java’s modified UTF-8

Vanilla physics

Player movement ported from the vanilla client, not approximated.

  • Input, travel and ground state
  • Vanilla-exact block collision
  • Step-up handling
  • Block data extracted from the game jar

Human input layer

Actions go through modeled input instead of teleporting state.

  • Mouse strokes and response delays
  • Fatigue modeling
  • Keystroke timing for chat
  • A recorder that fits a mouse profile to your own play

Authentication

Sign in with a real account or join offline-mode servers.

  • Microsoft device-code login
  • Xbox and XSTS, Minecraft token and profile
  • Chat keys and session join
  • Offline accounts by name

Client runtime

A vanilla-style main thread runs the connection.

  • Address resolution and login
  • Frames, ticks and a packet queue
  • Configuration and play phases
  • Player and entity state

Gameplay helpers

Higher-level tools on top of the same input model.

  • Route finding around walls, steps, drops and lava
  • Digging at vanilla speed for the held tool
  • Entity targeting and a combat helper
  • Inventory, hotbar and container handling

Quick start

Depend on the rapidbot crate by path or git, implement Controller, and spawn a bot.

  1. Depend on rapidbot. It re-exports the public API and a prelude.
  2. Implement Controller. tick runs once per client tick. Say where to look and what to hold.
  3. Spawn the bot. Give Bot::spawn a ClientConfig with a server address and an Account.
  4. Handle events. Await bot.next_event() for Loaded, Chat and others.
  5. Run with --release. Tick timing is part of what servers see, and debug builds are too slow to keep it regular.

A complete example lives at crates/rapidbot/examples/embed.rs. Several bots can run in one process, and each has its own main thread.

use rapidbot::prelude::*;

struct MyLogic { walker: Walker }

impl Controller for MyLogic {
    fn tick(&mut self, ctx: &mut TickContext<'_>) {
        // Called once per client tick.
        if self.walker.arrived() {
            self.walker.go_to(Vec3::new(100.0, 64.0, -20.0));
        }
        self.walker.tick(ctx);
    }
}

let config = ClientConfig::new(
    "play.example.net",
    Account::Offline { name: "Steve".into() },
);
let mut bot = Bot::spawn(config, MyLogic { walker: Walker::new(1) });
while let Some(event) = bot.next_event().await {
    match event {
        BotEvent::Loaded => bot.chat("/home"),
        BotEvent::Chat { name, text, .. } => println!("<{name:?}> {text}"),
        _ => {}
    }
}

Controller API

What a controller can read and do from inside tick. Each action goes through the input models and vanilla physics.

ItemWhat it does
Movement
WalkerPlans a route around walls, up steps, down drops and clear of lava, then follows it using modeled input. Use go_to, arrived and tick.
Chat and inventory
ctx.chat(..)Types a line into chat from inside a controller.
ctx.inventoryWhat the player carries and wears. A jump in mid-air opens a worn elytra.
ctx.select_slot(n)Presses a hotbar key.
ctx.close_container()Closes a screen the server opened.
Interaction
ctx.crosshairWhat the player is looking at.
ctx.hold_attack(true)Holds the left mouse button. This digs the looked-at block at exactly the vanilla speed for the held tool.
interact::aim_pointFinds where to look to hit a given block.
Entities and combat
ctx.entitiesEvery entity, where the client shows it.
ctx.targetThe entity under the crosshair.
ctx.click_attack()Clicks on the targeted entity.
combat::FighterAim, approach and attack-timing behaviour. See the fight example.
Connection
ResourcePackPolicyServer resource packs are declined by default. Set config.resource_packs = ResourcePackPolicy::Accept to answer “Yes”. The pack is then downloaded with the same HTTP request the Java client sends, because servers can check their pack host’s log.

Crates

The workspace has 11 crates. Most projects only depend on rapidbot, which re-exports the public API.

CratePurpose
Entry point
rapidbotThe crate to depend on. Re-exports the public API and a prelude.
Wire and protocol
rapidbot-bufWire types (VarInt, strings, UUIDs) and the Encode / Decode traits.
rapidbot-buf-derive#[derive(Encode, Decode)].
rapidbot-nbtNetwork NBT with Java’s modified UTF-8.
rapidbot-protocolFraming, compression, encryption, packet IDs, packets and the async connection.
World and physics
rapidbot-worldBlock data extracted from the jar, chunk storage and vanilla-exact block collision.
rapidbot-physicsPlayer movement ported from vanilla: input, travel, collision, step-up and ground state.
Input and identity
rapidbot-humanInput models: mouse strokes, response delays and fatigue.
rapidbot-recorderRecords your own mouse and game-key input while you play, and fits a mouse profile to it.
rapidbot-authMicrosoft login (device code), Xbox/XSTS, Minecraft token and profile, chat keys and session join.
Runtime
rapidbot-clientAddress resolution and login, then a vanilla-style main thread (frames, ticks, packet queue) running configuration and play. Provides the Controller trait, route finding, modeled input and player and entity state.

Run the examples

The repository ships runnable examples. Use --release for anything that joins a server.

ExampleWhat it does
pingPings a server with rapidbot-protocol.
cargo run -p rapidbot-protocol --example ping -- localhost 25565
joinJoins an offline-mode server and idles. Add --microsoft accounts/main.json to join with a Microsoft account.
cargo run --release -p rapidbot-client --example join -- localhost:25565 Steve
loginMicrosoft sign-in with a cached result. The accounts/ folder is gitignored.
cargo run -p rapidbot-auth --example login -- accounts/main.json
walkUses route finding to walk.
cargo run --release -p rapidbot-client --example walk -- localhost:25565 Walker
chatTypes the lines you give it into chat.
… --example chat -- localhost:25565 Walker "hello" "/msg Walker hi"
courseWalks +x through water and ladders, and glides when wearing an elytra.
… --example course -- localhost:25565 Walker 130
digDigs the listed blocks.
… --example dig -- localhost:25565 Walker 62 150 60
fightFights the nearest entity of a type.
… --example fight -- localhost:25565 Walker minecraft:husk

How it stays exact

Behaviour is ported from the vanilla client and checked against data generated from it.

Ported, not guessed

A tool fetches the vanilla jars, data reports and decompiled source into a gitignored vanilla/ folder. That code is a reference only: rapidbot writes its own implementation and never commits anything from vanilla/.

Generated data

  • gen_packet_ids.py regenerates the packet ID table
  • extract_blocks.py regenerates block data, attributes and Mth tables (needs javac)
  • extract_items.py regenerates item components and decoder test vectors
  • gen_clip_vectors.py regenerates ray cast test vectors

Tests

Unit tests, generated vectors and live tests. Run the workspace suite with:

cargo test --workspace

The testing and porting docs explain how each kind works.

Questions

Which Minecraft version does it support?

It targets Minecraft 26.3, protocol 777.

Does it open a game window?

No. It is a headless client. It runs a vanilla-style main thread with frames, ticks and a packet queue, but nothing is rendered.

How do accounts work?

Use Account::Offline with a name for offline-mode servers. For online servers, rapidbot-auth signs in with Microsoft using the device-code flow and handles the Xbox and Minecraft tokens, chat keys and session join. The login example caches the result in a file.

Can I run more than one bot?

Yes. Several bots can run in one process, and each has its own main thread.

Why build with --release?

Tick timing is part of what servers see. Debug builds are too slow to keep it regular.

What happens with server resource packs?

They are declined by default. If you set the policy to accept, the pack is really downloaded with the same HTTP request the Java client sends.

Where can I run bots?

Only on servers where you are allowed to. Read the Code of Conduct in the repository before you start.