探索作品
展示實體家具匯出格式#
本文件是 building-dex「展示實體家具」目錄對外的資料合約。任何伺服器外掛、工具或網站都能讀這份匯出， 自行計算包圍盒、檢查區域、原子化放置並加上自己的實體標籤；本目錄不依賴任何特定消費端， 也不包含任何消費端專屬的編號、API 或假設。欄位名一律英文，說明用繁體中文。
- 合約版本：
schema_version= 1.0.0（路徑中的v1= major） - 目標遊戲：Minecraft Java 26.3，原版（無模組）
- 產生器：
src/display_entity_export.py（src/display_entity_pipeline.py自動呼叫） - JSON Schema（draft 2020-12）：
export/v1/schema/manifest.schema.json、export/v1/schema/piece.schema.json
1. 網址#
| 用途 | URL |
|---|---|
| 目錄索引 | https://mc-intel.dubi.app/dex/building-dex/display-entity-01/export/v1/manifest.json |
| 單件資料 | https://mc-intel.dubi.app/dex/building-dex/display-entity-01/export/v1/pieces/<id>.json |
| Schema | …/export/v1/schema/manifest.schema.json、…/export/v1/schema/piece.schema.json |
| 數學測試向量 | …/export/v1/test-vectors.json |
| 退役（墓碑）清單 | …/export/v1/retired.json |
| 快照索引 | https://mc-intel.dubi.app/dex/building-dex/display-entity-01/export/snapshots.json |
| 版本快照 zip | https://mc-intel.dubi.app/dex/building-dex/display-entity-01/export/display-assets-v1.<hash12>.zip |
| 本文件（網頁版） | https://mc-intel.dubi.app/dex/building-dex/display-export-spec.html |
manifest.json 內的 asset 路徑相對於 base_url（= …/export/v1/）；snapshot 相對於 manifest 本身。
2. 版本、快照與相容性#
schema_version（semver）描述格式，不描述內容。- PATCH：文件澄清、schema 修正但不影響合法資料。
- MINOR：只做加法——新增選填欄位、新增
scales鍵、新增category值。消費端必須忽略不認得的欄位與 scale 鍵。 - MAJOR：刪除/改名欄位、改變座標或旋轉慣例、新增消費端無法安全略過的值（新的
mount、新的實體type）。 MAJOR 會開新路徑/export/v2/；/export/v1/停在最後一版內容繼續提供，棄用會先寫在 CHANGELOG。 - 內容變動（新增家具、修幾何、驗收狀態變化）不改
schema_version，只改content_hash與generated_at。content_hash= 目錄內容＋schema＋本文件的 sha256；內容沒變就不會變，generated_at也維持不變。 - 每個
content_hash對應一個確定性快照display-assets-v1.<content_hash 前 12 碼>.zip（內含v1/全部檔案與本文件）。snapshots.json列出保留中的快照與其 sha256；站上只保留最近 5 份。 - 建議消費端釘版本：下載一份快照 zip、核對
snapshots.json的 sha256、把它 vendor 進自己的 repo／資源， 升級時再手動換新快照。不要在伺服器執行期直接讀線上manifest.json。
3. manifest.json#
| 欄位 | 型別 | 說明 |
|---|---|---|
schema_version |
string | 1.x.y |
generated_at |
string | UTC ISO-8601（2026-09-30T07:44:50Z），內容不變時不變 |
content_hash |
string | 64 位 hex sha256 |
snapshot |
string | ../display-assets-v1.<hash12>.zip |
catalogue |
string | building-dex/display-entity-01 |
minecraft |
object | {"edition": "java", "version": "26.3"} |
base_url / spec_url |
string | 見 §1 |
schemas |
object | {"manifest": …, "piece": …}（相對 base_url） |
license_note |
string | 授權現況說明（見 §11） |
scales |
string[] | ["1", "1.25", "1.5", "2"] |
facings |
string[] | ["south", "west", "north", "east"] |
pieces |
row[] | 依 id 排序，含退役墓碑 |
pieces[] 每列（status: "active"）：
| 欄位 | 說明 |
|---|---|
id |
穩定 slug，^[a-z0-9][a-z0-9-]*$（§12） |
status |
active / retired |
name_zh / name_en |
顯示名 |
category |
seat table bed storage counter kitchen tableware bathroom lamp electronics music outdoor decor …（開放集合） |
mount |
floor / wall / tabletop / ceiling（§8） |
sittable |
原尺寸（1×）是否可坐 |
large |
大型件（實體上限 150，否則 60） |
verification |
本站自動幾何驗收：PASS / FAIL / UNVERIFIED（不等於進遊戲實測） |
license |
SPDX 識別碼，目前一律 CC-BY-4.0（§11） |
entity_count |
{"1": 22, "1.25": 22, …}，含坐墊 |
bbox |
{scale: {facing: {min, max, size}}}，與單件檔相同（§10） |
asset / sha256 |
單件檔路徑與其位元組 sha256 |
退役列只保證 id、status: "retired"、name_zh、name_en、retired_at、asset、sha256（最後一版單件檔仍保留時非 null）。
4. pieces/<id>.json#
自足：不需要任何其他檔案就能放置。頂層：
{
"schema_version": "1.0.0", "id": "bar-stool", "status": "active",
"name_zh": "高腳凳（含坐墊）", "name_en": "Bar Stool (with cushion)",
"category": "seat", "mount": "floor", "sittable": true, "large": false, "entity_limit": 60,
"verification": "PASS", "minecraft": {"edition": "java", "version": "26.3"},
"source": {"kind": "reference-build", "credit": "ph1-road in-game build", "reference": "bar_stool.mcfunction"},
"license": "CC-BY-4.0",
"scales": ["1", "1.25", "1.5", "2"], "facings": ["south", "west", "north", "east"],
"placements": { "<scale>": { "<facing>": Placement } }
}
placements 一共 4 scale × 4 facing = 16 份，全部已預先算好（旋轉、縮放、方塊屬性旋轉都已套用），
消費端不需要自己實作旋轉或縮放數學。Placement：
| 欄位 | 說明 |
|---|---|
scale |
number：1 / 1.25 / 1.5 / 2 |
facing / yaw / quarter_turns |
見 §5 |
display_only |
scale ≠ 1 時為 true：沒有真方塊、沒有坐墊（§9） |
sittable |
此 placement 是否可坐（只有 1× 可能為真） |
entity_count |
entities + cushions 的數量 |
support |
{"kind": mount, "direction"?: 牆在哪一側, "ceiling_height"?: 天花板離錨點高度}（§8） |
entities[] |
展示實體（§5）。順序固定，第 0 個適合當「錨點實體」 |
cushions[] |
坐墊實體（§7） |
blocks[] |
真方塊（§6） |
dropped[] |
縮放時丟掉的東西（人類可讀，如 "part 5 cushion"、"block 0 minecraft:barrier"） |
bbox |
{min, max, size}，錨點相對、方塊單位（§10） |
cells |
{min, max, list}，佔用的整數方塊格（§10） |
entities[] 每筆：
{"type": "block_display", "pos": [-0.28, 0.45, -0.28],
"transformation": {"translation": [-0.035, -0.45, -0.035], "left_rotation": [0, 0, 0, 1],
"scale": [0.07, 0.9, 0.07], "right_rotation": [0, 0, 0, 1]},
"block_state": {"id": "minecraft:dark_oak_planks", "properties": {}}}
type：block_display/item_display/text_display。block_display：block_state = {id, properties}，properties只列作者明確設定的屬性（其餘用方塊預設值）。item_display：item = {id, count}、item_display（原版 display context：nonefixedgroundguihead…）。text_display：text_display = {text, background?, line_width?, alignment?, shadow?, see_through?, text_opacity?, default_background?}， 鍵名與原版 NBT 相同；text可能是字串或文字元件物件。- 選填
render：brightness {block, sky}、billboard、view_range、shadow_radius、shadow_strength、glow_color_override（原版 NBT 同名）。
5. 座標系與變換#
錨點（anchor）：家具的「底面中心」。對應遊戲中一格方塊 B 的底面中心：anchor = (Bx + 0.5, By, Bz + 0.5)。
地面家具的 B 就是玩家腳下那格空氣格；tabletop 的錨點 y 是桌面高度（可為小數，§8）。
軸：Minecraft 世界軸（+x 東、+y 上、+z 南），單位 = 方塊。所有 pos、translation、bbox 都是相對錨點的方塊單位。
朝向：作者一律朝 south（正面朝 +z）。其他朝向是繞錨點的 +Y 軸旋轉：
| facing | quarter_turns t |
yaw（正面的 MC yaw） |
旋轉矩陣 Rf（row-major） | qf [x, y, z, w] |
|---|---|---|---|---|
| south | 0 | 0 | [[1,0,0],[0,1,0],[0,0,1]] |
[0, 0, 0, 1] |
| west | 1 | 90 | [[0,0,-1],[0,1,0],[1,0,0]] |
[0, -0.707107, 0, 0.707107] |
| north | 2 | 180 | [[-1,0,0],[0,1,0],[0,0,-1]] |
[0, -1, 0, 0] |
| east | 3 | 270 | [[0,0,1],[0,1,0],[-1,0,0]] |
[0, -0.707107, 0, -0.707107] |
即 θ = −t·90°（west 把 +z 轉到 −x）。預算資料已套好：pos' = Rf·pos、translation' = Rf·translation、
left_rotation' = qf ⊗ left_rotation、scale、right_rotation 不變。旋轉只烘進 transformation，實體本身的 yaw/pitch 一律為 0，
沒有鏡像（det = +1）。四元數順序是 [x, y, z, w]，與原版 NBT transformation 相同（q 與 −q 等價）。
放置一個實體：在世界座標 anchor + pos 生成該實體，Rotation = [0, 0]，transformation 原樣寫入。
世界頂點（模型空間點 p → 世界）：
M = Translate(pos + translation) · L · S · R (L = quat(left_rotation), S = diag(scale), R = quat(right_rotation))
world(p) = anchor + M · p
模型空間：block_display 的方塊模型佔 [0,1]³（例如完整方塊的八個角是 0/1 組合）；
item_display 的物品模型以實體原點為中心（原版 ItemDisplay 會再做 rotY(π) 與 display context 變換）；
text_display 是朝 +z、底邊置中的平面。
測試向量（test-vectors.json 有更多筆）：wooden-chair、scale 1、facing east、entities[0]，
anchor_world = [100.5, 64, -20.5]，pos = [0,0,0]、translation = [-0.206, 0, 0.216]、left_rotation = [0, -0.707107, 0, -0.707107]、
scale = [0.052, 0.415, 0.052]、right_rotation = [0,0,0,1]。模型角 p = (0,0,0) → (100.294, 64, -20.284)；
p = (1,1,1) → (100.346, 64.415, -20.336)。容差 1e-4。
block_state 物件形式：26.3 的 block_display NBT 只接受純 id 字串 "minecraft:x" 或
{id:"minecraft:x", properties:{k:"v"}}；"minecraft:x[k=v]" 與 {Name:…, Properties:…} 會靜默變成空氣。
本匯出一律給 {id, properties}；若你的 API 要 id[k=v] 字串，自行組合即可（真方塊另附完整 state 字串）。
注意：block_display 的 properties 不隨朝向旋轉（整個實體已經轉了）；真方塊的 properties 已隨朝向旋轉（§6）。
6. 真方塊（blocks[]，只出現在 1×）#
有些家具需要真方塊：可坐的樓梯／半磚座面、barrier（隱形碰撞支撐坐墊）、light（光源）。每筆：
| 欄位 | 說明 |
|---|---|
pos |
整數格位移（相對錨點格 B），該方塊佔 [x−0.5, x+0.5] × [y, y+1] × [z−0.5, z+0.5]（錨點相對） |
block_state |
{id, properties}，properties 已依朝向旋轉（facing、axis、rotation、連接方向鍵、鐵軌 shape） |
state |
完整方塊狀態字串（含全部屬性，排序），可直接給 setblock／block data 解析 |
collision |
是否有碰撞（light 為 false） |
visible |
是否有可見模型（barrier、light、structure_void 為 false） |
as_display |
等價的 block_display（pos + transformation），給想把真方塊轉成展示實體的消費端 |
消費端可以自由把真方塊換成 as_display（例如區域內不允許改方塊時），代價是失去碰撞與坐（坐墊需要真碰撞支撐），
隱形方塊轉換後沒有意義，應直接略過。放真方塊前請自行確認目標格可替換並記錄原方塊以便還原。
7. 坐墊（cushions[]，只出現在 1×）#
minecraft:cushion 實體（26.3 原版，可坐）。pos 為錨點相對世界位置，yaw 已含朝向，color 為 16 色染料名，
invulnerable 為 NBT Invulnerable。坐墊有重力，必須由正下方的真碰撞方塊撐住（展示實體沒有碰撞）；
所以生成順序應為：先真方塊、再坐墊。坐墊計入 entity_count。
8. 掛載方式（mount / support）#
mount |
錨點放哪 | support |
|---|---|---|
floor |
地面：B 是地面上方那格，錨點 y = 地面頂面 | {"kind": "floor"} |
wall |
背面貼牆：南向時牆面在 z = −0.5（B 的北面）；高度已含在幾何裡（錨點仍在地面） | {"kind": "wall", "direction": "north"}，direction = 牆在 B 的哪一側（隨 facing 旋轉） |
tabletop |
桌面上：錨點 y = 桌面頂面高度（可為小數，例如 0.9） | {"kind": "tabletop"} |
ceiling |
錨點在地面，幾何向上延伸到天花板 | {"kind": "ceiling", "ceiling_height": 3}：天花板底面在 anchor.y + ceiling_height；要貼合 H 高的天花板就放在 anchor.y = H − ceiling_height |
9. 尺寸（scales）#
1、1.25、1.5、2。縮放是繞錨點的等比放大（pos、translation、scale × k，旋轉不變）；wall 家具改繞牆面
（南向 z = −0.5）放大，讓背面保持貼牆；ceiling_height 同乘 k。非 1× 都是純展示：真方塊改成等大的 block_display
（已放進 entities），隱形方塊（barrier、light、structure_void）與坐墊被丟掉並列在 dropped。所以放大版不可坐。
16 份 placement 都已預算，消費端不要自己縮放。
10. 包圍盒與佔用格#
bbox.min/bbox.max：錨點相對的軸對齊包圍盒（方塊單位），涵蓋全部展示實體（依原版方塊模型實際外形，例如樓梯、半磚）、 坐墊與真方塊（真方塊一律算整格）。text_display以字寬估算，屬近似值。世界包圍盒 =anchor + bbox。cells：與任何部件 AABB 相交的整數格（相對錨點格 B；邊界剛好貼齊不算佔用，ε = 1e-6），加上所有真方塊格。min/max是其外框，list是逐格清單（L 形櫃檯等不是實心長方體）。世界格 =B + cell。cells假設錨點 y 是整數；tabletop等錨點 y 為小數時，請用anchor + bbox重新換算：floor(anchor.y + bbox.min.y) … ceil(anchor.y + bbox.max.y) − 1。- 做區域檢查時：
cells.list的每一格都必須在允許區域內；需要保守時用anchor + bbox的外擴整格。
11. 來源與授權#
source.kind = "original"：本站原創，credit = "mc-intel building-dex (Codex gpt-6-astra, original work)"。source.kind = "reference-build"：依遊戲內既有作品轉錄，credit為來源作品，reference為轉錄參考檔名。license一律"CC-BY-4.0"（https://creativecommons.org/licenses/by/4.0/）。使用時請標示： 「mc-intel building-dex（https://mc-intel.dubi.app/dex/building-dex/display/）」。個別件若改授權會以 MINOR 更新並記在 CHANGELOG。
12. 穩定 id 與退役#
id（= slug）永不改名、永不重用。要改名就是新 id＋舊 id 退役。- 內容可以在同一 id 下修正（幾何、材質、驗收狀態）；需要固定外觀請釘快照（§2）。
- 下架的家具不會從 manifest 消失：保留為墓碑列（
status: "retired"、retired_at），並列在retired.json； 若最後一版單件檔還在，asset仍指向它（檔內status也改為retired），已放置的實例可以照舊移除或保存。 - 消費端可以維護自己的編號對照表（自家 code ↔
id），本匯出不提供也不需要知道那張表。
13. 給消費端的建議#
- 釘版本：vendor 一份快照 zip，核對 sha256；升級是一個刻意的動作。
- 不要執行本站的
place_*.mcfunction/kill.mcfunction：它們是給單人／示範用的——setblock不看區域保護、execute align xz會自動對齊、所有實例共用同一個標籤，kill會刪掉整個世界裡所有同款。請用本匯出自行放置。 - 原子化放置：先用
cells／bbox檢查整個佔用範圍與實體上限，全部通過再一次生成；中途失敗就把已生成的全刪。 - 每個實例自己的標籤：每個生成的實體都加上你自己的「實例標籤／id」，移除時只刪該實例，並還原真方塊的原狀態。
- 忽略不認得的欄位與 scale 鍵（§2）。
verification = "FAIL"的家具有已知幾何問題（懸空、z-fighting 等），是否使用由消費端決定。
14. CHANGELOG#
1.0.0 — 2026-09-30#
- 首版：manifest、單件資料（4 朝向 × 4 尺寸預算）、真方塊與
as_display、坐墊、support、bbox、cells、 source／license（CC-BY-4.0）、墓碑、確定性快照、JSON Schema（draft 2020-12）、數學測試向量。