房間集成指南
將您的建築學帶到Locus。
使用您已經熟悉的專業工具製作模型、紋理、光照並進行導出。Locus 不規定作者工作流程；它只需一個 USDZ，並附帶一個用於開口、座位、表面以及可選燈光的小型明確界面。
從一個正在工作的房間開始
每次下載均為完整的房間 v5 ZIP，已於2026年9月5日更新。請使用兼容的Locus構建版本匯入，或解壓後研究完成的USDZ旁邊的材料和公共元資料。
使用較舊的版本？下載之前的兼容版本： 大廳頂層, 庭院畫廊, Horizon工作室.
由Locus編寫的部分在CC BY 4.0下可重復使用；嵌入的Poly Haven紋理仍然是CC0。請參閱 信用和許可證詳情.
選擇配送合同
完整軟體包v2是Locus 1.2.1及更高版本中標準的完整功能匯入格式。其ZIP根直接包含 locusplace.json 和 catalog/，一個房間住在下面 catalog/spaces/<space-id>/。用於穩定ID和原地更新、聲音、動畫、影片表面、座位組、來源以及支援的捆綁式體驗。
目前公開的房間構建器、腳手架、打包器、驗證器和可下載房間示例，仍生成下方的舊版／簡易平面結構兼容格式。它們不製作或驗證完整 Package v2。每次匯入平面結構格式都會獲得新的 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中必須有一個穩定且唯一的名稱。
開放時間和座位
每個房間都聲明一個 viewOpenings 入口。它與所選的Locus景觀具有邏輯連接；它不會切割USDZ。模型視窗和其他源幾何中的建築開口。坐標使用右手坐標系，+Y向上，-Z向前，以及四元數在 [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控制。 |
共享的間接層按以下比例縮放 2^overallEV。單個燈開關、溫度、顏色和亮度仍為本地控制，不會重新調色共享的反射光。將玻璃、水、透光材料、燈具發光網和可識別的燈具特定光暈排除在共享的間接接收器子樹之外；直接代理擁有本地的光池。
房間 v3強制執行最多12個作者代理，每個座位4個活躍代理，1個陰影投射代理，每個代理10,000流明，以及一個亮度範圍在-4…+1 EV之內。這些是安全限制，而不是目標值。
lighting 對於沒有訪客控制裝置的房間。使用 房間 v2 進行基本照明組，或使用 房間 v3 進行多個代理和房間擁有的預烘焙間接照明。保留您的材料設計
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 立即重復；不同的最小和最大值在每次完成播放後選擇一個新的隨機暫停。
建造最小的工作室
那個 最小房間建造器 從一個空置的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
將五個源檔案放在一個目錄中，並在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助手構建
將公眾樣品技能和您的簡短說明交給能夠運行本地腳本和檢查圖像的AI編碼AI 助手人。安裝Blender後，預設路由使用Python建立原始房間、設定材料、渲染審查圖像，並在背景中導出模型。然後它可以連接座位和可選燈光，為兼容格式搭建五個交付檔案，並驗證精確的平面ZIP。如果您願意，您仍然可以使用其他專業的3D工作流程。
無界面製作仍需目視檢查。保存的渲染圖有助於 AI 助手發現建模和材質問題；最後在 Apple Vision Pro 上通過 App 檢查，確認房間在 Locus 中的外觀與體驗。如果 AI 助手無法操作合適的 3D 工具或檢查圖片，必須說明哪些工作尚未完成。