🐍 Python API 速查手册

在编辑器里，所有积木最终都会翻译成 Python。本页是 vm 全局对象的完整速查手册——你可以直接写 Python 调用它们，或在"嵌入 Python 脚本"积木中混搭。

0. 运行环境（必看）

1. 命名空间（值对象）

这些是"取值用"的常量集合。直接当成 Python 对象的属性访问即可，IDE 即使没补全也不会出错——只要服务器认识这个名字就行。

2. 光标 & 坐标

"光标"是建造方块时的活动笔尖，初始落在玩家脚下。它有 x / y / z、朝向、俯仰角三组状态。理解光标是写好建造脚本的关键。

2.1 属性（直接读）

• vm.x, vm.y, vm.z —— 光标当前坐标（int）
• vm.getX(), vm.getY(), vm.getZ() —— 方法版（一样的值）
• vm.getPlayerName() —— 当前玩家游戏名
• vm.getTimeOfDay() —— 世界当前时间（tick；0=日出，6000=正午，12000=日落，18000=午夜）

2.2 位置对象（VisualModder 兼容）

下面三个方法返回 Location 对象（不是数字！）。Location 同时支持 VisualModder 风格的 getX()/getY()/getZ()/getYaw()/getPitch() 和 Pythonic 属性 .x/.y/.z/.yaw/.pitch。

# 三种取法等价：
player = vm.getPlayerPosition()
x1 = player.getX()    # VisualModder 风格
x2 = player.x         # Pythonic 属性
x3 = vm.getPlayerPosition().getX()  # 直接链式

# 解构：
px, py, pz = vm.getPlayerPosition()

# 用法：在玩家头顶 5 格画块石头
p = vm.getPlayerPosition()
vm.setBlock(p.x, p.y + 5, p.z, Block.STONE)

2.3 移动方法

2.4 例：用光标"画"一段台阶

vm.setMaterial(Block.OAK_PLANKS)
for i in range(10):
    vm.createBlock()
    vm.moveTo(1, Direction.FORWARD)   # 前进一格
    vm.moveTo(1, Direction.UP)        # 上升一格

3. 建造方块

所有"建造类"方法都参考光标的位置与朝向。如果你先调用 vm.setMaterial(Block.XXX)，后面不显式传材料的建造方法会自动用它。

3.1 单块/区域

3.2 平面 / 立体

3.3 曲线 / 几何

3.4 文字 / 像素图

# 三层像素图：1 = 边框石头，0 = 空气
grid = [
    "111",
    "101",
    "111",
]
vm.createDrawing(grid, [Block.AIR, Block.STONE])

3.5 杂项

4. 玩家控制

5. 世界 & 时间

6. 消息 & 音效

7. 世界状态查询

8. 事件监听

当玩家在 Minecraft 里发言、放置/破坏方块、右键交互时，让 Python 自动跑一段。

# 监听：聊天里说"打招呼"就回一句
vm.onEvent("chat", "打招呼", "player", "msg")
def _():
    vm.sendMessage(f"你好 {player}！你说的是：{msg}")
vm.onEventEnd()

9. 持久值

# 记住玩家造了几次塔
count = vm.readValue("tower_count") or 0
count += 1
vm.saveValue("tower_count", count)
vm.sendMessage(f"这是你第 {count} 次造塔！")

10. 烹饪手册（Cookbook）

10.1 用列表轮换材质做彩虹墙

palette = [
    Block.RED_STAINED_GLASS,
    Block.ORANGE_STAINED_GLASS,
    Block.YELLOW_STAINED_GLASS,
    Block.GREEN_STAINED_GLASS,
    Block.BLUE_STAINED_GLASS,
    Block.PURPLE_STAINED_GLASS,
]
vm.createWall(30, 6, palette)

10.2 随机散布的小树林

import random

vm.setMaterial(Block.OAK_LOG)
for _ in range(30):
    dx = random.randint(-15, 15)
    dz = random.randint(-15, 15)
    vm.setCursor(vm.x + dx, vm.y, vm.z + dz)
    # 树干 4 高
    for _ in range(4):
        vm.createBlock()
        vm.moveTo(1, Direction.UP)
    # 简单树冠
    vm.setMaterial(Block.OAK_LEAVES)
    vm.createSphere(2)
    vm.setMaterial(Block.OAK_LOG)

10.3 用条件读取脚下方块决定接下来怎么走

vm.setMaterial(Block.GRASS_BLOCK)
for i in range(50):
    here = vm.getBlockType(vm.x, vm.y - 1, vm.z)
    if here == "WATER":
        # 遇水就架桥
        vm.setCursor(vm.x, vm.y - 1, vm.z)
        vm.createBlock(Block.OAK_PLANKS)
        vm.setCursor(vm.x, vm.y + 1, vm.z)
    vm.moveTo(1, Direction.FORWARD)

10.4 让游戏成为"猜数游戏"主持人

import random

target = random.randint(1, 100)
vm.saveValue("guess_target", target)
vm.broadcast("🎯 我心里想了一个 1~100 的数。聊天框猜！'高 / 低' 提示。")

vm.onEvent("chat", "", "player", "msg")
def _():
    t = vm.readValue("guess_target")
    try:
        n = int(msg)
    except:
        return
    if n == t:
        vm.broadcast(f"🎉 {player} 猜中了！是 {t}")
        vm.clearEvents()
    elif n < t:
        vm.sendMessage("太低啦 ↓")
    else:
        vm.sendMessage("太高啦 ↑")
vm.onEventEnd()

10.5 演示"等待切批次"

for layer in range(5):
    vm.createSquare(6, True, Block.STONE)
    vm.moveTo(1, Direction.UP)
    vm.wait(1)   # 每盖一层等 1 秒：玩家会看见塔逐层升起，而不是一闪而成

11. 常见错误与排查