如何用 Python 创建你自己的 MCP Server – wiki基地

作者： /

用 Python 打造你的 Minecraft Pi 世界：MCP 服务器开发终极指南

Minecraft，这款风靡全球的沙盒游戏，不仅仅是一个娱乐平台，更是一个充满无限创造可能的虚拟世界。而当我们将强大的编程语言 Python 与 Minecraft 结合时，这种创造力将被提升到全新的维度。Minecraft Pi Edition (MCP) 提供了一个简洁而强大的 Python API，允许我们通过编写脚本来与游戏世界进行交互、自动化建造、创建小游戏，甚至实现与现实世界数据的联动。

本文将是一份详尽的指南，带你一步步了解如何利用 Python 和 mcpi 库来“控制”你的 Minecraft Pi Edition 或兼容环境（如带有 RaspberryJuice 插件的 Java/Bedrock 版），实现自动化和创造性的玩法。虽然我们通常称之为“创建 MCP 服务器”，但更准确地说，我们是编写一个 Python 客户端脚本，连接到 Minecraft 游戏内置的 API 服务器，并向其发送指令。

文章目标读者：

  • 对 Python 编程有基本了解的爱好者。
  • 希望将编程技能应用于 Minecraft 的玩家。
  • 寻求自动化建造或创建自定义 Minecraft 体验的创客和教育者。

我们将涵盖：

  1. 理解 Minecraft Pi API (mcpi)：它是如何工作的？
  2. 环境准备：安装 Python、mcpi 库以及配置 Minecraft。
  3. 建立连接：编写第一个连接到 Minecraft 的 Python 脚本。
  4. 世界交互基础：获取玩家信息、发送消息。
  5. 方块操作：读取和放置方块，构建基础。
  6. 坐标系统详解：理解 Minecraft 中的 X, Y, Z。
  7. 批量操作与结构建造：使用 setBlocks 高效构建。
  8. 事件处理：响应游戏内的特定事件（如方块被击打）。
  9. 高级应用与项目构思：从简单脚本到复杂项目。
  10. 代码组织与最佳实践：编写更健壮、可维护的代码。
  11. 常见问题与限制：了解 API 的能力边界。

准备好了吗？让我们启程，用 Python 代码在 Minecraft 中施展魔法！

1. 理解 Minecraft Pi API (mcpi)

Minecraft Pi Edition 最初是为 Raspberry Pi 设计的免费 Minecraft 版本。它的一个核心特性就是内置了一个基于网络的 API，允许外部程序通过 TCP/IP 连接并控制游戏。这个 API 非常简洁，主要通过一个名为 mcpi 的 Python 库来访问。

工作原理：

  1. Minecraft 游戏端：运行 Minecraft Pi Edition 或带有兼容插件（如 RaspberryJuice for Spigot/Bukkit on Java Edition, 或类似功能的 Bedrock 插件）的 Minecraft 实例。游戏内部会启动一个监听特定端口（默认为 4711）的服务器。
  2. Python 脚本端：我们编写的 Python 脚本使用 mcpi 库。
  3. 连接：脚本通过 mcpi 库创建一个到游戏 API 服务器的 TCP 连接。
  4. 通信：脚本通过这个连接发送指令（如 setBlock, postToChat），游戏服务器接收指令并执行相应的操作。游戏也可以将信息（如玩家位置、事件）发送回脚本。

所以，我们并不是在“创建”游戏服务器本身，而是创建一个“控制器”或“客户端”，通过官方（或兼容）API 与正在运行的游戏实例互动。

2. 环境准备

在开始编码之前，我们需要确保所有必要的软件和配置都已就绪。

2.1 Python 安装

你需要一个 Python 3 的环境。大多数现代 Linux 发行版（包括 Raspberry Pi OS）和 macOS 都预装了 Python 3。Windows 用户需要从 Python 官网 (python.org) 下载并安装。

  • 验证安装：打开终端或命令提示符，输入 python --version 或 python3 --version。如果看到版本号（如 Python 3.9.2），则表示安装成功。
  • pip (包管理器)：确保 pip（或 pip3）也已安装，它是用来安装 Python 库的工具。通常随 Python 一起安装。可以运行 pip --version 或 pip3 --version 检查。

2.2 安装 mcpi 库

mcpi 库是与 Minecraft API 交互的关键。使用 pip 安装它：

“`bash
pip install mcpi

或者，如果你的系统区分 python2 和 python3 的 pip

pip3 install mcpi
“`

等待安装完成。如果遇到权限问题，可能需要在 Linux/macOS 上使用 sudo pip install mcpi，或者在 Windows 上以管理员身份运行命令提示符。

2.3 配置 Minecraft 环境

你有几种选择来运行一个带有 Python API 的 Minecraft 环境：

  • 选项 A: Raspberry Pi 上的 Minecraft Pi Edition (最原始，但功能有限)

    • 如果你有 Raspberry Pi，可以直接安装运行免费的 Minecraft Pi Edition。
    • 启动游戏后，进入一个世界，API 服务器会自动启动。
    • 优点：简单直接，无需额外插件。
    • 缺点：游戏版本非常老旧，方块和功能有限。

  • 选项 B: Minecraft Java Edition + RaspberryJuice 插件 (推荐)

    • 这是目前最流行和功能最全的方式。
    • 你需要购买并安装 Minecraft Java Edition。
    • 安装一个支持插件的服务器核心，如 Spigot 或 Paper (papermc.io)。设置服务器可能需要一些额外的步骤，可以搜索相关教程。
    • 下载 RaspberryJuice 插件 (dev.bukkit.org/projects/raspberryjuice 或其 fork) 的 .jar 文件，放入服务器的 plugins 文件夹。
    • 启动你的 Spigot/Paper 服务器。
    • 使用 Minecraft Java Edition 客户端连接到你自己的服务器 (地址通常是 localhost 或服务器 IP)。
    • 优点：可以使用现代 Minecraft 版本的所有方块和特性，社区支持好，性能更佳。
    • 缺点：设置稍复杂，需要 Java 版游戏和服务器设置知识。

  • 选项 C: Minecraft Bedrock Edition + 特定插件/工具 (可行性不一)

    • Bedrock 版的 API 支持情况比较复杂，不像 Java 版有统一成熟的插件。可能需要特定的服务器软件（如 NukkitX + 相应插件）或第三方工具。
    • 设置方法依赖于你选择的具体工具。
    • 优点：可能适用于无法运行 Java 版的设备。
    • 缺点：API 兼容性和稳定性可能不如 Java 版 + RaspberryJuice。

强烈推荐使用选项 B (Java Edition + RaspberryJuice)，因为它提供了最佳的兼容性和功能。本指南后续的示例主要基于这种环境，但它们同样适用于原版 Minecraft Pi Edition。

确认 API 服务器运行：

无论使用哪种方式，确保你的 Minecraft 游戏（或服务器）正在运行，并且你已经进入了一个游戏世界。API 服务器此时应该在后台监听连接。

3. 建立连接

现在环境准备就绪，让我们编写第一个 Python 脚本来连接 Minecraft。

创建一个新的 Python 文件（例如 hello_minecraft.py），输入以下代码：

“`python

导入 mcpi 库中的 Minecraft 类

from mcpi.minecraft import Minecraft
import time # 导入时间库，稍后可能用到

print(“正在尝试连接到 Minecraft…”)

try:
# 创建 Minecraft 连接对象
# 如果 Minecraft 和脚本在同一台机器上运行，通常不需要参数
# 如果在不同机器，需要指定 IP 地址: Minecraft.create(“your_minecraft_server_ip”)
mc = Minecraft.create()

# 检查连接是否成功（虽然 create() 失败会抛异常，这里多做一步确认）
# 尝试获取玩家位置，如果成功，说明连接有效
pos = mc.player.getTilePos()
print(f"连接成功！当前玩家坐标: X={pos.x}, Y={pos.y}, Z={pos.z}")

# 向游戏内发送一条聊天消息
message = "你好，Minecraft！来自 Python 的问候！"
mc.postToChat(message)
print(f"已发送消息: {message}")

# 脚本可以继续执行其他操作...
# 例如，等待几秒钟
# time.sleep(5)
# mc.postToChat("Python 脚本还在运行...")

except ConnectionRefusedError:
print(“连接失败！请确认 Minecraft 游戏已运行，并且已进入一个世界。”)
print(“如果是 Java 版 + RaspberryJuice，请确保服务器和插件已正确启动。”)
except Exception as e:
print(f”发生错误: {e}”)

print(“脚本执行完毕。”)
“`

运行脚本：

打开终端或命令提示符，导航到保存 hello_minecraft.py 的目录，然后运行：

“`bash
python hello_minecraft.py

或 python3 hello_minecraft.py

“`

预期结果：

  • 终端会输出 “正在尝试连接到 Minecraft…”。
  • 如果连接成功，会打印 “连接成功！” 和玩家当前的整数坐标，然后在 Minecraft 游戏窗口的聊天栏中看到 “你好，Minecraft！来自 Python 的问候！”。
  • 如果连接失败，会打印相应的错误信息。

代码解释：

  • from mcpi.minecraft import Minecraft: 从 mcpi 库导入核心的 Minecraft 类。
  • mc = Minecraft.create(): 这是关键步骤。它尝试在默认地址 (localhost) 和默认端口 (4711) 建立到 Minecraft API 服务器的连接，并返回一个 Minecraft 对象 (mc)。这个对象是后续所有交互的入口。
  • mc.player.getTilePos(): 调用 mc 对象下的 player 对象的 getTilePos() 方法，获取玩家所在的方块的整数坐标。这可以验证连接是否有效。
  • mc.postToChat(message): 调用 mc 对象的 postToChat() 方法，将指定的字符串发送到游戏聊天框。
  • try...except: 使用异常处理来捕获可能发生的 ConnectionRefusedError（连接被拒绝，通常意味着游戏没运行或 API 没开）或其他错误，使程序更健壮。

常见连接问题排查：

  • 确认游戏/服务器运行：这是最常见的问题。确保你已经在 Minecraft 世界里。
  • 防火墙：检查是否有防火墙阻止了 Python 脚本到 Minecraft（端口 4711）的连接。
  • IP 地址：如果 Python 脚本和 Minecraft 不在同一台机器上，确保在 Minecraft.create("服务器IP地址") 中使用了正确的 IP 地址。
  • 插件问题 (Java 版)：确认 RaspberryJuice 插件已正确安装在服务器 plugins 目录，并且服务器启动时没有报告关于该插件的错误。

4. 世界交互基础

成功连接后，我们可以开始与 Minecraft 世界进行更深入的互动。

4.1 获取玩家信息

mcpi 提供了获取玩家各种信息的方法，都通过 mc.player 对象访问。

“`python
from mcpi.minecraft import Minecraft

mc = Minecraft.create()

获取精确的浮点数坐标

pos_float = mc.player.getPos()
print(f”玩家精确坐标: X={pos_float.x:.2f}, Y={pos_float.y:.2f}, Z={pos_float.z:.2f}”)

获取所在的方块整数坐标 (常用)

pos_tile = mc.player.getTilePos()
print(f”玩家方块坐标: X={pos_tile.x}, Y={pos_tile.y}, Z={pos_tile.z}”)

获取玩家朝向 (0-3: 南, 西, 北, 东)

direction = mc.player.getDirection() # 返回一个向量，通常不直接用

更常用的是获取旋转角度 (水平方向)

rotation = mc.player.getRotation() # 0=南, 90=西, 180=北, 270=东
print(f”玩家水平朝向角度: {rotation:.1f}”)

获取玩家站立位置的方块类型

standing_block = mc.getBlock(pos_tile.x, pos_tile.y – 1, pos_tile.z)
print(f”玩家脚下方块 ID: {standing_block}”)

获取玩家头顶位置的方块类型 (注意 Y+1)

head_block = mc.getBlock(pos_tile.x, pos_tile.y + 1, pos_tile.z)
print(f”玩家头顶方块 ID: {head_block}”)
“`

4.2 设置玩家状态

我们也可以通过代码改变玩家的状态。

“`python
from mcpi.minecraft import Minecraft
import time

mc = Minecraft.create()
pos = mc.player.getTilePos()

瞬移玩家到当前位置上方 10 格

mc.postToChat(“准备传送…”)
time.sleep(2)
mc.player.setPos(pos.x + 0.5, pos.y + 10, pos.z + 0.5) # 使用 setPos 移动到空中
mc.postToChat(“传送完成！”)

time.sleep(3)

将玩家移动到指定方块坐标（会落在该方块顶部）

mc.postToChat(“移动到 (0, 64, 0) 方块上方…”)
time.sleep(2)
mc.player.setTilePos(0, 64, 0) # 使用 setTilePos 移动到方块
mc.postToChat(“移动完成！”)

设置玩家飞行能力 (需要服务器/游戏模式允许)

注意：这个功能在原版 Pi Edition 可能无效，但在 RaspberryJuice 下通常可以

try:
mc.player.setting(“autojump”, True) # 例如，启用自动跳跃 (不同插件支持的 setting 可能不同)
mc.postToChat(“尝试启用自动跳跃 (效果取决于服务器设置)”)
except Exception as e:
print(f”设置玩家 setting 时出错: {e}”)

“`

注意: mc.player.setting() 的可用性和具体参数名可能因 API 实现（原版 Pi vs RaspberryJuice）而异。查阅你所用环境的文档很重要。

5. 方块操作

这是 mcpi 最核心、最有趣的功能：读取和修改世界中的方块。

5.1 方块 ID 和数据值 (Block ID & Data)

Minecraft 中的每种方块都有一个唯一的数字 ID。例如：
* 0: 空气 (Air)
* 1: 石头 (Stone)
* 2: 草方块 (Grass Block)
* 3: 泥土 (Dirt)
* 4: 圆石 (Cobblestone)
* 5: 木板 (Planks) – 不同木材有不同的数据值
* 17: 木头 (Log) – 不同木材有不同的数据值
* 41: 金块 (Gold Block)
* 42: 铁块 (Iron Block)
* 57: 钻石块 (Diamond Block)
* … 等等

你可以在网上找到完整的 Minecraft 方块 ID 列表（搜索 “Minecraft block IDs”）。

数据值 (Data Value): 某些方块（如羊毛、木板、楼梯）有不同的变种（颜色、类型、朝向）。这些变种通过一个附加的 “数据值”（0-15）来区分。

  • 示例:
    • 羊毛 (ID 35): 数据值 0 是白色羊毛，1 是橙色，4 是黄色，14 是红色等。
    • 木板 (ID 5): 数据值 0 是橡木木板，1 是云杉木板，2 是桦木木板等。
    • 楼梯 (ID 53 – 橡木楼梯): 数据值决定了楼梯的朝向。

5.2 获取方块信息

我们可以查询世界中任意坐标的方块类型。

“`python
from mcpi.minecraft import Minecraft
from mcpi import block # 导入预定义的方块 ID 常量

mc = Minecraft.create()
pos = mc.player.getTilePos()

获取玩家正前方一格的方块 ID

(需要简单计算前方坐标，这里假设玩家面朝 Z 轴正方向)

一个更通用的方法需要用到玩家朝向，后面会涉及

front_x, front_y, front_z = pos.x, pos.y, pos.z + 1
block_id = mc.getBlock(front_x, front_y, front_z)
print(f”玩家正前方 ({front_x}, {front_y}, {front_z}) 的方块 ID 是: {block_id}”)

获取方块 ID 和数据值

block_with_data = mc.getBlockWithData(front_x, front_y, front_z)
print(f”方块 ID: {block_with_data.id}, 数据值: {block_with_data.data}”)

使用预定义的常量提高可读性

if block_id == block.STONE.id:
print(“这是一个石头方块！”)
elif block_id == block.AIR.id:
print(“前方是空气。”)
else:
print(f”这是一个 ID 为 {block_id} 的未知方块。”)
“`

mcpi.block 模块: 这个模块包含了很多常用方块的 ID 和数据值定义为常量（如 block.STONE, block.GRASS, block.WOOL.id, block.WOOL.data 等），使用它们能让代码更易读、更少出错。

5.3 放置方块

这是实现自动化建造的关键。

“`python
from mcpi.minecraft import Minecraft
from mcpi import block
import time

mc = Minecraft.create()
pos = mc.player.getTilePos()

在玩家头顶上方放置一个钻石块

x, y, z = pos.x, pos.y + 2, pos.z
mc.setBlock(x, y, z, block.DIAMOND_BLOCK.id)
mc.postToChat(f”已在 ({x}, {y}, {z}) 放置钻石块！”)
print(f”已放置钻石块在 X={x}, Y={y}, Z={z}”)

time.sleep(2)

在玩家脚下放置一个红色羊毛块

羊毛 ID 是 35，红色数据值是 14

wool_red_id = block.WOOL.id
wool_red_data = 14
x, y, z = pos.x, pos.y – 1, pos.z
mc.setBlock(x, y, z, wool_red_id, wool_red_data)
mc.postToChat(f”已在脚下放置红色羊毛！ (ID={wool_red_id}, Data={wool_red_data})”)
print(f”已放置红色羊毛在 X={x}, Y={y}, Z={z}”)

time.sleep(2)

将玩家正前方两格的方块变为空气 (删除方块)

front_x, front_y, front_z = pos.x, pos.y, pos.z + 2 # 假设面朝 Z+
mc.setBlock(front_x, front_y, front_z, block.AIR.id)
mc.postToChat(“已清除前方第二格的方块。”)
print(f”已清除方块在 X={front_x}, Y={front_y}, Z={front_z}”)
“`

setBlock(x, y, z, block_id, [data]):
* x, y, z: 要放置方块的目标坐标（整数）。
* block_id: 方块的数字 ID。
* data (可选): 方块的数据值，默认为 0。如果放置需要特定变种的方块（如彩色羊毛、不同木板），则必须提供此参数。

6. 坐标系统详解

熟练运用坐标是 Minecraft 编程的基础。

  • X 轴: 通常代表东西方向。正 X 值通常是东方，负 X 值是西方。
  • Z 轴: 通常代表南北方向。正 Z 值通常是南方，负 Z 值是北方。
  • Y 轴: 代表垂直高度。Y=0 通常是基岩层底部附近，Y=62 左右是海平面，Y=255 (Java) 或更高 (Bedrock) 是世界高度上限。

坐标类型：

  • 绝对坐标: 指的是世界中的固定位置，不随玩家移动而改变 (如 0, 64, 0)。setBlock, getBlock 等函数使用绝对坐标。
  • 相对坐标: 指的是相对于玩家当前位置的偏移量。例如，(0, 2, 1) 表示玩家头顶上方两格、再往前一格的位置。

在 Python 中处理相对坐标：

你需要先获取玩家的当前坐标，然后进行加减运算得到绝对坐标。

“`python
from mcpi.minecraft import Minecraft
from mcpi import block

mc = Minecraft.create()

获取玩家当前方块坐标

player_pos = mc.player.getTilePos()

定义相对偏移量

offset_x = 5
offset_y = 0
offset_z = -3 # 往北 3 格

计算绝对坐标

target_x = player_pos.x + offset_x
target_y = player_pos.y + offset_y
target_z = player_pos.z + offset_z

在计算出的绝对坐标处放置一个金块

mc.setBlock(target_x, target_y, target_z, block.GOLD_BLOCK.id)
mc.postToChat(f”已在相对于你 ({offset_x}, {offset_y}, {offset_z}) 的位置放置金块。”)
print(f”金块放置在绝对坐标: ({target_x}, {target_y}, {target_z})”)
“`

理解坐标系和如何在绝对与相对坐标间转换对于构建结构至关重要。

7. 批量操作与结构建造

一次只放一个方块效率很低。mcpi 提供了 setBlocks() 方法来一次性填充一个长方体区域。

setBlocks(x1, y1, z1, x2, y2, z2, block_id, [data]):

  • (x1, y1, z1): 长方体的一个角坐标。
  • (x2, y2, z2): 长方体的对角坐标。
  • block_id, data: 要填充的方块类型和数据值。

这个命令会用指定的方块填充从 (min(x1,x2), min(y1,y2), min(z1,z2)) 到 (max(x1,x2), max(y1,y2), max(z1,z2)) 的整个区域。

示例 1: 清空一个区域

“`python
from mcpi.minecraft import Minecraft
from mcpi import block
import time

mc = Minecraft.create()
pos = mc.player.getTilePos()

mc.postToChat(“将在你前方 5x5x5 的区域内进行操作…”)
time.sleep(2)

定义区域的两个对角 (相对于玩家)

x1 = pos.x + 1
y1 = pos.y
z1 = pos.z + 1
x2 = pos.x + 5
y2 = pos.y + 4
z2 = pos.z + 5

用空气填充这个区域 (清空)

mc.setBlocks(x1, y1, z1, x2, y2, z2, block.AIR.id)
mc.postToChat(“区域已清空！”)
print(f”已清空区域: ({x1},{y1},{z1}) 到 ({x2},{y2},{z2})”)
“`

示例 2: 建造一个实心石块立方体

“`python

… (接上例代码) …

mc.postToChat(“现在建造一个 3x3x3 的石头立方体…”)
time.sleep(2)

定义立方体的对角 (这次直接用绝对坐标)

cube_x1 = 10
cube_y1 = 70
cube_z1 = 10
cube_x2 = 12 # 10 + 2
cube_y2 = 72 # 70 + 2
cube_z2 = 12 # 10 + 2

mc.setBlocks(cube_x1, cube_y1, cube_z1, cube_x2, cube_y2, cube_z2, block.STONE.id)
mc.postToChat(“石头立方体建造完成！”)
print(f”已建造石头立方体: ({cube_x1},{cube_y1},{cube_z1}) 到 ({cube_x2},{cube_y2},{cube_z2})”)
“`

示例 3: 建造一个空心玻璃房

这需要一点技巧。先建一个实心玻璃房，再在内部用空气填充，留下一层外壳。

“`python
from mcpi.minecraft import Minecraft
from mcpi import block
import time

mc = Minecraft.create()
pos = mc.player.getTilePos()

房子尺寸

width = 7
height = 5
depth = 6

房子地基坐标 (相对于玩家)

base_x = pos.x + 2
base_y = pos.y
base_z = pos.z + 2

计算房子的对角坐标

x1 = base_x
y1 = base_y
z1 = base_z
x2 = base_x + width – 1
y2 = base_y + height – 1
z2 = base_z + depth – 1

mc.postToChat(“正在建造玻璃房…”)
time.sleep(1)

1. 建造实心玻璃房

mc.setBlocks(x1, y1, z1, x2, y2, z2, block.GLASS.id)
print(f”已建造实心玻璃房: ({x1},{y1},{z1}) 到 ({x2},{y2},{z2})”)
time.sleep(1) # 给服务器一点处理时间

2. 清空内部，留下 1 格厚的墙壁/地板/天花板

inner_x1 = x1 + 1
inner_y1 = y1 + 1 # 注意：如果需要地板，这里应该是 y1
inner_z1 = z1 + 1
inner_x2 = x2 – 1
inner_y2 = y2 – 1 # 注意：如果需要天花板，这里应该是 y2
inner_z2 = z2 – 1

确保内部坐标有效 (房子不能太小)

if inner_x1 <= inner_x2 and inner_y1 <= inner_y2 and inner_z1 <= inner_z2:
mc.setBlocks(inner_x1, inner_y1, inner_z1, inner_x2, inner_y2, inner_z2, block.AIR.id)
print(f”已清空内部区域: ({inner_x1},{inner_y1},{inner_z1}) 到 ({inner_x2},{inner_y2},{inner_z2})”)
else:
print(“房子太小，无法清空内部。”)

mc.postToChat(“玻璃房建造完毕！(可能没有门)”)

(可以后续添加一个门)

door_x = base_x + width // 2
door_y = base_y
door_z = base_z # 门开在 Z 轴最小的那面墙上
mc.setBlock(door_x, door_y, door_z, block.AIR.id)
mc.setBlock(door_x, door_y + 1, door_z, block.AIR.id)
print(f”已在 ({door_x}, {door_y}, {door_z}) 处开门。”)
“`

通过组合 setBlock 和 setBlocks，以及运用循环和条件判断，你可以用 Python 建造出非常复杂的结构。

8. 事件处理

除了主动向 Minecraft 发送指令，我们还可以让脚本响应游戏内发生的事件。mcpi 主要支持对方块被击打（左键或右键）事件的响应。

工作方式：

API 不会主动推送事件给你的脚本。相反，你的脚本需要在一个循环中不断地轮询 (poll) 服务器，询问“自从上次我问了之后，有没有新的方块被击打事件发生？”

mc.events.pollBlockHits():

  • 这个方法会返回一个列表 (list)，包含自上次调用以来发生的所有方块击打事件。
  • 如果列表为空，表示没有新事件。
  • 每个事件是一个 BlockEvent 对象，包含以下属性：
    • type: 事件类型 (通常是 BlockEvent.HIT)
    • pos: 被击打方块的坐标 (Vec3 对象，包含 x, y, z)
    • face: 被击打的方块表面 (0-5，代表不同方向，如 0=下方, 1=上方, 2=北, 3=南, 4=西, 5=东)
    • entityId: 触发事件的实体（通常是玩家）的 ID。

示例：当玩家右键点击钻石块时，在其上方生成一个金块

“`python
from mcpi.minecraft import Minecraft
from mcpi import block
import time

mc = Minecraft.create()

mc.postToChat(“事件监听已启动：右键点击钻石块试试！”)
print(“脚本正在监听方块点击事件… 按 Ctrl+C 停止。”)

try:
while True:
# 轮询方块击打事件
block_hits = mc.events.pollBlockHits()

    # 检查是否有事件发生
    if block_hits:
        print(f"检测到 {len(block_hits)} 个方块击打事件。")

        # 遍历所有捕获到的事件
        for hit in block_hits:
            print(f"  - 事件: 坐标=({hit.pos.x},{hit.pos.y},{hit.pos.z}), "
                  f"表面={hit.face}, 玩家ID={hit.entityId}")

            # 获取被击打方块的信息
            hit_block = mc.getBlockWithData(hit.pos.x, hit.pos.y, hit.pos.z)

            # 检查是否是钻石块 (ID 57) 被击打
            if hit_block.id == block.DIAMOND_BLOCK.id:
                mc.postToChat("检测到钻石块被点击！")
                print("  -> 是钻石块！")

                # 在钻石块上方放置一个金块
                target_x = hit.pos.x
                target_y = hit.pos.y + 1
                target_z = hit.pos.z
                mc.setBlock(target_x, target_y, target_z, block.GOLD_BLOCK.id)
                print(f"  -> 已在 ({target_x},{target_y},{target_z}) 放置金块。")
            else:
                print(f"  -> 不是钻石块 (ID: {hit_block.id})。")

    # 等待一小段时间再轮询，避免 CPU 占用过高
    time.sleep(0.1) # 每秒轮询 10 次

except KeyboardInterrupt:
print(“脚本被用户中断。”)
except Exception as e:
print(f”发生错误: {e}”)
finally:
mc.postToChat(“事件监听已停止。”)
print(“脚本结束。”)

“`

运行这个脚本：

  1. 确保你的 Minecraft 游戏或服务器正在运行，并且你已进入世界。
  2. 放置一个钻石块在世界里。
  3. 运行这个 Python 脚本。
  4. 回到 Minecraft，用鼠标右键（通常是放置键）点击你放下的钻石块。
  5. 观察效果：游戏内聊天框会提示，终端会打印信息，并且钻石块上方会出现一个金块。
  6. 尝试点击其他方块，脚本会检测到点击，但不会放置金块。
  7. 在终端按 Ctrl+C 可以停止脚本。

事件处理的应用：

  • 魔法棒：右键点击特定方块触发特殊效果（闪电、建造结构、传送）。
  • 交互式建筑：点击按钮或拉杆来动态改变建筑结构。
  • 简单游戏：打地鼠（点击特定方块得分）、寻宝（点击线索方块）。
  • 调试工具：点击方块显示其 ID、数据值和坐标。

注意： mcpi 的事件系统相对简单，主要就是方块点击。更复杂的事件（如玩家移动、物品使用、实体交互）通常需要更高级的 Modding API（如 Forge, Fabric, Spigot API）来实现。

9. 高级应用与项目构思

掌握了基础的连接、方块操作和事件处理后，你可以开始构思更复杂的项目了。

  • 自动化建造器：
    • 读取设计图文件（如 CSV 或自定义格式），自动在 Minecraft 中建造对应的结构。
    • 建造复杂的几何形状、像素画或大型建筑。
    • 一键建造常用设施（如农场、刷怪塔）。
  • 迷你游戏：
    • Spleef / TNT Run：玩家奔跑时脚下方块消失，最后存活者获胜。
    • 迷宫生成器：用 setBlocks 随机生成迷宫，玩家需要找到出口。
    • 寻宝游戏：隐藏宝箱，通过点击线索方块（事件处理）获得提示。
    • 跑酷地图自动生成：随机放置方块供玩家跳跃。
  • 数据可视化：
    • 将现实世界的数据（如天气、股票价格、社交媒体动态）映射到 Minecraft 世界中（例如用不同颜色的羊毛块表示温度，用方块高度表示股价）。
    • 需要 Python 能够访问外部数据源（如 API、文件）。
  • 交互式艺术/教育工具：
    • 建造一个巨大的像素画板，玩家可以通过点击方块来改变颜色。
    • 创建一个模拟太阳系的装置，行星按比例和轨道移动（通过定时 setBlock 实现）。
    • 构建交互式的电路或逻辑门演示。
  • 与物理设备的联动 (需要额外硬件和库)：
    • 通过 Raspberry Pi 的 GPIO 引脚，让现实世界的按钮或传感器触发 Minecraft 中的事件。
    • 让 Minecraft 中的事件（如红石信号）控制现实世界的 LED 灯或电机。

项目构思的关键： 将你的想法分解为可以通过 mcpi API 实现的小步骤（放置方块、获取位置、检测点击等），然后用 Python 逻辑将它们组合起来。

10. 代码组织与最佳实践

当你的脚本变得越来越复杂时，良好的代码组织和遵循最佳实践变得尤为重要。

  • 使用函数：将重复的代码块或逻辑单元封装到函数中。例如，创建一个 build_house(x, y, z, width, height, depth) 函数。这使代码更模块化、易读、易复用。
  • 添加注释：解释代码的目的、复杂逻辑或重要变量。方便自己和他人理解。
  • 使用有意义的变量名：player_x 比 px 好，wall_material 比 wm 好。
  • 常量定义：将方块 ID、尺寸、固定坐标等定义为大写字母常量，放在脚本开头，方便修改和理解。
    python
    # Constants
    HOUSE_WIDTH = 10
    WALL_BLOCK = block.BRICK_BLOCK.id
    ROOF_BLOCK = block.WOOD_STAIRS.id
  • 错误处理 (try...except)：在可能出错的操作（如连接、复杂计算、文件读写）周围使用 try...except 来优雅地处理错误，而不是让脚本崩溃。
  • 适当使用 time.sleep()：在需要大量操作（尤其是 setBlocks）或在循环中（如事件轮询），加入短暂的 time.sleep() 可以给 Minecraft 服务器处理时间，避免脚本运行过快导致卡顿或 API 调用失败。但也不要过度使用，以免脚本效率低下。
  • 版本控制 (Git)：对于较大的项目，使用 Git 进行版本控制，方便追踪修改、协作和回滚。
  • 备份 Minecraft 世界：在运行可能大规模修改世界的脚本之前，务必备份你的 Minecraft 世界存档！一个错误的坐标或逻辑可能造成无法挽回的破坏。

示例：使用函数构建

“`python
from mcpi.minecraft import Minecraft
from mcpi import block
import time

— Constants —

WALL_MATERIAL = block.COBBLESTONE.id
ROOF_MATERIAL = block.WOOD_PLANKS.id # 简单平顶

— Functions —

def build_solid_cuboid(mc, x1, y1, z1, x2, y2, z2, block_id, block_data=0):
“””建造一个实心长方体”””
mc.setBlocks(x1, y1, z1, x2, y2, z2, block_id, block_data)
print(f”Built cuboid: ({x1},{y1},{z1}) to ({x2},{y2},{z2}) with ID {block_id}”)

def build_hollow_shell(mc, x1, y1, z1, x2, y2, z2, shell_block_id, shell_block_data=0):
“””建造一个空心外壳”””
# Build solid shell
build_solid_cuboid(mc, x1, y1, z1, x2, y2, z2, shell_block_id, shell_block_data)
time.sleep(0.5) # Give server time

# Hollow out the inside
inner_x1 = min(x1, x2) + 1
inner_y1 = min(y1, y2) + 1
inner_z1 = min(z1, z2) + 1
inner_x2 = max(x1, x2) - 1
inner_y2 = max(y1, y2) - 1
inner_z2 = max(z1, z2) - 1

if inner_x1 <= inner_x2 and inner_y1 <= inner_y2 and inner_z1 <= inner_z2:
    build_solid_cuboid(mc, inner_x1, inner_y1, inner_z1, inner_x2, inner_y2, inner_z2, block.AIR.id)
    print("Hollowed out the inside.")
else:
    print("Structure too small to hollow.")

def build_simple_house(mc, base_x, base_y, base_z, width, height, depth):
“””建造一个简单的房子”””
mc.postToChat(“Building a simple house…”)

# Calculate corners
x1, y1, z1 = base_x, base_y, base_z
x2 = base_x + width - 1
y2 = base_y + height - 1
z2 = base_z + depth - 1

# Build walls (hollow shell)
print("Building walls...")
build_hollow_shell(mc, x1, y1, z1, x2, y2 -1 , z2, WALL_MATERIAL) # Walls stop one block below roof height

# Build roof (solid flat roof)
print("Building roof...")
roof_y = y2 # Roof is at the top height
build_solid_cuboid(mc, x1, roof_y, z1, x2, roof_y, z2, ROOF_MATERIAL)

# Add a door (simple opening)
print("Adding door...")
door_x = base_x + width // 2
mc.setBlock(door_x, base_y, base_z, block.AIR.id) # Bottom part
mc.setBlock(door_x, base_y + 1, base_z, block.AIR.id) # Top part

mc.postToChat("House construction complete!")

— Main Execution —

if name == “main“:
print(“Connecting to Minecraft…”)
try:
mc_conn = Minecraft.create()
player_pos = mc_conn.player.getTilePos()

    # Build a house near the player
    house_x = player_pos.x + 5
    house_y = player_pos.y
    house_z = player_pos.z

    build_simple_house(mc_conn, house_x, house_y, house_z, width=7, height=4, depth=6)

except ConnectionRefusedError:
    print("Connection failed. Is Minecraft running with the API enabled?")
except Exception as e:
    print(f"An error occurred: {e}")

print("Script finished.")

“`

11. 常见问题与限制

  • API 功能有限：mcpi 是一个相对基础的 API。它不能直接：
    • 创建自定义方块或物品。
    • 生成或控制生物 (Mobs)。
    • 监听除方块点击外的复杂事件（如玩家移动、物品交互）。
    • 修改玩家物品栏（虽然有些 fork 或插件可能添加了实验性支持）。
    • 读取或修改 NBT 数据。
    • 对于这些高级功能，你需要转向更复杂的 Modding API（如 Spigot/Paper API for Java, 或 Bedrock Add-ons）。
  • 性能：大量连续的 setBlock 调用比一次 setBlocks 效率低得多。非常大的 setBlocks 操作也可能导致服务器暂时卡顿。需要权衡操作粒度和性能。
  • 兼容性：虽然 RaspberryJuice 插件试图模拟原版 Pi API，但可能存在细微差别或扩展功能。如果你在不同环境间切换，可能需要调整代码。原版 Minecraft Pi Edition 本身功能非常受限。
  • 坐标错误：坐标计算错误是导致建筑混乱或破坏的主要原因。务必仔细检查坐标逻辑，尤其是在使用相对坐标或循环时。
  • 多脚本冲突：如果同时运行多个 Python 脚本连接到同一个 Minecraft 实例，它们可能会相互干扰（例如，同时修改同一个方块）。需要协调或设计避免冲突的逻辑。
  • 服务器侧限制：服务器的配置（如视距、区块加载）可能会影响脚本的效果，尤其是在操作远距离的方块时。某些服务器插件（如领地插件）也可能阻止 Python 脚本修改特定区域。

结语

通过 mcpi 库，Python 为我们打开了一扇通往程序化控制 Minecraft 世界的大门。从简单的方块放置、信息获取，到复杂的结构建造和事件响应，你现在拥有了将编程创意融入这款流行游戏的工具。

我们已经详细探讨了环境搭建、API 基础、方块操作、坐标系统、批量建造、事件处理，以及代码组织和最佳实践。虽然 mcpi API 有其局限性，但它的简洁性使其成为入门 Minecraft 编程的绝佳选择，并且足以实现许多有趣和富有创造力的项目。

现在，真正的冒险开始了。尝试修改示例代码，构思你自己的项目，无论是自动化繁琐的建造任务，创造独特的迷你游戏，还是将 Minecraft 与外部世界连接起来。不断实践、查阅文档（包括 mcpi 库本身的源码和 RaspberryJuice 的说明），并从社区中学习。

用 Python 作为你的画笔，Minecraft 作为你的画布，去创造属于你自己的奇迹吧！

发表评论

您的邮箱地址不会被公开。 必填项已用 * 标注

滚动至顶部