API 參考

由 MCPyLib 1.2.1 的 client.py 產生。每個方法送出一個請求並回傳結果,失敗就拋出例外。

用戶端

一台伺服器一個 MCPyLib。第一次呼叫時連線,之後保持連線,斷線時自動重連一次。

MCPyLib

MCPyLib(
    ip: str = '127.0.0.1',
    port: int = 65535,
    token: str = '',
    timeout: float = 10.0,
)

與 Minecraft 伺服器互動的主要用戶端類別

參數

ipstr= '127.0.0.1'

伺服器 IP 位址

portint= 65535

伺服器連接埠

tokenstr= ''

驗證用的權杖

timeoutfloat= 10.0

Socket 逾時秒數

範例

>>> mc = MCPyLib(ip="127.0.0.1", port=65535, token="your_token")
>>> mc.setblock(100, 64, 200, "minecraft:stone")
1
>>> mc.getblock(100, 64, 200)
'minecraft:stone'

client.py 第 47 行

情境管理器

用 with 區塊,離開時自動關閉連線。

from mcpylib import MCPyLib

with MCPyLib(token="YOUR_TOKEN") as mc:
    mc.setblock(0, 64, 0, "stone")
# The connection is closed here.

例外

所有錯誤都繼承自 MCPyLibError。伺服器的錯誤訊息提到 token 時,用戶端拋出 AuthenticationError;其他失敗的指令則拋出 CommandError。

  • MCPyLibError(Exception)所有 MCPyLib 錯誤的基底例外
  • ConnectionError(MCPyLibError)無法連線到伺服器時拋出
  • AuthenticationError(MCPyLibError)驗證失敗時拋出
  • CommandError(MCPyLibError)指令執行失敗時拋出

從 mcpylib 匯入 ConnectionError,會蓋掉該模組裡 Python 內建的同名例外。

方塊

放置、讀取、複製與大量編輯方塊。大型建築用 edit() 最快。

setblock

mc.setblock(
    x: int,
    y: int,
    z: int,
    block_name: str,
    block_state: dict = None,
    nbt: dict = None,
) -> int

在指定座標放置方塊

參數

xint必填

X 座標

yint必填

Y 座標

zint必填

Z 座標

block_namestr必填

方塊類型(例如 "minecraft:stone")

block_statedict= None

選用的方塊狀態屬性(例如 {"facing": "north", "half": "bottom"})。方塊的任何原版屬性都可使用。

nbtdict= None

選用的方塊實體資料。只會套用兩種鍵:"CustomName"(純文字,用於箱子等容器)與 "Text1"-"Text4"(告示牌各行)。其他鍵會被忽略。

回傳值

int 成功時回傳 1

例外

  • ConnectionError 連線失敗時
  • AuthenticationError 驗證失敗時
  • CommandError 指令執行失敗時

範例

>>> mc.setblock(100, 64, 200, "minecraft:stone")
1
>>> mc.setblock(100, 64, 200, "minecraft:oak_stairs", block_state={"facing": "north", "half": "bottom"})
1
>>> mc.setblock(100, 64, 200, "minecraft:chest", nbt={"CustomName": "My Chest"})
1

協定動作 setblockclient.py 第 228 行

getblock

mc.getblock(x: int, y: int, z: int) -> str

取得指定座標的方塊類型

參數

xint必填

X 座標

yint必填

Y 座標

zint必填

Z 座標

回傳值

str 方塊類型(例如 "minecraft:stone")

例外

  • ConnectionError 連線失敗時
  • AuthenticationError 驗證失敗時
  • CommandError 指令執行失敗時

範例

>>> mc.getblock(100, 64, 200)
'minecraft:stone'

協定動作 getblockclient.py 第 281 行

getblocks

mc.getblocks(
    x1: int,
    y1: int,
    z1: int,
    x2: int,
    y2: int,
    z2: int,
) -> List[List[List[str]]]

以三維陣列取得矩形區域內的所有方塊

回傳與 edit() 相同 [x][y][z] 格式的三維陣列,因此可以讀取區域、修改後再用 edit() 寫回。

參數

x1int必填

起點 X 座標

y1int必填

起點 Y 座標

z1int必填

起點 Z 座標

x2int必填

終點 X 座標

y2int必填

終點 Y 座標

z2int必填

終點 Z 座標

回傳值

List[List[List[str]]] 方塊類型的三維串列 [x][y][z](例如 "minecraft:stone")

例外

  • ConnectionError 連線失敗時
  • AuthenticationError 驗證失敗時
  • CommandError 指令執行失敗時

範例

>>> blocks = mc.getblocks(100, 64, 200, 102, 65, 202)
>>> print(blocks[0][0][0])
'minecraft:stone'
>>> # Read, modify, and write back
>>> blocks = mc.getblocks(100, 64, 200, 110, 68, 210)
>>> for x in range(len(blocks)):
...     for y in range(len(blocks[0])):
...         for z in range(len(blocks[0][0])):
...             if blocks[x][y][z] == "minecraft:stone":
...                 blocks[x][y][z] = "minecraft:diamond_block"
>>> mc.edit(min(100, 110), min(64, 68), min(200, 210), blocks)

協定動作 getblocksclient.py 第 308 行

fill

mc.fill(
    x1: int,
    y1: int,
    z1: int,
    x2: int,
    y2: int,
    z2: int,
    block_name: str,
) -> int

以指定方塊填滿區域

參數

x1int必填

起點 X 座標

y1int必填

起點 Y 座標

z1int必填

起點 Z 座標

x2int必填

終點 X 座標

y2int必填

終點 Y 座標

z2int必填

終點 Z 座標

block_namestr必填

方塊類型(例如 "minecraft:glass")

回傳值

int 受影響的方塊數

例外

  • ConnectionError 連線失敗時
  • AuthenticationError 驗證失敗時
  • CommandError 指令執行失敗時

範例

>>> mc.fill(100, 64, 200, 110, 74, 210, "minecraft:glass")  # 11x11x11, corners inclusive
1331

協定動作 fillclient.py 第 358 行

clone

mc.clone(
    x1: int,
    y1: int,
    z1: int,
    x2: int,
    y2: int,
    z2: int,
    dest_x: int,
    dest_y: int,
    dest_z: int,
) -> int

把一個區域的方塊複製到新位置

參數

x1int必填

來源區域起點 X 座標

y1int必填

來源區域起點 Y 座標

z1int必填

來源區域起點 Z 座標

x2int必填

來源區域終點 X 座標

y2int必填

來源區域終點 Y 座標

z2int必填

來源區域終點 Z 座標

dest_xint必填

目的地 X 座標

dest_yint必填

目的地 Y 座標

dest_zint必填

目的地 Z 座標

回傳值

int 複製的方塊數

例外

  • ConnectionError 連線失敗時
  • AuthenticationError 驗證失敗時
  • CommandError 區域過大時(最多 32768 個方塊)

範例

>>> mc.clone(0, 64, 0, 10, 74, 10, 20, 64, 0)  # 11x11x11, corners inclusive
1331

協定動作 cloneclient.py 第 1106 行

edit

mc.edit(
    x: int,
    y: int,
    z: int,
    blocks: List[List[List]],
) -> int

高效能地大量編輯三維區域的方塊(類似 WorldEdit)

這個方法能在單一操作中快速放置大量不同的方塊,非常適合建造大型建築與結構,比反覆呼叫 setblock 快得多。

參數

xint必填

起點 X 座標

yint必填

起點 Y 座標

zint必填

起點 Z 座標

blocksList[List[List]]必填

方塊的 3D 陣列 [x][y][z],每個元素可以是:

  • str:方塊名稱(例如 "minecraft:stone")
  • None:略過此位置(保持不變)
  • dict:帶有狀態與 NBT 的複合方塊:
    {
        "block": "minecraft:chest",
        "block_state": {"facing": "north"},  # 選用
        "nbt": {"CustomName": "Storage"}  # 選用,鍵與 setblock() 相同
    }
    門、床和高花草只要給一格(下半部或床尾),另一半會自動補上,除非陣列本身已經設定了那個位置。

回傳值

int 放置的方塊數(None 項目與自動補上的另一半不計入)

例外

  • ConnectionError 連線失敗時
  • AuthenticationError 驗證失敗時
  • CommandError 方塊資料或座標無效時

範例

>>> # Simple 2x2x2 cube of stone and glass
>>> blocks = [
...     [["stone", "glass"], ["stone", "glass"]],
...     [["stone", "glass"], ["stone", "glass"]]
... ]
>>> mc.edit(100, 64, 200, blocks)
8
>>> # Mixed mode with simple and complex blocks
>>> blocks = [
...     [[None, "stone"], ["glass", None]],
...     [[{
...         "block": "minecraft:chest",
...         "block_state": {"facing": "north"},
...         "nbt": {"CustomName": "Loot"}
...     }, "stone"], ["diamond_block", "gold_block"]]
... ]
>>> mc.edit(100, 64, 200, blocks)
6
>>> # Build a 10x5x10 house with different materials
>>> import numpy as np
>>> blocks = np.full((10, 5, 10), None, dtype=object)
>>> # Floor
>>> blocks[:, 0, :] = "stone"
>>> # Walls
>>> blocks[0, :, :] = "cobblestone"
>>> blocks[9, :, :] = "cobblestone"
>>> blocks[:, :, 0] = "cobblestone"
>>> blocks[:, :, 9] = "cobblestone"
>>> # Roof
>>> blocks[:, 4, :] = "oak_planks"
>>> mc.edit(100, 64, 200, blocks.tolist())
308

協定動作 bulkEditclient.py 第 1147 行

玩家

查詢與傳送玩家、切換遊戲模式、給予物品、設定重生點與進度。

getPos

mc.getPos(username: str) -> List[int]

取得玩家位置

參數

usernamestr必填

玩家名稱

回傳值

List[int] [x, y, z] 座標串列

例外

  • ConnectionError 連線失敗時
  • AuthenticationError 驗證失敗時
  • CommandError 指令執行失敗時(例如找不到玩家)

範例

>>> mc.getPos("Steve")
[100, 64, 200]

協定動作 getPosclient.py 第 398 行

teleport

mc.teleport(
    username: str,
    x: float,
    y: float,
    z: float,
    yaw: float = None,
    pitch: float = None,
) -> bool

把玩家傳送到指定座標

參數

usernamestr必填

玩家名稱

xfloat必填

X 座標

yfloat必填

Y 座標

zfloat必填

Z 座標

yawfloat= None

選用的水平旋轉角(yaw)

pitchfloat= None

選用的垂直旋轉角(pitch)

回傳值

bool 成功時回傳 True

例外

  • ConnectionError 連線失敗時
  • AuthenticationError 驗證失敗時
  • CommandError 找不到玩家或傳送失敗時

範例

>>> mc.teleport("Steve", 100, 64, 200)
True
>>> mc.teleport("Steve", 100, 64, 200, yaw=90.0, pitch=0.0)
True

協定動作 teleportclient.py 第 421 行

gamemode

mc.gamemode(username: str, mode: str) -> bool

變更玩家的遊戲模式

參數

usernamestr必填

玩家名稱

modestr必填

遊戲模式(survival、creative、adventure、spectator)

回傳值

bool 成功時回傳 True

例外

  • ConnectionError 連線失敗時
  • AuthenticationError 驗證失敗時
  • CommandError 找不到玩家或遊戲模式無效時

範例

>>> mc.gamemode("Steve", "creative")
True
>>> mc.gamemode("Steve", "survival")
True

協定動作 gamemodeclient.py 第 460 行

give

mc.give(username: str, item: str, amount: int = 1) -> bool

給予玩家物品

參數

usernamestr必填

玩家名稱

itemstr必填

物品類型(例如 "minecraft:diamond")

amountint= 1

數量(1–64,預設 1)

回傳值

bool 成功時回傳 True

例外

  • ConnectionError 連線失敗時
  • AuthenticationError 驗證失敗時
  • CommandError 找不到玩家、物品無效或數量超出範圍時

範例

>>> mc.give("Steve", "minecraft:diamond", 10)
True
>>> mc.give("Steve", "diamond_sword")
True

協定動作 giveclient.py 第 551 行

spawnpoint

mc.spawnpoint(
    username: str,
    x: float = None,
    y: float = None,
    z: float = None,
) -> bool

設定玩家的重生點

參數

usernamestr必填

玩家名稱

xfloat= None

X 座標(預設為玩家目前位置)

yfloat= None

Y 座標(預設為玩家目前位置)

zfloat= None

Z 座標(預設為玩家目前位置)

回傳值

bool 成功時回傳 True

例外

  • ConnectionError 連線失敗時
  • AuthenticationError 驗證失敗時
  • CommandError 找不到玩家時

範例

>>> mc.spawnpoint("Steve", 100, 64, 200)
True
>>> mc.spawnpoint("Steve")  # Use current position
True

協定動作 spawnpointclient.py 第 1698 行

advancement

mc.advancement(
    username: str,
    action: str,
    advancement_key: str,
) -> bool

授予、撤銷或查詢玩家的進度

參數

usernamestr必填

玩家名稱

actionstr必填

動作("grant"、"revoke" 或 "query")

advancement_keystr必填

進度鍵值(例如 "story/mine_stone"、"minecraft:story/iron_tools")

回傳值

bool grant/revoke 成功時回傳 True;query 時回傳是否已完成的布林值

例外

  • ConnectionError 連線失敗時
  • AuthenticationError 驗證失敗時
  • CommandError 找不到玩家或進度無效時

範例

>>> mc.advancement("Steve", "grant", "story/mine_stone")
True
>>> mc.advancement("Steve", "query", "story/mine_stone")
True

協定動作 advancementclient.py 第 2265 行

效果與經驗

狀態效果、經驗值與等級,以及附魔。

effect

mc.effect(
    username: str,
    effect_type: str,
    duration: int = 30,
    amplifier: int = 0,
    hide_particles: bool = False,
) -> bool

對玩家套用藥水效果

參數

usernamestr必填

玩家名稱

effect_typestr必填

效果類型(例如 "speed"、"strength"、"minecraft:invisibility")

durationint= 30

持續秒數(預設 30)

amplifierint= 0

效果強度/等級(0 = 等級 I,1 = 等級 II,依此類推)

hide_particlesbool= False

是否隱藏效果粒子

回傳值

bool 效果套用成功時回傳 True

例外

  • ConnectionError 連線失敗時
  • AuthenticationError 驗證失敗時
  • CommandError 找不到玩家或效果類型無效時

範例

>>> mc.effect("Steve", "speed", duration=60, amplifier=1)
True
>>> mc.effect("Steve", "minecraft:invisibility", hide_particles=True)
True

協定動作 effectclient.py 第 1311 行

clearEffect

mc.clearEffect(
    username: str,
    effect_type: str = None,
) -> bool

移除玩家身上的藥水效果

參數

usernamestr必填

玩家名稱

effect_typestr= None

要移除的效果;None 表示移除全部效果

回傳值

bool 成功時回傳 True

例外

  • ConnectionError 連線失敗時
  • AuthenticationError 驗證失敗時
  • CommandError 找不到玩家或效果類型無效時

範例

>>> mc.clearEffect("Steve", "speed")
True
>>> mc.clearEffect("Steve")  # Remove all effects
True

協定動作 clearEffectclient.py 第 1345 行

experience

mc.experience(
    username: str,
    action: str,
    amount: int = 0,
    target: str = 'points',
) -> dict

管理玩家的經驗值與等級

參數

usernamestr必填

玩家名稱

actionstr必填

要執行的動作("add"、"set" 或 "query")

amountint= 0

經驗點數或等級數量。注意:target="points" 搭配 "set" 只會設定目前等級內的進度條(amount ÷ 升到下一級所需點數,限制在 0–1)。

targetstr= 'points'

目標類型("points" 或 "levels")

回傳值

dict 包含 level、points(總經驗值,由等級與進度算出)、progress 的字典

例外

  • ConnectionError 連線失敗時
  • AuthenticationError 驗證失敗時
  • CommandError 找不到玩家或動作無效時

範例

>>> mc.experience("Steve", "add", 100)
{'level': 7, 'points': 100, 'progress': 0.43}
>>> mc.experience("Steve", "set", 10, target="levels")
{'level': 10, 'points': 172, 'progress': 0.43}
>>> mc.experience("Steve", "query")
{'level': 10, 'points': 172, 'progress': 0.43}

協定動作 experienceclient.py 第 1398 行

enchant

mc.enchant(
    username: str,
    enchantment: str,
    level: int = 1,
) -> bool

附魔玩家主手上的物品

參數

usernamestr必填

玩家名稱

enchantmentstr必填

附魔名稱(例如 "sharpness"、"minecraft:unbreaking")

levelint= 1

附魔等級(預設 1)

回傳值

bool 成功時回傳 True

例外

  • ConnectionError 連線失敗時
  • AuthenticationError 驗證失敗時
  • CommandError 找不到玩家、手上沒有物品或附魔無效時

範例

>>> mc.enchant("Steve", "sharpness", 5)
True

協定動作 enchantclient.py 第 2155 行

物品欄

讀取與修改物品欄格位。

clear

mc.clear(
    username: str,
    item: str = None,
    max_count: int = -1,
) -> int

清除玩家物品欄中的物品

參數

usernamestr必填

玩家名稱

itemstr= None

要清除的物品類型(例如 "diamond");None 表示全部清除

max_countint= -1

最多移除的物品數(-1 表示全部)

回傳值

int 移除的物品數

例外

  • ConnectionError 連線失敗時
  • AuthenticationError 驗證失敗時
  • CommandError 找不到玩家或物品類型無效時

範例

>>> mc.clear("Steve")  # Clear entire inventory
64
>>> mc.clear("Steve", "diamond", 10)  # Remove up to 10 diamonds
10

協定動作 clearclient.py 第 1371 行

getItem

mc.getItem(username: str, slot: int) -> dict

取得玩家物品欄某一格的物品資訊

參數

usernamestr必填

玩家名稱

slotint必填

物品欄格位編號(主物品欄為 0–35)

回傳值

dict 包含 item、amount 與附魔(若有)的字典。空格位回傳 {'amount': 0}(不含 "item" 鍵)。

例外

  • ConnectionError 連線失敗時
  • AuthenticationError 驗證失敗時
  • CommandError 找不到玩家或格位無效時

範例

>>> mc.getItem("Steve", 0)
{'item': 'minecraft:diamond_sword', 'amount': 1, 'enchantments': {'sharpness': 5}}

協定動作 getItemclient.py 第 2182 行

setItem

mc.setItem(
    username: str,
    slot: int,
    item: str,
    amount: int = 1,
) -> bool

設定玩家物品欄某一格的物品

參數

usernamestr必填

玩家名稱

slotint必填

物品欄格位編號(主物品欄為 0–35)

itemstr必填

物品類型(例如 "diamond_sword"、"minecraft:golden_apple")

amountint= 1

物品數量(預設 1)

回傳值

bool 成功時回傳 True

例外

  • ConnectionError 連線失敗時
  • AuthenticationError 驗證失敗時
  • CommandError 找不到玩家、格位無效或物品無效時

範例

>>> mc.setItem("Steve", 0, "diamond_sword")
True

協定動作 setItemclient.py 第 2205 行

世界設定

時間、天氣、難度、遊戲規則、重生點、世界邊界與區塊載入。

time

mc.time(action: str, value: int = None) -> int

控制世界時間

參數

actionstr必填

要執行的動作(set、add、query)

valueint= None

set/add 動作使用的時間值(0–24000)

回傳值

int 目前的世界時間

例外

  • ConnectionError 連線失敗時
  • AuthenticationError 驗證失敗時
  • CommandError 動作無效或數值超出範圍時

範例

>>> mc.time("set", 1000)
1000
>>> mc.time("add", 6000)
7000
>>> mc.time("query")
7000

協定動作 timeclient.py 第 487 行

weather

mc.weather(condition: str, duration: int = None) -> bool

控制世界天氣

參數

conditionstr必填

天氣狀態(clear、rain、thunder)

durationint= None

選用的持續秒數

回傳值

bool 成功時回傳 True

例外

  • ConnectionError 連線失敗時
  • AuthenticationError 驗證失敗時
  • CommandError 天氣狀態無效時

範例

>>> mc.weather("clear")
True
>>> mc.weather("rain", duration=600)
True
>>> mc.weather("thunder", duration=300)
True

協定動作 weatherclient.py 第 519 行

difficulty

mc.difficulty(level: str) -> bool

設定世界難度

參數

levelstr必填

難度("peaceful"、"easy"、"normal"、"hard")

回傳值

bool 成功時回傳 True

例外

  • ConnectionError 連線失敗時
  • AuthenticationError 驗證失敗時
  • CommandError 難度無效時

範例

>>> mc.difficulty("hard")
True

協定動作 difficultyclient.py 第 1435 行

gamerule

mc.gamerule(rule: str, value: str = None) -> str

查詢或設定遊戲規則

參數

rulestr必填

遊戲規則名稱(例如 "keep_inventory"、"mob_griefing";舊版的駝峰式名稱如 "keepInventory" 也可使用)

valuestr= None

要設定的值;None 表示查詢目前的值

回傳值

str 遊戲規則目前的值(字串)

例外

  • ConnectionError 連線失敗時
  • AuthenticationError 驗證失敗時
  • CommandError 遊戲規則無效時

範例

>>> mc.gamerule("doDaylightCycle", "false")
'false'
>>> mc.gamerule("keep_inventory")
'false'

協定動作 gameruleclient.py 第 1456 行

defaultgamemode

mc.defaultgamemode(mode: str) -> bool

設定新玩家的預設遊戲模式

參數

modestr必填

遊戲模式(survival、creative、adventure、spectator)

回傳值

bool 成功時回傳 True

例外

  • ConnectionError 連線失敗時
  • AuthenticationError 驗證失敗時
  • CommandError 遊戲模式無效時

範例

>>> mc.defaultgamemode("creative")
True

協定動作 defaultgamemodeclient.py 第 2571 行

setworldspawn

mc.setworldspawn(x: int, y: int, z: int) -> bool

設定世界重生點

參數

xint必填

X 座標

yint必填

Y 座標

zint必填

Z 座標

回傳值

bool 成功時回傳 True

例外

  • ConnectionError 連線失敗時
  • AuthenticationError 驗證失敗時
  • CommandError 設定重生點失敗時

範例

>>> mc.setworldspawn(0, 64, 0)
True

協定動作 setworldspawnclient.py 第 1729 行

worldborder

mc.worldborder(
    action: str,
    value: float = None,
    time: int = None,
    x: float = None,
    z: float = None,
) -> dict

管理世界邊界

參數

actionstr必填

動作("get"、"set"、"center"、"add"、"damage"、"warning")

valuefloat= None

set/add 時為邊界大小,damage 時為傷害量,warning 時為警告距離

timeint= None

set/add 時為過渡秒數,warning 時為警告時間

xfloat= None

center 動作使用的 X 座標

zfloat= None

center 動作使用的 Z 座標

回傳值

dict 包含邊界資訊的字典

例外

  • ConnectionError 連線失敗時
  • AuthenticationError 驗證失敗時
  • CommandError 動作或參數無效時

範例

>>> mc.worldborder("get")
{'size': 59999968.0, 'center_x': 0.0, 'center_z': 0.0, 'damage_amount': 0.2, 'damage_buffer': 5.0, 'warning_distance': 5, 'warning_time': 15}
>>> mc.worldborder("set", value=1000, time=10)
{'size': 1000.0}
>>> mc.worldborder("center", x=100, z=200)
{'center_x': 100.0, 'center_z': 200.0}

協定動作 worldborderclient.py 第 1752 行

forceload

mc.forceload(action: str, x: int, z: int) -> bool

強制載入或卸載區塊

參數

actionstr必填

動作("add"、"remove"、"query")

xint必填

方塊 X 座標(會轉換為區塊座標)

zint必填

方塊 Z 座標(會轉換為區塊座標)

回傳值

bool add/remove/query 操作回傳 True 或 False

例外

  • ConnectionError 連線失敗時
  • AuthenticationError 驗證失敗時
  • CommandError 動作無效時

範例

>>> mc.forceload("add", 100, 200)
True
>>> mc.forceload("query", 100, 200)
True
>>> mc.forceload("remove", 100, 200)
True

協定動作 forceloadclient.py 第 1790 行

聊天、音效與粒子

訊息、標題、音效與粒子效果。

say

mc.say(message: str) -> bool

向所有玩家廣播訊息

參數

messagestr必填

要廣播的訊息

回傳值

bool 成功時回傳 True

例外

  • ConnectionError 連線失敗時
  • AuthenticationError 驗證失敗時
  • CommandError 廣播失敗時

範例

>>> mc.say("Hello everyone!")
True

協定動作 sayclient.py 第 1483 行

tell

mc.tell(username: str, message: str) -> bool

傳送私人訊息給玩家

參數

usernamestr必填

玩家名稱

messagestr必填

要傳送的訊息

回傳值

bool 成功時回傳 True

例外

  • ConnectionError 連線失敗時
  • AuthenticationError 驗證失敗時
  • CommandError 找不到玩家時

範例

>>> mc.tell("Steve", "Hello Steve!")
True

協定動作 tellclient.py 第 1504 行

tellraw

mc.tellraw(username: str, json_text: str) -> bool

傳送原始 JSON 文字訊息給玩家

此請求以原版 ``tellraw`` 指令執行,因此 ``username`` 也可以是 "@a" 之類的目標選擇器。

參數

usernamestr必填

玩家名稱(或目標選擇器)

json_textstr必填

字串形式的 JSON 文字元件(不是 dict 或 list)

回傳值

bool 指令送出後即回傳 True(找不到玩家只會記錄在伺服器日誌中)

例外

  • ConnectionError 連線失敗時
  • AuthenticationError 驗證失敗時
  • CommandError 找不到玩家或 JSON 無效時

範例

>>> mc.tellraw("Steve", '{"text":"Hello","color":"gold","bold":true}')
True

協定動作 tellrawclient.py 第 1526 行

title

mc.title(
    username: str,
    title: str = '',
    subtitle: str = '',
    fade_in: int = 10,
    stay: int = 70,
    fade_out: int = 20,
) -> bool

在玩家畫面上顯示標題

參數

usernamestr必填

玩家名稱

titlestr= ''

主標題文字

subtitlestr= ''

副標題文字

fade_inint= 10

淡入時間,單位為刻(預設 10)

stayint= 70

停留時間,單位為刻(預設 70)

fade_outint= 20

淡出時間,單位為刻(預設 20)

回傳值

bool 成功時回傳 True

例外

  • ConnectionError 連線失敗時
  • AuthenticationError 驗證失敗時
  • CommandError 找不到玩家時

範例

>>> mc.title("Steve", "Welcome!", "Enjoy your stay")
True

協定動作 titleclient.py 第 1552 行

playsound

mc.playsound(
    username: str,
    sound: str,
    source: str = 'master',
    x: float = None,
    y: float = None,
    z: float = None,
    volume: float = 1.0,
    pitch: float = 1.0,
) -> bool

為玩家播放音效

參數

usernamestr必填

玩家名稱

soundstr必填

音效名稱(例如 "entity.experience_orb.pickup")

sourcestr= 'master'

音效來源類別(master、music、record、weather、block、hostile、neutral、player、ambient、voice)

xfloat= None

X 座標(預設為玩家位置)

yfloat= None

Y 座標(預設為玩家位置)

zfloat= None

Z 座標(預設為玩家位置)

volumefloat= 1.0

音量(預設 1.0)

pitchfloat= 1.0

音調(預設 1.0)

回傳值

bool 成功時回傳 True

例外

  • ConnectionError 連線失敗時
  • AuthenticationError 驗證失敗時
  • CommandError 找不到玩家或音效無效時

範例

>>> mc.playsound("Steve", "entity.experience_orb.pickup")
True
>>> mc.playsound("Steve", "block.note_block.harp", x=100, y=64, z=200, pitch=1.5)
True

協定動作 playsoundclient.py 第 1586 行

stopsound

mc.stopsound(
    username: str,
    sound: str = None,
    source: str = None,
) -> bool

停止玩家的音效

參數

usernamestr必填

玩家名稱

soundstr= None

要停止的特定音效;None 表示停止所有音效

sourcestr= None

``sound`` 的音效類別(只在指定 ``sound`` 時生效;未指定音效時會停止所有音效)

回傳值

bool 成功時回傳 True

例外

  • ConnectionError 連線失敗時
  • AuthenticationError 驗證失敗時
  • CommandError 找不到玩家時

範例

>>> mc.stopsound("Steve")  # Stop all sounds
True
>>> mc.stopsound("Steve", "minecraft:music.creative")
True

協定動作 stopsoundclient.py 第 1628 行

particle

mc.particle(
    particle_type: str,
    x: float,
    y: float,
    z: float,
    count: int = 1,
    dx: float = 0,
    dy: float = 0,
    dz: float = 0,
    speed: float = 0,
) -> bool

在指定位置產生粒子

需要額外資料的粒子(例如 "dust"、"block"、"item")不受支援,會拋出 CommandError。

參數

particle_typestr必填

粒子類型(例如 "flame"、"heart"、"minecraft:smoke")

xfloat必填

X 座標

yfloat必填

Y 座標

zfloat必填

Z 座標

countint= 1

粒子數量(預設 1)

dxfloat= 0

X 方向擴散範圍(預設 0)

dyfloat= 0

Y 方向擴散範圍(預設 0)

dzfloat= 0

Z 方向擴散範圍(預設 0)

speedfloat= 0

粒子速度(預設 0)

回傳值

bool 成功時回傳 True

例外

  • ConnectionError 連線失敗時
  • AuthenticationError 驗證失敗時
  • CommandError 粒子類型無效時

範例

>>> mc.particle("flame", 100, 65, 200, count=50, dx=1, dy=1, dz=1, speed=0.1)
True

協定動作 particleclient.py 第 1658 行

實體

召喚實體,控制位置、移動、AI、生命值、騎乘與屬性。

summon

mc.summon(
    entity_type: str,
    x: float,
    y: float,
    z: float,
) -> str

在指定座標召喚實體

參數

entity_typestr必填

實體類型(例如 "minecraft:zombie"、"pig")

xfloat必填

X 座標

yfloat必填

Y 座標

zfloat必填

Z 座標

回傳值

str 實體 UUID 字串

例外

  • ConnectionError 連線失敗時
  • AuthenticationError 驗證失敗時
  • CommandError 實體類型或座標無效時

範例

>>> uuid = mc.summon("minecraft:zombie", 100, 64, 200)
>>> uuid = mc.summon("pig", 150, 70, 250)

協定動作 summonclient.py 第 580 行

kill

mc.kill(selector: str) -> int

從世界中移除實體

只接受三種選擇器形式("@e[type=zombie]" 之類的原版選擇器或 UUID 都會被拒絕)。"all" 與實體類型只作用於第一個(主)世界,每次最多移除 1000 個實體。

參數

selectorstr必填

"all"(所有非玩家實體,包含掉落物、盔甲座與物品展示框)、"zombie" 之類的實體類型,或 "player:username"(將該玩家生命值設為 0)

回傳值

int 被移除的實體數

例外

  • ConnectionError 連線失敗時
  • AuthenticationError 驗證失敗時
  • CommandError 選擇器無效或找不到玩家時

範例

>>> mc.kill("all")
42
>>> mc.kill("zombie")
5
>>> mc.kill("player:Steve")
1

協定動作 killclient.py 第 609 行

getEntityPos

mc.getEntityPos(entity_uuid: str) -> dict

依 UUID 取得實體位置

參數

entity_uuidstr必填

實體 UUID 字串

回傳值

dict 包含 x、y、z、yaw、pitch 鍵的位置字典

例外

  • ConnectionError 連線失敗時
  • AuthenticationError 驗證失敗時
  • CommandError 找不到實體或 UUID 無效時

範例

>>> uuid = mc.summon("zombie", 100, 64, 200)
>>> pos = mc.getEntityPos(uuid)
>>> print(f"Position: ({pos['x']}, {pos['y']}, {pos['z']})")

協定動作 getEntityPosclient.py 第 642 行

getEntityStatus

mc.getEntityStatus(entity_uuid: str) -> dict

取得實體的完整狀態資訊

參數

entity_uuidstr必填

實體 UUID 字串

回傳值

dict 狀態字典,包含: - uuid:實體 UUID - type:實體類型(例如 "minecraft:zombie") - custom_name:自訂名稱(實體沒有時不含此鍵) - is_valid:實體是否有效 - is_dead:實體是否已死亡 - position:{x, y, z} 座標 - velocity:{x, y, z} 速度向量 - world:世界名稱 - health:目前生命值(僅限 LivingEntity,否則不含此鍵) - max_health:最大生命值(僅限 LivingEntity,否則不含此鍵) - has_ai:是否啟用 AI(僅限 LivingEntity,否則不含此鍵) 伺服器會省略值為 null 的鍵,選用欄位請用 status.get("custom_name") 讀取。

例外

  • ConnectionError 連線失敗時
  • AuthenticationError 驗證失敗時
  • CommandError 找不到實體或 UUID 無效時

範例

>>> uuid = mc.summon("zombie", 100, 64, 200)
>>> status = mc.getEntityStatus(uuid)
>>> print(f"Health: {status['health']}/{status['max_health']}")
>>> print(f"AI enabled: {status['has_ai']}")

協定動作 getEntityStatusclient.py 第 666 行

teleportEntity

mc.teleportEntity(
    entity_uuid: str,
    x: float,
    y: float,
    z: float,
    yaw: float = None,
    pitch: float = None,
) -> bool

把實體傳送到指定座標

參數

entity_uuidstr必填

實體 UUID 字串

xfloat必填

目標 X 座標

yfloat必填

目標 Y 座標

zfloat必填

目標 Z 座標

yawfloat= None

選用的水平旋轉角(yaw)

pitchfloat= None

選用的垂直旋轉角(pitch)

回傳值

bool 成功時回傳 True

例外

  • ConnectionError 連線失敗時
  • AuthenticationError 驗證失敗時
  • CommandError 找不到實體或傳送失敗時

範例

>>> uuid = mc.summon("pig", 100, 64, 200)
>>> mc.teleportEntity(uuid, 110, 70, 210)
True
>>> mc.teleportEntity(uuid, 120, 64, 220, yaw=90.0, pitch=0.0)
True

協定動作 teleportEntityclient.py 第 705 行

setEntityVelocity

mc.setEntityVelocity(
    entity_uuid: str,
    vx: float,
    vy: float,
    vz: float,
) -> bool

設定實體的速度

參數

entity_uuidstr必填

實體 UUID 字串

vxfloat必填

X 方向速度分量(方塊/刻,限制在 ±10)

vyfloat必填

Y 方向速度分量(方塊/刻,限制在 ±10)

vzfloat必填

Z 方向速度分量(方塊/刻,限制在 ±10)

回傳值

bool 成功時回傳 True

例外

  • ConnectionError 連線失敗時
  • AuthenticationError 驗證失敗時
  • CommandError 找不到實體時

範例

>>> uuid = mc.summon("pig", 100, 64, 200)
>>> # Make the pig jump
>>> mc.setEntityVelocity(uuid, 0, 1.0, 0)
True
>>> # Push the pig forward
>>> mc.setEntityVelocity(uuid, 0.5, 0.2, 0.5)
True

協定動作 setEntityVelocityclient.py 第 752 行

setEntityRotation

mc.setEntityRotation(
    entity_uuid: str,
    yaw: float,
    pitch: float,
) -> bool

設定實體的旋轉(面向方向)

參數

entity_uuidstr必填

實體 UUID 字串

yawfloat必填

水平旋轉角(0=南、90=西、180=北、270=東)

pitchfloat必填

垂直旋轉角(-90=向上、0=水平、90=向下)

回傳值

bool 成功時回傳 True

例外

  • ConnectionError 連線失敗時
  • AuthenticationError 驗證失敗時
  • CommandError 找不到實體,或玩家的轉向被擋下(例如被其他外掛取消)

範例

>>> uuid = mc.summon("zombie", 100, 64, 200)
>>> # Face north
>>> mc.setEntityRotation(uuid, 180.0, 0.0)
True
>>> # Look up
>>> mc.setEntityRotation(uuid, 180.0, -45.0)
True

協定動作 setEntityRotationclient.py 第 792 行

setEntityAI

mc.setEntityAI(entity_uuid: str, enabled: bool) -> bool

啟用或停用生物實體的 AI

停用 AI 後,實體不會移動、攻擊或做出任何自主行為(就像雕像一樣)。

參數

entity_uuidstr必填

實體 UUID 字串

enabledbool必填

True 為啟用 AI,False 為停用

回傳值

bool 成功時回傳 True

例外

  • ConnectionError 連線失敗時
  • AuthenticationError 驗證失敗時
  • CommandError 找不到實體或實體不是 LivingEntity 時

範例

>>> uuid = mc.summon("zombie", 100, 64, 200)
>>> # Freeze the zombie (disable AI)
>>> mc.setEntityAI(uuid, False)
True
>>> # Re-enable AI
>>> mc.setEntityAI(uuid, True)
True

協定動作 setEntityAIclient.py 第 830 行

setEntityTarget

mc.setEntityTarget(
    entity_uuid: str,
    target_uuid: str = None,
) -> bool

設定或清除生物的攻擊目標

參數

entity_uuidstr必填

生物實體的 UUID

target_uuidstr= None

目標實體的 UUID(必須是 LivingEntity);None 表示清除目標

回傳值

bool 成功時回傳 True

例外

  • ConnectionError 連線失敗時
  • AuthenticationError 驗證失敗時
  • CommandError 找不到實體、實體不是 Mob 或目標無效時

範例

>>> zombie = mc.summon("zombie", 100, 64, 200)
>>> villager = mc.summon("villager", 105, 64, 200)
>>> # Make zombie target the villager
>>> mc.setEntityTarget(zombie, villager)
True
>>> # Clear the target
>>> mc.setEntityTarget(zombie, None)
True

協定動作 setEntityTargetclient.py 第 863 行

removeEntity

mc.removeEntity(entity_uuid: str) -> bool

從世界中移除一個實體

參數

entity_uuidstr必填

實體 UUID 字串

回傳值

bool 成功時回傳 True

例外

  • ConnectionError 連線失敗時
  • AuthenticationError 驗證失敗時
  • CommandError 找不到實體或實體是玩家時

範例

>>> uuid = mc.summon("pig", 100, 64, 200)
>>> mc.removeEntity(uuid)
True

協定動作 removeEntityclient.py 第 900 行

damage

mc.damage(
    entity_uuid: str,
    amount: float,
    source_uuid: str = None,
) -> bool

對實體造成傷害

參數

entity_uuidstr必填

目標實體 UUID

amountfloat必填

傷害量

source_uuidstr= None

選用的傷害來源實體 UUID

回傳值

bool 成功時回傳 True

例外

  • ConnectionError 連線失敗時
  • AuthenticationError 驗證失敗時
  • CommandError 找不到實體或實體不是 LivingEntity 時

範例

>>> uuid = mc.summon("zombie", 100, 64, 200)
>>> mc.damage(uuid, 5.0)
True

協定動作 damageclient.py 第 1817 行

ride

mc.ride(
    passenger_uuid: str,
    vehicle_uuid: str = None,
) -> bool

讓實體騎乘另一個實體,或下坐騎

參數

passenger_uuidstr必填

乘客實體的 UUID

vehicle_uuidstr= None

坐騎實體的 UUID;None 表示下坐騎

回傳值

bool 成功時回傳 True

例外

  • ConnectionError 連線失敗時
  • AuthenticationError 驗證失敗時
  • CommandError 找不到實體時

範例

>>> pig = mc.summon("pig", 100, 64, 200)
>>> zombie = mc.summon("zombie", 100, 64, 200)
>>> mc.ride(zombie, pig)  # Zombie rides the pig
True
>>> mc.ride(zombie)  # Zombie dismounts
True

協定動作 rideclient.py 第 2507 行

attribute

mc.attribute(
    entity_uuid: str,
    attribute_name: str,
    action: str = 'get',
    value: float = None,
) -> dict

查詢或設定實體屬性

參數

entity_uuidstr必填

實體 UUID

attribute_namestr必填

屬性名稱(例如 "MAX_HEALTH"、"MOVEMENT_SPEED"、"ATTACK_DAMAGE")

actionstr= 'get'

動作("get" 或 "set")

valuefloat= None

要設定的值("set" 動作必填)

回傳值

dict 包含 base_value 與 value 的字典

例外

  • ConnectionError 連線失敗時
  • AuthenticationError 驗證失敗時
  • CommandError 找不到實體或屬性無效時

範例

>>> mc.attribute(uuid, "MAX_HEALTH")
{'base_value': 20.0, 'value': 20.0}
>>> mc.attribute(uuid, "MAX_HEALTH", action="set", value=40.0)
{'base_value': 40.0, 'value': 40.0}

協定動作 attributeclient.py 第 2122 行

裝備與標籤

盔甲與手持物品,以及用來分組實體的計分板標籤。

getEntityEquipment

mc.getEntityEquipment(entity_uuid: str) -> dict

取得生物實體的裝備

參數

entity_uuidstr必填

實體 UUID 字串

回傳值

dict 裝備字典,包含以下鍵(值為 "minecraft:diamond_helmet" 之類的物品 ID);空欄位會被省略: - helmet - chestplate - leggings - boots - main_hand - off_hand

例外

  • ConnectionError 連線失敗時
  • AuthenticationError 驗證失敗時
  • CommandError 找不到實體或實體不支援裝備時

範例

>>> uuid = mc.summon("zombie", 100, 64, 200)
>>> equipment = mc.getEntityEquipment(uuid)
>>> print(f"Helmet: {equipment.get('helmet')}")  # None if no helmet

協定動作 getEntityEquipmentclient.py 第 924 行

setEntityEquipment

mc.setEntityEquipment(
    entity_uuid: str,
    equipment: dict,
    drop_chances: dict = None,
) -> bool

設定生物實體的裝備

參數

entity_uuidstr必填

實體 UUID 字串

equipmentdict必填

要設定的裝備欄位字典,鍵可以是:

  • helmet:物品名稱(例如 "diamond_helmet")
  • chestplate:物品名稱
  • leggings:物品名稱
  • boots:物品名稱
  • main_hand:物品名稱
  • off_hand:物品名稱
drop_chancesdict= None

選用,各欄位掉落機率(0.0–1.0)的字典

回傳值

bool 成功時回傳 True

例外

  • ConnectionError 連線失敗時
  • AuthenticationError 驗證失敗時
  • CommandError 找不到實體或實體不支援裝備時

範例

>>> uuid = mc.summon("zombie", 100, 64, 200)
>>> mc.setEntityEquipment(uuid, {
...     "helmet": "diamond_helmet",
...     "chestplate": "diamond_chestplate",
...     "main_hand": "diamond_sword"
... }, drop_chances={"helmet": 0.1, "main_hand": 0.5})
True

協定動作 setEntityEquipmentclient.py 第 955 行

addTag

mc.addTag(entity_uuid: str, tag: str) -> bool

為實體加上計分板標籤

參數

entity_uuidstr必填

實體 UUID

tagstr必填

標籤字串

回傳值

bool 加上標籤時回傳 True(原本就有則為 False)

例外

  • ConnectionError 連線失敗時
  • AuthenticationError 驗證失敗時
  • CommandError 找不到實體時

範例

>>> uuid = mc.summon("zombie", 100, 64, 200)
>>> mc.addTag(uuid, "boss")
True

協定動作 addTagclient.py 第 1962 行

removeTag

mc.removeTag(entity_uuid: str, tag: str) -> bool

移除實體的計分板標籤

參數

entity_uuidstr必填

實體 UUID

tagstr必填

標籤字串

回傳值

bool 移除標籤時回傳 True

例外

  • ConnectionError 連線失敗時
  • AuthenticationError 驗證失敗時
  • CommandError 找不到實體時

範例

>>> mc.removeTag(uuid, "boss")
True

協定動作 removeTagclient.py 第 1985 行

getTags

mc.getTags(entity_uuid: str) -> List[str]

取得實體的所有計分板標籤

參數

entity_uuidstr必填

實體 UUID

回傳值

List[str] 標籤字串串列

例外

  • ConnectionError 連線失敗時
  • AuthenticationError 驗證失敗時
  • CommandError 找不到實體時

範例

>>> mc.getTags(uuid)
['boss', 'enemy']

協定動作 getTagsclient.py 第 2007 行

村民

職業、等級與自訂交易。

getVillagerData

mc.getVillagerData(villager_uuid: str) -> dict

取得村民的職業、等級與交易資訊

參數

villager_uuidstr必填

村民實體的 UUID 字串

回傳值

dict 字典,包含: - profession:村民職業名稱(例如 "LIBRARIAN") - level:村民等級(1-5) - trades:交易字典清單,每筆包含: - buy1:{"item": str, "amount": int} - buy2:{"item": str, "amount": int}(僅在交易有第二項材料時出現) - sell:{"item": str, "amount": int} - uses:目前使用次數 - max_uses:最大使用次數

例外

  • ConnectionError 連線失敗時
  • AuthenticationError 驗證失敗時
  • CommandError 找不到實體或實體不是村民時

範例

>>> uuid = mc.summon("villager", 100, 64, 200)
>>> data = mc.getVillagerData(uuid)
>>> print(f"Profession: {data['profession']}")
>>> print(f"Number of trades: {len(data['trades'])}")

協定動作 getVillagerDataclient.py 第 999 行

setVillagerProfession

mc.setVillagerProfession(
    villager_uuid: str,
    profession: str,
) -> bool

設定村民的職業

參數

villager_uuidstr必填

村民實體的 UUID 字串

professionstr必填

職業名稱。可用的值:ARMORER、BUTCHER、CARTOGRAPHER、CLERIC、FARMER、FISHERMAN、FLETCHER、LEATHERWORKER、LIBRARIAN、MASON、NITWIT、NONE、SHEPHERD、TOOLSMITH、WEAPONSMITH

回傳值

bool 成功時回傳 True

例外

  • ConnectionError 連線失敗時
  • AuthenticationError 驗證失敗時
  • CommandError 找不到實體、實體不是村民或職業無效時

範例

>>> uuid = mc.summon("villager", 100, 64, 200)
>>> mc.setVillagerProfession(uuid, "LIBRARIAN")
True

協定動作 setVillagerProfessionclient.py 第 1033 行

setVillagerTrades

mc.setVillagerTrades(
    villager_uuid: str,
    trades: list,
) -> bool

設定村民的自訂交易(會取代所有既有交易)

參數

villager_uuidstr必填

村民實體的 UUID 字串

tradeslist必填

交易定義的串列,每筆交易是包含以下鍵的字典:

  • buy1:{"item": str, "amount": int},第一個材料(必填)
  • buy2:{"item": str, "amount": int},第二個材料(選用)
  • sell:{"item": str, "amount": int},交易成品(必填)
  • max_uses:最大使用次數(預設 10)
  • experience_reward:是否給予經驗(預設 True)

回傳值

bool 成功時回傳 True

例外

  • ConnectionError 連線失敗時
  • AuthenticationError 驗證失敗時
  • CommandError 找不到實體、實體不是村民或交易資料無效時

範例

>>> uuid = mc.summon("villager", 100, 64, 200)
>>> mc.setVillagerProfession(uuid, "LIBRARIAN")
>>> mc.setVillagerTrades(uuid, [
...     {
...         "buy1": {"item": "emerald", "amount": 10},
...         "sell": {"item": "diamond_sword", "amount": 1},
...         "max_uses": 5
...     },
...     {
...         "buy1": {"item": "emerald", "amount": 5},
...         "buy2": {"item": "book", "amount": 1},
...         "sell": {"item": "enchanted_book", "amount": 1},
...         "max_uses": 10
...     }
... ])
True

協定動作 setVillagerTradesclient.py 第 1062 行

計分板、隊伍與 Boss 血條

計分項目、分數、顯示位置、隊伍與 Boss 血條。

addObjective

mc.addObjective(
    name: str,
    criteria: str,
    display_name: str = None,
) -> bool

新增計分項目

參數

namestr必填

計分項目名稱

criteriastr必填

準則(例如 "dummy"、"playerKillCount")

display_namestr= None

顯示名稱(預設與名稱相同)

回傳值

bool 成功時回傳 True

例外

  • ConnectionError 連線失敗時
  • AuthenticationError 驗證失敗時
  • CommandError 計分項目已存在時

範例

>>> mc.addObjective("kills", "playerKillCount", "Player Kills")
True

協定動作 addObjectiveclient.py 第 1844 行

removeObjective

mc.removeObjective(name: str) -> bool

移除計分項目

參數

namestr必填

計分項目名稱

回傳值

bool 成功時回傳 True

例外

  • ConnectionError 連線失敗時
  • AuthenticationError 驗證失敗時
  • CommandError 找不到計分項目時

範例

>>> mc.removeObjective("kills")
True

協定動作 removeObjectiveclient.py 第 1870 行

setScore

mc.setScore(
    objective: str,
    player: str,
    score: int,
) -> bool

設定玩家在某計分項目的分數

參數

objectivestr必填

計分項目名稱

playerstr必填

玩家名稱或實體名稱

scoreint必填

分數

回傳值

bool 成功時回傳 True

例外

  • ConnectionError 連線失敗時
  • AuthenticationError 驗證失敗時
  • CommandError 找不到計分項目時

範例

>>> mc.setScore("kills", "Steve", 10)
True

協定動作 setScoreclient.py 第 1891 行

getScore

mc.getScore(objective: str, player: str) -> int

取得玩家在某計分項目的分數

參數

objectivestr必填

計分項目名稱

playerstr必填

玩家名稱或實體名稱

回傳值

int 分數

例外

  • ConnectionError 連線失敗時
  • AuthenticationError 驗證失敗時
  • CommandError 找不到計分項目時

範例

>>> mc.getScore("kills", "Steve")
10

協定動作 getScoreclient.py 第 1914 行

setDisplaySlot

mc.setDisplaySlot(
    slot: str,
    objective: str = None,
) -> bool

設定顯示位置要顯示哪個計分項目

參數

slotstr必填

顯示位置("below_name"、"sidebar"、"player_list")

objectivestr= None

計分項目名稱;None 表示清空該顯示位置

回傳值

bool 成功時回傳 True

例外

  • ConnectionError 連線失敗時
  • AuthenticationError 驗證失敗時
  • CommandError 顯示位置無效或找不到計分項目時

範例

>>> mc.setDisplaySlot("sidebar", "kills")
True
>>> mc.setDisplaySlot("sidebar")  # Clear sidebar
True

協定動作 setDisplaySlotclient.py 第 1936 行

team

mc.team(
    action: str,
    name: str = None,
    members: List[str] = None,
    option: str = None,
    value: str = None,
    display_name: str = None,
) -> dict

管理計分板隊伍

參數

actionstr必填

動作("add"、"remove"、"join"、"leave"、"modify"、"list")

namestr= None

隊伍名稱(大多數動作必填)

membersList[str]= None

玩家名稱串列(用於 join/leave)

optionstr= None

modify 使用的選項名稱(displayname、color、friendlyfire、seefriendlyinvisibles、prefix、suffix)

valuestr= None

modify 動作的值

display_namestr= None

add 動作的顯示名稱

回傳值

dict 包含隊伍資訊的字典

例外

  • ConnectionError 連線失敗時
  • AuthenticationError 驗證失敗時
  • CommandError 找不到隊伍或動作無效時

範例

>>> mc.team("add", "red_team", display_name="Red Team")
{'name': 'red_team'}
>>> mc.team("join", "red_team", members=["Steve", "Alex"])
{'added': 2}
>>> mc.team("modify", "red_team", option="color", value="RED")
{'modified': True}
>>> mc.team("list")
{'teams': [...]}

協定動作 teamclient.py 第 2028 行

bossbar

mc.bossbar(
    action: str,
    bar_id: str,
    title: str = None,
    color: str = None,
    style: str = None,
    progress: float = None,
    visible: bool = None,
    username: str = None,
) -> dict

管理 Boss 血條

Boss 血條存放在插件的記憶體中(不是原版 /bossbar 的 ID),伺服器重新啟動後就會消失。"add" 時若顏色或樣式無效,會改用 WHITE / SOLID;"set" 時則拋出 CommandError。

參數

actionstr必填

動作("add"、"remove"、"set"、"addplayer"、"removeplayer"、"get"、"list")

bar_idstr必填

Boss 血條 ID(每種動作都必填;"list" 可填任意值)

titlestr= None

血條標題(用於 add/set)

colorstr= None

血條顏色(WHITE、PINK、BLUE、RED、GREEN、YELLOW、PURPLE)(用於 add/set)

stylestr= None

血條樣式(SOLID、SEGMENTED_6、SEGMENTED_10、SEGMENTED_12、SEGMENTED_20)(用於 add/set)

progressfloat= None

進度值 0.0–1.0(用於 add/set)

visiblebool= None

是否顯示(用於 add/set)

usernamestr= None

玩家名稱(用於 addplayer/removeplayer)

回傳值

dict 包含 Boss 血條資訊的字典

例外

  • ConnectionError 連線失敗時
  • AuthenticationError 驗證失敗時
  • CommandError 找不到 Boss 血條或動作無效時

範例

>>> mc.bossbar("add", "my_bar", title="Boss Fight", color="RED")
{'id': 'my_bar'}
>>> mc.bossbar("addplayer", "my_bar", username="Steve")
{'added': True}
>>> mc.bossbar("set", "my_bar", progress=0.5)
{'updated': True}

協定動作 bossbarclient.py 第 2072 行

世界生成

尋找結構、產生戰利品、改變生態域,以及放置地物、結構與模板。

locate

mc.locate(
    structure: str,
    x: float = None,
    z: float = None,
) -> dict

尋找最近的結構

在第一個(主)世界中,從起點搜尋 100 個區塊範圍。

參數

structurestr必填

結構鍵(例如 "village_plains"、"minecraft:desert_pyramid"、"ancient_city")。不接受 "village" 之類的結構標籤。

xfloat= None

搜尋起點的 X 座標(預設為世界重生點)

zfloat= None

搜尋起點的 Z 座標(預設為世界重生點)

回傳值

dict 包含 found(bool)的字典,找到時另含 x、y、z。座標指向結構所在的區塊;y 不是地面高度(通常為 0)。

例外

  • ConnectionError 連線失敗時
  • AuthenticationError 驗證失敗時
  • CommandError 結構類型無效時

範例

>>> mc.locate("village_plains")
{'found': True, 'x': 16, 'y': 0, 'z': 112}

協定動作 locateclient.py 第 2235 行

loot

mc.loot(
    loot_table: str,
    x: float,
    y: float,
    z: float,
) -> int

依戰利品表產生戰利品並掉落在指定位置

參數

loot_tablestr必填

戰利品表名稱(例如 "chests/simple_dungeon")

xfloat必填

X 座標

yfloat必填

Y 座標

zfloat必填

Z 座標

回傳值

int 產生的物品數

例外

  • ConnectionError 連線失敗時
  • AuthenticationError 驗證失敗時
  • CommandError 戰利品表無效時

範例

>>> mc.loot("chests/simple_dungeon", 100, 64, 200)
5

協定動作 lootclient.py 第 2295 行

fillbiome

mc.fillbiome(
    x1: int,
    y1: int,
    z1: int,
    x2: int,
    y2: int,
    z2: int,
    biome: str,
    filter_biome: str = None,
) -> bool

以指定生態域填滿區域

執行原版 ``fillbiome`` 指令。區域必須已載入,而且原版會拒絕過大的區域;這類失敗(例如 "That position is not loaded")只會記錄在伺服器日誌中。

參數

x1int必填

起點 X 座標

y1int必填

起點 Y 座標

z1int必填

起點 Z 座標

x2int必填

終點 X 座標

y2int必填

終點 Y 座標

z2int必填

終點 Z 座標

biomestr必填

目標生態域(例如 "minecraft:plains")

filter_biomestr= None

只取代這個生態域(選用)

回傳值

bool 指令送出後即回傳 True

例外

  • ConnectionError 連線失敗時
  • AuthenticationError 驗證失敗時
  • CommandError 生態域名稱無效時

範例

>>> mc.fillbiome(100, 60, 200, 115, 75, 215, "minecraft:desert")
True

協定動作 fillbiomeclient.py 第 2322 行

placeFeature

mc.placeFeature(
    feature: str,
    x: int = None,
    y: int = None,
    z: int = None,
) -> bool

在指定位置放置已設定的地物

執行原版 ``place feature`` 指令。目標區塊必須已載入;原版的失敗訊息只會記錄在伺服器日誌中。

參數

featurestr必填

地物名稱(例如 "minecraft:oak")

xint= None

X 座標(選用)

yint= None

Y 座標(選用)

zint= None

Z 座標(選用)

回傳值

bool 成功時回傳 True

例外

  • ConnectionError 連線失敗時
  • AuthenticationError 驗證失敗時
  • CommandError 地物無效時

範例

>>> mc.placeFeature("minecraft:oak", 100, 64, 200)
True

協定動作 placeFeatureclient.py 第 2361 行

placeStructure

mc.placeStructure(
    structure: str,
    x: int = None,
    y: int = None,
    z: int = None,
) -> bool

在指定位置放置結構

執行原版 ``place structure`` 指令。目標區塊必須已載入;原版的失敗訊息只會記錄在伺服器日誌中。

參數

structurestr必填

結構名稱(例如 "minecraft:village_plains")

xint= None

X 座標(選用)

yint= None

Y 座標(選用)

zint= None

Z 座標(選用)

回傳值

bool 成功時回傳 True

例外

  • ConnectionError 連線失敗時
  • AuthenticationError 驗證失敗時
  • CommandError 結構無效時

範例

>>> mc.placeStructure("minecraft:village_plains", 100, 64, 200)
True

協定動作 placeStructureclient.py 第 2393 行

placeJigsaw

mc.placeJigsaw(
    pool: str,
    target: str,
    max_depth: int,
    x: int = None,
    y: int = None,
    z: int = None,
) -> bool

在指定位置放置拼圖結構池

執行原版 ``place jigsaw`` 指令。目標區塊必須已載入;原版的失敗訊息只會記錄在伺服器日誌中。

參數

poolstr必填

拼圖池名稱

targetstr必填

目標名稱

max_depthint必填

最大深度(1–20)

xint= None

X 座標(選用)

yint= None

Y 座標(選用)

zint= None

Z 座標(選用)

回傳值

bool 成功時回傳 True

例外

  • ConnectionError 連線失敗時
  • AuthenticationError 驗證失敗時
  • CommandError 拼圖池或參數無效時

範例

>>> mc.placeJigsaw("minecraft:village/plains/houses", "minecraft:empty", 7, 100, 64, 200)
True

協定動作 placeJigsawclient.py 第 2425 行

placeTemplate

mc.placeTemplate(
    template: str,
    x: int = None,
    y: int = None,
    z: int = None,
    rotation: str = 'none',
    mirror: str = 'none',
    integrity: float = 1.0,
    seed: int = 0,
) -> bool

在指定位置放置結構模板

執行原版 ``place template`` 指令。目標區塊必須已載入;原版的失敗訊息只會記錄在伺服器日誌中。

參數

templatestr必填

模板名稱

xint= None

X 座標(選用)

yint= None

Y 座標(選用)

zint= None

Z 座標(選用)

rotationstr= 'none'

旋轉(none、clockwise_90、180、counterclockwise_90)

mirrorstr= 'none'

鏡像模式(none、front_back、left_right)

integrityfloat= 1.0

結構完整度 0.0–1.0(預設 1.0)

seedint= 0

完整度使用的隨機種子(預設 0)

回傳值

bool 成功時回傳 True

例外

  • ConnectionError 連線失敗時
  • AuthenticationError 驗證失敗時
  • CommandError 模板無效時

範例

>>> mc.placeTemplate("my_house", 100, 64, 200, rotation="clockwise_90")
True

協定動作 placeTemplateclient.py 第 2463 行

伺服器

執行任何指令、列出線上玩家,並把玩家分散到地圖各處。

exec

mc.exec(command: str) -> bool

在伺服器上執行任何 Minecraft 指令

萬用的指令執行器,可執行任何 Minecraft 指令。適合還沒有專屬方法的指令。

指令以伺服器主控台身分執行。其輸出(包括 "No player was found" 之類的原版錯誤)只會出現在伺服器日誌中。

參數

commandstr必填

要執行的指令(開頭的 / 可有可無)

回傳值

bool 伺服器找到並執行了指令時回傳 True(即使指令本身回報失敗);指令不存在時回傳 False

例外

  • ConnectionError 連線失敗時
  • AuthenticationError 驗證失敗時
  • CommandError 指令執行失敗時

範例

>>> mc.exec("seed")
True
>>> mc.exec("/say Hello World")
True

協定動作 execclient.py 第 1281 行

list

mc.list() -> dict

取得線上玩家清單

回傳值

dict 包含 online_count、max_players 與 players 串列的字典

例外

  • ConnectionError 連線失敗時
  • AuthenticationError 驗證失敗時

範例

>>> mc.list()
{'online_count': 2, 'max_players': 20, 'players': [{'name': 'Steve', ...}]}

協定動作 listclient.py 第 2592 行

spreadplayers

mc.spreadplayers(
    center_x: float,
    center_z: float,
    spread_distance: float,
    max_range: float,
    usernames: List[str],
) -> bool

把玩家隨機分散到中心點周圍

執行原版 ``spreadplayers`` 指令(respectTeams = false);原版的失敗訊息只會記錄在伺服器日誌中。

參數

center_xfloat必填

中心 X 座標

center_zfloat必填

中心 Z 座標

spread_distancefloat必填

玩家之間的最小距離

max_rangefloat必填

與中心的最大距離

usernamesList[str]必填

要分散的玩家名稱串列

回傳值

bool 成功時回傳 True

例外

  • ConnectionError 連線失敗時
  • AuthenticationError 驗證失敗時
  • CommandError 找不到玩家或參數無效時

範例

>>> mc.spreadplayers(0, 0, 10, 100, ["Steve", "Alex"])
True

協定動作 spreadplayersclient.py 第 2535 行