# 方屿 / ISOCRAFT 原创材质库

材质库面向 **Minecraft Java Edition 1.20.1 / WorldEdit `.schem`**，现有 **437 项**：328 种完整格材质、56 种台阶、53 种楼梯。完整格包含保留的源水格；它表示流体占位，不属于固体建筑方块。原有 24 项的 ID、基础色、顶面色、侧面色与排列顺序保持兼容。

本套素材通过程序原创绘制，没有读取、提取、描摹或复制 Minecraft、Mojang、Microsoft 的游戏纹理。材质名称及标识符表达兼容目标，概念预览用于识别材料；导入游戏后的外观由游戏版本、资源包和光照决定。本项目不是 Mojang / Microsoft 官方产品。原创素材可在本项目及后续产品中自由修改、替换与组合。

## 覆盖范围

| 筛选分类 | 数量（含造型） | 主要材料 |
| --- | ---: | --- |
| 木材 | 78 | 橡木、云杉、白桦、丛林、金合欢、深色橡木、红树、樱花、竹、绯红、诡异；原木/菌柄、六面树皮/菌核、去皮、木板、竹马赛克 |
| 石材 | 116 | 石、圆石、石砖、苔化与裂纹、花岗岩、闪长岩、安山岩、深板岩各变体、砂岩、红砂岩、石英、海晶石、泥砖、矿石 |
| 彩色 | 81 | 16 色混凝土、混凝土粉末、陶瓦、带釉陶瓦、羊毛，以及原色陶瓦 |
| 玻璃 | 18 | 普通玻璃、遮光玻璃、16 色染色玻璃 |
| 自然 | 42 | 泥土、砂土、缠根泥土、灰化土、菌丝体、泥巴、沙与砾、冰雪、树叶、苔藓、瓜果、菌菇、海绵、蜜脾等 |
| 装饰 | 56 | 铜的四个氧化阶段与涂蜡对应物、切制铜、金属与宝石储存块、粗矿块、紫水晶、蛙明灯、海晶灯、标靶、书架与工作台等 |
| 下界 | 36 | 下界岩、下界砖、红色下界砖、黑石系列、玄武岩、灵魂沙/土、菌岩、疣块、荧石、菌光体、岩浆块、远古残骸 |
| 末地 | 10 | 末地石、末地石砖、紫珀系列，以及黑曜石与哭泣的黑曜石 |

六个彩色材质族均覆盖全部 16 色。木材共 11 族，竹马赛克额外提供独立台阶与楼梯。库中包含 1.20.1 的全部 53 种楼梯和 56 种正常可用台阶；不加入无法正常获得的石化橡木台阶。

材质库以建筑为重点，并非游戏 1003 个方块条目的全量镜像。门、活板门、栅栏、墙、玻璃板、地毯、台面植物及带背包内容的方块需要专门几何或实体数据，当前没有以立方体冒充。也未混入 1.21 及以后新增的凝灰岩砖、铜灯、铜格栅、苍白橡木等材料。

## 文件结构

以下路径相对 `dist/`。

| 路径 | 数量 | 用途 |
| --- | ---: | --- |
| `assets/textures/{id}.svg` | 437 | 16 × 16 侧面纹理 |
| `assets/textures/{id}-top.svg` | 437 | 16 × 16 顶面纹理 |
| `assets/textures-png/{id}.png`、`{id}-top.png` | 874 | 对应 SVG 的原生 16 × 16 RGBA PNG |
| `assets/textures-png/atlas.png` | 1 | 512 × 512 RGBA 图集，32 列 × 32 行、每格 16 px |
| `assets/textures-png/atlas-preview@4x.png` | 1 | 2048 × 2048 最近邻预览 |
| `assets/textures-png/atlas.json` | 1 | 图集位置、归一化 UV、半像素内缩 UV 与来源映射 |
| `assets/blocks/{id}.svg` | 437 | 64 × 64 透明等轴缩略图；台阶半高、楼梯两级 |
| `assets/icons/{name}.svg` | 28 | 24 × 24、1.75 px 圆角描边工具图标，含快速建造、框选、复制、移动、镜像与盖章 |
| `assets/icons/sprite.svg` | 1 | 工具图标 symbol 集合 |
| `assets/brand/isocraft-mark.svg` | 1 | 64 × 64 品牌标志 |
| `assets/brand/isocraft-lockup.svg` | 1 | 252 × 64 标志与文字 |
| `assets/tokens.json` | 1 | UI 颜色、字体、间距、圆角与动效；437 项简化填色 |
| `assets/catalog.svg` | 1 | 1120 px 宽、按类别自适应高度的完整图鉴 |
| `assets/catalog-summary.svg` | 1 | 960 × 1021 紧凑概览，24 项精选、分类数量与 28 枚工具图标 |
| `assets/registry-1.20.1.json` | 1 | 固定版本的 Java 1.20.1 方块 ID / 属性值校验表 |
| `blocks.js` | 1 | 437 项材料数据，schema 3 |
| `build-tools.js` | 1 | 填充、画墙、笔刷、连通替换和批量编辑计划；只使用方块 ID 与属性，不绑定纹理格式 |
| `camera.js` | 1 | 正交相机投影、反投影与自由环绕数学，可独立接入渲染器 |
| `selection-tools.js` | 1 | 捕获选区、水平旋转、镜像、方向属性变换及移动／粘贴变化计划 |

每种台阶和楼梯仍有自身 ID 的顶面、侧面纹理文件，图案由基础材料复用。纹理全部由整数像素矩形组成，带 `shape-rendering="crispEdges"`。缩略图纹理全部内联，没有外部引用，复制后可独立打开。完整图鉴收录每项材料，紧凑概览只展示代表例。

## 示例与操作预览

随包提供五组可编辑项目及对应 Java / WorldEdit `.schem`：`examples/forest-workshop.*` 为林间工坊，`examples/material-shapes.*` 展示台阶、楼梯与轴向，`examples/quick-build.*` 是从实际工作台下载的快速建造结果。快速建造示例包含 104 个方块，归一化包围盒为 10 × 4 × 3，其中 16 格为空气；可下载 [蓝图](../examples/quick-build.schem) 与 [可编辑项目](../examples/quick-build.isocraft.json)。

新增 [窗组件蓝图](../examples/reusable-window.schem) 与 [窗组件项目](../examples/reusable-window.isocraft.json)：31 个方块，5 × 5 × 2 包围盒内含 19 个空气格，使用原木、楼梯、台阶与玻璃构成可复用窗口。[变换结果蓝图](../examples/selection-transforms.schem) 与 [变换结果项目](../examples/selection-transforms.isocraft.json) 为实际框选、复制、抬高、旋转和镜像后下载的文件，共 62 个方块，10 × 7 × 5 包围盒内含 288 个空气格。

`preview-tools.jpg` 为实际小屋、画墙参数与辅助格的工作台截图；`preview-selection.jpg` 展示窗组件连续盖章与选区参数，`preview-*.jpg` 还包含桌面、手机及导出窗口预览。工具生成的建筑使用同一份材质与方块属性数据，截图中的辅助线不会导出。五组示例包含在素材 ZIP 与完整设计包中。

## 方块数据与导出约定

```js
import { BLOCKS } from './blocks.js';
const stair = BLOCKS.find(block => block.id === 'cherry_stairs');
// {
//   id: 'cherry_stairs', name: '樱花木楼梯', category: '木材',
//   color: '#D5A6A0', top: '#e9bab4', side: '#D5A6A0',
//   family: 'cherry', shape: 'stairs', base: 'cherry_planks',
//   search: '樱花木楼梯 cherry stairs 樱花木板 楼梯 阶梯 stairs',
//   state: 'minecraft:cherry_stairs[facing=south,half=bottom,shape=straight,waterlogged=false]',
//   texture: 'assets/textures/cherry_stairs.svg',
//   icon: 'assets/blocks/cherry_stairs.svg'
// }
```

- `id`：稳定的游戏方块标识符；不要使用中文显示名称作保存键。
- `category`：8 个筛选分类之一；`全部` 仅是界面筛选入口。
- `family`：具体材料家族，例如 `oak`、`concrete`、`deepslate`；可用于扩充材质和检索。
- `shape`：`cube`、`slab`、`stairs`；前端几何必须使用该字段，不能把台阶或楼梯画成完整立方体。
- `base`：基础材质 ID；完整方块通常指自身，造型条目指其纹理来源。
- `search`：含中文名、英文 ID 拆词与常用别称的搜索字符串。
- `texture`：侧面 SVG；顶面固定为 `assets/textures/${id}-top.svg`。每个 ID 都有自己的两张文件。
- `color` / `top` / `side`：无贴图时的简化填色。缩略图已有三面明暗；绘制场景时再按光照计算。
- `state`：完整 `minecraft:` blockstate；有属性的材料给出所有属性的默认值，可直接写入 Sponge palette。

台阶默认 `type=bottom,waterlogged=false`。楼梯默认 `facing=south,half=bottom,shape=straight,waterlogged=false`，上一级位于世界坐标正 Z（南）方向。改变方向时，应同时改变实例的几何方向与导出 `facing`；材质默认值可作为新实例模板。

原木、去皮木、菌柄、菌核、竹块、石英柱、紫珀柱、骨块、玄武岩、蛙明灯等轴向材料默认 `axis=y`。树叶明确 `distance=7,persistent=true,waterlogged=false`，避免导入后自然消失。水明确 `level=0`；红石灯与红石矿石明确 `lit=false`。纹理只表达静态识别外观，不模拟流体、光照或自动连接行为。

## 纹理家族

方块并非统一噪点换色。木板有错缝与木纹；原木顶面有年轮，侧面有树皮，去皮表面更平滑；竹材有竹节及横向拼花。砖类有错位灰缝，瓦片更细密，磨制石有收边，錾制石有嵌套几何纹，苔石带苔斑、裂纹砖带开裂路径。

混凝土为低对比平面，粉末为颗粒，羊毛为交织纤维，陶瓦为细陶土颗粒，带釉陶瓦为旋转对称拼花。矿石在基岩上嵌有对应矿点，金属有压边，宝石有切面；荧石、菌光体为发亮团簇，灯体为亮芯与边框。玻璃、冰、蜂蜜、黏液保留不同程度透明度，树叶与樱花有叶簇或花瓣。

## PNG 与图集

PNG 按 SVG 中矩形的顺序做 source-over alpha 混合，超出 16 × 16 的区域裁切。玻璃等半透明材料保留 alpha，不添加背景底色。

`atlas.png` 动态选择能装下所有纹理的最小二次幂正方形：当前为 512 × 512 / 32 × 32 格。前 874 格按 `BLOCKS` 顺序放置，每种材料依次为侧面、顶面，剩余格透明。`atlas.json` 提供每个纹理的 `x` / `y` / `width` / `height`、边界 `uv` 与内缩半像素的 `uvTexelCenters`，坐标原点为左上。

无 padding 的图集使用 `NEAREST` min/mag filter、`CLAMP_TO_EDGE` 并关闭 mipmap；内部格子仍需用 `uvTexelCenters` 防止邻格渗色。需要线性过滤或 mipmap 时，应增加边缘复制 padding 再打包。WebGL 的 Y 翻转需与左上原点约定保持一致。单张纹理可按用途设置 repeat，整张图集不要 repeat。

## 前端接入

```html
<img src="assets/blocks/cherry_stairs.svg" width="48" height="48" alt="樱花木楼梯">
<button aria-label="导出蓝图">
  <svg width="24" height="24" aria-hidden="true">
    <use href="assets/icons/sprite.svg#export"></use>
  </svg>
</button>
```

工具图标使用 `currentColor`；需随主题变色时使用 sprite、内联 SVG 或 CSS mask。绘制场景应缓存纹理或上传图集，避免为每个方块建立 SVG DOM 节点。

UI 保持冷白、青绿、淡黄主题。`paper #f7faf8`、`surface #ffffff`、`mist #e8efec`、`canvas #e5eeeb`、`ink #283e43`、`muted #788a8b`、`line #dce5e1`、`teal #34776c`、`teal-light #e2efea`、`yellow #f1cb69`。正文字体为 Microsoft YaHei UI / PingFang SC / Noto Sans SC，辅助数字使用 Cascadia Code / Consolas。

工具图标共 28 枚：`build`、`erase`、`pick`、`fill`、`wall`、`brush`、`guides`、`selection`、`copy`、`move`、`mirror`、`stamp`、`undo`、`redo`、`rotate`、`layers`、`grid`、`export`、`zoom`、`zoom_out`、`home`、`save`、`help`、`pan`、`search`、`close`、`chevron_down`、`check`。新增图标与原有线宽、圆角和 24 px 视框一致；`selection` 标记框选复用，`copy`、`move`、`mirror`、`stamp` 分别用于模块复制、整体移动、镜像与连续盖章。

## 再生成与校验

```sh
node scripts/generate-assets.mjs
node scripts/export-textures-png.mjs
node scripts/test-materials.mjs
```

生成器只依赖 Node.js 内置模块；按 ID 与面固定随机种子，重复运行文件内容相同。`generate-assets.mjs` 生成数据、SVG、tokens 与两张图鉴；`export-textures-png.mjs` 编码 PNG 和动态 POT 图集。修改输出后需同步修改生成器，避免下次生成被覆盖。

材质测试检查唯一 ID、1.20.1 注册表兼容、全部 blockstate 属性和值、造型、木材和彩色族覆盖、纹理/图标路径、PNG / atlas 数量与尺寸。还可用 `--skip-png` 单独检查 SVG 与数据。全部 SVG 经过 XML 解析，生成器经过重复运行 SHA-256 一致性检查。

注册表来自 [PrismarineJS / minecraft-data 固定提交](https://github.com/PrismarineJS/minecraft-data/tree/201ca802a1b2c968b02e7fa5b31dd74e8bff3d8b)：Java `1.20.1` 映射至 `data/pc/1.20/blocks.json`，包含 1003 个方块 ID。校验记录版本兼容性；仍需在实际 Minecraft + WorldEdit 环境导入 `.schem` 做游戏内验收。