Py-Ritone

Py-Ritone is a zero-setup local bridge between a Fabric Minecraft client (with Baritone installed) and Python.

Monorepo Layout

• mod/: Fabric client mod (pyritone_bridge) exposing a local WebSocket v2 bridge.
• python/: PyPI-ready package (pyritone) with async client, compatibility aliases, and CLI.
• protocol/: Versioned bridge protocol docs and JSON schema.
• docs/: Developer setup and runbook.

Quick Start

1. Install Minecraft Fabric client for 1.21.8.
2. Install Baritone v1.15.0 mod.
3. Build or install pyritone_bridge mod jar into your client mods folder.
4. Install Python package:

pip install pyritone

5. Start Minecraft client. Py-Ritone opens the local bridge at ws://127.0.0.1:27841/ws automatically.
6. Use the package:

import asyncio
from pyritone import Client


async def main() -> None:
    async with Client() as client:
        print(await client.ping())
        print(await client.status_get())
        print(await client.execute("goto 100 70 100"))


asyncio.run(main())

Demos / Videos

Beginner-friendly demo scripts live in python/demos/.

• Demo index: python/demos/README.md
• Demo video links use plain Markdown links (no embeds): Demo Catalog
• Fast start from repo root:

python -m pip install -e ./python
cd python
python demos/01_connect_discovery.py

• Suggested recording set (explicit):
  • 01 connect/discovery: python demos/01_connect_discovery.py
  • 02 basic commands: python demos/02_basic_commands.py
  • 03 goto + completion: python demos/03_goto_completion.py 100 70 100
  • 04 live event feed: python demos/04_live_event_feed.py --x 0 --y 1000 --z 0 --max-events 30
  • 05 cancel flow: python demos/05_cancel_task.py --delay 1.5
  • 06 settings mode switch: python demos/06_settings_mode_switch.py --mode builder
  • 07 mini console: python demos/07_mini_console.py
  • 08 async workflow: python demos/08_async_workflow.py 0 1000 0 --cancel-after 6 --heartbeat-interval 1.5
  • 09 local-path build helper: python demos/09_build_file_local_path.py "house.schem" --coords 100 -60 100 --wait
  • 10 CLI entrypoints: python demos/10_cli_entrypoints.py

Release Prep

• Async-only release checklist: docs/release-checklist.md
• Parity/fallback debt snapshot: python/docs/release-parity-fallback-report.md
• Release notes draft: docs/release-notes-v0.2.0.md
• Changelog: CHANGELOG.md

One-Click Dev Client

• Double-click run_dev_client.bat at repo root, or run it in terminal:

.\run_dev_client.bat

• In VS Code, use the task button:
  • Terminal -> Run Build Task -> Py-Ritone: Build and Run Dev Client

This compiles and starts the Fabric dev client, and auto-downloads Baritone for dev runtime.

Security Model (v1)

• Bridge binds to loopback only.
• Auth token is generated by the mod and written to:
  • <minecraft>/config/pyritone_bridge/bridge-info.json
• Python auto-discovers this file by default.

License

MIT