房间集成指南
将您的建筑学带到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 工具或检查图片，必须说明哪些工作尚未完成。