Skip to content
BranchesTags

Repository files navigation

minecraft-remote-api / Naohiro2g

Python Client/API package for Minecraft Remote

Write Python code to build automatically in the latest Minecraft world. This repository is dedicated to API development. If you intend to write user code, please refer to the sample repository mc_remote_samples.

Regarding the Minecraft Remote project, please refer to the section below, or visit the project homepage at mc-remote.com.

--

マイクラリモコンのためのPythonクライアント/APIパッケージ

Pythonコードを使って最新のマインクラフトの世界で自動建築が可能になります。 このリポジトリはAPI開発用です。ユーザーコードを書きたい場合は、サンプルリポジトリ mc_remote_samples をご参照ください。

Minecraft Remoteプロジェクトについては、以下のセクションをご覧いただくか、mc-remote.comのプロジェクトホームページをご覧ください。

Package Information

  • package name（パッケージ名）: minecraft-remote-api
  • description（概要）: Python Client/API for Minecraft Remote
  • version（バージョン）:
    • stable（PyPI）: 2000.0.0 — protocol 20.0.0
    • beta（GitHub pre-release タグのみ・PyPI 非公開）: 2100.0.0b2 — protocol 21.0.0 b2（下記 Migration Guide 参照）
  • module name（モジュール名）: mc_remote
  • author（著者）: Naohiro2g / Code2Create.Club
  • license（ライセンス）: MIT

--

Works with Minecraft Remote (McRemote) plugin for PaperMC servers. A sandbox server is available for testing. You can find the latest version of the package on PyPI.

PaperMCサーバー用のMinecraft Remote（McRemote）プラグインと連携します。テスト用にサンドボックスサーバーもご利用いただけます。 このパッケージの最新版は PyPI にあります。

Minecraft Remote World

Very Important Preparation / 非常に重要な準備作業

Edit these parameters in param_mc_remote.py to suit your environment.

param_mc_remote.pyのパラメータを自分の環境に合わせて編集してください。

PLAYER_NAME = "PLAYER_NAME"  # optional local memo; b2 identity comes from pairing
PLAYER_ORIGIN = Vec3(2000, 0, 2000)  # PO.x, PO.y, PO.z
ADRS_MCR = "sb.mc-remote.com"  # mc-remote sandbox server
PORT_MCR = 25575  # socket server port

  • For b2 auth, run the pairing command shown by the Python client in Minecraft. The paired in-game player becomes the authenticated identity.

    • Server address: sb.mc-remote.com
    • Server port: 25565 (No need to specify because it is the default port for Minecraft.)

  • PORT_MCR is the port for the socket server. The default value is 25575, but you can change it to any port you like. If you are using your own PaperMC server, make sure to set the same port in the plugins/McRemote/config.yml.

  • PLAYER_ORIGIN defines the origin of the building coordinate system. Building coordinates are computed relative to this origin. For example, executing setBlock(5, 68, 5, block.GOLD_BLOCK) will place a gold block at coordinates (2005, 68, 2005).

  • b2 認証では、Python クライアントが表示するペアリングコマンドを Minecraft 側で実行します。ペアリングしたゲーム内プレイヤーが認証済み identity になります。

    • サーバーアドレス: sb.mc-remote.com
    • ポート番号: 25565 （マインクラフトのデフォルトポートなので指定不要）

  • PORT_MCR はソケットサーバーのポート番号です。デフォルト値は 25575 ですが、任意のポートに変更可能です。自前のPaperMCサーバーを利用する場合は、plugins/McRemote/config.yml に同じポートを設定してください。

  • PLAYER_ORIGIN は建築座標系の原点となり、設定値からの相対座標でブロックが配置されます。たとえば、setBlock(5, 68, 5, block.GOLD_BLOCK) を実行すると、実際には座標（2005, 68, 2005）に金ブロックが設置されます。

If you are using your own PaperMC server, be sure to load the McRemote plugin. While running the server on your own PC offers a compact setup, if your PC is underpowered, it is preferable to use a server on another machine.

自前のPaperMCサーバーを利用する場合は、必ず McRemote プラグインをロードしてください。自分のPCでサーバーを構築するのが最もコンパクトですが、PCの性能が低い場合は他のマシン上のサーバーを利用することをおすすめします。

Discord Community and Sandbox Server / Discordコミュニティとサンドボックスサーバー

Join our Discord community for Minecraft Remote to ask questions and share your experiences with other users. We also offer a sandbox server for testing purposes—the perfect environment to experiment with the API without worrying about breaking anything. Visit the mc-remote-chat channel on our Discord server for support.

マイクラリモコン専用のDiscordコミュニティでは、質問を投稿したり、他のユーザーと経験を共有したりできます。さらに、テスト用のサンドボックスサーバーも用意しているので、APIの実験や新しいアイデアの試行を安心して行えます。サポートが必要な方は、Discordサーバー内の mc-remote-chat チャンネルをご利用ください。

Installation and Update / インストールと更新

For development / contributing — with uv（開発・貢献向け：uv を使う場合）

uv sync

# Make sure the virtual environment (.venv/) is created,
# and from now on, please work in that environment.
# 仮想環境(.venv/)が作成されたのを確認し、今後は、その環境内で作業してください。

to update dependencies, run (依存を更新するには、次のコマンドを実行):

uv lock --upgrade && uv sync

Poetry (2.x) でも開発できます。pyproject.toml は PEP 621 標準なので poetry install で 同様に .venv/ を作成して作業できます（ビルド／公開は uv を使用）。

Just use the package — with pip（パッケージを使うだけ：pip の場合）

pip install minecraft-remote-api

to update the package, run (パッケージを更新するには、次のコマンドを実行):

pip install minecraft-remote-api -U

Run Examples (サンプルを実行)

cd examples
python hello.py
python axis_flat.py

Manual helper scripts live in scripts/ and are run from the repo root with uv run python scripts/<name>.py.

Migration Guide: setPlayer → setWorld / setBuildOrigin (Draft) / 移行ガイド（ドラフト）

⚠️ Draft / ドラフト. Targets protocol 21.0.0 (2100.0.0b2, beta). This is a breaking change: setPlayer is removed and a matching McRemote plugin build is required. 2100.0.0b2 is published as a GitHub pre-release tag only (not on PyPI).

protocol 21.0.0（2100.0.0b2・ベータ）向け。setPlayer を削除する非互換変更で、対応する McRemote プラグインが必要です。2100.0.0b2 は GitHub の pre-release タグのみで配布（PyPI には出しません）。

What changed / 変更点

Build state (world + origin) is now separate from player identity and scoped per connection/stream. The single setPlayer(name, x, y, z) call is replaced by two methods.

建築状態（ワールド＋原点）がプレイヤーの識別情報から分離され、接続（ストリーム）ごとに保持されるようになりました。setPlayer(name, x, y, z) の1メソッドが、2つのメソッドに置き換わります。

Old (protocol ≤ 20.0.0 / 2000.0.0) New (protocol 21.0.0 / 2100.0.0b2)
mc.setPlayer(PLAYER_NAME, x, y, z) mc.setWorld("overworld") then mc.setBuildOrigin(x, y, z)
  • setWorld(dimension) — "overworld" / "nether" / "end"（または正確なワールド名）。既定は overworld。セッション中に変更可。
  • setBuildOrigin(x, y, z) — 建築座標系の原点。既定は (200, 0, 200)。セッション中に変更可。
  • setPlayer is removed / 削除。プレイヤー名は建築状態の一部ではなくなりました。
  • Coordinates stay relative to the origin: absolute y = origin y + dy (no implicit Y offset). / 座標は原点からの相対。絶対 y ＝ 原点 y ＋ dy（暗黙の Y オフセットなし）。
  • Each Minecraft instance = one connection = one independent build state, so multiple streams build in parallel without clobbering each other. / Minecraft インスタンス1つ＝1接続＝独立した建築状態。複数ストリームが互いに干渉せず並行建築できます。
  • b2 adds token auth on hello: call Minecraft.create(...), then run the shown /mcremote pair NNN-NNN command in Minecraft when prompted. Stored tokens are keyed by token_key or by address:port; the compatibility sandbox argument is only a local token-store alias and is never sent in hello.params.
  • b2 では hello に token 認証が加わりました。Minecraft.create(...) 実行後、表示された /mcremote pair NNN-NNN を Minecraft 側で実行します。保存 token は token_key または address:port で管理されます。互換用の sandbox 引数はローカル token-store alias のみで、hello.params には送信されません。
  • getPos() / setPos(world, x, y, z) operate on the paired player. Positions are relative to this stream's build origin, and setPos takes an explicit target world.
  • getPos() / setPos(world, x, y, z) はペアリング済みプレイヤーを対象にします。座標はこの stream の build origin 相対で、setPos は移動先 world を明示します。

Error handling / エラー処理

Connection/request failures no longer call sys.exit(); they raise catchable exceptions. 接続・リクエストの失敗で sys.exit() せず、捕捉可能な例外を送出します。

from mc_remote.connection import ConnectionLostError, RequestFailedError

try:
    mc.setBuildOrigin(0, 0, 0)
except RequestFailedError as e:   # server reported a failed request / サーバーが失敗を返した
    ...
except ConnectionLostError as e:  # connection to the server was lost / 接続が失われた
    ...

Both subclass McRemoteError, so except McRemoteError: catches either. / どちらも McRemoteError のサブクラスなので、except McRemoteError: で両方を捕捉できます。

Before / after / 変更前後

# Before / 変更前
mc = Minecraft.create(address=param.ADRS_MCR, port=param.PORT_MCR)
mc.setPlayer(param.PLAYER_NAME, PO.x, PO.y, PO.z)

# After / 変更後
mc = Minecraft.create(address=param.ADRS_MCR, port=param.PORT_MCR)
mc.setWorld("overworld")
mc.setBuildOrigin(PO.x, PO.y, PO.z)

Installing the beta / ベータの導入

2100.0.0b2 is not on PyPI, so a plain pip install / uv add keeps the current stable line. Testers install the exact beta from its GitHub tag.

2100.0.0b2 は PyPI に出さないため、素の pip install / uv add では従来の安定版のままです。テスターは GitHub タグから対象ベータを明示指定で導入します。

# exact-pin from the GitHub tag / GitHub タグを明示指定
uv add "minecraft-remote-api @ git+https://github.com/Naohiro2g/minecraft-remote-api@v2100.0.0b2"

About the Minecraft Remote Project

Minecraft Remote (or mc-remote) is a remote control system for Minecraft. The client communicates with a dedicated server provided by the McRemote plugin—which runs alongside your PaperMC server—while the API facilitates user interaction, allowing users to write code and perform automatic construction.

It is based on projects such as RaspberryJuice by zhowei, mcpi by martinohanlon, and JuicyraspberryPie by wensheng—all of which are designed to "support LEARNING" rather than conventional "EDUCATION", and reflect the collective wisdom and effort of their communities. The project is also strongly influenced by Dr. Mitchel Resnick (MIT)'s Lifelong Kindergarten.

References:

The Clear Mission of the Minecraft Remote Project

To Support the Acquisition of a Self-Learning Approach (for Beginners)

The primary goal is to foster a self-directed, exploratory learning approach rather than merely focusing on technical skills.

Technical Skills Acquired Through the Self-Learning Approach

  • Coding concepts and techniques
  • Techniques for open source development using Git/GitHub
  • Techniques for realizing/expressing one's own ideas

Key Points for Maintaining Motivation in Self-Learning

  • Provide the latest version of Minecraft as an engaging playground and sandbox.
  • Enable the reuse of code assets developed from previous projects.
  • Support a wide range of programming languages including Python, Scratch, C#, Java, etc. We are currently prioritizing the preparation of a Scratch version.
  • Expand beyond the Minecraft world to include 3D environments like Unity, Blender, and Houdini.
  • Supports output to 3D worlds and plans to support input—enabling interactive experiences that connect digital, real, and other virtual worlds.
  • Integrate artificial intelligence technologies. For instance, allow playing rock-paper-scissors with hand gestures in the Minecraft world using computer vision and machine learning.

Minecraft Remoteプロジェクトについて

Minecraft Remote / mc-remote（マイクラリモコン、あるいは、エムシーリモート） は、Minecraftのリモコンシステムです。クライアントは、PaperMCサーバーと併走して稼働する McRemoteプラグイン が提供する専用サーバーと通信を行い、一方、APIはユーザーとのやり取りを円滑にする役割を果たし、ユーザーがコードを記述して自動建築を実現できるようにします。

このプロジェクトは、zhoweiによるRaspberryJuice、martinohanlonによるmcpi、およびwenshengによるJuicyraspberryPieなどの、知識注入型の 「教育」 というよりも 「学習支援」 の意図を強く持ったプロジェクト群および、そのコミュニティの知恵と努力の成果に基づいています。また、Dr. Mitchel Resnick(MIT)のライフロングキンダーガーテンの影響を強く受けています。

リファレンス：

Minecraft Remoteプロジェクトの明確なミッション

(初学者の)自学自習アプローチ習得を支援すること

技術スキル習得は二の次とし、自発的な学びの姿勢を育むことを目的とします。

自学自習アプローチ習得の題材とする技術スキル

  • コーディングの概念と手法
  • Git/GitHubを活用したオープンソース開発の手法
  • 自分のアイデアを実現／表現する技術

自学自習のモチベーション維持における重要なポイント

  • 魅力的なプレイグラウンド、サンドボックスとして最新版マインクラフトを利用可能にすること
  • 過去のプロジェクトで培われてきたコード資産を活用できるようにすること
  • Python、Scratch、C#、Java他、幅広い言語の利用を可能にすること （Scratch版の準備を急務としている。）
  • マインクラフト世界だけでなく、Unity、Blender、Houdiniなどの3D世界の利用を可能にすること
  • 3D世界への出力に加え入力対応も計画中 — これにより、デジタル世界、現実世界、およびその他の仮想環境と連携するインタラクティブな体験を実現する
  • 人工知能技術の応用、例えば、コンピュータービジョンと機械学習を利用し、マインクラフト世界の中の手とじゃんけんができる仕組みなど。

Hacking, coding, and tinkering are the core of this project. We aim to create a system that allows users to explore and learn through their own experiences. The project is open to everyone, and we welcome contributions from all who share our vision.

Hacking Coding Tinkering

About

refreshed Python Client/API for Minecraft Remote

Resources

Readme
MIT license
Activity

Stars

3 stars

Watchers

1 watching

Forks

2 forks
Report repository

Releases

Packages

Used by

Contributors

Languages