參考靜態天空盒教學,從想法製作配套的 View。

從 Package v2 開始

當前房間製作請使用完整的 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.jpg

保留可編輯的源檔案、紋理、緩存和交換檔案在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是房間界面的一部分,因此在修訂過程中請保持其穩定。

作者用於使用,而不是僅供預覽。 將最終交付的同一個 ZIP 匯入 Apple Vision Pro,並逐個落座檢查。結構驗證通過的房間,仍可能存在視線高度不適、視野受阻、比例錯誤或活動餘量不足。

可選的空間適應

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 會在這個四邊形的範圍內播放網頁。

閱讀電視教學 或 閱讀 Room 電視規則。

保留您的材料設計

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 立即重復;不同的最小和最大值在每次完成播放後選擇一個新的隨機暫停。

動畫支援是實驗性的。 元資料、播放行為、控制、速度和間隔可能會發生變化。除非你有意接受這種風險,否則請忽略動畫元資料;這同樣適用於 房間 v5 中的動畫。

進階 Room 指南

基礎 USDZ、開口與座位調通後,可直接查閱以下 Package v2 Room 進階特性指南與欄位規格:

建造最小的工作室

那個 最小房間建造器 從一個空置的Blender場景開始,建立一個書桌、一個調校好的座椅、兩堵牆、一個屋頂和一個受控吊燈。它需要Blender 5.2和Python 3在 macOS 上。克隆或下載此倉庫,以便構建器可以使用捆綁的元資料 scaffolder;不需要外部模型、紋理或MCP連接。

  1. 從儲存庫根目錄中,運行構建器,輸出路徑不已存在。它保存可編輯的Blender檔案、獨立的USDZ檔案、縮略圖和六張坐姿審查圖像。
  2. 檢查每個圖像 review/。如果比例、座位方向、間隙或桌面使用性有誤,請糾正源。
  3. 運行公共打包器和驗證器,然後通過匯入確切的ZIP 空間 → 匯入 → 匯入一個房間 → 檔案.
  4. 選擇 最小閱讀室 在“空間”中,將其與“景觀”配對,然後進入虛擬空間。嘗試閱讀台座位、快捷控制中的“房間燈光”圖釘,以及 光線和圖片→房間。實時桌面對齊和舒適度需要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
  1. 解決來自USDZ導出器和公共驗證器的所有警告或錯誤。
  2. 在Locus中,選擇 匯入房間 並選擇確切驗證的ZIP。
  3. 將帶景的房間與Apple Vision Pro配對並進入。
  4. 嘗試每個座位,可選的桌子映射、渲染角色和你所聲明的燈光控制。
  5. 修復源並重新構建ZIP;不要手動補丁最終存檔。

使用AI助手構建

從 ChatGPT、另一種影像模型或你自己的參考圖開始。請代理製作平面圖和座位配置,然後讓它根據影像和圖紙建模、審查每個座位,並用公開工具驗證確切的 Package v2 封存檔。在 Apple Vision Pro 上匯入,並向代理傳送具體回饋以便迭代。 四步 Room 教學 在不存取 Locus 應用程式原始碼或 Simulator 的情況下,逐步說明此工作流程。

使用裝有 Blender 和 Xcode 或其 Command Line Tools 的 Mac。代理從匯出的模型推導座位,並為修訂保留穩定 ID。任何影像模型皆為選用;不需要 API 金鑰。如有需要,仍可使用其他專業 3D 工作流程。

不需要 Blender 視窗或 MCP 設定。

代理會儲存可重現的腳本和算圖、檢查影像並修訂 Room。它必須使用明確的算圖目錄執行 check_room.py、查看聯絡表,並報告封存檔 SHA-256 和剩餘的裝置檢查。

無介面製作仍包括視覺審查。儲存的算圖可協助代理發現建模和材質問題,但最終 Apple Vision Pro 預覽才能確認 Room 在 Locus 中的外觀和感受。匯入已準確檢查的封存檔,使用 Preview in 3D,與 View 配對,然後嘗試每個座位、燈光控制和 Hide Desk。如果代理無法操作合適的 3D 工具或檢查影像,必須說明哪些工作尚未完成。