Python编程Minecraft-03-基于minescript复写mcpy库

Python编程Minecraft系列（少儿编程）

第三章-基于minescript复写mcpy库

---

---

前言

minescript原始库api使用了调用execute函数执行minecraft的命令，对于中小学生来说不太友好，因此，基于minescript复写了一个相对友好的库，名为mcpy。

---

快速开始

安装和导入

MCPY已经整合了Minescript的所有功能，只需要导入一个包即可使用所有功能：

from mcpy import *

注意:

• 不再需要单独导入minescript包
• 所有Minescript的原始API都已集成到MCPY中
• 可以直接使用所有函数，包括echo(), chat(), execute()等

基本使用示例

#导入mcpy库
from mcpy import *

# 基础输出
echo("Hello, Minecraft!")
chat("欢迎使用MCPY！")

# 获取玩家当前位置
pos = player_position()
echo("玩家位置: " + str(pos))

# 方块操作（基于玩家位置）
place_block(pos[0] + 5, pos[1], pos[2], "diamond_block")
block_type = getblock(pos[0] + 5, pos[1], pos[2])
echo("方块类型: " + block_type)

# 建筑功能（在玩家前方建造房屋）
build_house(pos[0] + 10, pos[1], pos[2] + 10)

# 实体操作（在玩家附近生成动物）
spawn_animal(pos[0] + 3, pos[1], pos[2] + 3, "pig")

# 事件处理（按键G生成猪）
with EventQueue() as event_queue:
    # 注册键盘事件监听器
    event_queue.register_key_listener()
    
    while True:
        try:
            # 获取事件，设置超时时间
            event = event_queue.get(timeout=1.0)
            
            if event.type == EventType.KEY and event.action == 1:  # 按键按下
                if event.key == 71:  # G键
                    # 在玩家附近生成猪
                    x, y, z = get_player_position()
                    spawn_animal(x + 2, y, z, "pig")
                    show_message("🐷 已生成一只猪！")
                    play_sound("entity.pig.ambient")
                elif event.key == 256:  # ESC键
                    show_message("退出生成猪模式")
                    break
                    
        except:
            # 捕获超时异常（queue.Empty），这是正常的，继续等待
            continue

字符串格式化说明

在Python编程中，我们经常需要将变量的值插入到字符串中。MCPY API文档中使用了适合中小学生理解的字符串拼接方法：

基本字符串拼接

使用 + 号将字符串和变量连接起来：

name = "小明"
echo("玩家名称: " + name)

数字转字符串

当变量是数字时，需要用 str() 函数将其转换为字符串：

x, y, z = 100, 64, 200
echo("坐标: " + str(x) + ", " + str(y) + ", " + str(z))

其他格式化方法

除了字符串拼接，Python还有其他格式化方法：

1. format()方法（适合有一定基础的学生）：

name = "小明"
echo("玩家名称: {}".format(name))

2. f-string（Python 3.6+，较高级）：

name = "小明"
echo(f"玩家名称: {
     
     name}")

建议：初学者建议使用字符串拼接（+号）的方式，这样更容易理解和调试。

---

功能模块概览

MCPY包含以下主要功能模块：

1. 基础方块操作 - 放置、获取、批量操作方块
2. 建筑功能 - 快速建造各种结构
3. 动物和生物 - 生成和管理实体
4. 环境控制 - 天气、时间、效果控制
5. 玩家交互 - 传送、物品管理、界面显示
6. 输出和通信 - 消息输出、聊天、命令执行
7. 音效和粒子 - 声音和视觉效果
8. 红石控制 - 红石电路操作
9. 高级功能 - 数据处理、文件操作
10. 玩家信息与控制 - 玩家状态和操作
11. 实用工具函数 - 辅助功能
12. 事件处理系统 - 游戏事件监听和响应
13. 实体管理和世界信息 - 高级世界操作

---

Minecraft坐标系统说明

坐标轴定义

Minecraft使用三维坐标系统，所有位置都通过[x, y, z]坐标来表示。这些坐标是世界绝对坐标，与玩家朝向无关，始终保持固定的方向定义。

坐标轴方向

1. X轴（东西方向）：

   • 正X方向：向东 (East)
   • 负X方向：向西 (West)

2. Y轴（垂直方向）：

   • 正Y方向：向上 (Up)
   • 负Y方向：向下 (Down)
   • Y=64通常是海平面高度

3. Z轴（南北方向）：

   • 正Z方向：向南 (South)
   • 负Z方向：向北 (North)

重要特点

• 绝对坐标系统：坐标相对于世界原点(0,0,0)的绝对位置
• 固定方向：无论玩家面向哪个方向，坐标轴方向都是固定的
• 单位长度：每个坐标单位等于一个方块的边长
• 坐标范围：世界坐标通常在-30,000,000到+30,000,000之间

坐标使用示例

# 获取玩家位置（返回绝对坐标）
pos = player_position()  # 返回 [x, y, z] 列表
x, y, z = pos[0], pos[1], pos[2]

# 在玩家东边10格放置方块
place_block(int(x) + 10, int(y), int(z), "diamond_block")

# 在玩家南边5格放置方块  
place_block(int(x), int(y), int(z) + 5, "gold_block")

# 在玩家上方3格放置方块
place_block(int(x), int(y) + 3, int(z), "emerald_block")

方向对照表

方向	坐标变化	说明
东 (East)	X增加	+X方向
西 (West)	X减少	-X方向
上 (Up)	Y增加	+Y方向
下 (Down)	Y减少	-Y方向
南 (South)	Z增加	+Z方向
北 (North)	Z减少	-Z方向

---

API 函数分类

一、基础方块操作

1.1 place_block()

place_block(x: int, y: int, z: int, block_type: str = "stone")

在指定位置放置方块。

参数:

• x, y, z: 方块坐标位置
• block_type: 方块类型，默认为"stone"

方块状态支持:
某些方块支持状态属性，可以通过在方块名称后添加[属性=值]来设置：

# 普通火把（放置在地面）
place_block(x, y, z, "torch")

# 墙上火把（附着在墙面）
place_block(x, y, z, "wall_torch[facing=east]")   # 面向东方
place_block(x, y, z, "wall_torch[facing=west]")   # 面向西方
place_block(x, y, z, "wall_torch[facing=north]")  # 面向北方
place_block(x, y, z, "wall_torch[facing=south]")  # 面向南方

# 墙上告示牌（附着在墙面）
place_block(x, y, z, "oak_wall_sign[facing=east]")   # 面向东方的橡木告示牌
place_block(x, y, z, "birch_wall_sign[facing=west]") # 面向西方的白桦告示牌
place_block(x, y, z, "spruce_wall_sign[facing=north]") # 面向北方的云杉告示牌

# 物品展示框（附着在墙面）
place_block(x, y, z, "item_frame[facing=east]")   # 面向东方的物品展示框
place_block(x, y, z, "item_frame[facing=west]")   # 面向西方的物品展示框
place_block(x, y, z, "item_frame[facing=north]")  # 面向北方的物品展示框
place_block(x, y, z, "item_frame[facing=south]")  # 面向南方的物品展示框

# 画（附着在墙面）
place_block(x, y, z, "painting[facing=east]")     # 面向东方的画
place_block(x, y, z, "painting[facing=west]")     # 面向西方的画

# 墙上旗帜（附着在墙面）
place_block(x, y, z, "white_wall_banner[facing=east]")  # 面向东方的白色旗帜
place_block(x, y, z, "red_wall_banner[facing=west]")    # 面向西方的红色旗帜

# 楼梯方块
place_block(x, y, z, "oak_stairs[facing=north,half=bottom]")

# 红石中继器
place_block(x, y, z, "repeater[facing=east,delay=4]")

示例:

place_block(100, 64, 100, "diamond_block")  # 放置钻石块
place_block(0, 65, 0, "grass_block")        # 放置草方块
place_block(10, 64, 10)                     # 放置默认石头方块

# 在墙上放置火把照明
place_block(x + 1, y + 2, z, "wall_torch[facing=east]")  # 东墙上的火把
place_block(x - 1, y + 2, z, "wall_torch[facing=west]")  # 西墙上的火把

# 在墙上放置装饰物品
place_block(x, y + 2, z + 1, "oak_wall_sign[facing=south]")  # 南墙上的告示牌
place_block(x + 1, y + 2, z + 5, "item_frame[facing=north]") # 北墙上的物品展示框
place_block(x - 1, y + 3, z + 2, "painting[facing=east]")    # 东墙上的画
place_block(x + 5, y + 3, z, "white_wall_banner[facing=south]") # 南墙上的白色旗帜

1.2 get_block()

get_block(x: int, y: int, z: int) -> str

获取指定位置的方块类型。

参数:

• x, y, z: 方块坐标位置

返回值:

• 方块类型字符串

示例:

block = get_block(100, 64, 100)
echo("这个位置的方块是: " + block)

# 检查玩家脚下的方块
x, y, z = get_player_position()
ground_block = get_block(x, y-1, z)
echo("你脚下是: " + ground_block)

1.3 clear_block()

clear_block(x: int, y: int, z: int)

清除指定位置的方块（替换为空气）。

参数:

• x, y, z: 方块坐标位置

示例:

clear_block(100, 64, 100)  # 清除这个位置的方块

1.4 fill_area()

fill_area(x1: int, y1: int, z1: int, x2: int, y2: int, z2: int, block_type: str = "stone")

用指定方块填充立方体区域。

参数:

• x1, y1, z1: 起始坐标
• x2, y2, z2: 结束坐标
• block_type: 填充的方块类型，默认为"stone"

示例:

fill_area(0, 64, 0, 10, 64, 10, "grass_block")  # 创建草地平台
fill_area(0, 65, 0, 10, 70, 10, "glass")        # 创建玻璃盒子

1.5 get_block_list()

get_block_list(positions: List[List[int]]) -> List[str]

批量获取多个位置的方块类型。

参数:

• positions: 位置列表，每个位置为[x, y, z]格式的列表

返回值:

• 方块类型字符串列表，与输入位置列表对应

示例:

# 批量获取方块
positions = [[100, 64, 100], [101, 64, 100], [102, 64, 100]]
blocks = get_block_list(positions)
for i, block in enumerate(blocks):
    echo(f"位置 {
     
     positions[i]} 的方块是: {
     
     block}")

1.6 get_block_region()

get_block_region(pos1: Tuple[int, int, int], pos2: Tuple[int, int, int]) -> BlockRegion

获取区域内所有方块信息。

参数:

• pos1: 起始坐标(x, y, z)
• pos2: 结束坐标(x, y, z)

返回值:

• BlockRegion对象

示例:

# 获取区域内所有方块
region = get_block_region((0, 64, 0), (10, 70, 10))
for x in range(region.x_length):
    for y in range(region.y_length):
        for z in range(region.z_length):
            block = region.get_block(
                region.min_pos[0] + x,
                region.min_pos[1] + y, 
                region.min_pos[2] + z
            )
            echo("方块 (" + str(x) + "," + str(y) + "," + str(z) + "): " + block)

1.7 clear_area()

clear_area(x1: int, y1: int, z1: int, x2: int, y2: int, z2: int)

清空立方体区域（用空气填充）。

参数:

• x1, y1, z1: 起始坐标
• x2, y2, z2: 结束坐标

示例:

clear_area(0, 65, 0, 10, 70, 10)  # 清空一个区域

二、批量方块操作 - BlockPacker

1.8 BlockPacker类

from mcpy import BlockPacker

BlockPacker是用于批量方块操作的高级工具类。

创建BlockPacker

packer = BlockPacker()

添加方块

packer.setblock(position: Tuple[int, int, int], block_type: str)
packer.add_blocks(positions: List[Tuple[int, int, int]], block_types: List[str])

参数:

• position: 方块位置(x, y, z)
• block_type: 方块类型
• positions: 位置列表
• block_types: 方块类型列表

示例:

# 创建方块打包器
packer = BlockPacker()

# 添加单个方块
packer.setblock((100, 64, 100), "stone")
packer.setblock((101, 64, 100), "cobblestone")

# 批量添加方块
positions = [(102, 64, 100), (103, 64, 100)]
block_types = ["diamond_block", "gold_block"]
packer.add_blocks(positions, block_types)

打包和放置

blockpack = packer.pack(metadata: dict = None)
blockpack.place(offset: Tuple[int, int, int])
blockpack.write_world(position: Tuple[int, int, int])

参数:

• metadata: 可选的元数据字典
• offset: 偏移位置
• position: 放置位置

示例:

# 打包方块
blockpack = packer.pack({
   
   "author": "作者", "description": "建筑描述"})

# 在新位置放置
blockpack.place((200, 64, 200))
blockpack.write_world((300, 64, 300))

保存和加载方块包

# 保存到文件
blockpack.write_file("my_building.bp")

# 从文件加载
from mcpy import BlockPack
loaded_pack = BlockPack.read_file("my_building.bp")
loaded_pack.write_world((100, 64, 100))  # 在新位置放置

示例:

# 完整的方块包使用示例
packer = BlockPacker()

# 创建一个小房子
for x in range(5):
    for z in range(5):
        packer.setblock((x, 0, z), "stone")  # 地基
        if x == 0 or x == 4 or z == 0 or z == 4:
            for y in range(1, 4):
                packer.setblock((x, y, z), "cobblestone")  # 墙壁

# 打包并保存
house_pack = packer.pack({
   
   "name": "小房子", "author": "MCPY"})
house_pack.write_file("small_house.bp")

# 在多个位置放置房子
for i in range(3):
    house_pack.write_world((i * 10, 64, 0))

2.1 build_house()

build_house(x: int, y: int, z: int, width: int = 8, height: int = 6, depth: int = 8, 
           wall_material: str = "stone_bricks", floor_material: str = "oak_planks", 
           roof_material: str = "oak_planks")

建造完整的房屋，包含精美的建筑细节和室内装饰。

参数:

• x, y, z: 房屋起始位置（西南角）
• width, height, depth: 房屋尺寸，默认8x6x8
• wall_material: 墙壁材料，默认"stone_bricks"（石砖）
• floor_material: 地板材料，默认"oak_planks"（橡木板）
• roof_material: 屋顶材料，默认"oak_planks"（橡木板）

建筑特点:

• 地基设计: 外围石砖地基，内部橡木地板
• 墙体结构: 5层高石砖墙体，坚固美观
• 门窗设计: 南面双门入口配台阶，东西北三面安装玻璃窗
• 装饰元素: 窗户同高度橡木板装饰圈，提升美观度
• 屋顶设计: 三角形屋顶，东西两侧橡木楼梯斜面
• 室内装饰: 包含床、储物箱和火把照明

示例:

build_house(100, 64, 100)  # 建造默认房屋
build_house(0, 64, 0, 10, 7, 10, "bricks", "dark_oak_planks", "spruce_planks")  # 建造大型砖房

2.2 build_wall()

build_wall(x1: int, y1: int, z1: int, x2: int, y2, z2: int, material: str = "cobblestone")

建造墙壁。墙壁高度通过起始和结束位置的y坐标差来确定。

参数:

• x1, y1, z1: 墙壁起始位置
• x2, y2, z2: 墙壁结束位置
• material: 墙壁材料，默认"cobblestone"

高度设定说明:
墙壁的高度由y1和y2坐标的差值决定：

• 高度计算: 墙壁高度 = |y2 - y1| + 1
• 建造方向: 墙壁会填充从较低y坐标到较高y坐标之间的所有方块
• 最小高度: 当y1 = y2时，建造1格高的墙壁
• 向上建造: 当y2 > y1时，墙壁向上延伸
• 向下建造: 当y1 > y2时，墙壁向下延伸

示例:

# 建造3格高的石砖墙（从y=64到y=66）
build_wall(0, 64, 0, 10, 66, 0, "stone_bricks")

# 建造5格高的圆石墙（从y=60到y=64）
build_wall(100, 60, 50, 120, 64, 50, "cobblestone")

# 建造1格高的围墙（y坐标相同）
build_wall(0, 64, 0, 0, 64, 20, "oak_fence")

# 建造垂直墙壁（沿z轴，高度为4格）
build_wall(10, 64, 10, 10, 67, 20, "brick")

# 建造水平墙壁（沿x轴，高度为6格）
build_wall(0, 64, 0, 15, 69, 0, "stone")

2.3 build_bridge()

build_bridge(x1: int, y: int, z1: int, x2: int, z2: int, material: str = "oak_planks")

建造桥梁，自动添加栏杆。

参数:

• x1, y, z1: 桥梁起始位置
• x2, z2: 桥梁结束位置（相同y坐标）
• material: 桥梁材料，默认"oak_planks"

示例:

build_bridge(0, 64