Guía de integración de habitaciones
Trae tu arquitectura a Locus.
Modelo, textura, luz y exportación con las herramientas profesionales que ya conoces. Locus no prescribe un flujo de trabajo de autorización; consume un USDZ más una pequeña interfaz explícita para aperturas, asientos, superficies y luces opcionales.
Empieza con una habitación que funcione
Cada descarga es un Room v5 ZIP completo, actualizado el 5 de septiembre de 2026. Cámbialo con una versión compatible de Locus, o desempácalo para estudiar los materiales y los metadatos públicos junto al USDZ terminado.
¿Utiliza una versión más antigua? Descargue una versión compatible anterior: Altarío Loft, Galería del patio, Atelier Horizonte.
Las partes escritas por Locus son reutilizables bajo CC BY 4.0; las texturas incorporadas de Poly Haven siguen siendo CC0. Consulte el detalles de créditos y licencia.
Elija el contrato de entrega
Complete Package v2 es el formato de importación completo de características canónico en Locus 1.2.1 y versiones posteriores. Su raíz ZIP contiene directamente locusplace.json Y catalog/, y una habitación vive debajo de catalog/spaces/<space-id>/. Úsalo para IDs estables y actualizaciones in situ, sonido, animaciones, superficies de vídeo, grupos de asientos, procedencia y Experiencias empaquetadas compatibles.
El actual generador público de habitaciones, montacargas, empaquetador, validador y ejemplos descargables de habitaciones sigue produciendo el formato de compatibilidad plano heredado/simple a continuación. No autorizan ni validan el paquete completo v2. Cada importación plana recibe un nuevo UUID.
Contrato de entrega heredada/simple
Entrega un ZIP de compatibilidad plana con exactamente cinco archivos raíz:
my-room.zip
├── space.json
├── provenance.json
├── teleport-points.json
├── scene.usdz
└── thumbnail.jpgscene.usdzEs autónomo, a escala de metros, +Y hacia arriba y utiliza el mundo -Z como hacia adelante.space.jsonDescribe la habitación. Tiene un nombre de pantalla pero no un ID de activo de autor; Locus asigna un nuevo UUID en cada importación plana.teleport-points.jsondeclara al menos un asiento utilizable.provenance.jsonCreador de registros honestos, derechos, crédito, cambios y uso de IA.thumbnail.jpgEstá escrito con la habitación; Locus no lo genera durante la importación.
Mantenga fuentes, texturas, cachés e intercambios de archivos editables fuera del ZIP. Cada entidad referenciada por los metadatos debe tener un nombre estable y único en el USDZ entregado.
Horarios y plazas
Cada habitación declara exactamente uno viewOpenings entrada. Es una conexión lógica con el Locus View seleccionado; no corta el USDZ. Ventanas del modelo y otras aperturas arquitectónicas en la geometría de la fuente. Las coordenadas utilizan metros de mano derecha, +Y hacia arriba, -Z hacia adelante y quaterniones en [x, y, z, w] Pedido.
Cada punto de teletransporte define una posición de ojo y una dirección de orientación. anchorXZ Se normaliza en los límites de la habitación exportados; sourceFloorOffset Identifica su nivel; eyeHeight Se mide desde ese piso. Los identificadores de asiento forman parte de la interfaz de la habitación, por lo que manténlos estables en todas las revisiones.
Adaptación espacial opcional
spatialAdaptation conecta las partes semánticas de tu USDZ con las características de Locus:
| Campo | Contrato |
|---|---|
wallEntities | Referencias de pared validadas; estas no ocultan paredes virtuales ni conducen al Portal de la habitación. |
roofEntities | Referencias de techo o techo validadas; estas no ocultan el techo virtual. |
deskEntitiesByTeleportID | Asigna un ID de asiento a la entidad exacta para su superficie de mesa. Un asiento fuera de este mapa es un asiento de salón de primera clase (sofá, cama de día, banco): se carga a su altura de suelo y de vista autorizadas y nunca recibe medidas de escritorio, alineación o paso de datos — no mapees una mesita de café cercana solo para darle un escritorio. |
deskGroupEntitiesByTeleportID | Opcional, 1.1.5+. Nombres, para un asiento respaldado por un escritorio que ya tiene un deskEntitiesByTeleportID entrada, la única entidad cuyo subárbol completo es el escritorio oculto de ese asiento, por lo que Locus puede ofrecer un control de escritorio oculto para los visitantes. La entidad nombrada debe resolverse de forma única y ser un ancestro de la entidad de la superficie del escritorio, o la habitación no carga. Los lectores anteriores ignoran este campo. |
Una entidad de escritorio mapeada debe ser la propia superficie de la mesa o una losa delimitada de forma estrecha. No incluya sillas, lámparas, patas, ordenadores ni accesorios sueltos debajo de ella; Locus utiliza los límites de la entidad para derivar la altura superficial, la huella y la orientación.
Interfaz de iluminación opcional
Los metadatos de iluminación indican a Locus qué mallas emisivas exportadas y fuentes de tiempo de ejecución delimitadas pertenecen a cada control orientado al visitante. No prescribe cómo modelar, sombrear o hornear la habitación.
| Campo | Comportamiento de Locus |
|---|---|
luminaireGroups | Un grupo es un interruptor lógico y un conjunto de controles de brillo/color. |
entities | Nombra los cuerpos de los receptores emisivos. Un receptor habilitado permanece visiblemente emisivo desde cada asiento. |
proxy / proxies | Declara fuentes de puntos o puntos delimitados. Usa proxies En la habitación v3 cuando un interruptor impulsa múltiples emisores físicos. |
nearTeleportIDs | Solo limita las fuentes proxy directas a los asientos seleccionados; no oculta ni oscurece el cuerpo del fixture en otro lugar. |
bakedIndirect.entities | Subárboles de receptor Room v3 para luz indirecta de baja frecuencia controlada por el maestro de las luces de la habitación y el EV general de la habitación. |
La capa indirecta compartida se escala por 2^overallEV. Los interruptores de luz individuales, la temperatura, el color y el brillo siguen siendo controles locales y no recolorean ese rebote compartido. Mantenga fuera de la subárbol del receptor indirecto compartido los cristales, el agua, los materiales transmisibles, las mallas de brillo de los focos y los halos reconocibles específicos del foco; los proxies directos poseen pozos locales de luz.
Room v3 impone un máximo de 12 proxies autorizados, 4 proxies activos en cualquier asiento, 1 proxy de proyección en la sombra, 10.000 lumens por proxy y un rango de brillo de -4…+1 EV. Estos son límites de seguridad, no valores objetivo.
lighting para una habitación sin instalaciones controladas por visitantes. Utilice Room v2 para grupos de iluminación básicos, o Room v3 para múltiples proxies e iluminación indirecta preprogramada propiedad de la habitación.Preserve su diseño de material
Locus utiliza los materiales, texturas, UV y transformaciones PBR compatibles en su USDZ exportado. Nombres como glass, tamaño de los muebles e identidad de la habitación importada no elijan los presets de material. Corrija los problemas de material y de exportación en la fuente editable, luego vuelva a reconstruir el Room ZIP.
La habitación v5 añade explícito rendering.softenedReflectionEntities Y rendering.uiFadeEntities. Utilice el primero solo cuando desee una reflexión de Vista con los detalles de la escena horizontales eliminados; no refleja el interior de la habitación. Utilice el segundo para permitir que los muebles seleccionados se desvanezcan mientras bloquea una ventana de un visitante. Los roles omitidos no otorgan ninguno de los comportamientos.
Cada foco v5 declara una unidad direction en las coordenadas de la habitación exportadas, como [0.6, -0.8, 0]. Solo proporciona la posición del ancla. Estos campos requieren una construcción Locus capaz de v5. Utilice el Auditoría opcional del modelo USD Para comprobar las referencias exportadas y los sombreadores compatibles. Lea el materiales compatibles, valores predeterminados y reglas de migración Antes de exportar.
Animaciones ambientales experimentales
La habitación v4 puede conectar clips de animación ya integrados en el USDZ a controles de visitantes nombrados. Cada ambientAnimations La entrada identifica una entidad y una animación, además de su conmutación inicial, rango de velocidad y rango de intervalo de reproducción.
Los visitantes pueden encender o apagar todas las animaciones experimentales de una habitación con el Movimiento de la habitación Azulejo en Controles Rápidos. En Ajustes → Movimiento → Habitación Pueden cambiar cada animación, modificar su velocidad y intervalo experimental, y luego guardar esos valores para esta habitación en el dispositivo actual. Un intervalo de 0–0 Se repite inmediatamente; diferentes valores mínimos y máximos seleccionan una pausa aleatoria nueva después de cada reproducción completada.
Construye la habitación más pequeña que funcione
El Constructor de habitaciones minimalista Empieza desde una escena vacía de Blender y crea un escritorio, una silla calibrada, dos paredes, un techo y un colgante controlado. Necesita Blender 5.2 y Python 3 en macOS. Clonifica o descarga este repositorio para que el constructor pueda utilizar el escaneo de metadatos empaquetado; no se necesitan modelos, texturas externos ni la conexión a MCP.
- Desde la raíz del repositorio, ejecute el generador con una ruta de salida que ya no exista. Almacena el archivo editable Blender, un USDZ independiente, una miniatura y seis imágenes de revisión sentadas.
- Inspeccione cada imagen en
review/. Corrige la fuente si la escala, la dirección del asiento, el espacio libre o la usabilidad de la mesa de trabajo están equivocados. - Ejecute el empaquetador y validador público, luego importe el ZIP exacto a través de Lugares → Importar → Importar una habitación → Archivos.
- Seleccionar Salón de lectura minimalista En Lugares, úsalo con una Vista e ingresa Espacio Virtual. Prueba el asiento de la Mesa de lectura, la baldosa de luces de la habitación en Controles rápidos y Luz y fotos → Habitación. La alineación y la comodidad de la mesa real requieren 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.zipUtilice la ruta absoluta de su ejecutable Blender si blender No está en PATH. El constructor y el empaquetador se niegan a sobrescribir la salida existente. Mantenga la fuente editable y revise las imágenes fuera del archivo ZIP de cinco archivos. El referencia de interacción completa en tiempo de ejecución explica cómo los asientos, la seguridad, el registro de colisiones, la calidad medida, el mapeo de escritorios y los permisos de autor se conectan a la aplicación.
Empacar, validar y luego importar el ZIP de compatibilidad
Mantenga los cinco archivos fuente en un directorio y ejecute las herramientas de formato plano público en 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- Resolver todas las advertencias o errores del exportador USDZ y del validador público.
- En Locus, elige Importar una Habitación y seleccione el ZIP exacto y validado.
- Asocia la habitación con una vista y entra en ella en Apple Vision Pro.
- Pruebe cada asiento, mapeo de escritorio opcional, rol de renderización y control de iluminación que haya declarado.
- Corrija la fuente y vuelva a construir ZIP; no parchee el archivo final a mano.
Construye con un asistente de IA
Entrega a un agente de codificación de IA tu muestra de habilidad pública y tu breve descripción a un agente que pueda ejecutar scripts locales e inspeccionar imágenes. Con Blender instalado, la ruta predeterminada utiliza Python para crear una habitación original, configurar los materiales, renderizar las imágenes de revisión y exportar el modelo de fondo. A continuación, puede conectar los asientos y las luces opcionales, estructurar los cinco archivos de entrega para el formato de compatibilidad y validar el ZIP plano exacto. Todavía puedes utilizar otro flujo de trabajo 3D profesional si lo prefieres.
La autorización sin cabeza aún incluye revisión visual. Los renders guardados ayudan al agente a detectar problemas de modelado y de material; la comprobación final dentro de la aplicación en Apple Vision Pro confirma cómo se ve y se siente la habitación en Locus. Si el agente no puede operar una herramienta 3D adecuada o inspeccionar imágenes, debe explicar qué trabajo sigue incompleto.