跳轉至
資源版本修訂中優先平台26.3 優先
探索作品

展示實體家具匯出格式#

本文件是 building-dex「展示實體家具」目錄對外的資料合約。任何伺服器外掛、工具或網站都能讀這份匯出, 自行計算包圍盒、檢查區域、原子化放置並加上自己的實體標籤;本目錄不依賴任何特定消費端, 也不包含任何消費端專屬的編號、API 或假設。欄位名一律英文,說明用繁體中文。

  • 合約版本:schema_version = 1.8.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:none fixed ground gui head …)。
  • 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×)#

1.8.0 的坐用樓梯/半磚已轉為展示實體,座位由插件掛載;light(光源)仍可放置。碰撞只使用 behavior.collision。以下真方塊欄位保留相容舊快照及非坐用方塊:

欄位 說明
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(例如區域內不允許改方塊時),代價是失去該方塊本身的碰撞。1.8.0 插件座位不依賴真方塊,因此不失去坐的能力;舊快照的坐墊仍需要真碰撞支撐。 隱形方塊轉換後沒有意義,應直接略過。放真方塊前請自行確認目標格可替換並記錄原方塊以便還原。

自 stargate ≥2.20.0,消費端只有在錨點位於整數方塊座標時才放置真方塊、坐墊、barrier 與 bed。碰撞資料定義於整數錨點;小數錨點只能呈現展示模型,不應四捨五入後放置這些實體/方塊。

7. 座位與舊坐墊(只出現在 1×)#

1.8.0 消費端優先使用 behavior.seats(§24)。新輸出不放坐墊實體、不使用 sit-only 真方塊;以下 cushions[] 說明僅適用舊快照。

minecraft:cushion 實體(26.3 原版,可坐)。pos 為錨點相對世界位置,yaw 已含朝向,color 為 16 色染料名, invulnerable 為 NBT Invulnerable。26.3 坐墊是 BlockAttachedEntity,沒有重力、不會下落;每 100 ticks 檢查支撐,失去支撐時消失並掉落物品。必須由正下方的真碰撞方塊撐住(展示實體沒有碰撞)。 pos.y 對齊支撐表面;現有「下沉 0.1」資料慣例已經遊戲內驗證可坐,這是 1.7.x 及以前的資料慣例,不能當作 1.8.0 的座面頂部座標。 生成順序應為:先真方塊、再坐墊。坐墊計入 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. 給消費端的建議#

  1. 釘版本:vendor 一份快照 zip,核對 sha256;升級是一個刻意的動作。
  2. 不要執行本站的 place_*.mcfunction / kill.mcfunction:它們是給單人/示範用的——setblock 不看區域保護、 execute align xz 會自動對齊、所有實例共用同一個標籤,kill 會刪掉整個世界裡所有同款。請用本匯出自行放置。
  3. 原子化放置:先用 cells/bbox 檢查整個佔用範圍與實體上限,全部通過再一次生成;中途失敗就把已生成的全刪。
  4. 每個實例自己的標籤:每個生成的實體都加上你自己的「實例標籤/id」,移除時只刪該實例,並還原真方塊的原狀態。
  5. 忽略不認得的欄位與 scale 鍵(§2)。
  6. verification = "FAIL" 的家具有已知幾何問題(懸空、z-fighting 等),是否使用由消費端決定。

14. 官方家具資源包(1.1.0)#

Display Entity 資料繼續提供;另由 src/display_entity_resourcepack.py 產生 namespace building_dex 的官方資源包(移植 stargate-plugin 8af1847 furniture-pack)。 manifest.resource_pack 是選填物件:filename 為 building_dex-furniture-<zip sha256 前12碼>.zip;sha1 為登入資源包驗證值,size 為 zip bytes, url 目前為 null,待 R2 上傳後才提供。zip 不放 Pages,也不包含於資料快照;本地位於 export/resourcepack/,旁邊有 <filename>.sha1。pack_info、report 路徑相對 manifest。 zip entries 依名稱排序,固定 1980-01-01 時戳;26.3 的 pack.mcmeta 使用 client jar 驗證的 min_format / max_format [97,1]。模型僅引用原版材質,不再散布材質圖片。

pack-info.json.pieces[id]:model_id = building_dex:<slug>(item definition id;模型本體為 building_dex:item/<slug>),k ≤ 1 為模型縮小係數,centre 為南向 1x 家具的模型中心(blocks), text_parts 保存無法烘焙的文字實體完整位置、變換與文字設定。placement 提供南向 1x 的 item_display 範本:paper 物品的 minecraft:item_model component = model_id,item_display=none, translation = centre,scale = 1/k,right_rotation = identity。

一般放置尺度 s、朝向 Y:translation = s·Y·centre,left_rotation = Y,scale = s/k。 朝向角度 south=0、west=-90、north=180、east=90 度;全部相對同一個家具 anchor。 模型頂點 m 還原為 world = anchor + s·Y·(centre + D·(m−8)/(16k)),D=diag(-1,1,-1) 為 item_display 本身的 Y 半圈旋轉。文字實體另外生成,原 pos/translation/scale 同乘 s 並套額外 Y, 不能再套模型的 k/centre。1.8.0 座位依 behavior.seats 處理;碰撞取 behavior.collision,不放 sit-only 支撐方塊。

report.json.pieces[id] 包含 k、centre、elements、sheared(近似的 element 數)、sheared_parts (原 parts/blocks 索引)、text_parts、textures、uvlock_ignored,以及與 spec.json 世界頂點比較的誤差。 非均勻縮放與旋轉造成的 shear 使用上游 polar decomposition 近似,round-trip 跳過這些元素。 summary 提供全部家具的統計及例外清單。zip 內含 report、pack-info、CC BY 4.0 的 CREDITS; 外部 JSON 額外包含 zip metadata,避免自我雜湊循環。

15. CHANGELOG#

1.8.0 — 2026-10-03 (MINOR)#

  • 所有家具明訂 behavior.collision.mode;none 必須附 reason,格式為 enum: 自由說明,enum 限 tableware|small_decor|walkthrough|hanging|flat|other。
  • 低矮家具(茶几、矮凳、矮桌、暖桌等)保留達 10% 相交門檻的整格 barrier;碰撞高於外觀是預期行為,不因高度低於約 0.6 而刪除。最低可見格層不低於錨點地板 y=0;輕微埋入地板的椅腳不能使薄座面的 XZ 覆蓋例外失效。
  • 餐具、小擺飾及 mount: tabletop 無碰撞。拱門、樹木、植栽、樂器、懸掛/壁掛/天花板裝飾、地毯及薄框架刻意可穿越,保留原因說明。
  • 大型實心櫃體、櫃檯、雕像、機器及家電:可見實心聯集達 50% 的格位補上 barrier 核心,既有 barrier 仍須達 10% 覆蓋門檻。新增核心若與可選照明格衝突,保留發光位置 point,將真 light 方塊移到不衝突的 cell;消費端以輸出的 cell 和相對候選 offset 放置,不從 point 重新推算。
  • 大床僅外框/床頭/床尾可碰撞;整個床墊投影及 vanilla bed 的 head/foot 格柱均不得有 barrier,確保床面可走、可躺。原有 lie 的真床方塊不變。
  • 座椅改由插件掛載隱形載具;移除 cushion 實體,坐用真方塊以相同 vanilla 模型轉 display,隱形支撐移除。未有坐墊的座椅不新增坐墊。既有軟墊外觀保留為一般展示幾何。
  • 相容性:1.8.x 保留 building_dex:<id>/seated 舊模型,以凍結的 1.7.2 entities-only 幾何生成;pack-info 的 seated.legacy: true 表示只供既有世界引用,新放置不得使用。移除另行公告。

完整碰撞與座位契約見 §24。

1.7.2 — 2026-10-03 (PATCH)#

  • 以 1×、closed/open、四朝向的可見幾何覆蓋率檢查所有 barrier/collision 格;14 件家具修改,移除 39 個 state/cell 項目(21 個件別格位)。99 個「碰撞太小」state/cell 候選只報告、不補格。完整修改名單與「碰撞太小」候選見 collision-audit-1.7.2.json、COLLISION-1.7.2.md。
  • kitchen-upper-cabinet:碰撞移至 y=1;y=2 可見體積不足 10%,移除。door-cabinet:移除 closed 的前方 (0,0,1),保留櫃體,重新生成 open 與 sweep。
  • round-table:新增 (0,0,0) pedestal barrier,讓將真方塊轉為 display 的消費端保留碰撞;桌面外緣不新增碰撞。
  • 修正 §7 的 BlockAttachedEntity 支撐檢查與消失/掉落說明,坐墊資料不變;§6 明訂整數錨點限制。

碰撞覆蓋規則(1.7.2)#

每個放置的碰撞格須與該狀態可見實心幾何的聯集相交至少 10% 格體積。 薄水平實心零件(世界 y 厚度 ≤1/8 block)可改用至少 10% 的 XZ 格底面積,但只限整件最低可見幾何所在的格層;上層薄板仍須通過體積門檻,避免頭部高度出現整格牆。 檢查使用 vanilla 模型面、展示 TRS、group closed/open 變換、可見真方塊及坐墊;文字、平面物品圖像、火焰/流體效果與無可見模型的 barrier/light 不提供覆蓋,重疊零件不重複計算。樓梯等模型省略的 cuboid 內部面以各元素的八角頂點驗證後補成實心,保留元素之間的空隙。格範圍沿用 §6。 軸對齊幾何使用頂點分割積分;斜面 cuboid 以凸多面體切割求不重疊聯集;其他面網格使用投影邊線、面高度交線與格邊界的平面排列,將各多邊形面積乘上重心處的垂直聯集長度,精確積分分段線性體積(浮點容差 1e-7)。不以整件或零件 AABB 代替實心體積。報告保留體積與底面積供檢閱。 可見實心體積 ≥50% 且沒有真碰撞方塊或 behavior collision 的格只列為候選,不自動補格。 sweep_cells 是動畫途徑的保守空間清查,不是放置的 barrier,仍由完整 motion swept box 重新計算;不套用靜態覆蓋刪除規則。 可見真方塊與顯式 barrier 可以共用格位:原版放置以 keep 保留真方塊;轉 display 的消費端使用 barrier,兩者不重複放置。

1.7.1 — 2026-10-02 (PATCH)#

  • 1.7.1b:media index 新增明確 actions 按鈕與播放契約(§23);action_labels 僅含自身動作,舊合併表保留於 action_labels_legacy 一版。variants 僅供有 toggle_light action 的家具。
  • 移除 coffee-maker、siren、stage-flame-machine、unknown-machine 的手動 toggle_light;其光源屬於運轉指示/效果。washing-machine、toaster、microwave、rice-cooker 原本已無該 action,修正 index 不再暴露假燈光按鈕。

  • 掃掠碰撞格排除錨點層下方(y < 0),避免把支撐方塊判為障礙;新增 verifier。

  • 所有 sequence 的各 group t=0 必須等於 closed/rest pose;修正咖啡機與運轉燈面等不一致資料。
  • 同一 action 的 tracks 必須等長;shaved-ice-maker 的 shave 統一為 100 ticks。
  • 有 toggle_light 的家具待機燈號跟隨 toggle(預設 on),timeline 僅在播放時覆寫;完成/停止後恢復當前 toggle。
  • 明確保留 hold_final 的最後光源 cue,直到 reset/stop(例如 rice-cooker 保溫燈)。actions_schema 維持 1.7.0。

1.7.0 — 2026-10-02 (MINOR)#

  • 核准運轉工具:可停止循環、逐格計分、門蓋互鎖與多群組 action tracks(§22)。
  • viewer 使用 action 專屬 tracks;GLB 保留獨立 action 名稱與播放 metadata;掃掠聯集涵蓋 override。
  • 保留既有 light/seating/lie 規則;家具內容由後續十份 worker brief 分批修改。

1.6.0 — 2026-10-02 (MINOR)#

  • 新增 lie 躺下動作、頭/腳整數 cell、隱藏原版床與 ownership 契約(第 21 節)。
  • 床移除坐墊,使用完整包覆原版床的床墊;預覽器支援躺下玩家示意。
  • 全域世界空間分離 gate 由 0.002 提升為 0.006,修正目標由 0.003 提升為 0.01。

  • Add optional resource-pack pieces[id].seated: an entities-only model for 1× placements with cushions and visible real blocks. This prevents drawing the placed blocks twice (consumer support: plugin ≥2.13.4).

  • Light OFF retains glass, water, fabric, wax and other enclosure materials. Only actual light-emitting block states may be substituted, using their close unlit counterparts. Brightness-only sources such as screens retain their textures and lose emission.
  • Aquarium: an exposed lamp strip follows the lid; glass, water and fish stay unchanged. Interaction boxes are unchanged (the plugin's hinge fix already handles them).
  • Media validation now measures source-only screen masks and rejects excessive luminance changes outside those masks. GLB OFF removes emission and dims only the source material, preserving texture and alpha.

1.5.1 — 2026-10-01#

  • Resource-pack builds reject mixed texture atlases in every model; shell-wreath uses block-textured shell accents.

  • off_block_states keys match entity block_state exactly, without injecting default properties.

  • Sequence groups declare rest_pose: t0; display consumers apply the first frame on placement.
  • Multi-part action IDs name their group; old IDs remain aliases for one MINOR (through 1.6.x).
  • sounds/particles use canonical action IDs; transition cues remain in sound_events.
  • Interaction width and height minimum 0.3; explicit light state labels; visible diffuser off materials.
  • Automatic same-camera 3/4 on/off luminance checks for all light-toggle pieces (display and GLB).

1.5.0 — 2026-10-01#

  • 新增 actions、default_action 與部件 Dialog;咖啡機裝豆/沖煮/取杯三動作。
  • 最終欄位:keyframe.t、action.groups、action.motion、action.toggle.default、off_model_id。
  • 全部互動提供 26.3 原生聲音;media index 合併繁中動作名稱。

1.4.0 — 2026-10-01#

  • 六款機械風扇與兩款磨豆機轉軸;燈光 on/off、off 材質模型與 GLB variants。
  • ATM 吐鈔、糖果/扭蛋轉出一顆;sequence、one_shot、hold_ticks 與 cooldown。
  • 保留 1.3 欄位、四向與 ownership 契約;所有新功能僅在 1× 開啟。

1.3.0 — 2026-09-30#

  • 多活動群組、X/Y/Z 旋轉與平移;保留 open_degrees 的 Y 軸舊別名。
  • 新增 motion、motion_space 與選填 linked;每群組保留獨立原點模型、完整端點 transforms。
  • 任意旋轉軸的解析 sweep_cells、平移 sweep_cells、viewer 群組動畫與靠近模擬、proximity fallback。
  • consumer 既有座標、ownership、required、尺度、重啟與碰撞責任完全保留。

1.2.0 — 2026-09-30#

  • 四件行為試點:光源、逐件 opt-in 碰撞、獨立門模型、點擊盒、動畫與聲音;四向預算、僅 1× 支援。
  • 新增 behavior_version、supported_behavior_scales、capabilities、behavior_entity_count;未宣告行為的家具維持既有契約。

1.1.0 — 2026-09-30#

  • 新增官方 building_dex 資源包、選填 resource_pack manifest 欄位、pack-info/report 與放置公式; 保留原有 Display Entity 資料。zip 留在本地,待 R2 發布。

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)、數學測試向量。

16. 選填行為(1.2.0 / behavior 1.0)#

本次恰好四件:streetlight、table-lamp、chandelier、door-cabinet。 前三件採研究表的 15 / 12 / 15 級光源;路燈只阻擋柱腳一格,燈頭沒有碰撞,桌燈與吊燈 明確宣告 collision.mode="none"。單門櫃採中空木櫃、獨立門片,原尺寸 10 個展示部件。

1.2/1.3 頂層 behavior_version="1.0"(1.5 新輸出為 "1.5")、supported_behavior_scales=["1"],以及 capabilities={lighting,seating,collision,animation,interaction} 五個布林能力旗標只出現在行為家具。 placements["1"][facing].behavior 已預算四向。未列入支援的尺度只放閉合視覺, 不生成 Interaction、動態門、光源或 barrier;缺少 behavior 代表沒有行為。 碰撞必須逐件 opt-in,不得把 cells.list、模型佔格或 bbox 自動填成 barrier。

欄位 契約與消費端責任
initial_state 固定 closed;伺服器重新啟動一律恢復閉合視覺與 closed 碰撞,不延續過渡態
lights[] id、level、連續座標 point、整數 cell、required:false、candidate_offsets。先試主格,再依序試主格加候選向量;全部非空氣就跳過光源,家具仍放置
collision.mode barrier 或 none;只有明確列出的格才有碰撞
collision.cells_by_state 至少 closed / open;每格 {pos:[x,y,z],required:true}。兩態共有的櫃體格永遠保留,不因開門刪除
collision.sweep_cells 由門扇轉動的保守 AABB 取格,每格 {pos,required:true};是檢查區域,不是要填 barrier 的格
parts[] id、model_id、model_origin、各尺度 k、完整 closed_transform / open_transform(translation、left_rotation、scale、right_rotation)
parts[].pivot 動態門軸,已依 placement 朝向旋轉的連續座標;open_degrees 是繞 +Y 的 ±90°,swept_box:{min,max} 包含整段門弧,包含解析計算的中途極值
interactions[] {id,part_id,center,width,height,response};center 是盒底部中心,寬度同時作用 X/Z,height 向上;不提供物理碰撞
trigger {type:"click"} 或 {type:"proximity",radius,close_after_ticks};proximity 的進入/離開遲滯由消費端實作
animation duration_ticks=10、start_delay_ticks=0、teleport_duration=0;每次切換重新設定 start_interpolation=0,transform 插值 10 ticks
sounds open / close 各 {id,volume,pitch},使用原版木門音效,每次切換播放一次
behavior_entity_count placement 的 entity_count 旁新增額外預算;Interaction 數+獨立動態門 display 數。櫃子 2、燈 0;未支援尺度 0。manifest 也按尺度列出。barrier/light 不是實體

所有連續位置、pivots 與原本 entities 共用 anchor,單位是方塊;整數格相對 anchor 的方塊 B。 標準 anchor=(Bx+0.5,By,Bz+0.5),所以選光源格使用 [floor(point.x+0.5),floor(point.y),floor(point.z+0.5)],不能直接 floor 相對 X/Z。 候選向量、格位、點擊盒中心、軸心與 transforms 均已旋轉四向。 桌面 anchor.y 有小數時,以 floor(anchor.y+point.y)-floor(anchor.y) 重算光源主格 Y, 候選整數向量不變;一般光照選格必須用真正的世界 anchor。 model_origin 是例外:它描述模型烘焙前的 south 原始座標,所有朝向共用同一模型。 不要再把已預算的 transform 旋轉一次。

資源包保留 building_dex:<slug> 完整閉合模型,供舊消費端與未支援尺度使用。 行為消費端用 building_dex:door-cabinet/body 固定模型與 building_dex:door-cabinet/door 門模型取代整件模型(不要重複生成原始 parts)。 pack-info.json.pieces[slug].parts[group] 提供 model_id、model_origin、k、k_by_scale。 門軸烘在模型 [8,8,8];D=diag(-1,1,-1) 校正仍適用。 門的 translation 固定在已旋轉軸心、left_rotation=F·Ry(angle)、scale=1/k, 使整段插值都繞真正門軸。k 是模型烘焙因子,與放置尺度不同。 資源包櫃子實際成本為 1 body+1 door+1 Interaction=3;原始 entity_count=10 仍是 Display Entity fallback 的數量,使用 fallback 時額外只需 1 Interaction。

放置前消費端必須檢查所有 required 碰撞格是空氣,否則拒絕整件放置。 只可在目前為空氣的格放 light / barrier,拆除時只把自己仍擁有且用途相符的格恢復 air, 不需要保存原方塊 journal。需要逐實例 ownership;共享光源必須有引用計數/最高亮度 合併,或拒絕共用,不得刪掉其他家具/玩家的方塊。光源 optional,不阻止家具放置。 此行為規則優先於 §6、§13 對舊式真方塊原狀還原的一般建議。

開門先移除本實例 closed 中、open 沒有的門 barrier,再送動畫;櫃體共有格保留。 關門前查 sweep_cells 與目標 closed 格內的玩家/其他實體與新增方塊,有佔用就延後; 10 ticks 完成後再查一次才放 barrier。有人進入則保持通行並重新開門,不能在玩家身上 生成障礙。管理者可選預留掃掠空間或允許建造後拒絕關門;任何情況不得覆蓋非空氣方塊。 單門櫃的點擊盒保留 width=1.9、height=0.91,涵蓋門片與操作空間。1.7.2 已移除南側 (0,0,1) 的多餘 barrier;closed/open 只保留櫃體 (0,0,0),點擊盒本身不提供碰撞。 Interaction id 對應 part_id;移動後消費端應把點擊盒跟隨同一門軸變換,避免在舊位置 保留點擊目標。消費端須自行實作事件去重、冷卻、動畫期間重入與實例狀態鎖。

fallback 的 place 原有展示命令保持相容,另加分組標籤、Interaction 與 setblock … keep; 每個成功佔用格在 anchor 上標記 ownership,kill 只清除這些格。open/close/finish_close 是單实例手動示範,不自帶點擊事件迴圈;沿用 §13 的共用標籤限制。個別原始 display 以端點 transform 插值,中心走弦線;需嚴格保持門軸的消費端使用上述 hinge-local 資源包模型。網頁則直接繞軸心旋轉 0.5 秒;夜間地面光暈只是示意,沒有 Minecraft 遮擋或光傳播模擬。「碰撞」切換只顯示明確宣告的碰撞格。

16.1 多活動群組(1.3.0)#

parts[].motion 為 {type:"rotate",axis:"x"|"y"|"z",degrees:±N} 或 {type:"slide",offset:[dx,dy,dz]},旋轉角不得為零,絕對值不超過 360。 舊 open_degrees 等同 rotate-y;共存時必須一致。motion_space:"source" 表示 motion 的軸與位移是 south 原始座標;消費端應直接使用已預算四向的 完整 transforms,勿再旋轉一次。所有 pivot 仍為 placement anchor 相對座標。 旋轉原點在鉸鏈邊;平移原點在群組自有參考點,開啟 translation 會加入旋轉後位移。 旋轉端點 left_rotation=F·Raxis(angle),平移時 rotation 不變。 轉角超過 180° 時,viewer/消費端要依 motion 分段插值,不能只用最短路徑 quaternion 插值;fallback 會產生分段 step functions,在共 10 ticks 內依指定方向轉動;掃掠涵蓋完整路徑。

每一活動群組輸出 building_dex:<slug>/<group> 模型,靜態預設群組為 building_dex:<slug>/body;pack-info 的 model_origin、k、k_by_scale 逐群組提供。 目前活動群組只接受 block_display,請把活動的把手等也寫為 block_display。 behavior.linked 是活動群組 id 陣列的陣列,例如 [["left","right"]]。 點擊 interaction.part_id 時移動其 linked 連通群組;沒有 linked 時各自獨立。 proximity 觸發所有活動群組。各群組皆有完整 swept_box,collision.sweep_cells 為所有群組掃掠的聯集,任意軸轉動採用解析弧線極值,平移採用兩端角點。

碰撞仍逐件而非逐群組:任一群組開啟時移除 closed-only 格,只有所有群組 閉合且掃掠檢查通過後才能恢復;兩態共有櫃體格保持。獨立群組不要配置 open-only barrier。玩家阻擋時延後關閉,伺服器重啟一律 closed。behavior_entity_count 仍為 interaction 數加活動模型群組數;光源與 barrier 不算實體。

Viewer 的群組選單支援 linked 連動、靠近開關模擬玩家進出及 close_after_ticks 延時,保留夜間光照與碰撞顯示。Fallback open/close 仍為全群組單實例展示; proximity 額外產生 proximity_<facing> 與 proximity_anchor_<facing>,datapack 透過 vanilla tick/load tags 自動初始化計分板並逐 anchor 呼叫; 也可由呼叫端每 tick 在放置 anchor 呼叫前者。它使用 de_bh_idle 計分板、radius 進入與 radius+0.5 離開遲滯;受阻會重試。正式消費端必須自行管理逐實例 tick、群組狀態、 連動及重啟;不可把展示用的全域群組 selector 當作多人實例管理。

17. 行為 1.4:轉動、燈光與一次性運作#

本節是 additive 契約;/v1/、原有放置、碰撞、座標與 1.3 的 parts、 closed_transform / open_transform 不變。舊 consumer 可忽略未知欄位及 motion type, 繼續使用整件靜態模型。行為只適用 1×;重啟、重新放置時回到宣告的預設狀態。

  • motion.type: "spin":axis: "x" | "y" | "z"、pivot: [x,y,z]、 degrees_per_second(絕對值 ≤ 360)、period_ticks: 5、loop: true。 toggle.default: "off";葉片與輪轂為獨立群組,模型原點位於轉軸。 parts[].motion_space: "source" 的軸維持南向局部空間;actions[].motion 則已轉成 該 placement 的軸與正負速度,禁止再轉一次朝向。 consumer 每 5 ticks 更新一次旋轉,start_interpolation=0、interpolation_duration=5、 teleport_duration=0。180°/s 風扇每段 45°,120°/s 磨豆機每段 30°; 即使最高 360°/s,每段也只有 90°。累計角度形成循環,切勿只送出 0°→360° (四元數會視為相同端點)。GLB spin 含四段 90°、完整一圈,consumer 設為循環播放。
  • light_toggle: {default:"on", off_block_states:{原明列 block_state:未發光 block_state}, remove_brightness:true};states:["on","off"]、default_state:"on"。 light_states.on.lights 是開燈候選光源,light_states.off.lights 固定空陣列, .off.swap 是相容別名。關燈移除該實例擁有的 light cells,全部 display entity 移除 brightness,依映射換材質;開燈還原原始資料。不得清除別人的 light/barrier。 lantern 可保留外形但必須移除 brightness;資源包的 off 元件 light_emission 全為 0。
  • 資源包整件與每個行為群組均提供 /off item model。pack-info.pieces[id].off_model_id 及 .parts[group].off_model_id 是精確 item_model ID。整件 building_dex:<id> 或群組 building_dex:<id>/<group> 透過 minecraft:condition 選擇外觀:設定 minecraft:custom_model_data={flags:[true]} 的 flags[0] 為關燈;false 或缺省為開燈。 on/off 共用原點與 k,切換時不改 TRS。group consumer 必須切換所有群組,不能只切換 body。
  • GLB 以 KHR_materials_variants 宣告 on、off;預設 on。off 材質沒有 emissive, 原發光面改成暗色外觀。media index 僅在有手動 toggle_light action 時列出 variants(§23)。 舊 viewer 的 light_on / light_off 是外觀切換事件,不是假造的幾何動畫。
  • 一次性 motion.type: "sequence":keyframes:[{t:0,transform:TRS},…],時間欄位固定為 t(ticks),嚴格遞增。one_shot:true、hold_ticks 為提示,實際暫停由重複 keyframe 決定。 動畫走到最後一格後還原預設,cooldown_ticks 期間拒絕重入。TRS 欄位為 translation,left_rotation,scale,right_rotation。原始 piece / parts[].motion 的 TRS 相對群組原點; export actions[].motion.keyframes[].transform 已包含原點、朝向與資源包 k,可直接套用 item_display。 不得對它再乘 k 或重加 pivot。個別 block_display fallback 應套用原始群組局部 motion 到每個零件。
  • ATM 清單:abd,bill 於 0/10/40/50 ticks 伸出、等待、縮回,純視覺、不產生物品。 糖果/扭蛋清單:candy-machine、capsule-toy-machine,GLB 動畫 dispense; candy 軌跡為主要 motion,knob 以群組 motion 同步旋轉一圈。多群組同時開始; action.group_motions[group] 提供不同於主要 motion 的已解析軌跡(例如 knob), consumer 必須優先使用該群組軌跡,其他群組使用 action.motion。
  • 機械風扇:electric-fan、retro-fan、wall-fan、ceiling-fan、ventilation-fan、air-circulator。 不包含植物或手持扇。壁掛風扇與循環扇的機頭已調平,使 XYZ 軸契約與實際葉片平面一致。 磨豆機:coffee-grinder、pro-coffee-grinder,轉 crank/burr,預設停轉。
  • 所有動作音效為 sounds.<action>={id,volume,pitch},原生 26.3 sound event ID。 1.5.1 起 sounds 的 key 固定為 canonical action id;狀態音效改放 sound_events: open,close,spin_start,spin_stop,spin_loop,light_on,light_off; spin_loop.interval_ticks 是 consumer 重播間隔,停轉後立即停止排程。網站不播放聲音。 檢查使用官方 26.3 asset index 對應的 minecraft/sounds.json(聲音資產位於 asset objects, 不在此版本 client.jar 內)。

18. 行為 1.5:依部件選動作#

behavior.actions[] 中每項為 {id,label,kind,groups,motion?,toggle?,sounds,particles?,cooldown_ticks?}。 label 是繁體中文;kind 僅 open | spin | toggle_light | sequence。 groups 固定為陣列,group 僅是第一個群組的相容別名。kind 專屬參數一律在 motion: open 含群組原有 motion 與完整 closed/open transforms;spin 含 axis/pivot/degrees_per_second; sequence 含 keyframes。spin 預設在 action.toggle.default。 behavior.default_action 是 sneak+右鍵要執行的 action id。 只有碰撞/座位而沒有可執行動作的被動家具保留 actions:[]、default_action:null,不產生假互動。

點擊 interactions[] 所指部件:action:"<id>" 直接執行;action:"menu" 搭配 menu_actions:[ids] 顯示原生 Dialog(最多 6 項)。單一動作直接執行;sneak+右鍵跑整件 default_action。 燈光與門/抽屜共用部件時,既有盒以 menu_actions 明列原動作及 toggle_light;不再加整件大盒遮住部件。ATM 螢幕與咖啡機指示燈另有小型 light-click 盒,咖啡機蓋子與沖煮選單保持獨立。

咖啡機(coffee-maker,stovetop-espresso-maker,espresso-maker,siphon)範例:

{"default_action":"brew","actions":[
  {"id":"load_beans","label":"開蓋裝咖啡豆","kind":"open","groups":["lid"]},
  {"id":"brew","label":"煮咖啡","kind":"sequence","groups":["stream"]},
  {"id":"take_cup","label":"取咖啡","kind":"sequence","groups":["cup"]}
],"interactions":[
  {"id":"lid-click","part_id":"lid","action":"load_beans"},
  {"id":"body-click","part_id":"body","action":"menu","menu_actions":["brew","take_cup"]}
]}

上例省略 motion、聲音與盒幾何;實際 JSON 均完整提供。裝豆是可切換的開/關蓋, 煮咖啡 60 ticks,取杯伸出再縮回。原先只有開蓋的咖啡機已改成上述三動作;1.7.1b 移除咖啡機的獨立燈光動作。 GLB 動畫為 open,close,brew,take_cup;保留 dispense 作 brew 的 1.4 動畫別名。 behavior.particles.brew 與 brew action 的 particles.brew 提供 {id:"minecraft:cloud",pos:[x,y,z],count:3,duration_ticks:60};pos 已按四向解析,consumer 自行播放。

behavior.action_labels 是 action label 的網站相容資料。1.7.1 起 media index 的 action_labels 僅含該家具自身 action id → label;舊的預設合併表移至 action_labels_legacy 保留一版。按鈕與播放行為請使用 §23 的 actions。

19. Consumer feedback fixes (1.5.1)#

light_toggle.off_block_states: match by exact block_state as written in entities; consumers may fall back to id-only. Serialize the id plus sorted explicit properties (id[k=v,...]); with empty properties, use the bare id. Do not add vanilla default properties when looking up the key. Off values are model lookup states. Real-block keys rotate only their written properties for the placement facing. Display keys retain source orientation.

Sequence parts[].rest_pose: "t0": display consumers must apply t=0 when placing (and restarting). The entities retain source geometry so viewer/group animations can reconstruct the complete mesh, including hidden streams; apply the group's first source-space keyframe about its pivot exactly once, rotated into placement space. Resource-pack consumers use closed_transform (already t=0); GLB nodes already contain their t=0 transforms. Do not multiply resolved resource-pack action transforms directly onto individual source display transforms.

Every actions[].sounds and actions[].particles key equals that action's canonical id. Behavior-level sounds/particles aggregate those same canonical keys. Optional sound_events preserves state-specific cues (open, close, spin_start, spin_stop, spin_loop, light_on, light_off), including volume, pitch and repeat intervals; select the transition cue instead of double-playing the primary cue. The old sequence cue dispense is not used as a coffee sound/particle lookup key. aliases accepts the previous action id through 1.6.x (one MINOR); canonical IDs win and aliases never duplicate another canonical id. Interaction/default-action references use canonical IDs. All interaction boxes have width >= 0.3 (both X/Z) and height >= 0.3; expansion preserves their geometric centre. No physical exceptions were required.

toggle_light.label is 開燈/關燈; label_on: "關燈" is the label shown when the light is ON = the action that turns it off. label_off: "開燈" is shown when the light is OFF. Consumers should use these explicit state labels.

As of 1.6.0, only actual emitting block states change to close unlit blocks. Brightness-only sources retain their texture; non-source enclosure materials remain unchanged. GLB KHR_materials_variants OFF removes emission and uses source-only baseColorFactor = [0.65,0.65,0.65,1]; other materials and all alpha modes stay unchanged. Local media validation renders occlusion-aware source ID masks at 512px. It measures mean signed luminance decrease (normalized sRGB Rec.709) inside the visible source mask (>0.005, at least four pixels), and requires mean absolute change outside the mask to stay below 0.01. The normal 3/4 view is tested first; a lower view also checks bulbs exposed beneath opaque shades when necessary. Every tested view must pass the outside-mask guard. Display and GLB source changes must both pass. Depth testing includes occlusion; hidden bulbs alone cannot satisfy this gate. Reports list every tested light and failure.

Resource-pack single-atlas guard (2026-10-01)#

Every emitted model, including whole-piece, behavior group, and light-off variants, is checked before the pack is written. A model may use either item-atlas sprites (*:item/*) or block-atlas sprites (*:block/* etc.), never both; build failures list all offending model paths and their textures. Texture objects and aliases are resolved.

shell-wreath uses stepped bone-block silhouettes with raised smooth-sandstone and white-terracotta spiral accents in place of its three nautilus-shell items. The source piece is changed so preview, fallback, media, and resource pack agree. A separate static item-atlas entity was not selected: current behavior groups retain a legacy combined model, and static pieces have no extra-static-part placement contract. Splitting only the group model would leave the legacy model invalid.

20. Seated resource-pack placement (1.6.0,1.8.x 僅供舊世界)#

1.8.x:以下 /seated 欄位保留並加上 legacy: true,模型來自凍結的 1.7.2 entities-only 幾何。新放置必須用一般模型與插件 seats,不得選用 /seated。以下生成條件及放置順序僅描述 1.6–1.7 舊快照。

For a piece whose placements["1"]["south"] has both cushions and at least one blocks entry with visible: true, pack-info includes:

"seated": {
  "model_id": "building_dex:sofa-two-seat/seated",
  "k": 0.5,
  "centre": [0, 0.5, 0]
}

The numbers above illustrate the shape only; use the actual per-piece k and centre. /seated is converted exclusively from the public placement's entities, without any blocks or cushions. Apply the normal model placement formula using this model's own k and centre. Spawn the visible real blocks and cushions separately. If entities is empty, the entry is {"model_id": null}: place no resource-pack item_display. Other scales use the whole-piece model. This field is additive; consumers must select it whenever they place the visible real blocks instead of also drawing the whole-piece model.

The complete affected-piece list and light audit evidence are in LIGHT-OFF-AUDIT.md beside this source document.

21. 躺下動作與隱藏原版床(1.6.0)#

behavior.actions[] 新增 kind: "lie"。床的 default_action 為 lie, 互動盒可直接指向此 id,或由 menu_actions 選取。此動作不使用坐墊、乘坐或移動部件。

{"id":"lie","kind":"lie","label":"躺下","groups":[],
 "bed_block":"minecraft:light_blue_bed","head_cell":[0,0,-1],"foot_cell":[0,0,0],
 "sounds":{"lie":{"id":"minecraft:block.wool.place","volume":0.35,"pitch":1}}}
  • bed_block:16 種原版床之一,顏色配合寢具;不可用其他方塊替代。
  • head_cell、foot_cell:placement 座標的整數 cell;Y=0,相鄰且水平。 頭端朝向枕頭/床頭板。四個 facing 已分別旋轉;consumer 不得再次旋轉。 X/Z cell 中心遵循本合約的 anchor 約定(cell 邊界為中心 ±0.5)。
  • 1.8.0:head/foot 格及其上方不得出現在 collision.cells_by_state。消費端仍依 lie 資料放置兩半原版床;床格的保留、擁有權及回收不變。外框 barrier 只可在床墊投影以外且通過覆蓋門檻的格位。
  • 1.6–1.7 舊快照才將兩個 bed cell 列為 barrier,供 consumer 以兩半原版床替換。
  • 放置前,兩格都必須是 air,且不得與其他家具的 real-block ownership 衝突。 先完成整體 preflight 再以原子操作保留兩格;任一格失敗必須回滾,不能留下半張床。 若家具已放置 barrier,只能替換本實例已擁有的 barrier;不可覆蓋玩家方塊或別的實例。
  • facing 由 foot → head 的水平向量決定;分別寫入 part=foot、part=head, 維持一致 facing,交由遊戲更新 occupied 狀態。不能把視覺家具的正面 facing 直接當床 facing。
  • 記錄實例、世界、兩格座標及預期 bed state 的 ownership。移動/旋轉/移除家具前, 先處理睡眠玩家,再僅移除仍屬本實例且符合預期的方塊。不得刪除後來被玩家替換的方塊。 chunk unload/reload 與重啟後仍須保存 ownership,防止孤兒床和誤刪。
  • lie 交由 consumer 呼叫原版床睡眠流程;不得用坐椅、假睡姿或強制傳送替代。 原版的時間、維度、附近怪物、床被佔用、重生點設定、起床與安全出口規則仍適用。 不承諾任何時刻都能入睡或任意維度都安全;不要繞過遊戲對不允許使用床之維度的判定。 移除床後,重生點有效性仍由原版處理。
  • 床墊的連續內層包覆整個 1×2×9/16 方塊體積,頂面介於 0.5625–0.69。 大床只配置一張原版床,玩家實際躺在這兩格的位置,並不自動置中於整個模型。 resource-pack 的 k 僅為模型壓縮倍率,還原後仍用上述世界座標;不得把 cell 乘上 k。 1.25/1.5/2 倍展示版維持 display-only,不建立床、不提供 lie。
  • 預覽器的「躺下」/「起身」只加入或移除玩家視覺模型,不寫世界方塊或重生點。
  • 所有模型最終還原世界尺寸後的 z-fighting gate 提升至 0.006,修正目標 0.01。 本次床幾何使用至少 0.01 分離;模型序列化及 k 還原後仍須驗證。

床清單、排除理由、床墊高度與四向 cell 見 BED-LIE-REPORT.md。

作者端的連續性與分離#

piece.json 可選擇 clearance_order: "spatial",使多層容器按原本的空間順序分離, 避免後寫入的托盤穿過杯子。clearance_assemblies 是互不重複的 parts 索引陣列; 每個子組先驗證內部表面,再整組移動,讓紙牌圖案、貝殼凸肋與海馬眼睛跟著本體。 這兩欄只用於作者端重建,consumer 直接使用已解析的 placement/resource-pack 模型。

連續性 gate 仍先檢查實際幾何。只有原作者幾何確實相接、且分離後間隙不超過原接觸 容差加兩倍修正目標(0.01 + 2×0.01)的連接,才能列為刻意分離;原先就懸空的部件 不能用此規則豁免。接觸浮點容差另加 0.00002,以涵蓋五位小數序列化誤差。 所有 z-fighting 面積與世界距離 gate 仍獨立執行,最終模型必須零違規。

22. 核准運轉(1.7.0,全部為選填加法)#

既有 kind 與欄位不變。新作者使用 actions_schema:"1.7.0",頂層 behavior_version="1.7";舊作者 1.5.1/1.6.0 保持原行為。此版本只準備工具與工作簡報,不批次改寫既有家具。

選填欄位 規則
actions[].group_motions sequence/spin 每個 group 各自的 motion(open 沿用部件的存取 motion);與 action.motion 相同,匯出後為朝向/k 已解析的 placement-space。優先於 primary motion;未覆寫群組沿用 parts motion。
actions[].source_motions 匯出器產生的完整每群組 south-space tracks;供 viewer/GLB 從原始幾何重建。不得與 placement-space transforms 疊乘。
actions[].playback.loop sequence 循環到再次按下停止;預設 false。spin 本身持續旋轉。loop 首末 transform 須一致。
actions[].playback.stop_ticks 0..200 ticks;停止效果音與粒子立即生效,幾何在此時間內回 t0;spin 以線性減速到零並保留停止方向。預設 0。
actions[].playback.hold_final 一次性 sequence 保持末格;預設 false,完成恢復 t0。不可與 loop 同用。
actions[].playback.step_ticks 正整數;每次從上次游標向前走 N ticks,對整段 sequence 的週期取餘數並停留;用於兩側獨立計分牌。不得與 loop 同用。
actions[].reset_actions 此動作啟動時清除所列 action id 的 step 游標;歸零幾何仍由本動作 tracks 提供。
actions[].interlocks [{group,state:"open"|"closed",on_change:"stop"|"block"}];只引用可開關的真實門蓋群組。

consumer 在啟動前檢查所有 interlocks,過渡中的門蓋不算 open/closed。 block 拒絕會違反運轉條件的門蓋操作;stop 先停止運轉,再改門蓋。 音樂盒 state=open 可在關蓋時停播;微波爐 state=closed 開門立即停熱;洗衣機 state=closed/block 必須先停機才能開門。檢查涵蓋 linked groups、預設按鈕、Dialog、靠近。 同一群組不能同時執行兩個動作;相互獨立的群組可同時運轉。播放中再按操作鍵停止; 完成後遵守既有 cooldown_ticks(自該次開始計算)。重建/重啟取消全部計時器並回 t0; 不保留 step 游標或運轉狀態。

有限洗程用 sequence 描述筒反轉、脫水與結束;多關節用每群組的絕對 south-space TRS keyframes 烘好相依路徑,無需引入 parent hierarchy。spin 的不同軸和速率由 各 group track 描述;sequence 所有 group 必須都是 sequence(把旋轉烘為 ≤90° 相鄰四元數 keyframes)。新 tracks 的 right_rotation 為 identity,將固定右旋烘入幾何。 資源模型的 pivot/k 計算不變;sweep_cells/bbox 包含所有 action override 的掃掠聯集。

play_audio 研究提案以 sequence + 真實部件的 identity track + 原版音效表示, 不是新的 kind,也不需要讓外殼跳動。聲音保持 canonical action key,循環必須提供 interval_ticks;停止立即取消 loop 並對本實例停止音效。原版沒有精確機器/樂器錄音時 使用最接近的 26.3 原版提示音,不宣稱為新增音檔。蒸氣/薄霧沿用 particles 的位置、數量、 持續 ticks,loop 時每輪重播,停止即取消新粒子;已存在粒子自然消散。網站只預覽幾何。 螢幕切換用既有 toggle_light,局部定時燈號以獨立可隱藏發光群組表示;不更動全局 light ownership。

1.7 GLB clips 按 action id 命名,open 另有 <id>__close。保留 open/close/spin 相容 alias 一個 MINOR(指向同 kind 的 default_action 或第一個動作,不合併獨立群組);舊版維持 open/close/spin 與 brew 的 dispense alias。extras 保留 action_id、playback、interlocks;標準 GLB 播放器 可播放單一週期,互動 consumer 才負責 loop/step/stop/interlock;GLB 不執行音效與 Minecraft 粒子。

actions[].light_timeline:[{t,on:[light_id,...]}] 可同步運轉的真 light cells。 這個 sequence 只管理 timeline 曾出現過的 light id。若家具也有 toggle_light action, t=0 必須反映預設 toggle(預設 on),不可強制熄燈;未播放時以當前 toggle 狀態為準。 播放期間 timeline 暫時覆寫這些 light,正常完成(非 hold_final)或 reset/stop 後, 釋放覆寫並恢復當前 toggle 狀態,不能把 t=0 的預設 on 當成使用者目前的選擇。 沒有 toggle_light 的家具可用 on=[] 待機,reset/stop 回到 t=0。 hold_final=true 完成後保留末格幾何與最後一個 light cue,直到 action 被 reset/stop; 例如 rice-cooker cook 完成後 warming 保溫燈繼續亮。hold_final 是恢復待機規則的例外。 1.7.1 全目錄盤點:同時有 timeline 與 toggle_light 的家具為 arcade-combat-game、 arcade-fighting-game、arcade-mahjong-game、brake-tapper、crosswalk-signal、digital-alarm-clock、 pinball-machine、siren、squid-jukebox、stage-flame-machine、unknown-machine、vending-machine; 其中 crosswalk-signal 與 digital-alarm-clock 的 t=0 已符合預設,其餘十件已修正。 1.7.1b 再移除 siren、stage-flame-machine、unknown-machine 的手動 toggle_light; 保留其 sequence 與 light_timeline,待機使用 t=0,並非可供手動切換的照明。 所有 sequence tracks 的 t=0 transform 必須等於該 group 的 closed/rest pose,且同一 action 的所有 tracks 必須有相同末格 tick。collision.sweep_cells 一律不得包含 y < 0 的支撐層。 時間排序且不得超出動作長度;循環末格 on 集合與首格相同。每次取最後一個 t≤目前 tick 的 cue,依原 ownership 規則開/關該些 light;不可覆蓋外部方塊。共享動件或受控 light id 的 動作不得同時播放。視覺發光面仍以同時間的獨立群組 keyframes 控制,viewer 的光源標記/ 夜間光暈同步 cue,GLB extras 保留 timeline。需要蓋子互鎖的螢幕(laptop、NES)使用 sequence 的隱藏/顯示發光面與 light_timeline;一般螢幕仍用 toggle_light,既有燈光規則不變。 sound_events 的 cue 可選 at_tick(延遲開始)、stop_at_tick(停止該段聲音); 未指定維持原事件名稱語意。這些時間為該輪開始起算的 ticks,consumer 取消時一律立即停音。

23. Media index:明確動作契約(1.7.1)#

本地 media/snapshots/<hash12>.json(發布時對應媒體服務的同快照 index)之 pieces[slug] 保留 thumb、glb、bytes、sha256、size、animations,並新增以下欄位。 animations 是 GLB clip 清單(包含相容 alias),不可用來推導按鈕。 actions 永遠存在;無動作為 [],每列是一個作者定義的按鈕,順序跟隨來源:

欄位 型別/語意
id 穩定 action id
kind open / spin / toggle_light / sequence / lie
label 原始繁中標籤,不解析「/」來判斷播放方式
label_on / label_off 選填,原始狀態標籤;目前 on 時顯示 label_on,目前 off 時顯示 label_off
playback toggle / once / loop / hold_final / step,見下文
animations {start: "實際 GLB clip", stop?: "實際 GLB clip"};每個名稱均驗證存在
default boolean;是否等於 behavior.default_action,並非初始 on/off,也不表示自動播放

open 使用 toggle,start 開啟、stop 關閉;1.7 clips 為 action id 與 <id>__close, 舊版為 open / close。spin 使用 loop;停止時 consumer 停止循環,無虛構 stop clip。 sequence 依 playback 設定:loop 持續循環、step 每次推進 step_ticks、hold_final 播完 保留末格直到 reset/stop,其餘 once 播放一次後恢復。step_ticks、stop_ticks、interlocks、 light_timeline 等細節繼續由 GLB animation extras 提供;不從標籤猜測。

無家具 clip 的兩種動作例外: toggle_light 與 lie 的 animations 為 {},playback 為 toggle;前者切換 on/off 材質,後者切換玩家躺下/起身(位置讀 placement behavior), 不得捏造 GLB clip 名稱。variants: ["on", "off"] 僅在有 toggle_light action 時存在。 內部 light_toggle/off 材質資料可供 sequence 指示燈使用,不構成手動燈光能力。

action_labels 永遠存在,精確為本列 actions 的 id → label(無動作為 {}),不合併 無關預設。action_labels_legacy 保留舊版完整合併結果一個版本,只供過渡。

{"actions":[{"id":"heat","kind":"sequence","label":"加熱/停止",
 "playback":"once","animations":{"start":"heat"},"default":true}],
 "action_labels":{"heat":"加熱/停止"}}

上例省略其他相容欄位;有限長加熱雖可提前停止,仍為 once,並非 loop。 盤點移除手動 toggle_light:coffee-maker(咖啡機指示燈)、siren(鳴笛燈)、 stage-flame-machine(噴火效果)、unknown-machine(運轉燈)。保留 lamps/lanterns、 screens/TVs/monitors、arcade cabinets、signs 等可獨立控制照明;digital-alarm-clock、 crosswalk-signal、squid-jukebox、vending-machine 的顯示/裝飾照明也保留。

24. 碰撞政策與插件座位(1.8.0)#

所有單件 schema_version 為 1.8.0,頂層 behavior_version 為 1.8。運轉動作仍沿用原有 actions_schema;座位不是 moving-group 動畫。

  1. 低矮家具保留相交至少 10% 的整格 barrier,不以外觀高度刪除碰撞;薄水平實心零件沿用最低可見格層的 XZ 面積門檻,埋於 y<0 的幾何不算可見格層。
  2. 餐具、小擺設與所有 mount: tabletop 件為 none。桌面掛載例外優先於低家具規則。
  3. 床墊投影及 vanilla head/foot 格柱不可放 barrier。僅不侵入這些格柱、且通過 10% 門檻的外框/床頭/床尾格可放 barrier;沒有合格格位時明確記為 none,不可補入床面。
  4. 大型實心件可見聯集體積 ≥50% 的格位補實心核心;拱門、植物、樂器、懸掛/壁掛/天花板裝飾、平面墊及薄框架刻意可穿越。
  5. 每件必有 collision.mode: barrier|none。none 必須帶 reason 字串,格式 enum: 自由說明,enum 為 tableware|small_decor|walkthrough|hanging|flat|other,且 closed/open 碰撞陣列都為空。碰撞覆蓋依 §15 的 1.7.2 幾何方法計算。

插件座位 seats#

每個 placements["1"][facing].behavior.seats 為陣列,例如:

{"seats":[{"id":"s1","pos":[0,0.48,0],"yaw":0,"click":[0,0.48,0]}]}

pos 是大腿接觸的可見座面頂部中心,精度 ±0.02 block;髖關節約在上方 0.12,不能把舊 cushion entity 的原點直接當座面。yaw 是已依朝向旋轉的 Minecraft 角度:0 南、90 西、180 北、270/−90 東。沙發、長凳、野餐桌每個坐位一筆,最多 16 筆,id 在單件內唯一。pos/可選 click 的 x/z 限 ±8,y 限 −1..8,皆須有限數值。

click 指該座位專屬 0.5×0.5 點擊框中心;省略時從整件點擊框/barrier 選最近空位。消費端發現 seats 必須優先使用,不能依賴真方塊或舊 cushion 支撐,也不放 sit-only blocks[];照明方塊仍可放置,碰撞只取 behavior.collision。椅凳座面可保留整格 barrier,插件下座時將玩家移到座椅前方。浴缸不提供座位;馬桶蓋/座圈提供座位,蹲式馬桶、站式便器及無可見座面的流動廁所不提供座位。

預覽器「坐下」顯示每個座位的坐姿玩家,切換後「站起來」移除。媒體索引 actions 對有座位的件提供 kind: "sit",無 GLB 動畫 clip 的掛載動作由消費端處理。詳細逐件座面、碰撞決策與修改名單見 seating-decisions-1.8.0.json、collision-audit-1.8.0.json、COLLISION-1.8.0.md。

回到展示實體家具