Metadata-Version: 2.4
Name: mcblueprint
Version: 0.1.0
Summary: Unified library for operating Minecraft blueprints (vanilla .nbt, Litematica .litematic, WorldEdit .schem)
Author: ShimamuraNdAdachi
License-Expression: MIT
Project-URL: Homepage, https://github.com/ShimamuraNdAdachi/mcblueprint
Project-URL: Repository, https://github.com/ShimamuraNdAdachi/mcblueprint
Project-URL: Issues, https://github.com/ShimamuraNdAdachi/mcblueprint/issues
Project-URL: Changelog, https://github.com/ShimamuraNdAdachi/mcblueprint/blob/main/CHANGELOG.md
Keywords: minecraft,blueprint,schematic,structure,nbt,litematic,litematica,schem,worldedit,create-mod
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Games/Entertainment
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: nbtlib<3,>=2.0
Provides-Extra: export
Requires-Dist: Pillow>=10; extra == "export"
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == "dev"
Requires-Dist: mypy>=1.11; extra == "dev"
Requires-Dist: Pillow>=10; extra == "dev"
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: ruff>=0.6; extra == "dev"
Requires-Dist: twine>=5.0; extra == "dev"
Dynamic: license-file

# mcblueprint

[English](README.en.md) | 简体中文

[![CI](https://github.com/ShimamuraNdAdachi/mcblueprint/actions/workflows/ci.yml/badge.svg)](https://github.com/ShimamuraNdAdachi/mcblueprint/actions/workflows/ci.yml)
[![PyPI](https://img.shields.io/pypi/v/mcblueprint.svg)](https://pypi.org/project/mcblueprint/)
[![Python](https://img.shields.io/pypi/pyversions/mcblueprint.svg)](https://pypi.org/project/mcblueprint/)
[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
[![Typing](https://img.shields.io/badge/typing-py.typed-blue.svg)](https://peps.python.org/pep-0561/)

统一读写、编辑与转换 Minecraft 蓝图的 Python 库：一套核心模型同时支持
**原版结构 `.nbt`**（Create 机械动力蓝图亦为此格式）、**Litematica 投影 `.litematic`**
与 **WorldEdit Sponge v2 `.schem`**。

## 特性

- **三格式统一**：同一套 `Blueprint` 模型读写三种格式，互转只需 `load` → `save`。
- **编辑与变换**：按块替换、平移、90° 旋转、镜像，几何变换会同步重映射
  `facing` / `axis` / `rotation` / `half` / `hinge` 等朝向属性。
- **方块实体与实体**：箱子物品、告示牌文字等方块实体数据，以及蓝图级实体，两格式间无损互转。
- **链式形状生成器**：盒体、线、圆环、多边形、球/椭球/柱/锥/棱锥/穹顶、螺旋、楼梯、管道。
- **分析统计**：表面积（暴露面数）、连通分量、两蓝图差异对比。
- **导出**：JSON、OBJ、高度图（CSV/JSON/PNG）、PNG 分层切片。
- **纯内存模型**：不做惰性加载；除 `nbtlib` 外无硬依赖（PNG 导出才需要 Pillow）。
- **全量类型标注**：随包分发 `py.typed`，下游可直接享受类型提示。

## 安装

```bash
pip install mcblueprint

# 需要 PNG 导出（分层切片 / 高度图 PNG）时：
pip install "mcblueprint[export]"
```

要求 Python ≥ 3.10。

## 快速上手

### 生成 → 保存 → 读回 → 修改 → 转换

```python
import mcblueprint as mb
from mcblueprint import Builder

# 1) 链式构建一个形状
bp = (Builder()
      .box((0, 0, 0), (9, 3, 9), "minecraft:stone_bricks", hollow=True)
      .box((1, 1, 1), (8, 1, 8), "minecraft:oak_planks")
      .sphere((5, 7, 5), 4, "minecraft:glass", hollow=True)
      .build("tower"))

# 2) 写盘（按扩展名推断格式）
mb.save(bp, "tower.litematic")

# 3) 读回（按内容嗅探格式，不看扩展名）
bp2 = mb.load("tower.litematic")

# 4) 编辑与变换（原地修改）
bp2.replace("minecraft:oak_planks", "minecraft:spruce_planks")   # 返回替换的方块数
bp2.rotate("y", times=1)                                        # 绕 y 轴转 90°
bp2.translate(0, 10, 0)                                         # 整体抬高 10 格

# 5) 转成原版结构（机械动力蓝图台 / 结构方块可直接用）
mb.save(bp2, "tower.nbt")
```

### 纯字节接口与分析

```python
import mcblueprint as mb

# 承接上一段的 bp
data = mb.save_bytes(bp, "schem")        # 编码为 WorldEdit .schem 字节
print(mb.detect_format(data))            # 'schem'
bp3 = mb.load_bytes(data)                # 从字节解析

print(bp.block_count())                  # 非空气方块总数
print(bp.surface_area())                 # 暴露面数
print(len(mb.connected_components(bp)))  # 连通分量个数
print(bp.stats().most_common(3))         # 方块直方图 top 3
print(bp.bounds(), bp.is_empty())

delta = mb.diff(bp, bp3)                 # 两蓝图差异
print(delta.added_blocks, delta.removed_blocks, delta.unchanged_blocks)
```

### 方块状态与方块实体

```python
from mcblueprint import BlockState

state = BlockState.from_string("minecraft:oak_stairs[facing=east,half=bottom]")
print(state.name, state.properties)      # minecraft:oak_stairs {'facing': 'east', 'half': 'bottom'}

region = bp.region()                     # 不带参数取第一个区域
region.set(0, 4, 0, "minecraft:glowstone")
region.set_tile_entity(3, 1, 2, {"id": "minecraft:chest", "CustomName": '{"text":"Demo"}'})
print(region.get_tile_entity(3, 1, 2).nbt)
```

### 导出

```python
from mcblueprint.export import write_heightmap, write_json, write_obj

write_json(bp, "tower.json")             # 可视化 / 调试用 JSON
write_obj(bp, "tower.obj")               # 暴露面网格
write_heightmap(bp, "tower.csv")         # 高度图（csv / json / png）

bp.render_png("tower.png", axis="y")     # 单张 PNG（需 mcblueprint[export]）
bp.render_slices("slices/", axis="y")    # 每层一张 PNG
```

## 支持的格式

| 格式名 | 扩展名 | 说明 | 多区域 | 方块实体 | 实体 |
|---|---|---|---|---|---|
| `vanilla` | `.nbt` | 原版结构（`StructureTemplate`），gzip；Create 机械动力蓝图同此格式 | 单区域 | ✅ | ✅ |
| `litematic` | `.litematic` | Litematica 投影，gzip，`BlockStates` 位打包 | ✅ | ✅ | ✅ |
| `schem` | `.schem` | WorldEdit Sponge v2（varint `BlockData` + `Palette`） | 单区域 | ✅ | 部分 ¹ |

- 格式选择顺序：显式 `fmt` 参数 > 内容嗅探 > 扩展名推断。
- 单区域格式遇到多区域蓝图时自动合并；区域互相重叠时抛 `ConversionError`。
- 手动指定：`mb.load("data.bin", fmt="litematic")` / `mb.save(bp, "out.dat", fmt="vanilla")`。

> ¹ `.schem` 的实体存在非标准 `Entities` 字段中（Sponge v2 规范未定义），
> 与其他工具互换时不保证被保留。

## API 速查

| 入口 | 说明 |
|---|---|
| `mb.load(path, fmt=None)` | 读文件（`path` 可为 `str` / `Path` / 二进制文件对象） |
| `mb.save(bp, path, fmt=None)` | 写文件；写文件对象时必须显式给 `fmt` |
| `mb.load_bytes(data, fmt=None)` / `mb.save_bytes(bp, fmt)` | 字节接口 |
| `mb.detect_format(data)` | 返回 `"vanilla"` / `"litematic"` / `"schem"` / `None` |
| `Blueprint.region(name=None)` | 取区域（默认第一个） |
| `Blueprint.get_block/set_block/replace` | 全局坐标读写与按块替换 |
| `Blueprint.translate/rotate/mirror` | 原地变换（含朝向属性重映射） |
| `Blueprint.bounds/stats/block_count/is_empty` | 包围盒与统计 |
| `Blueprint.surface_area/connected_components/diff` | 分析与对比 |
| `Blueprint.clone()` | 深拷贝（含元数据） |
| `Region.get/set/fill/clone/stats` | 区域本地坐标读写与填充 |
| `Region.get_tile_entity/set_tile_entity/remove_tile_entity` | 方块实体 |
| `Builder.<shape>(...)` → `.build(name)` | 链式形状生成，产出单区域 `Blueprint` |
| `mcblueprint.export.*` | `write_json` / `write_obj` / `write_heightmap` / `render` / `render_slices` |
| `mcblueprint.errors.*` | `McBlueprintError` / `UnknownFormatError` / `ConversionError` / `OutOfBoundsError` |

> 坐标约定：`Blueprint` 层用全局坐标，`Region` 层用本地坐标 `0..size-1`；
> 未命中任何区域的全局坐标读作 `minecraft:air`。

## 开发

```bash
python -m venv .venv && . .venv/bin/activate    # Windows: .venv\Scripts\activate
pip install -e ".[dev]"

ruff check mcblueprint tests   # 静态检查
mypy                           # 类型检查
pytest -q                      # 单元测试
python -m build && twine check dist/*   # 打包校验
```

架构与接口设计见 [`DESIGN.md`](DESIGN.md)，功能取舍与路线图见 [`ROADMAP.md`](ROADMAP.md)，
参与方式见 [`CONTRIBUTING.md`](CONTRIBUTING.md)，变更记录见 [`CHANGELOG.md`](CHANGELOG.md)。
安全问题请按 [`SECURITY.md`](SECURITY.md) 私下报告。

## 许可证

[MIT](LICENSE)
