Skip to main content

water-structure Python 教程

water-structure 是 WaterStructureCpp 的 Python 绑定,用于识别、检查和转换 Minecraft Java/Bedrock 结构文件,以及把结构 流式写入 Bedrock 世界。平台 wheel 已包含原生动态库与方块映射资产,正常安装时不需要 另外部署 C++ 库。

当前项目处于 Alpha 阶段。转换真实世界前,请先备份目标世界。不要在 Minecraft 正在打开世界时写入同一个世界目录或 .mcworld 文件。

1. 安装

建议为每个项目创建独立虚拟环境。

Windows PowerShell

py -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
python -m pip install water-structure

Linux / macOS

python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install water-structure

Android Termux(arm64-v8a)

pkg update
pkg install python
python -m pip install --upgrade pip
python -m pip install water-structure

访问手机共享存储前执行一次 termux-setup-storage,之后可以使用 ~/storage/downloads 等路径。如果 pip 报 wheel 平台不兼容,先检查当前 pip 是否识别 Android 标签:

python -m pip debug --verbose | grep android

当前 Termux wheel 目标为 Android API 24+、arm64-v8a。

验证安装

python -c "import water_structure as ws; print(ws.version(), ws.abi_version())"

version() 是捆绑的原生库版本,abi_version() 是 C ABI 版本。当前 ABI 为 1; Python 包和原生库 ABI 不匹配时会直接导入失败。

2. 核心接口

接口 用途 是否产生输出文件
Context.format(path) 自动识别输入格式 否
Context.inspect(path) 获取尺寸、偏移和非空气数量 否
Context.convert(input, format, output) 转为一个已实现 writer 的结构格式 是
Context.to_world(input, world) 写入 Bedrock 目录世界或 .mcworld 是
formats() 读取逐方向 capability matrix 否

输入格式始终自动识别;输出格式必须明确指定。扩展名不会替你决定 SchemV1 还是 SchemV2。

所有操作都通过 Context 使用。它会加载 runtime registry 和升级映射,因此同一批 连续任务应复用一个 Context:

from water_structure import Context

with Context() as ctx:
    print(ctx.format("building.schem"))
    print(ctx.inspect("building.schem"))
# 离开 with 后自动释放原生资源

不要让多个 Python 线程同时调用同一个 Context。需要并发隔离时,每个线程或进程 创建自己的 Context;大型转换通常受磁盘与内存带宽限制,并发任务过多反而更慢。

可以在提交批处理前检查目标方向是否真正实现:

from water_structure import formats

for capability in formats():
    print(
        capability.name,
        "reader=", capability.file_reader,
        "writer=", capability.file_writer,
        "to-world=", capability.structure_to_world,
        "from-world=", capability.world_to_structure,
    )

capability 是按方向审计的;有 reader 不等于能写同格式,有 file writer 也不等于结果 是完全无损 round-trip。lossy_round_trip=True 表示存在已声明的有损投影。

3. 第一次转换

下面示例自动识别输入,然后输出指定版本的 .schem:

from pathlib import Path
from water_structure import Context

source = Path(r"D:\import\building.mcworld")
output = Path(r"D:\import\building-v2.schem")

with Context() as ctx:
    detected = ctx.format(source, streaming_world_import=True)
    info = ctx.inspect(source, streaming_world_import=True)

    print("格式:", detected)
    print("尺寸:", info.width, info.height, info.length)
    print("偏移:", info.offset_x, info.offset_y, info.offset_z)
    print("非空气:", info.non_air_blocks)

    ctx.convert(source, "SchemV2", output, threads=0)

print("已生成:", output)

路径参数接受 str、pathlib.Path 和其他 os.PathLike;中文路径无需手工编码。

4. 格式识别与结构信息

format()

with Context() as ctx:
    print(ctx.format("house.schem"))
    print(ctx.format("world.mcworld", streaming_world_import=True))

返回 registry 格式名,例如 SchemV1、SchemV2、BDX 或 MCWorld。同扩展名 格式会按兼容顺序读取文件头和内容试探,而不是只看扩展名。

inspect()

info = ctx.inspect("house.schem")

print(info.format_id)       # 内部 StructureId 数值
print(info.width)           # X 方向尺寸
print(info.height)          # Y 方向尺寸
print(info.length)          # Z 方向尺寸
print(info.offset_x)
print(info.offset_y)
print(info.offset_z)
print(info.non_air_blocks)

返回值为不可变的 StructureInfo 命名元组:

StructureInfo(
    format_id: int,
    width: int,
    height: int,
    length: int,
    offset_x: int,
    offset_y: int,
    offset_z: int,
    non_air_blocks: int,
)

对目录世界或 .mcworld 调用 format()/inspect() 时,可以设置 streaming_world_import=True,避免为了读取元信息而构造完整内存结构。统计非空气数量 仍然需要扫描相关世界数据,所以“大文件低内存”不等于“无需读取”。该参数只属于 format() 和 inspect();convert() 会由 C++ 转换器选择对应的流式路径。

5. convert():结构格式互转

ctx.convert(input_path, target_format, output_path, threads=0)
  • input_path:自动识别的源结构文件、目录世界或 .mcworld。
  • target_format:目标 writer 的 registry 名称;建议使用下表中的标准写法。
  • output_path:目标文件路径,父目录应已存在。
  • threads:编码 worker 数,必须大于等于 0。

当前已验证的 writer:

target_format 常用扩展名 说明
Schematic .schematic 经典 Java legacy 格式
SchemV1 .schem Sponge Schematic V1
SchemV2 .schem Sponge Schematic V2
Litematic .litematic Litematica
MCStructure .mcstructure Bedrock Structure Block 格式
BDX .bdx Brotli 压缩命令流
AxiomBP .bp Axiom Blueprint
MCFunction .mcfunction / .txt Bedrock fill/setblock 命令流
IBImport .ibi 命令段流式输出,支持 fill 合并
FuHongV4 .json FuHong V4 JSON
FuHongV5 .fhbuild FuHong V5 二进制格式

有 reader 不代表有 writer。尝试输出到只有 reader 的格式会抛出 capability error, 不会猜测或伪造协议。

.schem 必须指定 V1/V2

ctx.convert("input.bdx", "SchemV1", "output-v1.schem")
ctx.convert("input.bdx", "SchemV2", "output-v2.schem")

不能把目标格式写成模糊的 Schem。

转为 BDX

ctx.convert("building.mcworld", "BDX", "building.bdx", threads=2)

BDX 读取与写入使用流式命令处理;大型稀疏世界仍可能花费较长时间进行范围扫描、 Brotli 编码和世界数据读取。

转为 IBImport

ctx.convert("building.schem", "IBImport", "building.ibi", threads=0)

IBImport writer 会把连续同类方块尽量合并为 fill,其命令坐标使用相对坐标。

转为 MCFunction

ctx.convert("building.mcworld", "MCFunction", "building.mcfunction")

# 合并到已有世界时不清空目标范围,只输出非空气方块
ctx.convert(
    "building.mcworld",
    "MCFunction",
    "building-merge.mcfunction",
    clear_air=False,
)

# 按 16x16 区块分别执行三维合并,方块放置 fill 不会跨区块边界
ctx.convert(
    "building.mcworld",
    "MCFunction",
    "building-by-chunk.mcfunction",
    chunk_partition=True,
)

生成的是 Bedrock 方块状态命令。fill 和 setblock 坐标使用 ~x ~y ~z,执行 函数时以执行位置为结构锚点。MCFunction 没有统一的 Bedrock 方块实体 NBT 协议, 因此 writer 会跳过方块实体 NBT,而不是让整个转换失败。

threads 应如何选择

ctx.convert(source, "MCFunction", output, threads=0)  # 推荐:自动
ctx.convert(source, "MCFunction", output, threads=1)  # 串行、便于基准对比
ctx.convert(source, "MCFunction", output, threads=2)  # 显式两个编码线程
  • threads=0:自动选择;极小任务使用 1 个 worker,其他任务默认最多 2 个。
  • threads=1:禁用 writer 编码并行。
  • threads=N:显式设置编码 worker 数。

线程数只控制支持并行编码的阶段,不会让所有解析器和压缩步骤自动变成 N 线程。 大型转换常受磁盘、LevelDB、压缩或内存带宽限制,超过 2 个编码线程不保证更快。

流式内存与队列选项

ctx.convert(
    source,
    "SchemV2",
    output,
    memory_budget_mib=450,
    max_in_flight_tasks=0,
    max_in_flight_chunks=0,
    allow_temporary_spool=True,
)
  • memory_budget_mib 是原生流式队列和缓存的软预算,允许范围为 64~8192 MiB;它不是 操作系统级硬上限。
  • 两个 max_in_flight_* 为 0 时使用原生保守默认值;显式值允许范围为 0~4096。
  • allow_temporary_spool=False 会禁止需要受控临时文件的优化或兼容路径,某些超大或 必须回看输入的格式可能因此失败。

若必须保证整个进程不超过 500 MiB,应在进程外同时使用项目的 limited_runner;不要 把 memory_budget_mib=500 当成硬限制,因为动态库、runtime registry、Python 和压缩库 本身也会占内存。

SchemV1/V2 写入世界时会走直接 gzip 流路径,跳过完整 BlockData 临时文件;即使 Palette 位于 BlockData/Data 后面,也只做不落盘的元数据扫描。超过 uint16 palette 容量等特殊输入自动回退到索引临时文件路径。

6. to_world():写入 Bedrock 世界

ctx.to_world(
    input_path,
    world_path,
    start=(0, -4, 0),
    threads=0,
    memory_budget_mib=450,
    max_in_flight_chunks=0,
)

start 是 (chunk_x, subchunk_y, chunk_z),不是方块坐标。默认 Y 为 -4,对应 方块高度 -64;每个 chunk/subchunk 轴单位对应 16 个方块。

写入目录世界

from pathlib import Path
from water_structure import Context

target = Path("output_world")
with Context() as ctx:
    ctx.to_world("building.schem", target)

目标不存在时会创建目录世界。目标是已有世界目录时会更新其 LevelDB 数据;请先备份, 并确保 Minecraft 没有占用该世界。

写入 .mcworld

输出路径使用 .mcworld 或 .zip 扩展名时,可以直接创建新的世界归档,不需要先 准备模板:

from pathlib import Path
from water_structure import Context

target = Path("building.mcworld")

with Context() as ctx:
    ctx.to_world("building.schem", target, start=(0, -4, 0))

库会先创建私有临时世界目录并流式写入 LevelDB,成功关闭后再 deflate 打包为 .mcworld。目标已经是现有 .mcworld 时仍会安全解压、写回并重新打包;修改现有 世界前请保留备份。

7. 批量转换

下面示例复用 Context,逐个转换目录中的文件,并让单个失败不影响后续任务:

from pathlib import Path
from water_structure import Context, Error

source_dir = Path("inputs")
output_dir = Path("outputs")
output_dir.mkdir(parents=True, exist_ok=True)
sources = sorted(source_dir.glob("*.bdx"))

with Context() as ctx:
    for index, source in enumerate(sources, start=1):
        output = output_dir / f"{source.stem}.schem"
        print(f"[{index}/{len(sources)}] {source.name} -> {output.name}")
        if output.exists():
            print("  跳过:输出已存在")
            continue
        try:
            ctx.convert(source, "SchemV2", output, threads=0)
        except Error as exc:
            print(f"  失败:{exc}")
        else:
            print("  完成")

8. 进度显示

convert() 和 to_world() 都支持可选的 progress 回调。回调接收一个 Progress 命名元组:

from water_structure import Context, Progress

def show_progress(value: Progress) -> None:
    if value.percent is None:
        print(f"[{value.stage}] {value.elapsed:.1f}s", flush=True)
        return
    eta = "n/a" if value.eta is None else f"{value.eta:.1f}s"
    print(
        f"[{value.stage}] {value.percent:5.1f}% "
        f"{value.completed}/{value.total} ETA {eta}",
        flush=True,
    )

with Context() as ctx:
    ctx.convert(
        "building.mcworld",
        "SchemV2",
        "building.schem",
        progress=show_progress,
    )

Progress 字段:

字段 含义
stage open、read、encode、write 或 finalize
completed 当前阶段已完成的工作单位
total 当前阶段总工作单位;未知时为 None
percent 当前阶段百分比;未知时为 None
elapsed 当前阶段已用秒数
eta 当前阶段预计剩余秒数;无法计算时为 None
indeterminate 是否应该显示 spinner 而不是百分比

转换进度按 chunk/batch 节点报告,不按方块回调。原生层至少间隔约 100ms 才通知一次, 因此正常回调不会显著影响性能;回调中不要执行耗时工作,也不要重入同一个 Context。 压缩和最终封装可能没有可靠总量,会显示 percent=None,这不是转换卡住。

回调异常无法从 ctypes 原生线程直接抛回,因此绑定会先让转换结束,再重新抛出保存的 异常。异常发生后输出文件可能已经生成,程序应自行决定是否删除它。

如果要更新 GUI,请在后台线程调用 convert(),回调只向线程安全队列写入快照;不要在 回调中直接操作大多数 GUI toolkit 的控件。

9. 错误处理

原生转换错误统一抛出 water_structure.Error,它继承自 RuntimeError:

from water_structure import Context, Error

try:
    with Context() as ctx:
        ctx.convert("broken.bdx", "SchemV2", "output.schem")
except Error as exc:
    print("转换失败:", exc)

Python 参数错误仍使用标准异常。例如 threads=-1 会抛 ValueError;关闭 Context 后继续调用会抛 Error("WaterStructure context is closed")。

批处理程序应记录源路径、目标格式和完整消息。不要捕获所有异常后静默忽略,否则会 隐藏磁盘写满、格式截断或方块状态不兼容等问题。

10. 自定义资产与源码树调试

正常 wheel 已捆绑资产,不要传 assets_directory。只有开发或验证自定义 runtime 映射时才显式指定:

with Context(assets_directory="path/to/assets") as ctx:
    ...

源码树调试时,可以让 Python 加载本地构建的动态库:

# Windows
$env:WATER_STRUCTURE_LIBRARY = "D:\Projects\WaterStructureCpp\build\windows\x64\release\water_structure_shared.dll"
python your_script.py
# Linux / Termux;macOS 使用 .dylib
export WATER_STRUCTURE_LIBRARY=/absolute/path/to/libwater_structure_shared.so
python your_script.py

动态库架构、C ABI 和 Python 包内资产必须匹配。

11. 常见问题

VS Code 显示“无法解析导入 water_structure”

python -m pip show water-structure
python -c "import sys; print(sys.executable)"

然后在 VS Code 执行 Python: Select Interpreter,选择同一个解释器。优先使用 python -m pip,不要用裸 pip 猜测安装位置。

unable to load WaterStructure native library

检查 wheel 是否匹配操作系统和 CPU 架构、是否从正确的 Python 环境运行,以及 wheel 内 .dll/.so/.dylib 是否被安全软件删除。源码调试时还要检查 WATER_STRUCTURE_LIBRARY。

Windows 官方 wheel 使用 ctypes 加载稳定 C ABI 的 water_structure_shared.dll, 不需要 CPython 专用 .pyd。因此同一个 py3-none-win_amd64 wheel 可以用于所有满足 Requires-Python 的 CPython 版本;把普通 DLL 仅改扩展名为 .pyd 不会增加兼容性。

No matching distribution found

PyPI 没有与当前平台标签匹配的 wheel。更新 pip 后重试;仍失败则需要使用对应平台的 GitHub Actions artifact 或从源码构建。

为什么 .schem 不能只写 Schem

V1 和 V2 共用扩展名但协议不同。输出必须显式选择 SchemV1 或 SchemV2。

为什么提高线程数没有加速

threads 只影响支持并行的 writer 编码阶段。读取世界、Brotli、NBT、LevelDB 或 磁盘写入可能才是瓶颈;线程增加后也可能受内存带宽和调度开销影响。

12. API 速查

from water_structure import (
    Context, Error, FormatCapabilities, Progress, StructureInfo,
    abi_version, formats, version,
)

version() -> str
abi_version() -> int
formats() -> tuple[FormatCapabilities, ...]

Context(assets_directory=None)
Context.close() -> None
Context.format(path, *, streaming_world_import=False) -> str
Context.inspect(path, *, streaming_world_import=False) -> StructureInfo
Context.convert(input_path, target_format, output_path, *, threads=0,
                clear_air=True, chunk_partition=False, memory_budget_mib=450,
                max_in_flight_tasks=0, max_in_flight_chunks=0,
                allow_temporary_spool=True, progress=None) -> None
Context.to_world(input_path, world_path, *, start=(0, -4, 0), threads=0,
                 memory_budget_mib=450, max_in_flight_chunks=0,
                 allow_temporary_spool=True, progress=None) -> None

包内提供 py.typed 和 .pyi,类型检查器可以识别公开 API。

13. 从源码构建 wheel

先安装 xmake、C++ 工具链和 Python 构建工具,然后在仓库根目录执行:

python -m pip install build twine
python python/build_wheel.py
python -m twine check dist/python/*.whl

Windows 也可使用:

.\python\build_wheel.ps1

构建脚本不指定线程数,由 xmake 使用默认并行度。生成的 wheel 在 dist/python/; 原生构建输出隔离在 build/python-native/,不会误选 build/python-wheel/ 中的旧 DLL。 脚本会校验二进制类型、wheel 平台标签、类型文件、原生库和 assets 是否确实被打包。

交叉构建必须同时给出已经编译好的动态库和真实平台标签,例如 Android:

python python/build_wheel.py \
  --skip-native-build \
  --native-library build/android/arm64-v8a/release/libwater_structure_shared.so \
  --platform-tag android_24_arm64_v8a \
  --output dist/termux

--platform-tag 只改变标签,不会转换二进制或修复动态依赖。准备公开 Linux wheel 时应在 目标 manylinux 容器内构建并用 auditwheel 检查/修复;macOS 发布前相应检查 deployment target、架构和外部 dylib。不要把普通 Ubuntu 构建直接重命名为 manylinux。

先在干净虚拟环境中安装并运行 smoke test,再上传 PyPI。Windows 发布脚本使用独立的 dist/python-upload/,只上传本次构建的 wheel,不会把 dist/python/ 中所有历史版本 一起交给 twine:

.\python\publish.ps1 -TestPyPI  # 先验证 TestPyPI
.\python\publish.ps1           # 确认后发布官方 PyPI

Metadata

Release files for water-structure 0.1.8

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Built distribution (wheel)

Table of built distributions (wheels) for water-structure 0.1.8
File Interpreter ABI Platform Actions
water_structure-0.1.8-py3-none-win_amd64.whl Python 3 none Windows x86-64 Details for water_structure-0.1.8-py3-none-win_amd64.whl

Release files / water_structure-0.1.8-py3-none-win_amd64.whl

Download URL water_structure-0.1.8-py3-none-win_amd64.whl
Size 3.2 MB
Tags Python 3 Windows x86-64
SHA-256 checksum
How to use checksums
7fdea289b6fd1b7189e4e0d310929dc4ee483ca35ee19be891d3d03c0b4913f2
BLAKE2b-256 checksum
How to use checksums
2a711e29844ab187e39fb3aec5b77e62009737ff1e630fdfb69a764d9dbb03b8
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.13.13

Security for water-structure 0.1.8

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page