API一覧（b8 / protocol 23.2.0）
公開済みのrelease b8（protocol 23.2.0、artifact 2320.0.0b8、 Minecraft 1.21.11、2026-10-03公開）で使えるProtocol APIの一覧です。 各言語のClient Libraryでの書き方は、それぞれのリポジトリを見てください。
このページは、仕様の正本wire-format-designの§4コマンド表と§7.3 error表から 自動生成しています。正確な条件、検証の順序、上限は正本を見てください。機械可読版（api.json）
接続 ／ 建築の文脈 ／ ブロック ／ 看板 ／ プレイヤー ／ エンティティ ／ 演出（パーティクル・音・雷） ／ チャット ／ イベント ／ カタログ ／ 認証 ／ エラー応答
接続
| メソッド | 用途 | パラメーター（params） | 応答 | 備考（wireの記述） |
|---|---|---|---|---|
hello | 接続の最初に一度だけ送り、protocolの照合、認証、建築の文脈の受け取りをする | object（§6） | あり | 接続ハンドシェイク。1接続に1回。identity/auth/build を担う |
connection.flush | それまでに送ったcommandが処理されたことを確かめる区切り | [] | null | 同一connectionの先行commandに対する明示barrier（§3.5） |
建築の文脈
| メソッド | 用途 | パラメーター（params） | 応答 | 備考（wireの記述） |
|---|---|---|---|---|
build.setDimension | 建築する次元（overworld、the_nether など）を変える | [dimension_ref] | {dimension,origin} | protocol 22のstream-local DimensionKeyを変更（§5.1） |
build.setOrigin | 座標の原点を変える | [x, y, z] | {dimension,origin} | build originを変更し、server正準build contextを返す |
ブロック
| メソッド | 用途 | パラメーター（params） | 応答 | 備考（wireの記述） |
|---|---|---|---|---|
world.setBlock | ブロックを1つ置く | [x, y, z, blockSpec] | id付きはnull / notification時なし | protocol 22では構造化BlockSpecで1ブロック設置（§7.1） |
world.setBlocks | 直方体の範囲をブロックで埋める | [x1, y1, z1, x2, y2, z2, blockSpec] | id付きはnull / notification時なし | protocol 22では構造化BlockSpecで直方体充填（§7.1） |
world.getBlock | ブロックを1つ調べる | [x, y, z] | あり | protocol 22では構造化BlockValueを返す（§7.1） |
world.getBlocks | 直方体の範囲のブロックをまとめて調べる | [x1, y1, z1, x2, y2, z2] | BlockValue[] | protocol 22の有界領域query（§7.1.1） |
world.getHeight | その位置のいちばん上の地面の高さを調べる | [x, z]または[x, z, max_y] | あり | origin相対の最上面block高を返す（b5、§5.6） |
看板
| メソッド | 用途 | パラメーター（params） | 応答 | 備考（wireの記述） |
|---|---|---|---|---|
world.getSign | 看板の両面の文字を読む | [x, y, z] | {front:[LineValue×4],back:[LineValue×4],waxed:bool} | signの両面とwaxedを正準形で取得（b6、§5.8.1） |
world.setSign | 看板の面の文字を4行まとめて書き換える | [x, y, z, {front?:[LineSpec×4],back?:[LineSpec×4]}] | null | 指定面を面内no-mergeの厳密4行へ置換（b6、§5.8.1） |
world.updateSignLine | 看板の1行だけを書き換える | [x, y, z, face, line_index, LineSpec] | null | signの一面・一行だけをPATCH（b6、§5.8.1） |
プレイヤー
| メソッド | 用途 | パラメーター（params） | 応答 | 備考（wireの記述） |
|---|---|---|---|---|
player.getPos | 自分の位置を調べる | [] | あり | paired playerの現在dimensionと現在位置をstream origin相対で返す（§5.2） |
player.setPos | 自分を移動させる | [dimension_ref, x, y, z] | あり | paired playerを指定dimensionのstream origin相対位置へteleportする（§5.2） |
player.getPose | 自分の位置と向きを調べる | [] | あり | paired playerの現在dimension・位置・向きをstream origin相対で返す（§5.3） |
player.setPose | 自分の位置と向きをまとめて変える | [dimension_ref, x, y, z, yaw, pitch] | あり | 指定dimensionへ位置・向きを1回のteleportで一体反映する（§5.3） |
player.getDirection | 自分の向いている方向を調べる | [] | DirectionValue | paired playerの現在方向を返す（b7、§5.8.2） |
player.setDirection | 自分の向きだけを変える | [x,y,z] | 適用後のDirectionValue | 非zero vectorを正規化してpaired playerの向きだけを変える（b7、§5.8.2） |
エンティティ
| メソッド | 用途 | パラメーター（params） | 応答 | 備考（wireの記述） |
|---|---|---|---|---|
world.spawnEntity | エンティティ（動物など）を出し、あとで操作するためのhandleを受け取る | [x, y, z, entity] | あり | entityを生成しepoch-scoped handleを返す（b5、§5.7） |
world.getNearbyEntities | 近くのエンティティを探して一覧を受け取る | [x, y, z, radius, max_entities] | あり | boundedな近傍entity検索。playerを除外。[{handle,type,pos}, ...]、0件は[]（b8、§5.8.3） |
entity.getPose | エンティティの位置と向きを調べる | [handle] | あり | handle対象のpose {dimension,pos,yaw,pitch}を返す（b8、§5.8.3） |
entity.setPose | エンティティの位置と向きをまとめて変える | [handle, dimension_ref, x, y, z, yaw, pitch] | あり | 1回のteleportでposeを一体更新し、再読取りしたposeを返す（b8、§5.8.3） |
entity.getDirection | エンティティの向いている方向を調べる | [handle] | DirectionValue | handle対象の現在方向を返す（b7、§5.8.2） |
entity.setDirection | エンティティの向きだけを変える | [handle,x,y,z] | 適用後のDirectionValue | 非zero vectorを正規化してhandle対象の向きだけを変える（b7、§5.8.2） |
entity.remove | エンティティを消す | [handle] | あり | entityを除去しhandleを即時失効。成功時null（b8、§5.8.3） |
演出（パーティクル・音・雷）
| メソッド | 用途 | パラメーター（params） | 応答 | 備考（wireの記述） |
|---|---|---|---|---|
world.spawnParticle | パーティクルを出す（色や大きさ、見せる相手も選べる） | [x, y, z, offset_x, offset_y, offset_z, particle, speed, count, (force)] | あり | 9／10 params、force省略時true。b8でparticleにobject形ParticleSpecを追加（§5.7／§5.8.3） |
world.playSound | 位置から音を鳴らす | [x, y, z, sound_id, (options)] | null | 位置から音を鳴らす。receiverはworld／self（b8、§5.8.3） |
world.playBlockSound | その位置のブロックの音（置く、叩く、壊すなど）を鳴らす | [x, y, z, kind, (options)] | null | その位置のblockの音を鳴らす（b8、§5.8.3） |
world.strikeLightning | 雷を落とす | [x,y,z] | null | current dimensionのorigin相対位置へdamage-capableなfull lightningを要求する（b7、§5.8.2） |
チャット
| メソッド | 用途 | パラメーター（params） | 応答 | 備考（wireの記述） |
|---|---|---|---|---|
chat.post | チャットに書き込む | [msg] | id付きrequestの成功resultはnull（b9から、2026-10-03-01） / notification 時なし | チャット送信 |
イベント
| メソッド | 用途 | パラメーター（params） | 応答 | 備考（wireの記述） |
|---|---|---|---|---|
events.poll | 起きたイベント（つつく、チャット、矢が当たるなど）を受け取る | [after_sequence]／[after_sequence, {max_events}] | あり | epoch-scoped event ringを非破壊取得。filterは初回stable後の候補（§5.4、2026-09-30-03） |
カタログ
| メソッド | 用途 | パラメーター（params） | 応答 | 備考（wireの記述） |
|---|---|---|---|---|
catalog.get | サーバーで使えるブロック、エンティティ、パーティクルの一覧を受け取る | [] | あり | 稼働中 registry から block/entity/particle catalog を取得（b3 実装予定、§7.2.1） |
認証
ペアリングとcredential管理は、表とは別に正本の§6.5 ペアリング、§6.6 credential管理で定めています。
| メソッド | 用途 |
|---|---|
auth.pairBegin | ペアリングを始め、Minecraftで承認するためのコードを受け取る |
auth.pairPoll | ペアリングが承認されたかを確かめ、承認されたらtokenを受け取る |
auth.listCredentials | 自分の長期credentialの一覧を見る |
auth.revoke | 長期credentialを取り消す |
auth.logout | 今使っている長期credentialを取り消して終わる |
エラー応答（reason）
失敗したときは、JSON-RPCのerrorのdata.reasonで理由を見分けます。
| 理由（reason） | コード（code） | 分類 | 意味 | 導入 |
|---|---|---|---|---|
unknown_block | -32602（Invalid params） | block検証 | block_idがblock不在（無印補完後の未知名含む） | ○ |
unknown_property | -32602（Invalid params） | block検証 | property名がそのblockに無い | ○ |
invalid_property_value | -32602（Invalid params） | property検証 | block state、sign色／装飾等の値が許容外。allowedを返せる | b1、signはb6 |
invalid_params | -32602（Invalid params） | params 検証 | JSON-RPC params の形・型・座標値が不正 | b2 |
zero_direction | -32602（Invalid params） | params 検証 | directionの3成分がsigned zeroだけで向きを定義できない | b7 |
unknown_dimension | -32602（Invalid params） | params 検証 | 指定DimensionKeyがloaded dimensionとして解決できない | b5／protocol 22 |
build_denied | -32000番台（実装定義域） | world-state | build policy / 範囲 / 認可により操作拒否。返せる場合は data.bounds / data.violating 等で理由を補足 | ○ |
permission_denied | -32000番台（実装定義域） | player-state | LuckPerms 等の認可により操作拒否。token は温存 | b2 |
player_offline | -32000番台（実装定義域） | player-state | token は有効だが paired player がオンラインでない | b2 |
teleport_failed | -32000番台（実装定義域） | player-state | player.setPose、entity.setPose等のteleport自体がpermission_denied／player_offline／unknown_dimension／invalid_params以外の要因で失敗 | b5／protocol 22、entity.setPoseはb8 |
height_not_found | -32000番台（実装定義域） | world-query | 指定上限以下に「非passableかつ直上passable」のblockが無い | b5 |
no_block | -32000番台（実装定義域） | world-state | world.playBlockSoundの位置のblockが空気 | b8 |
not_a_sign | -32000番台（実装定義域） | sign-state | 指定座標のblockがsignでない | b6 |
sign_waxed | -32000番台（実装定義域） | sign-state | waxed signへのwriteを拒否。readは許可 | b6 |
sign_update_failed | -32000番台（実装定義域） | sign-state | mutation時にstale snapshot等を検出し、部分変更なしでwriteを拒否 | b6 |
unknown_particle | -32602（Invalid params） | resource-ref | particle ID（§5.0.2で補った後）がregistryに無い、または非正準形 | b5 |
particle_data_required | -32602（Invalid params） | resource-ref | typed data必須particleでdataが欠落（文字列shorthandを含む） | b5、b8で意味を精密化 |
particle_data_unsupported | -32602（Invalid params） | resource-ref | 登録済みだが、B8でdata型に対応しないparticleへ、objectでdataを指定して要求 | b8 |
unknown_entity | -32602（Invalid params） | resource-ref | entity ID（§5.0.2で補った後）がregistryに無い、または非正準形 | b5 |
entity_not_spawnable | -32602（Invalid params） | resource-ref | playerまたはspawnを許可しないentity type | b5 |
unknown_sound | -32602（Invalid params） | resource-ref | sound ID（§5.0.2で補った後）がRegistry.SOUND_EVENTに無い、または非正準形 | b8 |
backpressure | -32000番台（実装定義域） | availability | 副作用開始前の一時的な処理能力超過。同一要求を後でretry可能 | b5 |
work_limit_exceeded | -32000番台（実装定義域） | availability | 入力量または走査量がwork上限を超過。自動retryせず入力を縮小する | b5 |
entity_capacity_exhausted | -32000番台（実装定義域） | availability | handle slotを副作用前に予約できない。自動retryしない | b5 |
entity_handle_not_found | -32000番台（実装定義域） | entity-state | foreign／unknown handle。存在差を公開しない | b5 |
entity_removed | -32000番台（実装定義域） | entity-state | known handleの対象entityが除去済み | b5 |
entity_unloaded | -32000番台（実装定義域） | entity-state | known handleの対象entityがunloadされ現在操作不能 | b5 |
entity_dimension_changed | -32000番台（実装定義域） | entity-state | 対象entityが外部要因でissued dimensionから移動。b7 directionでは初回検出時にhandleを失効 | b5、b7 |
entity_spawn_failed | -32000番台（実装定義域） | entity-state | admission後のspawn自体が失敗 | b5 |
entity_not_found | -32000番台（実装定義域） | entity-state | b7 directionでempty／foreign／unknown／旧epoch／旧形式、または失効後のhandleを同値化 | b7 |
entity_unavailable | -32000番台（実装定義域） | entity-state | b7 directionでknown handleの対象が最初にremoved／unloaded／invalidと判明し、その場で失効 | b7 |
internal_error | -32603（Internal error） | server-state | 結果が確定できない。非冪等操作を自動retryしない | b5 |
credential_not_found | -32602（Invalid params） | params 検証 | auth.revoke で指定した credential_id が要求元 UUID の active credential に無い（他 player の ID と存在しない ID を同値へ畳んで存在を隠す）。caller の token は温存し、ref に credential_id を返す | bN |
credential_limit_reached | -32000番台（実装定義域） | credential-state | UUID ごとの active long-lived credential 上限に到達。data.type / data.limit / data.active を返す。古い credential を自動失効させず、ユーザーが list / revoke する | bN |
credential_store_unavailable | -32000番台（実装定義域） | auth-service | server が credential 状態を現在検証できない、または credential 管理操作の durable な結果を確定できない。data.operation（resolve/issue/list/revoke/touch）を返す。単独では token を invalid と分類せず、client は token を削除せず自動再ペアリングもしない（token 温存・再試行） | bN |