mcblueprint 0.1.0__tar.gz

mcblueprint-0.1.0/CHANGELOG.md

@@ -0,0 +1,33 @@
+# 变更日志
+
+本文件记录本库的显著变更，格式参考 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.1.0/)，
+版本号遵循 [语义化版本](https://semver.org/lang/zh-CN/)。
+
+## [Unreleased]
+
+## [0.1.0] — 未发布
+
+首个版本，尚未发布到 PyPI。
+
+### 新增
+
+- **核心模型**（`mcblueprint.core`）：`BlockState` / `Palette` / `Region` / `Blueprint` /
+  `Metadata` / `TileEntity`，与磁盘格式解耦。
+- **格式适配**（`mcblueprint.formats`）：原版结构 `.nbt`（含 Create 机械动力蓝图）、
+  Litematica `.litematic`（多 region、位打包 `BlockState`、负 `Size` 归一化）、
+  WorldEdit Sponge v2 `.schem`；统一 `detect`/`decode`/`encode` 接口。
+- **统一 API**（`mcblueprint.api`）：`load` / `save` / `load_bytes` / `save_bytes` /
+  `detect_format`，按「显式 fmt > 内容嗅探 > 扩展名」选择格式。
+- **变换**（`mcblueprint.transform`）：`translate` / `rotate` / `mirror`，几何变换同步
+  重映射 `facing` / `axis` / `rotation` / `half` / `hinge` 等朝向属性。
+- **形状生成**（`mcblueprint.generate`）：链式 `Builder`，覆盖盒体、线、圆/环/椭圆/多边形、
+  球/椭球/柱/锥/棱锥/穹顶、圆环/螺旋/斜坡/楼梯/管道。
+- **分析**（`mcblueprint.analysis`）：`surface_area` / `connected_components` / `diff`。
+- **导出**（`mcblueprint.export`）：JSON、OBJ、高度图（CSV/JSON/PNG）、PNG 分层切片
+  （PNG 相关需 `mcblueprint[export]`）。
+- **异常体系**（`mcblueprint.errors`）：`McBlueprintError` / `UnknownFormatError` /
+  `ConversionError` / `OutOfBoundsError`；畸形输入统一收敛为 `ConversionError`。
+- 全量类型标注并随包分发 `py.typed`。
+
+[Unreleased]: https://github.com/ShimamuraNdAdachi/mcblueprint/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/ShimamuraNdAdachi/mcblueprint/releases/tag/v0.1.0

mcblueprint-0.1.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,39 @@
+# 贡献者行为准则
+
+本项目采用 [Contributor Covenant v2.1](https://www.contributor-covenant.org/version/2/1/code_of_conduct/)
+作为行为准则（中文译本：<https://www.contributor-covenant.org/zh-cn/version/2/1/code_of_conduct/>）。
+完整条款以该链接为准，本页仅说明本项目的执行方式。
+
+## 我们的承诺
+
+为了营造开放、友好的环境，我们承诺：无论年龄、体型、可见或不可见的残障、族裔、
+性别特征、性别认同与表达、经验水平、教育程度、社会经济状况、国籍、外貌、种族、宗教，
+或性取向与性认同，参与本项目的每个人都免于骚扰。
+
+## 期望行为
+
+- 使用友好与包容的语言，尊重不同观点与经验；
+- 接受建设性批评，也以建设性方式提出批评；
+- 聚焦于对项目与社区最有利的事；
+- 对代码与设计就事论事，不针对个人。
+
+## 不可接受的行为
+
+- 性化的言语或图像、不受欢迎的性关注或挑逗；
+- 挑衅、侮辱/贬损性评论、人身攻击或政治攻击；
+- 公开或私下的骚扰、跟踪；
+- 未经许可公布他人的私人信息（如住址、邮箱）；
+- 在专业场合中其他可被合理认定为不当的行为。
+
+## 执行
+
+- **举报渠道**：请通过 GitHub 私信 [@ShimamuraNdAdachi](https://github.com/ShimamuraNdAdachi)
+  或使用仓库的私密举报功能联系维护者；涉及安全漏洞请改用 [SECURITY.md](SECURITY.md) 的渠道。
+- **处理方式**：维护者会审阅并调查所有投诉，必要时采取删除评论、关闭 issue/PR、
+  警告、临时或永久封禁等措施，并尽量对举报者身份保密。
+- **适用范围**：本准则适用于项目空间（issue、PR、讨论区）以及个人代表项目时的公开场合。
+
+## 归属
+
+本准则改编自 [Contributor Covenant](https://www.contributor-covenant.org) v2.1，
+以 [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/) 授权。

mcblueprint-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,87 @@
+# 贡献指南
+
+感谢愿意为本项目出力。提交前请花两分钟读完本页。
+
+## 环境准备
+
+```bash
+git clone https://github.com/ShimamuraNdAdachi/mcblueprint.git
+cd mcblueprint
+python -m venv .venv
+. .venv/bin/activate            # Windows: .venv\Scripts\activate
+pip install -e ".[dev]"
+```
+
+## 提交前必须通过的三项检查
+
+```bash
+ruff check mcblueprint tests tools   # 静态检查
+mypy                                 # 类型检查（files = mcblueprint）
+pytest -q                            # 单元测试
+```
+
+CI 会以 Python 3.10 / 3.11 / 3.12 / 3.13 重复执行上述检查，并额外做一次
+`python -m build` + 发行包内容校验。
+
+## 代码与文档规范
+
+1. **注释与文档使用中文**，代码中的展示文本（异常消息、日志等）统一英文（DESIGN §12）。
+2. 行宽上限 **120 列**（由 ruff 的 `line-length` 约束）。
+3. **不强制 `ruff format`**：现有代码的手工折行与格式化器输出不同；若要统一格式请单独提交，
+   不要混在功能改动里。
+4. 中文注释/文档中的全角标点属既定风格，故 `RUF001`/`RUF002`/`RUF003` 已在配置中关闭。
+5. 公开 API 的变更必须同步 `DESIGN.md`（接口契约）、`ROADMAP.md`（取舍）与
+   `CHANGELOG.md`（面向使用者）；`README.md` 与 `README.en.md` 是同一份内容的双语版本，
+   改动其一必须同时改另一份。
+6. 遇到不确定的设计选择，先开 issue 讨论，不要直接往主分支堆实现。
+
+## 提交信息
+
+沿用现有风格：`范围: 说明`，范围用英文小写模块名，例如：
+
+```
+formats: 结构不完整的文件改抛 ConversionError
+core/blueprint: 统一区域重叠时的语义为「先出现者胜」
+工程化：引入 ruff + mypy + CI，并修掉检查暴露出的问题
+```
+
+一次提交只做一件事；纯格式化/重命名请与行为改动分开。
+
+## 测试约定
+
+- 测试必须**可重复、可离线**运行，且不得写脏仓库：需要落盘时用
+  `tempfile.TemporaryDirectory()`（或在 pytest 中用 `tmp_path`）。
+- 样本分两类，二者不可互相替代：
+  - `tests/fixtures/sample.litematic` 由本库自身生成，只能验证**自洽**（自指盲区）；
+  - `tests/fixtures/external.litematic` 字段布局与位打包由独立实现手写，
+    用于验证**与真实格式兼容**（见 `tests/fixtures/make_external_litematic.py`）。
+- 新增格式/边界行为时，请同时补一个「畸形输入应抛 `ConversionError`」的负例。
+- 需要人工在 Minecraft 里目视校验时，用 `python -m tests.test_generate_demo`（或设置环境变量
+  `MCBLUEPRINT_DEMO_DIR=generated`）把演示蓝图写到 `generated/`，不要把生成物提交进仓库。
+
+## 发布流程（维护者）
+
+发布使用 PyPI **Trusted Publishing**（OIDC），仓库里不存在也不应存在任何 PyPI token。
+
+1. 在 PyPI / TestPyPI 的项目设置里配置 trusted publisher：
+   - Owner: `ShimamuraNdAdachi`，Repository: `mcblueprint`；
+   - Workflow: `release.yml`，Environment: `pypi` / `testpypi`（需与工作流里的
+     `environment:` 完全一致）。
+2. 更新 `mcblueprint/__init__.py` 的 `__version__` 与 `CHANGELOG.md`，合并到 `main`。
+3. 手动触发 `.github/workflows/release.yml`（`target = testpypi`）做一次预演，
+   在 TestPyPI 上用干净环境 `pip install --index-url https://test.pypi.org/simple/ mcblueprint` 验证。
+4. 打 tag 并推送：`git tag v0.1.0 && git push origin v0.1.0`。
+   工作流会校验 tag 与 `__version__` 一致（不一致直接失败），构建、`twine check`、
+   发布到 PyPI，并创建对应的 GitHub Release。
+
+> 本仓库（`mcblueprint`）是**唯一的工作仓库**：开发、CI 与发布都在这里进行；
+> 早期的 `mcblueprint-dev` 仅作历史存档（已在 GitHub 上归档）。
+> 仓库的公开历史从 `v0.1.0` 的初始提交开始，开发期的提交记录不在本仓库中。
+>
+> 若将来仓库再次改名，需要同步四处：`pyproject.toml` 的 `[project.urls]`、
+> `README.md` / `README.en.md` 的徽章与链接、`CHANGELOG.md` 的版本对比链接、
+> 以及 PyPI 上的 trusted publisher 配置。
+
+## 许可证
+
+本项目以 [MIT](../LICENSE) 发布。提交贡献即表示你同意以同一许可证分发你的贡献。

mcblueprint-0.1.0/DESIGN.md

@@ -0,0 +1,357 @@
+# MC 蓝图操作库 — 架构与接口设计
+
+> 状态：已实现（架构与接口已落地，功能取舍见 ROADMAP.md）
+> 库名（暂定）：`mcblueprint`，可随时改名
+
+## 1. 目标
+
+一个 Python 库，统一操作两种 Minecraft 蓝图：
+
+| 简称 | 格式 | 扩展名 | 压缩 |
+|---|---|---|---|
+| `vanilla` | 原版结构（vanilla ``StructureTemplate``，机械动力蓝图亦为此格式） | `.nbt` | gzip |
+| `litematic` | 投影模组（Litematica）蓝图 | `.litematic` | gzip |
+
+支持四类操作：**编辑修改、变换操作、格式转换、分析统计**。
+
+## 2. 格式背景（来自真实样本）
+
+### 2.1 原版结构 `.nbt`（样本 `l1.nbt`、`testnbt.nbt`、`vanilla-test.nbt`）
+
+机械动力（Create）的蓝图本质即原版 ``StructureTemplate`` 格式，故统一以 ``vanilla`` 命名。
+样本实际为 gzip 压缩（与初稿「裸 NBT」不符），加载端同时兼容裸 NBT。
+
+```
+根 Compound
+├─ size:    List[Int] x3           # 蓝图尺寸 (sx, sy, sz)
+├─ entities: List[Compound]        # 实体（样本为空）
+├─ blocks:  List[Compound]         # 每条 { pos: List[Int]x3, state: Int, nbt?: Compound }
+├─ palette: List[Compound]         # 每条 { Name: String, Properties?: Compound }
+└─ (mod 私有字段) DataVersion, Railways_DataVersion, brewinandchewin:data_version
+```
+
+- **方块存储**：稀疏列表，`pos` 为相对坐标，`state` 指向 `palette` 下标。
+- **无绝对位置**：蓝图坐标相对于锚点（原点 `(0,0,0)`）。
+- **调色板条目**：`Name`（如 `minecraft:quartz_block`）+ 可选 `Properties`（如 `{facing: west}`）。
+- **方块实体数据**：可选字段 `nbt`，内联在 `blocks` 条目中，仅当方块带方块实体时出现（如 `create:motor`、`minecraft:chest` 的 `Items`）。
+
+### 2.2 投影 `.litematic`（样本 `双维度猪灵交易480猪（主世界端）.litematic`）
+
+```
+根 Compound（gzip 压缩）
+├─ Regions: Compound           # key = region 名
+│   └─ <region>: Compound
+│       ├─ Size: Compound {x,y,z}              # region 尺寸
+│       ├─ Position: Compound {x,y,z}          # region 世界坐标偏移
+│       ├─ BlockStatePalette: List[Compound]   # { Name, Properties? }
+│       ├─ BlockStates: LongArray              # 位打包的体素下标
+│       ├─ TileEntities: List[Compound]        # { id, x, y, z, ... }
+│       ├─ Entities: List[Compound]
+│       ├─ PendingBlockTicks / PendingFluidTicks: List
+├─ Metadata: Compound { Name, Author, Description, TimeCreated, ... }
+├─ Version, SubVersion, MinecraftDataVersion
+```
+
+- **方块存储**：密集位打包。`BlockStates` 为 `long[]`，每条 `bits = max(2, ceil(log2(palette_size)))` 位；`palette_size == 1` 时仍写 `bits = 2` 的全零数组（不省略）。体素下标 `index = x + sx * (z + sz * y)`（x 最快，y 最慢）。
+- **坐标**：region 有 `Position`（世界绝对坐标偏移），体素内部为本地坐标。`Size` 可为负——负号表示区域沿负方向延伸，`Position` 为最大角点；容器体素始终按最小角点顺序存储。
+- **方块实体**：独立 `TileEntities` 列表，`x/y/z` 为体素本地坐标 `0..size-1`（与 `BlockStates` 同套坐标），而非世界坐标。
+- **多 region**：一个文件可含多个 region。
+
+### 2.3 关键差异 → 决定了适配层必须做的事
+
+| 维度 | vanilla | litematic |
+|---|---|---|
+| 压缩 | gzip | gzip |
+| 体素存储 | 稀疏列表 `{pos,state}` | 密集位打包 `long[]` |
+| 绝对坐标 | 无（锚点=原点） | region `Position` |
+| region 数 | 单 | 多 |
+| 方块实体数据 | 有，内联在 `blocks[i].nbt`（可选） | 有，独立 `TileEntities` 列表 |
+| 实体 | `entities` | `Entities` + Ticks |
+
+---
+
+## 3. 总体架构（分层）
+
+```
+mcblueprint/
+├── core/            # 格式无关的核心模型（唯一真值）
+├── formats/         # 格式适配层：磁盘格式 <-> core 模型
+├── transform/       # 变换与方块朝向属性重映射
+├── api.py           # 统一对外入口
+└── errors.py        # 异常体系
+```
+
+- **core**：所有编辑/变换/统计操作只针对核心模型，与格式解耦。
+- **formats**：每个格式实现同一个接口，只负责编解码（差异封装于此）。
+- **api**：用户唯一接触点，自动嗅探格式。
+
+---
+
+## 4. 核心数据模型（`core/`）
+
+### 4.1 `BlockState`
+
+不可变值对象，表示一个方块状态。
+
+```python
+class BlockState:
+    name: str                      # "minecraft:hopper"
+    properties: dict[str, str]     # {"facing": "west", "enabled": "true"}
+
+    @classmethod
+    def from_string(cls, s: str) -> "BlockState"   # "minecraft:hopper[facing=west,enabled=true]"
+    def __str__(self) -> str                        # 标准字符串形式
+    # 实现 __eq__ / __hash__（基于 name + properties）
+```
+
+约定：字符串采用 Minecraft 标准语法 `namespace:id[prop=val,...]`，作为调色板 key 与用户交互的规范表示。
+
+### 4.2 `Palette`
+
+有序调色板，下标 <-> 状态互转。
+
+```python
+class Palette:
+    def index_of(self, state: BlockState) -> int        # 不存在抛 KeyError
+    def state_of(self, index: int) -> BlockState        # 越界抛 IndexError
+    def add(self, state: BlockState) -> int             # 去重，返回下标
+    def __len__(self) -> int
+    def __iter__(self) -> Iterator[BlockState]
+```
+
+### 4.3 `Region`
+
+单个体素区域（本地坐标 `0..size-1`）。
+
+```python
+class Region:
+    name: str
+    position: tuple[int, int, int]    # 本 region 在蓝图/世界空间的原点偏移
+    size: tuple[int, int, int]        # (sx, sy, sz)，恒为正
+
+    def get(self, x, y, z) -> BlockState
+    def set(self, x, y, z, state: BlockState)
+    def fill(self, box, state: BlockState) -> int       # 返回写入方块数
+    def clone(self) -> "Region"
+    def stats(self) -> Counter[BlockState]
+
+    # ---- 方块实体 ----
+    def get_tile_entity(self, x, y, z) -> "TileEntity | None"
+    def set_tile_entity(self, x, y, z, nbt: dict)
+    def remove_tile_entity(self, x, y, z)
+```
+
+- 内部体素存储封装为私有实现（稀疏 dict 或密集数组），对外只暴露 `get/set`。
+- 坐标越界抛 `IndexError`。
+- **坐标约定**：`get/set` 用**本地坐标**。
+
+### 4.4 `Blueprint`
+
+顶层对象，一个或多个 region + 元数据。
+
+```python
+class Blueprint:
+    metadata: Metadata
+    regions: list[Region]
+
+    def region(self, name: str | None = None) -> Region
+    # ---- 编辑 ----
+    def get_block(self, x, y, z) -> BlockState        # 全局坐标
+    def set_block(self, x, y, z, state: BlockState)
+    def replace(self, old, new) -> int                # old/new 可为 BlockState 或字符串
+    # ---- 变换 ----
+    def translate(self, dx, dy, dz)
+    def rotate(self, axis: str, times: int = 1)       # axis ∈ {x,y,z}
+    def mirror(self, axis: str)                       # axis 为镜像平面法线
+    # ---- 分析 ----
+    def bounds(self) -> tuple[tuple[int,int,int], tuple[int,int,int]]  # (min, max) 全局
+    def stats(self) -> Counter[BlockState]
+    def block_count(self) -> int
+    # ---- 其他 ----
+    def clone(self) -> "Blueprint"
+```
+
+### 4.5 `Metadata`
+
+```python
+@dataclass
+class Metadata:
+    name: str = ""
+    author: str = ""
+    description: str = ""
+    time_created: int | None = None
+    time_modified: int | None = None
+    # 预留：其他格式特有字段放入 extras: dict
+    extras: dict = field(default_factory=dict)
+```
+
+### 4.6 坐标统一抽象规则
+
+- 核心模型内所有体素用**本地坐标** `0..size-1`。
+- `Region.position` 保存该 region 的原点偏移；`Blueprint.get_block` 用**全局坐标** = `position + 本地坐标`。
+- **vanilla → core**：单 region，`position = (0,0,0)`（锚点即原点）。
+- **litematic → core**：region 的 `position` 取自 NBT `Position` 字段；`size` 取 `Size` 的绝对值。`Size` 为负时，`Position` 是最大角点，加载器归一化为最小角点并取正尺寸（体素按最小角点顺序存储，无需按符号翻转）。
+- 未命中任何 region 的全局坐标：`get_block` 返回 `air`（`minecraft:air`）。
+
+### 4.7 方块实体（`TileEntity`）
+
+承载方块实体 NBT（箱子的 `Items`、告示牌文字、漏斗内容物等），与方块状态属性分离。
+
+```python
+class TileEntity:
+    position: tuple[int, int, int]
+    nbt: dict                       # 原样保留的复合标签，如 {"id": "minecraft:chest", "Items": [...]}
+```
+
+- 存储方式：`Region` 内部用 `{位置: TileEntity}` 稀疏映射；`Region.clone` 连同方块实体一起深拷贝。
+- 归属校验（某坐标是否有对应方块）由上层操作负责，核心模型不强制。
+- 仅通过 `Region.get_tile_entity / set_tile_entity / remove_tile_entity` 访问，不在 `Blueprint` 层做全局坐标封装。
+- **两格式统一映射**：
+  - vanilla：从 `blocks[i].nbt` 提取（`pos` 即位置）；保存时写回 `nbt` 字段。
+  - litematic：从 `TileEntities` 列表提取（`x/y/z` 为本地坐标）；保存时写回该列表。
+- `nbt` 内的 `id` 是**方块实体类型 id**，可能与方块状态 `Name` 不同（如 `create:shaft` 方块对应 `create:simple_kinetic` 方块实体），原样保留，不做归一化。
+
+---
+
+## 5. 格式适配层（`formats/`）
+
+### 5.1 抽象接口
+
+```python
+class BlueprintFormat(ABC):
+    name: str                # "vanilla" / "litematic" / "schem"
+    extensions: list[str]    # [".nbt"] / [".litematic"] / [".schem"]
+
+    @classmethod
+    def detect(cls, data: bytes) -> bool          # 按魔数/结构判断，不依赖扩展名
+    @classmethod
+    def decode(cls, data: bytes) -> Blueprint     # 字节 -> 核心模型
+    @classmethod
+    def encode(cls, bp: Blueprint) -> bytes       # 核心模型 -> 字节
+```
+
+- 适配器**只在字节层面**工作；文件读写、格式推断与选择由 `api.py` 统一负责，避免
+  「基类走文件流、api 走字节」两条并行路径。
+- `detect` 是**便宜的结构探测**，对任意输入都只返回 `True`/`False`（不抛异常）。
+  「探测为真」不保证可解码：字段缺失或取值畸形时 `decode` 必须抛
+  `McBlueprintError` 子类（实测约定为 `ConversionError`），不得泄漏 `KeyError`/
+  `IndexError` 等原始异常。
+- `detect`：vanilla 判断根含 `size`+`blocks`+`palette`；litematic 判断解压后根含
+  `Regions`；schem 判断根含 `Version==2` 且含 `Palette`+`BlockData`+`Width`+`Height`+`Length`。
+
+### 5.2 实现
+
+```python
+class VanillaNbtFormat(BlueprintFormat):  # formats/vanilla_nbt.py
+class LitematicFormat(BlueprintFormat):   # formats/litematic.py
+class SchemFormat(BlueprintFormat):       # formats/schem.py
+```
+
+- `VanillaNbtFormat`：读 `blocks` 稀疏列表重建体素；写时从体素生成列表。
+- `LitematicFormat`：读位打包 `long[]`（`bits = max(2, ceil(log2(palette_size)))`）；写时按同规则重打包。负责 gzip 解压/压缩。
+- `SchemFormat`：WorldEdit Sponge v2 `.schem`，`BlockData` 为 varint 数组，`Palette` 为状态字符串到下标。
+- 单 region 格式（vanilla/schem）遇到多 region 时由 `_common.merge_regions` 合并；区域互相重叠时抛 `ConversionError`。
+- 共享工具（gzip、`require_keys`、`palette_state`、`merge_regions`）集中在 `formats/_common.py`，适配器之间不互相引用私有实现。
+
+---
+
+## 6. 统一对外 API（`api.py`）
+
+```python
+def load(path: str | Path | BinaryIO) -> Blueprint
+def save(bp: Blueprint, path: str | Path | BinaryIO, fmt: str | None = None)
+
+def load_bytes(data: bytes, fmt: str | None = None) -> Blueprint
+def save_bytes(bp: Blueprint, fmt: str) -> bytes
+
+def detect_format(data: bytes) -> str | None      # "vanilla" | "litematic" | None
+```
+
+- `load`：读字节 → `detect_format` 自动探测（`fmt` 未给定时）→ 调用对应 `load`。
+- `save`：`fmt` 缺省时按扩展名推断（`.nbt`→vanilla，`.litematic`→litematic），也可显式指定。
+- `detect_format` 内部按 `extensions` + 结构判断。
+
+---
+
+## 7. 变换操作（`transform/`）
+
+变换分两层：
+
+1. **几何变换**：坐标重排（旋转/镜像/平移），纯数组操作。
+2. **朝向属性重映射**：对带方向的方块状态，同步变换 `facing / axis / rotation / half` 等属性。
+
+```python
+# transform/orientation.py
+def rotate_state(state: BlockState, axis: str, times: int) -> BlockState
+def mirror_state(state: BlockState, axis: str) -> BlockState
+```
+
+- 采用**数据驱动规则表**，覆盖常见带朝向方块（`facing`/`axis`/`rotation`/`half`/`hinge` 等）。
+- 规则表外未识别的方块：几何变换照做，属性原样保留（保守策略）。
+- ⚠️ 这是全库**工作量最大**的模块，建议作为独立里程碑。
+
+---
+
+## 8. 格式转换策略
+
+`load(A) → Blueprint → save(B)` 天然支持互转，但需明确差异处理：
+
+| 方向 | 策略 |
+|---|---|
+| vanilla → litematic | 单 region；`Position=(0,0,0)`；生成 `Metadata`（Name 取文件名） |
+| litematic → vanilla | 单 region 直接转；**多 region**：若各 region 不重叠则合并为一个 region，重叠则抛 `ConversionError` |
+| 方块实体数据 | 两格式都支持，仅存储位置不同（vanilla `blocks[i].nbt` / litematic `TileEntities`）→ **可无损互转** |
+| 实体 `Entities` | vanilla `entities` / litematic `Entities` 原样保留；vanilla→litematic 归入 `Entities` |
+
+- 调色板在两格式间**结构一致**（均为 `{Name, Properties}`），可直接映射。
+
+---
+
+## 9. 错误体系（`errors.py`）
+
+```python
+class McBlueprintError(Exception): ...
+class UnknownFormatError(McBlueprintError): ...     # 无法识别格式
+class ConversionError(McBlueprintError): ...        # 格式间无法无损转换
+class OutOfBoundsError(IndexError, McBlueprintError): ...  # 坐标越界
+```
+
+---
+
+## 10. 依赖与兼容
+
+- 依赖：`nbtlib`（读写 NBT，含 gzip、`LongArray`、`List`、`Compound`）。
+- Python ≥ 3.10（dataclass、`match`、`X | None` 语法）。
+- 纯内存模型，不引入惰性加载。
+
+---
+
+## 11. 实现里程碑
+
+1. **core**：`BlockState` / `Palette` / `Region` / `Blueprint` + 单测。
+2. **formats**：`VanillaNbtFormat`、`LitematicFormat` 读写（含位打包、gzip）。
+3. **api**：`load/save/detect_format`，用两份样本做往返（round-trip）验证。
+4. **transform**：几何变换 + 朝向属性规则表（分阶段补全规则）。
+5. **分析统计 + 格式转换**：`stats/bounds/replace` 与互转的差异策略。
+6. 打包为可安装库（`pyproject.toml`）。
+
+---
+
+## 12. 开发规范
+
+1. 注释使用中文，代码使用的展示文本统一英文（如异常展示等）
+2. 遇到不确定选择停下确认
+3. 提交前本地跑齐三项检查（CI 会重复执行，配置见 `pyproject.toml`）：
+
+   ```bash
+   ruff check mcblueprint tests   # 静态检查
+   mypy                           # 类型检查（files = mcblueprint）
+   pytest -q                      # 单元测试
+   ```
+
+4. 行宽上限 120 列（由 ruff 的 `line-length` 约束）；**不强制 `ruff format`**——现有代码
+   的手工折行与格式化器输出不同，若要统一格式请作为独立提交，不要混在功能改动里
+5. 中文注释/文档中的全角标点属既定风格，故 ruff 的 `RUF001`/`RUF002`/`RUF003` 已关闭
+6. 测试样本分两类：`tests/fixtures/sample.litematic` 由本库自身生成，只能验证自洽；
+   需要验证与真实格式兼容时使用 `tests/fixtures/external.litematic`（字段布局手写 +
+   独立位打包实现，见 `tests/fixtures/make_external_litematic.py`）

mcblueprint-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ShimamuraNdAdachi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

mcblueprint-0.1.0/MANIFEST.in

@@ -0,0 +1,32 @@
+# sdist 内容清单。
+#
+# 目的有二：
+# 1. 让源码包自带许可证、README、变更日志与完整测试样本，可离线复现
+#    `pytest`（setuptools 默认只自动收录 `tests/test*.py`，会漏掉
+#    `tests/__init__.py` 与 `tests/fixtures/`）。
+# 2. 收紧自动发现范围：否则仓库根目录下任何多余的 `.py` 都会被塞进 sdist。
+#
+# wheel 不受本文件影响：`[tool.setuptools.packages.find]` 只收录
+# `mcblueprint*`，故 tests 不会进入 wheel。
+
+include LICENSE
+include README.md
+include README.en.md
+include CHANGELOG.md
+include DESIGN.md
+include ROADMAP.md
+include CONTRIBUTING.md
+include SECURITY.md
+include CODE_OF_CONDUCT.md
+
+recursive-include mcblueprint py.typed
+
+recursive-include tests *.py *.nbt *.litematic
+
+# 参考模组源码与本地运行产物永不入库、也不进发行包。
+prune example-code
+prune generated
+prune .github
+prune .claude
+
+global-exclude *.py[cod] *.so __pycache__ .DS_Store Thumbs.db desktop.ini