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