Créez une Vue assortie à partir d’une idée avec le tutoriel de skybox statique.

Commencer avec Package v2

Pour créer une pièce actuelle, utilisez un Package v2 complet. Il fournit un identifiant stable, les mises à jour et les fonctionnalités prises en charge. Par défaut, empaquetez la pièce et sa vue séparément pour pouvoir les distribuer, les remplacer ou les supprimer indépendamment.

Créez et validez une pièce Package v2 complète.

Télécharger des exemples

Les Rooms gratuites et certaines Views gratuites peuvent être téléchargées comme exemples à étudier, certaines avec leur source Blender. Parcourir les exemples dans la galerie.

Les agents de programmation peuvent lire place-examples.json pour connaître l’URL, la taille, le SHA-256, les fonctionnalités et la licence de chaque téléchargement.

Anciens paquets de pièces à étudier

Ces ZIP de compatibilité à structure plate restent disponibles pour étudier leurs matériaux et leurs métadonnées publiques à côté du fichier USDZ final. Ils ne décrivent pas les fonctionnalités actuelles de Package v2.

Ouvrez les téléchargements historiques et les notes de compatibilité

Téléchargements compatibles antérieurs : Salon d'atrium, Galerie de la cour, Atelier Horizon.

Les pièces écrites par Locus sont réutilisables sous CC BY 4.0 ; les textures intégrées Poly Haven restent CC0. Voir le Détails des crédits et des licences.

Choisissez le contrat de livraison

Package v2 complet est le format d’importation recommandé pour toutes les fonctionnalités à partir de Locus 1.2.1. La racine du ZIP contient directement locusplace.json et catalog/, et une pièce vit sous catalog/spaces/<space-id>/. Utilisez-le pour les identifiants stables, les mises à jour sur place, le son, les animations, les surfaces vidéo, les groupes de sièges, les textes localisés, la provenance, les compositions Pièce/Vue prises en charge et les Experiences incluses. Créez-le avec tools/pack_locusplace.py, vérifiez-le avec tools/validate_locusplace.py, exécutez ensuite check_room.py avec la version cible et un répertoire de rendus vide explicitement indiqué ; examinez sa planche-contact des rendus de sièges.

Pour une création courante, empaquetez séparément la pièce et sa vue : chacune possède son archive et un identifiant stable packageID, afin de pouvoir le distribuer, le remplacer et le supprimer indépendamment. Une archive Package v2 combinée reste possible pour des contenus à gérer ensemble, mais ce n’est pas le choix par défaut pour créer une pièce.

Le générateur de pièce et l’outil de structure existants produisent volontairement l’ancien format de compatibilité simple à plat décrit ci-dessous. Leur outil d’empaquetage et leur validateur restent utiles pour les imports simples, mais une archive à plat ne peut pas porter les champs réservés aux paquets complets. Chaque import à plat reçoit un nouvel UUID.

Contrat de livraison héritée/simple

Fournir un ZIP de compatibilité plate avec exactement cinq fichiers racines :

my-room.zip
├── space.json
├── provenance.json
├── teleport-points.json
├── scene.usdz
└── thumbnail.jpg

Conservez les sources, les textures, les caches et les fichiers d'échange modifiables en dehors du ZIP. Chaque entité référencée par les métadonnées doit avoir un nom stable et unique dans le USDZ livré.

Ouvertures et places

Avant Locus 1.4.5, chaque pièce déclare une seule entrée viewOpenings ; à partir de 1.4.5 (formatVersion: 11 dans les ZIP plats, ou destinationOpenings , dans Package v2), les ouvertures sont facultatives et une pièce peut en déclarer plusieurs. Il s’agit d’une connexion logique vers la View sélectionnée ; elle ne découpe pas l’USDZ. Modélisez les fenêtres et ouvertures réelles dans la géométrie source. Les coordonnées utilisent des mètres main droite, +Y vers le haut, -Z vers l’avant et des quaternions au format [x, y, z, w] Commande.

Chaque point de téléportation définit une position d'œil et une direction de regard. anchorXZ est normalisé dans les limites de la pièce exportées ; sourceFloorOffset identifie son niveau ; eyeHeight est mesuré à partir de ce sol. Les identifiants de siège font partie de l'interface de la pièce, alors gardez-les stables lors des révisions.

Auteur à utiliser, pas seulement à prévisualiser. Importez le ZIP exact livré et asseyez-vous à chaque place sur Apple Vision Pro. Une Pièce dont la structure est valide peut encore avoir une hauteur de vue inconfortable, une vue obstruée, une échelle incorrecte ou un dégagement insuffisant.

Adaptation spatiale facultative

spatialAdaptation relie les parties sémantiques de votre USDZ aux fonctionnalités de Locus :

Champcontrat
wallEntitiesRéférences de murs validées ; celles-ci ne masquent pas les murs virtuels ni ne conduisent au Portail de la pièce.
roofEntitiesRéférences de toiture ou de plafond validées ; celles-ci ne masquent pas la toiture virtuelle.
deskEntitiesByTeleportIDCartographie l'ID de siège vers l'entité exacte pour sa surface de table. Un siège exclu de cette carte est un siège salon de première classe (canapé, lit-douche, banc) : il est chargé à sa hauteur de sol et à sa hauteur des yeux autorisées et ne reçoit jamais de mesures de bureau, d'alignement ou de passage — ne cartographiez pas une table de café à proximité juste pour lui donner un bureau.
deskGroupEntitiesByTeleportIDOptionnel, 1.1.5+. Noms, pour un siège sur dossier de bureau qui a déjà un deskEntitiesByTeleportID entrée, l'entité dont l'ensemble du sous-arbre est le bureau caché de ce siège, de sorte que Locus peut offrir un contrôle du bureau caché aux visiteurs. L'entité nommée doit être résolue de manière unique et être un ancêtre de l'entité de surface du bureau, sinon la pièce ne se charge pas. Les lecteurs plus anciens ignorent ce champ.

Une entité de bureau cartographiée doit être la table elle-même ou une plaque délimitée de manière rigoureuse. N'incluez pas de chaises, de lampes, de pieds, d'ordinateurs ou d'accessoires lâches en dessous ; Locus utilise les limites de l'entité pour déduire la hauteur de surface, l'empreinte au sol et l'orientation.

Interface d'éclairage optionnelle

Les métadonnées d'éclairage indiquent à Locus quels mailles émises exportées et sources de runtime délimitées appartiennent à chaque contrôle orienté vers le visiteur. Elles ne prescrivent pas comment modéliser, ombrer ou pré-emballer la pièce.

ChampComportement de Locus
luminaireGroupsUn groupe est un interrupteur logique et un ensemble de commandes de luminosité/couleur.
entitiesNomme les corps des luminaires émissifs. Un luminaire activé reste visiblement émissif depuis chaque siège.
proxy / proxiesDéclare des sources de points ou de taches délimitées. utiliser proxies Dans la pièce v3, lorsqu'un interrupteur alimente plusieurs émetteurs physiques.
nearTeleportIDsIl limite uniquement les sources proxy directes aux sièges sélectionnés ; il ne masque pas ou n'assombrit pas le corps de l'appareil ailleurs.
bakedIndirect.entitiesSous-arbres récepteur Room v3 pour la lumière indirecte à basse fréquence contrôlée par le maître des lumières de la pièce et l'EV de la pièce dans son ensemble.
bakedIndirect.layersContribution directe et réfléchie d’un groupe de luminaires à l’atlas récepteur partagé, pour que l’interrupteur, l’EV et la couleur du groupe agissent sur les surfaces environnantes.

L’ancien format de pièce simple à structure plate utilise formatVersion: 10. Dans le format recommandé Package v2, space.json doit restent formatVersion: 2 ; indiquez lighting.bakedIndirect.layers à cet endroit, sans jamais reprendre le numéro de version ancien.

Utilisez des couches précalculées par groupe lorsqu’une lampe contrôlée indépendamment doit éclairer les murs, sols, tables ou plafonds. Précalculez chaque groupe seul et conservez les UV de base ainsi que LocusIndirectUV pour l’atlas récepteur, et composez en lumière linéaire l’atlas partagé avec tous les groupes allumés. N’intégrez pas la lumière d’une lampe commutable dans un atlas partagé statique toujours actif, et ne comptez pas deux fois sa zone éclairée précalculée en ajoutant une source de substitution.

La couche indirecte partagée est mise à l'échelle par 2^overallEV. Les interrupteurs, la température, la couleur et la luminosité de chaque lampe restent des commandes locales et ne recolorent pas cet éclairage indirect partagé de base. Excluez le verre, l’eau, les matériaux transmissifs, les maillages lumineux des lampes et les halos reconnaissables d’une lampe de la sous-arborescence réceptrice de l’éclairage indirect partagé ; les sources directes de substitution gèrent les zones éclairées locales.

Room v3 impose un maximum de 12 proxys autorisés, 4 proxys actifs à chaque siège, 1 proxy de projection d'ombre, 10 000 lumens par proxy et une plage de luminosité de -4…+1 EV. Ce sont des limites de sécurité, pas des valeurs cibles.

L'éclairage est facultatif. omettre lighting pour une pièce sans éclairage contrôlable par les visiteurs. Utilisez Room v2 pour les groupes d’éclairage simples, Room v3 pour l’éclairage indirect global précalculé de la pièce, et les couches précalculées lorsqu’un groupe doit modifier les surfaces qu’il éclaire.

Téléviseurs facultatifs

Nécessite Locus 1.4.9 ou une version ultérieure et le Package v2 complet ; le format de compatibilité plat ne peut pas contenir de téléviseurs.

Une pièce peut déclarer jusqu’à quatre téléviseurs. Chacun désigne un écran dans l’USDZ : un quadrilatère plat 16:9 qui lui est propre, avec ses propres UV, non imbriqué sous une autre entité nommée. Son matériau est l’état éteint du téléviseur, par exemple du verre sombre ou une œuvre, et ne doit pas émettre de lumière. Quand un visiteur allume le téléviseur, Locus affiche une page web dans les limites de ce quadrilatère.

Lire le tutoriel téléviseur ou les règles des téléviseurs Room.

Préservez votre design matériel

Locus utilise les matériaux, textures, UV et transformations PBR pris en charge dans votre USDZ exporté. Des noms tels que glass, taille de la pièce et identité de la pièce importée ne choisissent pas les préréglages de matériaux. Corrigez les problèmes de matériau et d'exportation dans la source editable, puis reconstruisez le Room ZIP.

Room v5 ajoute explicite rendering.softenedReflectionEntities et rendering.uiFadeEntities. Utilisez le premier uniquement lorsque vous souhaitez une réflexion de vue avec les détails de la scène horizontaux supprimés ; cela ne reflète pas l'intérieur de la pièce. Utilisez le second pour permettre aux meubles sélectionnés de s'estomper tout en bloquant une fenêtre de visiteur. Les rôles omis ne confèrent ni l'un ni l'autre de ces comportements.

Chaque projecteur v5 déclare une unité direction Dans les coordonnées de la pièce exportées, telles que [0.6, -0.8, 0]. Seule la position d'alimentation de l'ancre est fournie. Ces champs nécessitent une version de Locus compatible v5. Utilisez le Audit de modèle USD facultatif Pour vérifier les références exportées et les shaders pris en charge. Lisez le matériaux pris en charge, paramètres par défaut et règles de migration avant l'exportation.

Animations ambiantes expérimentales

Room v4 peut connecter des clips d'animation déjà intégrés dans le USDZ à des contrôles visiteurs nommés. chacun ambientAnimations L'entrée identifie une entité et une animation, ainsi que son commutateur initial, sa plage de vitesse et sa plage d'intervalle de relecture.

Les visiteurs peuvent activer ou désactiver toutes les animations expérimentales d'une pièce avec le Mouvement de la pièce Tuile dans les Commandes rapides. dans Paramètres → Mouvement → pièce Ils peuvent basculer sur chaque animation, modifier sa vitesse et son intervalle expérimentaux, puis enregistrer ces valeurs pour cette pièce sur l'appareil actuel. Un intervalle de 0–0 se répète immédiatement ; différentes valeurs minimales et maximales sélectionnent une pause aléatoire fraîche après chaque lecture terminée.

Le support d'animation est expérimental. Les métadonnées, le comportement de lecture, les commandes, la vitesse et les intervalles peuvent changer. Omettez les métadonnées d'animation à moins d'accepter intentionnellement ce risque ; cela s'applique également aux animations dans Room v5.

Guides avancés pour les Rooms

Une fois le USDZ de base, les ouvertures et les sièges fonctionnels, passez directement aux guides et références des nouvelles fonctions Room de Package v2 :

Construire la plus petite pièce fonctionnelle

le Constructeur de pièces minimaliste Commence à partir d'une scène vide Blender et crée un bureau, un siège calibré, deux murs, un toit et un pendant contrôlé. Il nécessite Blender 5.2 et Python 3 sur macOS. Clonez ou téléchargez ce dépôt afin que le constructeur puisse utiliser le scaffolder de métadonnées intégré ; aucun modèle, texture externe ou connexion MCP n’est nécessaire.

  1. Depuis le racine du dépôt, lancez le constructeur avec un chemin de sortie qui n'existe pas déjà. Il enregistre le fichier editable Blender, un USDZ autonome, une miniature et six images de revue assises.
  2. Inspectez chaque image dans review/. Corrigez la source si l'échelle, la direction du siège, l'espacement ou l'utilisabilité de la surface de travail sont incorrects.
  3. Lancez le packer et le validateur publics, puis importez le ZIP exact via Lieux → Importer → Importer une pièce → Fichiers.
  4. Sélectionner pièce de lecture minimale Dans Places, associez-le à une Vue et entrez dans l'Espace virtuel. Essayez le siège de la table de lecture, la tuile d'éclairage de la pièce dans Contrôles rapides, et Lumière et photo → pièce. L'alignement et le confort sur table réelle nécessitent 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

Utilisez le chemin absolu de votre exécutable Blender si blender n'est pas sur PATH. Le constructeur et le emballeur refusent de surcharger la sortie existante. Conservez la source editable et examinez les images en dehors du fichier ZIP contenant les cinq fichiers. le référence complète de l'interaction en temps d'exécution explique comment les sièges, la sécurité, la comptabilité des collisions, la qualité mesurée, la cartographie des bureaux et les autorisations des auteurs sont connectés à l'application.

Emballer, valider, puis importer le ZIP compatible

Pour une pièce complète en Package v2, utilisez le guide et outils des paquets complets. Placez les cinq fichiers sources dans un dossier et exécutez sous macOS les outils publics conservés pour le format à plat :

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. Résolvez toutes les avertissements ou erreurs de l'exportateur USDZ et du validateur public.
  2. Dans Locus, choisissez Importer une Pièce et sélectionnez le ZIP exact validé.
  3. Appareillez la pièce avec une vue et entrez-la sur Apple Vision Pro.
  4. Essayez chaque siège, la cartographie de bureau facultative, le rôle de rendu et le contrôle de la lumière que vous avez déclarés.
  5. Corrigez la source et reconstruisez le ZIP ; ne modifiez pas l'archive finale à la main.

Construire avec un assistant IA

Commencez avec une image conceptuelle de ChatGPT, d’un autre modèle d’image ou de votre propre référence. Demandez à un agent un plan au sol et une disposition des sièges, puis faites-lui modéliser à partir de l’image et du plan, examiner chaque siège et valider l’archive Package v2 exacte avec les outils publics. Importez-la sur Apple Vision Pro et envoyez à l’agent des retours concrets pour itérer. Le tutoriel Room en quatre étapes explique ce flux de travail sans accès au code source de l’application Locus ni à un Simulator.

Utilisez un Mac avec Blender et Xcode ou ses Command Line Tools. L’agent dérive les sièges du modèle exporté et préserve des ID stables pour les révisions. Tout modèle d’image est facultatif ; aucune clé API n’est nécessaire. Vous pouvez toujours utiliser un autre flux de travail 3D professionnel si vous le préférez.

Aucune fenêtre Blender ou configuration MCP n'est requise.

L’agent enregistre des scripts et rendus reproductibles, vérifie les images et révise le Room. Il doit exécuter check_room.py avec un répertoire de rendus explicitement indiqué, examiner la planche-contact et signaler le SHA-256 de l’archive ainsi que les vérifications d’appareil restantes.

La création sans interface comprend toujours une revue visuelle. Les rendus enregistrés aident l’agent à repérer les problèmes de modélisation et de matériau, mais l’aperçu final sur Apple Vision Pro confirme l’aspect et le ressenti du Room dans Locus. Importez l’archive exacte vérifiée, utilisez Aperçu en 3D, associez-la à une View, puis essayez chaque siège, commande d’éclairage et Hide Desk. Si l’agent ne peut pas utiliser un outil 3D adapté ou inspecter les images, il doit expliquer le travail restant incomplet.