Skip to content

feat: add a modern, drop-in mcpi client package (#61) - #63

Merged
sakebomb merged 1 commit into
masterfrom
feat/mcpi-client
Aug 20, 2026
Merged

feat: add a modern, drop-in mcpi client package (#61)#63
sakebomb merged 1 commit into
masterfrom
feat/mcpi-client

Conversation

@sakebomb

Copy link
Copy Markdown
Owner

First slice of epic #61 — a standalone, modern, pip-installable mcpi package so existing Minecraft-Pi curriculum runs unchanged against RaspberryJuice on current Minecraft (Paper 26.2 / Java 25).

Summary

  • New mcpi-client/ package reproducing the classic API: from mcpi.minecraft import Minecraft; mc = Minecraft.create(), mc.setBlock/getBlock/getBlocks/getHeight/setSign/postToChat/spawnEntity/..., mc.player.*, mc.entity.*, mc.events.*, plus mcpi.block / mcpi.entity constants, Vec3, Block, Entity.
  • Modernized: Python 3.9+, type hints, py.typed, tested. The classic *args + Vec3-flattening ergonomics are preserved (setBlock(x,y,z,id) and setBlock(pos,id) both work); classic numeric block ids still work via the server's legacy-id bridge.
  • Wire-correct: command names target the current server registry (world.spawnEntity, events.*, player.events.*), not the stale bundled strings. Its own connection carries over the classic drain() so a stray Fail from an unimplemented command can't desync the next query.
  • Naming: distribution is raspberryjuice-mcpi (avoids the legacy PyPI mcpi); the import name stays mcpi, so curriculum imports are unchanged.
  • Pi-only commands RaspberryJuice never implemented (checkpoints, camera) are omitted; auth tokens aren't supported here (single-user/classroom-LAN focus — use the raspberryjuice client on a secured server).
  • Main README documents both clients; a new mcpi-test CI job runs the suite.

Test plan

  • pytest mcpi-client — 25 tests pass on the FakeServer harness: block wire-format (incl. Vec3 args + float-flooring), reply parsing (getBlock/getBlockWithData/getBlocks/getHeight), player pos/tile (ints vs floats), chat, entities (spawn/get/remove), event polls (chat/block/projectile + empty), RequestError on Fail, the drain() stale-reply guard, setSign comma/paren neutralizing, block constants, Vec3 arithmetic, context-manager close
  • python -m build --wheel builds raspberryjuice_mcpi-0.1.0-py3-none-any.whl
  • Curriculum entry points verified: from mcpi.minecraft import Minecraft, from mcpi import block, entity, block.GOLD_BLOCK.id == 41
  • Not yet run against a live Paper 26.2 server — the epic's live canonical-example verification is a tracked follow-up ([Epic] Modern, installable mcpi-compatible Python library (run existing curriculum verbatim) #61); wire format is covered by the FakeServer tests

Follow-ups (tracked in #61)

Live-run canonical Adventures in Minecraft snippets end-to-end; optional Pi-only stubs / token support if a need appears; PyPI publish (with #11).

https://claude.ai/code/session_01AcK3SgXRTVzAKBdPZw72sr

Part of epic #61. Ships mcpi-client/, a standalone pip-installable `mcpi`
package so existing Minecraft-Pi curriculum (Adventures in Minecraft, Raspberry
Pi tutorials) runs unchanged against RaspberryJuice on Paper 26.2 - the fastest
path to kids using this.

It reproduces the classic API (from mcpi.minecraft import Minecraft;
Minecraft.create(); mc.setBlock/getBlock/postToChat; mcpi.block/entity/vec3
constants; the *args + Vec3 flattening ergonomics), modernized to Python 3.9+,
type-hinted, and tested. Command names target the current server registry
(namespaced world.*/events.*), not the stale bundled strings. Its own
connection carries over the classic drain() so a stray Fail from an
unimplemented command can't desync the next query.

Distribution name is raspberryjuice-mcpi (avoids the legacy PyPI `mcpi`); the
import name stays `mcpi` so curriculum imports are unchanged. Pi-only commands
RaspberryJuice never implemented (checkpoints, camera) are omitted; tokens
aren't supported here (use the raspberryjuice client on a secured server).

25 tests on the FakeServer harness (wire-format + reply parsing + the drain
guard + value objects); a new mcpi-test CI job; wheel builds clean.
@sakebomb
sakebomb merged commit 418937f into master Aug 20, 2026
4 checks passed
@sakebomb
sakebomb deleted the feat/mcpi-client branch August 20, 2026 03:21
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant