探索作品
展示實體家具匯出格式#
本文件是 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: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×)#
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. 給消費端的建議#
- 釘版本:vendor 一份快照 zip,核對 sha256;升級是一個刻意的動作。
- 不要執行本站的
place_*.mcfunction/kill.mcfunction:它們是給單人/示範用的——setblock不看區域保護、execute align xz會自動對齊、所有實例共用同一個標籤,kill會刪掉整個世界裡所有同款。請用本匯出自行放置。 - 原子化放置:先用
cells/bbox檢查整個佔用範圍與實體上限,全部通過再一次生成;中途失敗就把已生成的全刪。 - 每個實例自己的標籤:每個生成的實體都加上你自己的「實例標籤/id」,移除時只刪該實例,並還原真方塊的原狀態。
- 忽略不認得的欄位與 scale 鍵(§2)。
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_packmanifest 欄位、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° (四元數會視為相同端點)。GLBspin含四段 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。- 資源包整件與每個行為群組均提供
/offitem 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 相對群組原點; exportactions[].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:
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 動畫。
- 低矮家具保留相交至少 10% 的整格 barrier,不以外觀高度刪除碰撞;薄水平實心零件沿用最低可見格層的 XZ 面積門檻,埋於 y<0 的幾何不算可見格層。
- 餐具、小擺設與所有
mount: tabletop件為none。桌面掛載例外優先於低家具規則。 - 床墊投影及 vanilla head/foot 格柱不可放 barrier。僅不侵入這些格柱、且通過 10% 門檻的外框/床頭/床尾格可放 barrier;沒有合格格位時明確記為
none,不可補入床面。 - 大型實心件可見聯集體積 ≥50% 的格位補實心核心;拱門、植物、樂器、懸掛/壁掛/天花板裝飾、平面墊及薄框架刻意可穿越。
- 每件必有
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 為陣列,例如:
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。