{"id":48666675,"url":"https://github.com/oxidized-mc/client-headless","last_synced_at":"2026-04-10T11:05:47.562Z","repository":{"id":347161515,"uuid":"1193081942","full_name":"oxidized-mc/client-headless","owner":"oxidized-mc","description":"A Rust framework for headless Minecraft Java Edition clients — bots, testing, automation, and protocol analysis","archived":false,"fork":false,"pushed_at":"2026-04-04T17:50:51.000Z","size":210,"stargazers_count":0,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-04T19:11:46.317Z","etag":null,"topics":["automation","bot-framework","headless-client","minecraft","minecraft-bot","minecraft-java","minecraft-protocol","protocol-analysis","rust"],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/oxidized-mc.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE-APACHE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-26T21:21:40.000Z","updated_at":"2026-04-04T17:50:56.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/oxidized-mc/client-headless","commit_stats":null,"previous_names":["dodoflix/headlesscraft","oxidized-mc/client-headless"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/oxidized-mc/client-headless","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oxidized-mc%2Fclient-headless","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oxidized-mc%2Fclient-headless/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oxidized-mc%2Fclient-headless/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oxidized-mc%2Fclient-headless/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/oxidized-mc","download_url":"https://codeload.github.com/oxidized-mc/client-headless/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oxidized-mc%2Fclient-headless/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31639526,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-10T07:40:12.752Z","status":"ssl_error","status_checked_at":"2026-04-10T07:40:11.664Z","response_time":98,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["automation","bot-framework","headless-client","minecraft","minecraft-bot","minecraft-java","minecraft-protocol","protocol-analysis","rust"],"created_at":"2026-04-10T11:05:47.487Z","updated_at":"2026-04-10T11:05:47.551Z","avatar_url":"https://github.com/oxidized-mc.png","language":"Rust","readme":"# oxidized-client-headless\n\n\u003e A Rust framework for building headless Minecraft Java Edition clients — bots, testing tools, and automation.\n\n[![CI](https://github.com/oxidized-mc/client-headless/actions/workflows/ci.yml/badge.svg)](https://github.com/oxidized-mc/client-headless/actions/workflows/ci.yml)\n[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)\n\n---\n\n## What is oxidized-client-headless?\n\noxidized-client-headless is a Rust library that emulates a Minecraft Java Edition client without rendering.\nIt connects to vanilla servers, handles the full protocol lifecycle (handshake → login → configuration → play),\nand exposes a high-level API for building:\n\n- **Bots** — automated players that can navigate, interact, chat, and follow complex behaviors\n- **Testing tools** — connect to your server and verify behavior programmatically\n- **Stress testers** — spawn hundreds of headless clients to load-test servers\n- **Protocol analyzers** — inspect and log every packet in both directions\n- **Proxy frameworks** — sit between a real client and server, intercepting traffic\n\n## Status\n\n**Pre-alpha** — project scaffolding and planning phase. No functional client yet.\n\n## Target Protocol\n\n- **Minecraft Java Edition 26.1** (protocol version `775`, world version `4786`)\n- **Reference:** Decompiled vanilla 26.1 JAR in `mc-server-ref/decompiled/` (gitignored)\n\n## Architecture\n\noxidized-client-headless is a single Rust crate. Low-level protocol primitives (codec, NBT,\ntypes, chat, crypto, compression, transport, auth) are provided by the shared\n[oxidized-mc](https://github.com/oxidized-mc) crate ecosystem. This crate focuses on\nclient-specific logic:\n\n- **client** — connection management, authentication, session handling\n- **world** — client-side world state (chunks, entities, biomes)\n- **bot** — high-level bot behavior API and event system\n\n## Quick Start\n\n\u003e Requires **Rust 1.85+** (pinned in `rust-toolchain.toml`).\n\n```bash\n# Clone\ngit clone https://github.com/oxidized-mc/client-headless.git\ncd client-headless\n\n# Build\ncargo build\n\n# Run tests\ncargo test\n\n# Check lints\ncargo clippy --all-targets -- -D warnings\n```\n\n### Use as a dependency\n\n```toml\n[dependencies]\noxidized-client-headless = \"0.1\"\n```\n\n```rust\nuse oxidized_client_headless::Client;\n\n#[tokio::main]\nasync fn main() -\u003e anyhow::Result\u003c()\u003e {\n    let client = Client::builder()\n        .address(\"localhost:25565\")\n        .username(\"Bot\")\n        .build()\n        .await?;\n\n    client.connect().await?;\n    // ... interact with the server\n    Ok(())\n}\n```\n\n## Goals\n\n| Goal | Description |\n|------|-------------|\n| **Protocol fidelity** | Wire-compatible with vanilla 26.1 servers — every packet, every field, every edge case |\n| **Ergonomic API** | High-level builder patterns for common tasks, low-level access when needed |\n| **Performance** | Async-first with Tokio, zero-copy where possible, support hundreds of concurrent clients |\n| **Testability** | First-class support for server testing — assert on game state, packet sequences, timing |\n| **Extensibility** | Plugin/event system for custom bot behaviors without forking |\n\n## Documentation\n\n- [Contributing](CONTRIBUTING.md)\n\n## License\n\nLicensed under the [MIT License](LICENSE).\n\n## Contribution\n\nUnless you explicitly state otherwise, any contribution intentionally submitted\nfor inclusion in the work by you, as defined in the Apache-2.0 license, shall be\ndual licensed as above, without any additional terms or conditions.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Foxidized-mc%2Fclient-headless","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Foxidized-mc%2Fclient-headless","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Foxidized-mc%2Fclient-headless/lists"}