房間集成指南
將您的建築學帶到Locus。
使用您已經熟悉的專業工具製作模型、紋理、光照並進行導出。Locus 不規定作者工作流程;它只需一個 USDZ,並附帶一個用於開口、座位、表面以及可選燈光的小型明確界面。
從 Package v2 開始
當前房間製作請使用完整的 Package v2,它支援穩定身份、更新和當前功能。預設將房間與配套景觀分別打包,以便獨立交付、替換或移除。
下載範例
免費 Room 和部分免費 View 可作為範例下載研究,其中一些附有 Blender 原始檔。 在藝廊中瀏覽範例。
程式設計代理可以讀取 place-examples.json 以取得每個下載的 URL、大小、SHA-256、功能和授權。
房間歷史示例包
這些扁平兼容 ZIP 作為學習示例保留,可對照成品 USDZ 研究材質和公開元數據。它們不代表當前 Package v2 的功能。
展開歷史下載與兼容性說明
更早的兼容版本下載: 大廳頂層, 庭院畫廊, Horizon工作室.
由Locus編寫的部分在CC BY 4.0下可重復使用;嵌入的Poly Haven紋理仍然是CC0。請參閱 信用和許可證詳情.
選擇配送合同
完整 Package v2 是 Locus 1.2.1 及後續版本推薦的完整功能導入格式。ZIP 根目錄直接包含 locusplace.json 和 catalog/,一個房間住在下面 catalog/spaces/<space-id>/。它支持穩定 ID、原地更新、聲音、動畫、視頻表面、座位分組、本地化顯示文本、來源信息、受支持的 Room/View 組合,以及隨包提供的 Experience。使用 tools/pack_locusplace.py,並使用 tools/validate_locusplace.py,然後使用目標版本和明確為空的算圖目錄執行 check_room.py,並查看座位算圖聯絡表。
常規製作時,請將房間和配套景觀分別打包:各自使用獨立的壓縮包和穩定的 packageID,從而可以獨立交付、替換和移除。有意讓內容作為整體維護時,仍可使用合併的 Package v2 壓縮包;但常規房間製作流程預設分開打包。
現有 Room 構建器與腳手架有意生成下述舊版簡易扁平兼容格式。其打包器與校驗器仍適用於簡單導入,但扁平歸檔無法攜帶僅完整包支持的字段。每次扁平導入都會獲得一個新的 UUID。
舊版/簡易格式交付契約
提供一個具有五個根檔案的統一兼容ZIP:
my-room.zip
├── space.json
├── provenance.json
├── teleport-points.json
├── scene.usdz
└── thumbnail.jpgscene.usdz是自contained的,量程為米,+Y向上,並使用世界-Z作為正向。space.json描述房間。它有一個顯示名稱,但沒有作者資產ID;Locus 在每次平整匯入時都會分配一個新的UUID。teleport-points.json聲明至少有一個可用的座位。provenance.json誠實記錄建立者、權利、署名、更改和AI使用。thumbnail.jpg由房間編寫;Locus在匯入時不會生成它。
保留可編輯的源檔案、紋理、緩存和交換檔案在ZIP之外。所有元資料引用的實體在交付的USDZ中必須有一個穩定且唯一的名稱。
開放時間和座位
在 Locus 1.4.5 之前,每個 Room 只能宣告 1 個 viewOpenings 條目;自 1.4.5 起(扁平 ZIP 中為formatVersion: 11 ,或 destinationOpenings ,Package v2 中為 [x, y, z, w] 訂單。
每個傳送點都定義了一個眼睛的位置和面部朝向。 anchorXZ 已歸一化為導出房間邊界; sourceFloorOffset 確定其水平; eyeHeight 是從那層樓測量的。座位ID是房間界面的一部分,因此在修訂過程中請保持其穩定。
可選的空間適應
spatialAdaptation 將您的USDZ語義部分連接到Locus的功能:
| 字段 | 合同 |
|---|---|
wallEntities | 已驗證的牆面參考;這些不會隱藏虛擬牆壁或驅動房間傳送門。 |
roofEntities | 已驗證的屋頂或天花板參考;這些不會隱藏虛擬屋頂。 |
deskEntitiesByTeleportID | 將座位ID映射至其桌面表面對應的精確實體。此地圖中未包含的座位為一等休閒座椅(沙發、日間床、長凳):它加載在作者指定的樓層和視線高度,且永遠不會獲得桌子尺寸、對齊或通過資訊——不要僅僅為了給它一個桌子就將附近的咖啡桌映射進去。 |
deskGroupEntitiesByTeleportID | 可選,1.1.5+。名稱,對於已經有一個的辦公桌後座 deskEntitiesByTeleportID 入口,即整個子樹均為該座位隱藏書桌的唯一實體,因此Locus可以提供訪客隱藏書桌控制功能。命名實體必須唯一標識,且為書桌表面實體的一個祖先,否則房間無法加載。舊讀者忽略此字段。 |
映射的桌子實體應是桌面本身或一個緊密封閉的板材。不要在其下方包含椅子、燈具、腿、電腦或鬆散道具;Locus 使用實體的邊界來推導出表面高度、足跡和方向。
可選照明界面
照明元資料告訴 Locus,每個面向訪客的控制器屬於哪些導出發光網格和邊界運行時源。它並不規定如何建模、著色或烘焙房間。
| 字段 | Locus的行為 |
|---|---|
luminaireGroups | 一個分組對應一個邏輯開關,以及一套亮度/顏色控制。 |
entities | 命名發熱部件的機身。啟用後的部件從每個座位的發熱情況都保持可見。 |
proxy / proxies | 聲明邊界點或點源。使用 proxies 在房間v3中,當一個開關驅動多個物理髮射器時。 |
nearTeleportIDs | 它只限制直接代理源到選定的座位;它不會隱藏或變暗其他固定裝置的身體。 |
bakedIndirect.entities | 房間v3接收器子樹用於低頻間接光控制,由房間燈光主控和整體房間EV控制。 |
bakedIndirect.layers | 一個燈組對共享接收面圖集的直接光和反射光貢獻,使該燈組的開關、EV 和顏色能夠影響周圍表面。 |
舊版/簡單扁平房間格式使用 formatVersion: 10。在推薦使用的 Package v2 中, space.json 必須 保持為 formatVersion: 2;將 lighting.bakedIndirect.layers ,不要照抄舊版的版本號。
當可獨立控制的燈具需要照亮牆壁、地板、桌面或天花板時,請使用按燈組烘焙的光照層。分別烘焙各組,保留基礎 UV 以及 LocusIndirectUV 用於接收面圖集,並在線性光空間中合成所有燈組開啓時的共享圖集。不要將可開關燈具的光照寫入始終開啓的靜態共享圖集,也不要用代理光源重復計算已烘焙的光照區域。
共享的間接層按以下比例縮放 2^overallEV。各盞燈的開關、色溫、顏色和亮度仍是局部控制項,不會改變該基礎共享反彈光的顏色。玻璃、水、透射材質、燈具發光網格,以及可辨認為某盞燈效果的光暈,都應排除在共享間接光接收子樹之外;局部光照區域由直接光源代理負責。
房間 v3強制執行最多12個作者代理,每個座位4個活躍代理,1個陰影投射代理,每個代理10,000流明,以及一個亮度範圍在-4…+1 EV之內。這些是安全限制,而不是目標值。
lighting ,適用於不含使用者可控燈具的房間。基礎燈組使用 Room v2;房間整體的烘焙間接光使用 Room v3;需要按燈組改變受光表面時使用烘焙光照層。可選的電視
需要 Locus 1.4.9 或更新版本以及完整 Package v2;扁平相容格式無法攜帶電視。
一個房間最多可以宣告四台電視。每台電視指向 USDZ 中的一個螢幕:一個獨立的平面 16:9 四邊形,有自己的 UV,不巢狀在其他被引用的實體之下。它的材質就是電視關機時的樣子,例如深色玻璃或藝術畫,不應發光。訪客開啟電視後,Locus 會在這個四邊形的範圍內播放網頁。
保留您的材料設計
Locus 使用您導出 USDZ 中的支援的 PBR 材料、紋理、UV 和變換。例如,名稱如下 glass、傢具尺寸和匯入房間的標識不會決定材質預設。請在可編輯源中修正材質和導出問題,再重新構建房間 ZIP。
房間v5添加了明確的 rendering.softenedReflectionEntities 和 rendering.uiFadeEntities。僅在需要顯示帶有水平場景細節去除的景觀反射時使用第一個;它不會反映房間內部。使用第二個可以允許選擇的傢具在遮擋訪客視窗時淡化。省略的角色不會賦予任何行為。
每個v5焦點宣佈一個單位 direction 在導出房間坐標中,例如 [0.6, -0.8, 0]。僅提供錨定供應位置。這些字段需要v5兼容的Locus構建。使用 可選的美元模型審計 檢查導出參考和支援的著色器。閱讀 支援材料、預設值和遷移規則 在出口前。
實驗性環境動畫
房間 v4可以連接已嵌入在USDZ中的動畫剪輯到命名訪客控制器。每個 ambientAnimations 輸入標識一個實體和一個動畫,以及它的初始切換、速度範圍和重播間隔範圍。
訪客可以通過 房間動態 快捷控制中的圖釘。在 設定 → 運動 → 房間 他們可以切換每個動畫,更改其實驗速度和間隔,然後將這些值保存到當前裝置上的這個房間。間隔為 0–0 立即重復;不同的最小和最大值在每次完成播放後選擇一個新的隨機暫停。
進階 Room 指南
基礎 USDZ、開口與座位調通後,可直接查閱以下 Package v2 Room 進階特性指南與欄位規格:
建造最小的工作室
那個 最小房間建造器 從一個空置的Blender場景開始,建立一個書桌、一個調校好的座椅、兩堵牆、一個屋頂和一個受控吊燈。它需要Blender 5.2和Python 3在 macOS 上。克隆或下載此倉庫,以便構建器可以使用捆綁的元資料 scaffolder;不需要外部模型、紋理或MCP連接。
- 從儲存庫根目錄中,運行構建器,輸出路徑不已存在。它保存可編輯的Blender檔案、獨立的USDZ檔案、縮略圖和六張坐姿審查圖像。
- 檢查每個圖像
review/。如果比例、座位方向、間隙或桌面使用性有誤,請糾正源。 - 運行公共打包器和驗證器,然後通過匯入確切的ZIP 空間 → 匯入 → 匯入一個房間 → 檔案.
- 選擇 最小閱讀室 在“空間”中,將其與“景觀”配對,然後進入虛擬空間。嘗試閱讀台座位、快捷控制中的“房間燈光”圖釘,以及 光線和圖片→房間。實時桌面對齊和舒適度需要Apple Vision Pro。
blender --background --factory-startup --python-exit-code 1 \
--python tools/build_minimal_room.py -- \
--output /absolute/path/to/minimal-reading-room
python3 tools/pack_locus_asset.py \
/absolute/path/to/minimal-reading-room/room \
/absolute/path/to/minimal-reading-room.zip
python3 tools/validate_locus_asset.py /absolute/path/to/minimal-reading-room.zip如果使用您的Blender可執行程序的絕對路徑 blender 不在 PATH 中。構建器和打包工具不會覆蓋已有輸出。請將可編輯源和復核圖片保存在五檔案 ZIP 之外。該 完整的運行時交互參考 解釋座位、安全、碰撞賬簿、測量質量、桌子映射和作者權限如何與應用程序連接。
打包、驗證,然後匯入兼容性 ZIP
製作完整的 Package v2 Room,請使用 完整包指南與工具。把五個源文件放在同一目錄中,在 macOS 上運行保留的公開平鋪格式工具:
python3 tools/pack_locus_asset.py /absolute/path/to/room /absolute/path/to/my-room.zip
python3 tools/validate_locus_asset.py /absolute/path/to/my-room.zip- 解決來自USDZ導出器和公共驗證器的所有警告或錯誤。
- 在Locus中,選擇 匯入房間 並選擇確切驗證的ZIP。
- 將帶景的房間與Apple Vision Pro配對並進入。
- 嘗試每個座位,可選的桌子映射、渲染角色和你所聲明的燈光控制。
- 修復源並重新構建ZIP;不要手動補丁最終存檔。
使用AI助手構建
從 ChatGPT、另一種影像模型或你自己的參考圖開始。請代理製作平面圖和座位配置,然後讓它根據影像和圖紙建模、審查每個座位,並用公開工具驗證確切的 Package v2 封存檔。在 Apple Vision Pro 上匯入,並向代理傳送具體回饋以便迭代。 四步 Room 教學 在不存取 Locus 應用程式原始碼或 Simulator 的情況下,逐步說明此工作流程。
使用裝有 Blender 和 Xcode 或其 Command Line Tools 的 Mac。代理從匯出的模型推導座位,並為修訂保留穩定 ID。任何影像模型皆為選用;不需要 API 金鑰。如有需要,仍可使用其他專業 3D 工作流程。
代理會儲存可重現的腳本和算圖、檢查影像並修訂 Room。它必須使用明確的算圖目錄執行 check_room.py、查看聯絡表,並報告封存檔 SHA-256 和剩餘的裝置檢查。
無介面製作仍包括視覺審查。儲存的算圖可協助代理發現建模和材質問題,但最終 Apple Vision Pro 預覽才能確認 Room 在 Locus 中的外觀和感受。匯入已準確檢查的封存檔,使用 Preview in 3D,與 View 配對,然後嘗試每個座位、燈光控制和 Hide Desk。如果代理無法操作合適的 3D 工具或檢查影像,必須說明哪些工作尚未完成。