PythonクライアントAPI一覧（ドラフト）

Pythonから使う操作を、用途別に探すための一覧です。対象実装: minecraft-remote-api 2320.0.0b9 / Protocol 23.2.0。

Minecraftクラスの公開メソッド・読み取り専用propertyと、よく使う入力・戻り値の型、例外をまとめています。

初めて使うときは READMEの導入手順を進めてください。APIの作例も参照できます。

サーバーが受け取る名前・引数・応答は Protocol API一覧で確認できます。掲載対象のreleaseはページ冒頭に表示されます。たとえばPythonのmc.playSound()は通信上のworld.playSoundに対応します。

用途から探す

用途	主な入口
接続と終了	`create`、`close`、`flush`
建築原点・次元・実行モード	`setDimension`、`setBuildOrigin`、`setBuildMode`、`build_mode`、`trace_delay`
ブロック	`setBlock`、`getBlock`、`setBlocks`、`getBlocks`、`getHeight`
プレイヤー	`getPos`、`setPos`、`getPose`、`setPose`、`getDirection`、`setDirection`
エンティティ	`spawnEntity`、`getNearbyEntities`、`getEntityPose`、`setEntityPose`、`getEntityDirection`、`setEntityDirection`、`removeEntity`
看板	`getSign`、`setSign`、`updateSignLine`
パーティクル・音・雷	`spawnParticle`、`playSound`、`playBlockSound`、`strikeLightning`
チャットとイベント	`postToChat`、`pollEvents`、`assertEventContext`
カタログと補完	`getCatalog`、`sync_constants`
接続処理を組み立てるとき	`hello`、`authenticate`
入力・戻り値の型	ブロック、位置、エンティティ、パーティクル、看板、イベント
例外と警告	サーバーの拒否、接続切断、カタログ生成
短い作例	接続、ブロックの復元、エンティティ、音、イベント

共通の読み方

ブロック座標は整数、プレイヤー・エンティティ・パーティクル・playSound()の位置は小数も使えます。playBlockSound()は整数のブロック座標です。建築原点を設定するsetBuildOrigin()の座標は絶対位置で、それ以外の操作の位置は建築原点から相対です。
dimensionはoverworldのような無印、またはminecraft:overworldのような完全修飾IDを渡せます。返るdimensionは完全修飾です。
block・particle・entity・soundのIDはminecraft:を省略できます。Pythonは入力をそのまま送り、サーバーが補います。
シグネチャの * より後はキーワード専用引数です。型の書き分けにはoverloadを表示します。型注釈がない引数・戻り値は実装の表記を保ち、説明で補います。
getBlock()の結果は BlockValue なのでvalue.block_idやvalue.stateで読みます。getPos()やgetPose()の結果はdictなのでresult["pos"]で読みます。
worldを変える操作の効果はサーバー上に残ります。作例ではブロックの復元やエンティティの削除も示します。パーティクルは自然に消えます。
通常のAPI操作は自動再試行しません。接続時のpairing処理と、手動でAPIをもう一度呼ぶ操作は各項目を参照してください。

接続と終了

Python	用途	戻り値・値	対応するProtocol API
`Minecraft.create()`	サーバーへ接続し、認証と必要なpairing、カタログ同期を進める	`Minecraft`	`hello`、`auth.pairBegin`、`auth.pairPoll`、`catalog.get`
`mc.close()`	先行するFAST commandの完了を待ち、接続を閉じる	正常終了時はTrue	`connection.flush`
`mc.flush()`	この接続で先に送ったcommandの完了を確認する	`None`	`connection.flush`

`Minecraft.create`

サーバーへ接続し、認証と必要なpairing、カタログ同期を進める。

Minecraft.create(
    address = 'localhost',
    port = 25575,
    debug = False,
    handshake = True,
    sandbox = None,
    token_type = 'session',
    pair = True,
    token_key = None,
    sync_catalog = True,
    wirescope = None,
    build_mode = BuildMode.DEBUG,
    trace_delay = 0.25,
) -> Minecraft

戻り値・値: 接続したMinecraftオブジェクト。

from mc_remote import Minecraftでimportできます。Minecraft.create()が通常の入口です。
保存済みtokenでhelloを試し、認証に必要なときだけpairing commandを表示してMinecraft内の承認を待ちます。pair=Falseはこの待機を行わず、必要ならPairingRequiredErrorを返します。
sync_catalog=Trueでは接続後に補完を生成します。生成が失敗した場合はCatalogProjectionWarningを出し、接続したオブジェクトを返します。
wirescope=Trueは同梱WireScopeをlocalhostで開く設定です。WireScopeStation.local()も渡せます。NoneまたはFalseで無効です。
handshake=Falseは接続処理を自分で組み立てる用途です。sandboxはローカルtoken保存先のkeyを指定する互換引数です。

実装を見る

`mc.close`

先行するFAST commandの完了を待ち、接続を閉じる。

mc.close()

戻り値・値: 正常終了時はTrue。完了を確認できない場合は例外。

with Minecraft.create(...) as mc:のブロックを抜けるとclose()が呼ばれます。明示的にclose()を呼ぶこともできます。
正常に閉じたあとにもう一度呼んでもTrueを返します。同梱WireScopeの実行状態も閉じます。

実装を見る

`mc.flush`

この接続で先に送ったcommandの完了を確認する。

mc.flush() -> None

戻り値・値: None。

ブロックの現在値を読む操作はgetBlock()/getBlocks()で行います。
タイムアウトした場合はRequestTimeoutErrorになり、接続を閉じます。先行操作の完了は不明なので、自動再試行しません。

実装を見る

建築原点・次元・実行モード

Python	用途	戻り値・値	対応するProtocol API
`mc.setDimension()`	この接続で建築する次元を変える	dimensionとoriginを含むdict	`build.setDimension`
`mc.setBuildOrigin()`	この接続の建築座標の原点を設定する	dimensionとoriginを含むdict	`build.setOrigin`
`mc.setBuildMode()`	ブロック設置の実行モードとTRACEの待ち時間を変える	`None`	`connection.flush`
`mc.build_mode`	現在のブロック設置モードを読む	`BuildMode`	Python内の補助機能
`mc.trace_delay`	現在のTRACEの待ち時間を読む	`float`	Python内の補助機能

`mc.setDimension`

この接続で建築する次元を変える。

mc.setDimension(dimension)

戻り値・値: dimensionとoriginを含むdict。

プレイヤーを次元間で移動する操作はsetPos()/setPose()で行います。

実装を見る

`mc.setBuildOrigin`

この接続の建築座標の原点を設定する。

mc.setBuildOrigin(x, y, z)

戻り値・値: dimensionとoriginを含むdict。

x・y・zは絶対位置の整数です。以後の位置はこの原点から相対になります。Yにも同じ加算を使います。

実装を見る

`mc.setBuildMode`

ブロック設置の実行モードとTRACEの待ち時間を変える。

mc.setBuildMode(mode: BuildMode) -> None

mc.setBuildMode(mode: BuildMode, *, trace_delay: float) -> None

戻り値・値: None。

modeは BuildMode の値です。変更時は先行commandをflushしてから切り替えます。
trace_delayは0〜2秒です。省略すると現在の値を保ちます。
FASTがnotificationになるのはsetBlock()/setBlocks()です。spawnParticle()などは各モードでも応答を待ちます。

実装を見る

`mc.build_mode`

現在のブロック設置モードを読む。

mc.build_mode: BuildMode

戻り値・値: BuildMode。読み取り専用property。

変更はsetBuildMode()で行います。

実装を見る

`mc.trace_delay`

現在のTRACEの待ち時間を読む。

mc.trace_delay: float

戻り値・値: 秒を表すfloat。読み取り専用property。

変更はsetBuildMode(..., trace_delay=...)で行います。

実装を見る

ブロック

Python	用途	戻り値・値	対応するProtocol API
`mc.setBlock()`	ブロックを1つ置く	`None`	`world.setBlock`
`mc.getBlock()`	ブロックを1つ調べる	`BlockValue`	`world.getBlock`
`mc.setBlocks()`	直方体の範囲を同じブロックで埋める	`None`	`world.setBlocks`
`mc.getBlocks()`	直方体の範囲のブロックをまとめて調べる	`tuple[BlockValue, ...]`	`world.getBlocks`
`mc.getHeight()`	X/Z位置のいちばん上の地面の高さを調べる	`int`	`world.getHeight`

`mc.setBlock`

ブロックを1つ置く。

mc.setBlock(x, y, z, block_id, *, state = None)

戻り値・値: None。

block_idはID文字列、stateはpropertyのmappingです。stateはキーワード専用で、Noneは空のstateに変換します。指定しないpropertyはMinecraftの既定値になります。
mc_constantsの型付きIDでは、対応するstateの型をoverloadで補完できます。BlockIdと_StateTはこの型の対応を表します。
設置後の値はgetBlock()で確認します。

型の書き分け（overload）

mc.setBlock(x, y, z, block_id: BlockId[_StateT], *, state: _StateT | None = None) -> None

mc.setBlock(x, y, z, block_id: str, *, state: Mapping[str, StateScalar] | None = None) -> None

実装を見る

`mc.getBlock`

ブロックを1つ調べる。

mc.getBlock(x, y, z) -> BlockValue

戻り値・値: BlockValue。block_idとstateは属性で読みます。

実装を見る

`mc.setBlocks`

直方体の範囲を同じブロックで埋める。

mc.setBlocks(x0, y0, z0, x1, y1, z1, block_id, *, state = None)

戻り値・値: None。

両端を含む範囲です。block_idとstateの扱いはsetBlock()と同じです。範囲と作業量の上限はサーバーが判定します。

型の書き分け（overload）

mc.setBlocks(
    x0,
    y0,
    z0,
    x1,
    y1,
    z1,
    block_id: BlockId[_StateT],
    *,
    state: _StateT | None = None,
) -> None

mc.setBlocks(
    x0,
    y0,
    z0,
    x1,
    y1,
    z1,
    block_id: str,
    *,
    state: Mapping[str, StateScalar] | None = None,
) -> None

実装を見る

`mc.getBlocks`

直方体の範囲のブロックをまとめて調べる。

mc.getBlocks(x0, y0, z0, x1, y1, z1) -> tuple[BlockValue, ...]

戻り値・値: BlockValueのtuple。

各軸は入力の大小からmin/maxを決め、両端を含みます。結果はZが最も速く変わり、次にY、最後にXの順です。
tupleと各BlockValueは取得時点の変更不能なsnapshotです。

実装を見る

`mc.getHeight`

X/Z位置のいちばん上の地面の高さを調べる。

mc.getHeight(x, z, max_y = None)

戻り値・値: 建築原点から相対のYを表すint。

max_yを指定すると、その高さを含む範囲まで調べます。

型の書き分け（overload）

mc.getHeight(x, z) -> int

mc.getHeight(x, z, max_y) -> int

実装を見る

プレイヤー

Python	用途	戻り値・値	対応するProtocol API
`mc.getPos()`	pairingしたプレイヤーの位置を調べる	dimensionとposを含むdict	`player.getPos`
`mc.setPos()`	pairingしたプレイヤーを移動させる	移動後のdimensionとposを含むdict	`player.setPos`
`mc.getPose()`	pairingしたプレイヤーの位置と角度を調べる	dimension・pos・yaw・pitchを含むdict	`player.getPose`
`mc.setPose()`	pairingしたプレイヤーの位置と角度をまとめて変える	移動後のdimension・pos・yaw・pitchを含むdict	`player.setPose`
`mc.getDirection()`	pairingしたプレイヤーの視線方向を調べる	`DirectionValue`	`player.getDirection`
`mc.setDirection()`	pairingしたプレイヤーの向きだけを変える	`DirectionValue`	`player.setDirection`

`mc.getPos`

pairingしたプレイヤーの位置を調べる。

mc.getPos()

戻り値・値: dimensionとposを含むdict。posは[x, y, z]のlist。

posは建築原点から相対です。プレイヤー名は渡しません。

実装を見る

`mc.setPos`

pairingしたプレイヤーを移動させる。

mc.setPos(dimension, x, y, z)

戻り値・値: 移動後のdimensionとposを含むdict。

dimensionを明示します。x・y・zは建築原点から相対で、小数も使えます。

実装を見る

`mc.getPose`

pairingしたプレイヤーの位置と角度を調べる。

mc.getPose()

戻り値・値: dimension・pos・yaw・pitchを含むdict。

posは[x, y, z]のlistで、建築原点から相対です。yaw・pitchは角度です。

実装を見る

`mc.setPose`

pairingしたプレイヤーの位置と角度をまとめて変える。

mc.setPose(dimension, x, y, z, yaw, pitch)

戻り値・値: 移動後のdimension・pos・yaw・pitchを含むdict。

dimensionを明示します。yaw・pitchは角度で、数値の検証と正準化はサーバーが行います。

実装を見る

`mc.getDirection`

pairingしたプレイヤーの視線方向を調べる。

mc.getDirection() -> DirectionValue

戻り値・値: DirectionValue。X/Y/Z成分のtuple。

実装を見る

`mc.setDirection`

pairingしたプレイヤーの向きだけを変える。

mc.setDirection(x, y, z) -> DirectionValue

戻り値・値: 変更後のDirectionValue。

有限な方向ベクトルを渡します。サーバーが正規化し、Pythonは入力の大きさや精度を変えず送ります。

実装を見る

エンティティ

Python	用途	戻り値・値	対応するProtocol API
`mc.spawnEntity()`	エンティティを出し、操作するためのhandleを受け取る	`EntityHandle`	`world.spawnEntity`
`mc.getNearbyEntities()`	指定位置の近くのエンティティを一覧で受け取る	`tuple[NearbyEntity, ...]`	`world.getNearbyEntities`
`mc.getEntityPose()`	handleで指定したエンティティの位置と角度を調べる	`PoseValue`	`entity.getPose`
`mc.setEntityPose()`	handleで指定したエンティティの位置と角度をまとめて変える	`PoseValue`	`entity.setPose`
`mc.getEntityDirection()`	handleで指定したエンティティの向きを調べる	`DirectionValue`	`entity.getDirection`
`mc.setEntityDirection()`	handleで指定したエンティティの向きだけを変える	`DirectionValue`	`entity.setDirection`
`mc.removeEntity()`	handleで指定したエンティティを削除する	`None`	`entity.remove`

`mc.spawnEntity`

エンティティを出し、操作するためのhandleを受け取る。

mc.spawnEntity(x, y, z, entity) -> EntityHandle

戻り値・値: EntityHandle。文字列のsubclass。

entityはcowなどのID文字列です。handleは取得した接続で使い、再接続後は取り直します。

実装を見る

`mc.getNearbyEntities`

指定位置の近くのエンティティを一覧で受け取る。

mc.getNearbyEntities(x, y, z, radius, max_entities) -> tuple[NearbyEntity, ...]

戻り値・値: NearbyEntity のtuple。距離の近い順。

radiusとmax_entitiesは必須引数です。半径は0〜64、件数は1〜64で、サーバーがさらに小さい上限を設定している場合があります。
プレイヤーは含みません。検索でchunkをloadせず、結果のposは建築原点から相対です。取得後にエンティティが消える場合があります。

実装を見る

`mc.getEntityPose`

handleで指定したエンティティの位置と角度を調べる。

mc.getEntityPose(handle: str) -> PoseValue

戻り値・値: PoseValue。dimension・pos・yaw・pitchを含むdict。

実装を見る

`mc.setEntityPose`

handleで指定したエンティティの位置と角度をまとめて変える。

mc.setEntityPose(handle: str, dimension, x, y, z, yaw, pitch) -> PoseValue

戻り値・値: 移動後のPoseValue。

次元を移動しても成功時は同じhandleを使えます。この接続の建築次元・原点は変わりません。

実装を見る

`mc.getEntityDirection`

handleで指定したエンティティの向きを調べる。

mc.getEntityDirection(handle: str) -> DirectionValue

戻り値・値: DirectionValue。

実装を見る

`mc.setEntityDirection`

handleで指定したエンティティの向きだけを変える。

mc.setEntityDirection(handle: str, x, y, z) -> DirectionValue

戻り値・値: 変更後のDirectionValue。

実装を見る

`mc.removeEntity`

handleで指定したエンティティを削除する。

mc.removeEntity(handle: str) -> None

戻り値・値: None。

削除したhandleは即時失効します。

実装を見る

看板

Python	用途	戻り値・値	対応するProtocol API
`mc.getSign()`	看板の両面の文字とwaxed状態を読む	`SignValue`	`world.getSign`
`mc.setSign()`	看板の指定した面の4行をまとめて書き換える	`None`	`world.setSign`
`mc.updateSignLine()`	看板の指定した面の1行だけを書き換える	`None`	`world.updateSignLine`

`mc.getSign`

看板の両面の文字とwaxed状態を読む。

mc.getSign(x, y, z) -> SignValue

戻り値・値: SignValue。各面はLineValueの4要素tuple。

指定位置に看板が必要です。waxedな看板も読めます。

実装を見る

`mc.setSign`

看板の指定した面の4行をまとめて書き換える。

mc.setSign(x, y, z, *, front = None, back = None) -> None

戻り値・値: None。

frontまたはbackの少なくとも片方を、4行のsequenceで指定します。省略した面は保ち、指定した面の4行はすべて置き換えます。
各行は文字列、またはtext・color・decorationsを持つmappingです。waxedな看板への変更はsign_waxedになります。

実装を見る

`mc.updateSignLine`

看板の指定した面の1行だけを書き換える。

mc.updateSignLine(x, y, z, face, line_index, line) -> None

戻り値・値: None。

faceはfront/back、line_indexは0〜3です。lineは文字列、またはtext・color・decorationsのmappingです。

実装を見る

パーティクル・音・雷

Python	用途	戻り値・値	対応するProtocol API
`mc.spawnParticle()`	指定位置にパーティクルを出す	`int`	`world.spawnParticle`
`mc.playSound()`	指定位置から登録された音を鳴らす	`None`	`world.playSound`
`mc.playBlockSound()`	その位置のブロックの音を鳴らす	`None`	`world.playBlockSound`
`mc.strikeLightning()`	指定位置に雷を落とす	`None`	`world.strikeLightning`

`mc.spawnParticle`

指定位置にパーティクルを出す。

mc.spawnParticle(
    x,
    y,
    z,
    offset_x,
    offset_y,
    offset_z,
    particle: str | ParticleSpec,
    speed,
    count,
) -> int

mc.spawnParticle(
    x,
    y,
    z,
    offset_x,
    offset_y,
    offset_z,
    particle: str | ParticleSpec,
    speed,
    count,
    force: bool,
) -> int

戻り値・値: サーバーが返した生成数のint。

particleはID文字列または ParticleSpec のdictです。色や大きさ、表示先を指定できます。offset_x/y/zとspeedは0以上、countは0以上の整数です。
forceを省略すると項目を送らず、サーバーの既定trueを使います。明示するときはboolを渡します。
受け取った生成数と、Minecraft画面で実際に見える粒子数は別です。描画はクライアントの距離・設定にも依存します。
FASTでも応答を待つrequestです。3Dグラフの作例も参照できます。

実装を見る

`mc.playSound`

指定位置から登録された音を鳴らす。

mc.playSound(
    x,
    y,
    z,
    sound_id: str,
    *,
    volume: int | float | None = None,
    pitch: int | float | None = None,
    note: int | None = None,
    receiver: Literal['world', 'self'] | None = 'world',
) -> None

戻り値・値: None。

sound_idはblock.note_block.harpなどのIDです。volume・pitch・note・receiverはキーワード専用引数です。
volumeは0〜1、pitchは0.5〜2、noteは整数0〜24です。pitchとnoteを両方指定すると送信前にValueErrorになります。note=12は倍率1です。
Noneはその項目を送らず、volume/pitchはサーバーの既定1.0を使います。note=0やvolume=0は省略になりません。
receiverのworldは近くのプレイヤー向け、selfはpairingしたプレイヤー向けです。
辞書の設定は **controls の形で渡せます。音名からnoteへの換算はユーザーコードで行います。

実装を見る

`mc.playBlockSound`

その位置のブロックの音を鳴らす。

mc.playBlockSound(
    x,
    y,
    z,
    kind: str,
    *,
    volume: int | float | None = None,
    pitch: int | float | None = None,
    note: int | None = None,
    receiver: Literal['world', 'self'] | None = 'world',
) -> None

戻り値・値: None。

座標はブロック位置の整数です。kindはplace/hit/break/step/fallです。ブロックの設置や破壊は行いません。
省略したvolume/pitchは、そのブロックのSoundGroupの値を使います。pitchまたはnoteを指定すると元の高さを置き換えます。
None・pitch/note・receiverの渡し方はplaySound()と同じです。airの位置ではno_blockになります。

実装を見る

`mc.strikeLightning`

指定位置に雷を落とす。

mc.strikeLightning(x, y, z) -> None

戻り値・値: None。

worldにdamage・発火などの効果を与える操作です。自動再試行しません。

実装を見る

チャットとイベント

Python	用途	戻り値・値	対応するProtocol API
`mc.postToChat()`	Minecraftのチャットにメッセージを送る	`None`	`chat.post`
`mc.pollEvents()`	この接続の未取得のイベントを受け取る	`EventBatch`	`events.poll`
`mc.assertEventContext()`	イベントの座標系が現在の建築原点・次元と一致するか確認する	`None`	Python内の補助機能

`mc.postToChat`

Minecraftのチャットにメッセージを送る。

mc.postToChat(message) -> None

戻り値・値: None。成功resultはnull。

実装を見る

`mc.pollEvents`

この接続の未取得のイベントを受け取る。

mc.pollEvents(max_events = None) -> EventBatch

戻り値・値: EventBatch。eventsはEventValueのtuple。

Pythonが取得位置のカーソルを管理し、正常な応答を確認したあとに進めます。再接続時はカーソルをリセットします。
未知のイベントは共通fieldと順序を検査してからeventsから省きます。through_sequenceとloss counterはサーバーの値を保持します。
同じ接続でlatest_sequenceや累積loss counterが逆行した場合は応答を拒否し、取得位置を進めません。再接続時は前回値もリセットします。
max_eventsは正の整数、省略するとサーバーの取得件数を使います。
各イベントは発生時のdimensionとoriginを持ちます。位置を建築に使う前にassertEventContext()で現在の原点と合うかを確認できます。

実装を見る

`mc.assertEventContext`

イベントの座標系が現在の建築原点・次元と一致するか確認する。

mc.assertEventContext(event: EventValue) -> None

戻り値・値: 一致時はNone。不一致時はEventContextMismatchError。

ローカルで確認し、イベントを捨てたり建築状態を変更したりしません。

実装を見る

カタログと補完

Python	用途	戻り値・値	対応するProtocol API
`mc.getCatalog()`	接続先のブロック・エンティティ・パーティクルのカタログを取得する	サーバーのカタログを含むdict	`catalog.get`
`mc.sync_constants()`	カタログをcacheし、現在のプロジェクトの補完ファイルを生成する	生成したmc_constants.pyのpath文字列	`catalog.get`

`mc.getCatalog`

接続先のブロック・エンティティ・パーティクルのカタログを取得する。

mc.getCatalog()

戻り値・値: サーバーのカタログを含むdict。

別の短命な認証済み接続を使います。補完ファイルを生成する場合はsync_constants()を使います。

実装を見る

`mc.sync_constants`

カタログをcacheし、現在のプロジェクトの補完ファイルを生成する。

mc.sync_constants(target_dir = None, force = False)

戻り値・値: 生成したmc_constants.pyのpath文字列。同期できるcatalog hashが無い場合はNone。

target_dirの省略時は現在の作業ディレクトリです。mc_constants.py・mc_constants.pyi・manifestを生成します。force=Trueではcacheがあっても取り直します。
Git管理下では生成物をignoreする設定が必要です。mcremote initで設定できます。
明示的に呼んだときの失敗はCatalogProjectionErrorです。create()内の自動同期では警告になります。

実装を見る

接続処理を組み立てるとき

Python	用途	戻り値・値	対応するProtocol API
`mc.hello()`	接続の最初のhelloを送り、応答をこのオブジェクトに保持する	hello応答のdict	`hello`
`mc.authenticate()`	ローカルtoken保存先のkeyを使い、helloと必要なpairingを進める	認証後のhello応答のdict	`hello`、`auth.pairBegin`、`auth.pairPoll`

`mc.hello`

接続の最初のhelloを送り、応答をこのオブジェクトに保持する。

mc.hello(auth_token = None)

戻り値・値: hello応答のdict。

通常はcreate()が行います。1接続に1回のhandshakeです。auth_tokenは保存済みcredentialを自分で扱う用途です。

実装を見る

`mc.authenticate`

ローカルtoken保存先のkeyを使い、helloと必要なpairingを進める。

mc.authenticate(server_key, token_type = 'session', pair = True)

戻り値・値: 認証後のhello応答のdict。

通常はcreate()が行います。server_keyはローカル保存先のkeyで、接続先アドレスを変更する引数ではありません。

実装を見る

入力・戻り値の型

`BuildMode`

setBlock()/setBlocks()の実行方法を選ぶEnumです。

from mc_remote.minecraft import BuildMode

BuildMode.DEBUG: DEBUG
BuildMode.TRACE: TRACE
BuildMode.FAST: FAST

DEBUGは応答を待つrequest、TRACEはrequest後に待ち時間を入れるモード、FASTはnotificationで送るモードです。FASTの完了はflush()/close()で確認します。

定義を見る

`BlockValue`

取得したブロックの変更不能なデータクラスです。

from mc_remote.minecraft import BlockValue

フィールド	型	既定値・省略
`block_id`	`str`	`必須`
`state`	`Mapping[str, StateScalar]`	`必須`

block_idは完全修飾、stateは完全なpropertyのmappingです。復元はmc.setBlock(x, y, z, value.block_id, state=value.state)で行えます。

定義を見る

`BlockId`

生成したblock IDと、そのstateの型を結びつける型補完用のマーカーです。

from mc_remote.block_value import BlockId

mc_constantsの定数は実行時には通常の文字列です。学習者がBlockIdを生成して渡す必要はありません。

定義を見る

`StateScalar`

ブロックのstateの値に使うscalarの型です。

from mc_remote.block_value import StateScalar

StateScalar = str | int | float | bool

定義を見る

`DirectionValue`

向きのX/Y/Z成分の変更不能なtupleです。

from mc_remote.minecraft import DirectionValue

DirectionValue = tuple[int | float, int | float, int | float]

サーバーが正規化した値を受け取ります。Pythonは再roundしません。

定義を見る

`EntityHandle`

エンティティを操作するための不透明な文字列です。

from mc_remote.minecraft import EntityHandle

spawnEntity()/getNearbyEntities()で得た値を使います。取得した接続でのみ有効で、再接続後は取り直します。

定義を見る

`NearbyEntity`

近傍検索で取得したエンティティの変更不能なデータクラスです。

from mc_remote.minecraft import NearbyEntity

フィールド	型	既定値・省略
`handle`	`EntityHandle`	`必須`
`type`	`str`	`必須`
`pos`	`tuple[int \| float, int \| float, int \| float]`	`必須`

typeは完全修飾のentity ID、posは建築原点から相対です。

定義を見る

`PoseValue`

エンティティの姿勢を返すTypedDictです。実行時はdictです。

from mc_remote.minecraft import PoseValue

フィールド	型	既定値・省略
`dimension`	`str`	`必須`
`pos`	`list[int \| float]`	`必須`
`yaw`	`int \| float`	`必須`
`pitch`	`int \| float`	`必須`

posは建築原点から相対の[x, y, z]、yaw・pitchは角度です。playerのgetPose()も同じkeyを持つdictを返します。

定義を見る

`ParticleSpec`

パーティクルのID、表示先、dataを指定するTypedDictです。実行時はdictです。

from mc_remote.minecraft import ParticleSpec

フィールド	型	既定値・省略
`particle_id`	`str`	`必須`
`receiver`	`Literal['world', 'self']`	`省略可`
`data`	`DustData \| BlockParticleData`	`省略可`

receiverの省略時はworld、selfはpairingしたプレイヤー向けです。data省略とdata=Noneは異なり、NoneはJSON nullとして送りサーバーが拒否します。

定義を見る

`DustData`

dustの色と大きさを指定するTypedDictです。

from mc_remote.minecraft import DustData

フィールド	型	既定値・省略
`color`	`list[int]`	`必須`
`size`	`int \| float`	`必須`

colorはRGBの0〜255の整数3個、sizeは0.01〜4.0です。

定義を見る

`BlockParticleData`

block系パーティクルのブロックIDとstateを指定するTypedDictです。

from mc_remote.minecraft import BlockParticleData

フィールド	型	既定値・省略
`block_id`	`str`	`必須`
`state`	`Mapping[str, StateScalar]`	`必須`

定義を見る

`SoundOptions`

音のキーワード引数を変数のdictにまとめるためのTypedDictです。

from mc_remote.minecraft import SoundOptions

フィールド	型	既定値・省略
`volume`	`int \| float`	`省略可`
`pitch`	`int \| float`	`省略可`
`note`	`int`	`省略可`
`receiver`	`Literal['world', 'self']`	`省略可`

mc.playSound(..., **controls)の形で渡します。pitchとnoteは片方だけを指定します。

定義を見る

`LineValue`

看板から読んだ1行の変更不能なデータクラスです。

from mc_remote.minecraft import LineValue

フィールド	型	既定値・省略
`text`	`str`	`必須`
`color`	`str`	`必須`
`decorations`	`tuple[str, ...]`	`必須`

定義を見る

`SignValue`

看板の両面とwaxed状態の変更不能なデータクラスです。

from mc_remote.minecraft import SignValue

フィールド	型	既定値・省略
`front`	`tuple[LineValue, ...]`	`必須`
`back`	`tuple[LineValue, ...]`	`必須`
`waxed`	`bool`	`必須`

front/backはそれぞれ4行のLineValueのtupleです。

定義を見る

`EventBatch`

pollEvents()で取得したイベントと取得位置・欠落統計の変更不能なデータクラスです。

from mc_remote.minecraft import EventBatch

フィールド	型	既定値・省略
`events`	`tuple[EventValue, ...]`	`必須`
`through_sequence`	`int`	`必須`
`latest_sequence`	`int`	`必須`
`filtered_out`	`int`	`必須`
`overflow_dropped_total`	`int`	`必須`
`capacity_dropped_total`	`int`	`必須`
`explicitly_discarded_total`	`int`	`必須`

eventsを反復して各EventValueを読みます。loss_totals propertyはoverflow/capacity/explicitly_discardedの変更不能なmappingを返します。

定義を見る

`EventValue`

受け取るイベントの型のunionです。

from mc_remote.minecraft import EventValue

EventValue = PickaxePokeEvent | ChatPostedEvent | ProjectileHitEvent

event.typeでイベントの種類を判断し、対応する属性を読みます。

定義を見る

`PickaxePokeEvent`

ツルハシでブロックを叩いたイベントです。

from mc_remote.minecraft import PickaxePokeEvent

フィールド	型	既定値・省略
`sequence`	`int`	`必須`
`dimension`	`str`	`必須`
`origin`	`tuple[int, int, int]`	`必須`
`pos`	`tuple[int, int, int]`	`必須`
`face`	`str`	`必須`
`block`	`BlockValue`	`必須`
`hand`	`str`	`必須`
`item`	`str`	`必須`
`type`	`str`	`'pickaxe_poke'`

posは発生時のoriginから相対、blockはその時点のBlockValueです。

定義を見る

`ChatPostedEvent`

チャットに投稿されたイベントです。

from mc_remote.minecraft import ChatPostedEvent

フィールド	型	既定値・省略
`sequence`	`int`	`必須`
`dimension`	`str`	`必須`
`origin`	`tuple[int, int, int]`	`必須`
`message`	`str`	`必須`
`type`	`str`	`'chat_posted'`

定義を見る

`ProjectileHitEvent`

投射物が当たったイベントです。

from mc_remote.minecraft import ProjectileHitEvent

フィールド	型	既定値・省略
`sequence`	`int`	`必須`
`dimension`	`str`	`必須`
`origin`	`tuple[int, int, int]`	`必須`
`projectile`	`str`	`必須`
`pos`	`tuple[int \| float, int \| float, int \| float]`	`必須`
`target`	`ProjectileTarget`	`必須`
`type`	`str`	`'projectile_hit'`

target.kindで当たった対象の種類を判断します。

定義を見る

`ProjectileTarget`

投射物が当たった対象の型のunionです。

from mc_remote.minecraft import ProjectileTarget

ProjectileTarget = BlockTarget | PlayerTarget | EntityTarget

定義を見る

`BlockTarget`

投射物が当たったブロックを表すデータクラスです。

from mc_remote.minecraft import BlockTarget

フィールド	型	既定値・省略
`pos`	`tuple[int, int, int]`	`必須`
`block`	`BlockValue`	`必須`
`face`	`str \| None`	`None`
`kind`	`str`	`'block'`

定義を見る

`PlayerTarget`

投射物がプレイヤーに当たったことを表すデータクラスです。

from mc_remote.minecraft import PlayerTarget

フィールド	型	既定値・省略
`kind`	`str`	`'player'`

定義を見る

`EntityTarget`

投射物が当たったエンティティのhandleを持つデータクラスです。

from mc_remote.minecraft import EntityTarget

フィールド	型	既定値・省略
`handle`	`EntityHandle`	`必須`
`kind`	`str`	`'entity'`

定義を見る

`WireScopeStation`

WireScopeの表示方法を選ぶ設定オブジェクトです。

from mc_remote.wirescope import WireScopeStation

WireScopeStation.local()で作り、Minecraft.create(wirescope=...)に渡します。wirescope=Trueも同じ設定の簡単な入口です。

定義を見る

例外と警告

サーバーの拒否はMcRpcErrorです。reason・code・message・dataを読めます。処理を分けるときはreasonを使います。Protocolのerror一覧も参照してください。
Python内の引数チェックではValueError/TypeErrorも発生します。通信の完了が不明なRequestTimeoutErrorは、操作が実行されなかったことを意味しません。

名前	意味	import元
`McRemoteError`	クライアント例外の基底	`mc_remote.minecraft`
`McRpcError`	サーバーのJSON-RPC error。reasonで理由を読む	`mc_remote.minecraft`
`ConnectionLostError`	接続が失われた	`mc_remote.minecraft`
`RequestTimeoutError`	送信後のタイムアウト。完了は不明	`mc_remote.minecraft`
`RequestFailedError`	McRpcErrorの互換用基底	`mc_remote.minecraft`
`PairingRequiredError`	pair=Falseで認証にpairingが必要	`mc_remote.minecraft`
`EventContextMismatchError`	イベントと現在の建築座標系が違う	`mc_remote.minecraft`
`CatalogProjectionError`	明示的な補完生成の失敗。stageで段階を読む	`mc_remote.minecraft`
`CatalogProjectionWarning`	create()での自動補完生成の失敗	`mc_remote.minecraft`
`WireScopeWarning`	WireScopeの起動・観測の警告	`mc_remote.minecraft`

短い作例

以下は接続方法と、接続済みのmcで行う操作の例です。localhostは同じPCの対応サーバーを指します。別のPCへ接続する場合はaddressを置き換えてください。 APIの作例はMinecraftへログインし、pairingと接続を済ませてから実行します。ブロックやエンティティを変更する例では復元・削除も行います。

接続してチャットを送る

必要ならターミナルに表示されたpair commandをMinecraft内で実行します。withを抜けると接続を閉じます。

from mc_remote import Minecraft

with Minecraft.create(address="localhost", port=25575) as mc:
    mc.postToChat("Hello, Minecraft!")

プレイヤーの位置を読む

以後の例のmcは接続済みのMinecraftオブジェクトです。posは現在の建築原点から相対です。

location = mc.getPos()
print(location["dimension"], location["pos"])

ブロックを置き、取得した値から戻す

原点のブロックを一時的にoak_logへ変えます。元のIDとstateを保存し、最後に戻します。

before = mc.getBlock(0, 0, 0)
try:
    mc.setBlock(0, 0, 0, "oak_log", state={"axis": "y"})
    value = mc.getBlock(0, 0, 0)
    print(value.block_id, dict(value.state))
finally:
    mc.setBlock(0, 0, 0, before.block_id, state=before.state)

エンティティを出し、poseを読んで削除する

牛を一時的に出します。handleを保存して操作し、最後に削除します。

handle = mc.spawnEntity(0, 2, 0, "cow")
try:
    pose = mc.getEntityPose(handle)
    print(pose["dimension"], pose["pos"])
finally:
    mc.removeEntity(handle)

青いdustを自分だけに見せる

ブロックを変更せず、建築原点の3ブロック上へパーティクルを出します。粒子は自然に消えます。

from mc_remote.minecraft import ParticleSpec

dust: ParticleSpec = {
    "particle_id": "dust",
    "receiver": "self",
    "data": {"color": [64, 160, 255], "size": 1.0},
}
count = mc.spawnParticle(0, 3, 0, 0, 0, 0, dust, 0, 8)
print(count)

音の高さをnoteで指定する

pairingした自分向けに鳴らします。辞書にまとめた設定はキーワード引数へ展開します。

from mc_remote.minecraft import SoundOptions

controls: SoundOptions = {"volume": 0.5, "note": 12, "receiver": "self"}
mc.playSound(0, 1, 0, "block.note_block.harp", **controls)

ブロックの音とサーバーの拒否理由

指定位置のブロックを変えず、hitの音を自分向けに鳴らします。airなどの場合はreasonで理由を確認します。

from mc_remote.minecraft import McRpcError

try:
    mc.playBlockSound(0, 0, 0, "hit", receiver="self")
except McRpcError as error:
    print(error.reason)

イベントを取得して読む

取得したイベントのtypeに応じて属性を読みます。pokeの位置を使う前には座標系の一致を確認します。

batch = mc.pollEvents(max_events=16)
for event in batch.events:
    if event.type == "pickaxe_poke":
        mc.assertEventContext(event)
        print(event.pos, event.block.block_id)
    elif event.type == "chat_posted":
        print(event.message)
    elif event.type == "projectile_hit":
        print(event.pos, event.target.kind)

ブロック設置のモードを変える

TRACEへ切り替え、現在のモードと待ち時間を読みます。

from mc_remote.minecraft import BuildMode

mc.setBuildMode(BuildMode.TRACE, trace_delay=0.1)
print(mc.build_mode, mc.trace_delay)

補完ファイルを更新する

現在のプロジェクトへ補完を生成します。Git管理下では先にmcremote initでignoreを設定します。

path = mc.sync_constants()
if path is not None:
    print(path)

一覧の更新

引数・型注釈・overload・定数の既定値・値オブジェクトのフィールド・版情報は実装から生成します。用途、戻り値の説明、作例は metadata で補っています。型注釈がない箇所の説明と、掲載する補助型・例外の範囲はドラフトのレビュー対象です。

uv run --frozen python scripts/build_client_api_reference.py
uv run --frozen python scripts/build_client_api_reference.py --check

生成器はPython 3.11以上で動き、サーバーへ接続せずにファイルを読みます。 CIでは生成結果の古さと、Minecraftの公開メソッド／propertyの掲載漏れを確認します。

FilesExpand file tree

python-api-reference_ja.md

Latest commit

History

python-api-reference_ja.md

File metadata and controls

PythonクライアントAPI一覧（ドラフト）

用途から探す

共通の読み方

接続と終了

Minecraft.create

mc.close

mc.flush

建築原点・次元・実行モード

mc.setDimension

mc.setBuildOrigin

mc.setBuildMode

mc.build_mode

mc.trace_delay

ブロック

mc.setBlock

mc.getBlock

mc.setBlocks

mc.getBlocks

mc.getHeight

プレイヤー

mc.getPos

mc.setPos

mc.getPose

mc.setPose

mc.getDirection

mc.setDirection

エンティティ

mc.spawnEntity

mc.getNearbyEntities

mc.getEntityPose

mc.setEntityPose

mc.getEntityDirection

mc.setEntityDirection

mc.removeEntity

看板

mc.getSign

mc.setSign

mc.updateSignLine

パーティクル・音・雷

mc.spawnParticle

mc.playSound

mc.playBlockSound

mc.strikeLightning

チャットとイベント

mc.postToChat

mc.pollEvents

mc.assertEventContext

カタログと補完

mc.getCatalog

mc.sync_constants

接続処理を組み立てるとき

mc.hello

mc.authenticate

入力・戻り値の型

BuildMode

BlockValue

BlockId

StateScalar

DirectionValue

EntityHandle

NearbyEntity

PoseValue

ParticleSpec

DustData

BlockParticleData

SoundOptions

LineValue

SignValue

EventBatch

EventValue

PickaxePokeEvent

ChatPostedEvent

ProjectileHitEvent

ProjectileTarget

`Minecraft.create`

`mc.close`

`mc.flush`

`mc.setDimension`

`mc.setBuildOrigin`

`mc.setBuildMode`

`mc.build_mode`

`mc.trace_delay`

`mc.setBlock`

`mc.getBlock`

`mc.setBlocks`

`mc.getBlocks`

`mc.getHeight`

`mc.getPos`

`mc.setPos`

`mc.getPose`

`mc.setPose`

`mc.getDirection`

`mc.setDirection`

`mc.spawnEntity`

`mc.getNearbyEntities`

`mc.getEntityPose`

`mc.setEntityPose`

`mc.getEntityDirection`

`mc.setEntityDirection`

`mc.removeEntity`

`mc.getSign`

`mc.setSign`

`mc.updateSignLine`

`mc.spawnParticle`

`mc.playSound`

`mc.playBlockSound`

`mc.strikeLightning`

`mc.postToChat`

`mc.pollEvents`

`mc.assertEventContext`

`mc.getCatalog`

`mc.sync_constants`

`mc.hello`

`mc.authenticate`

`BuildMode`

`BlockValue`

`BlockId`

`StateScalar`

`DirectionValue`

`EntityHandle`

`NearbyEntity`

`PoseValue`

`ParticleSpec`

`DustData`

`BlockParticleData`

`SoundOptions`

`LineValue`

`SignValue`

`EventBatch`

`EventValue`

`PickaxePokeEvent`

`ChatPostedEvent`

`ProjectileHitEvent`

`ProjectileTarget`

`BlockTarget`

`PlayerTarget`

`EntityTarget`

`WireScopeStation`