Technische Referenz

Vollständige Locus Package v2 erstellen

Status: kanonischer Vertrag für Veröffentlichung, Speicherung, Kombination und vollständigen Import. Ab Locus 1.2.1 lässt sich dieses Archiv über Dateien oder eine öffentliche HTTPS-URL als Ansicht oder Raum importieren. Das ältere flache Format in der locus-asset-format.md bleibt eine Kompatibilitätseingabe.

Ein .zip oder .locusplace ist ein gewöhnliches ZIP-Archiv mit einer oder mehreren Package-v2-Destinations (Produktname: Ansichten), Spaces (Räume) und Experiences. Es bildet den sicheren Veröffentlichungs- und Integritätsrahmen, den Locus selbst sowie vollständige portable Pakete verwenden. Direkt in der ZIP-Wurzel liegen locusplace.json und catalog/ direkt in der ZIP-Wurzel. Legen Sie beide nicht in einen zusätzlichen übergeordneten Ordner.

Die Prüfung basiert auf Archivbytes und Manifesten, niemals auf der Dateiendung. Ein vollständiges Paket bewahrt packageID, die Inhalts-IDs, contentVersion -Updatestrom und unterstützte Experiences. Ein erneuter Import desselben Inhalts-Hashes ist eine idempotente Operation ohne Änderung. Der gepflegte Packer und Validator erstellen und prüfen genau dieses Format.

Dieser Paketrahmen enthält reine Daten, keine ausführbaren Erweiterungen. Innerhalb derselben Locus-Version hat jede von der Laufzeit verarbeitete Package-v2-Funktion dieselbe Bedeutung, unabhängig davon, ob das Archiv integriert ist, aus der Bibliothek stammt oder über Dateien/URL importiert wurde. Die Herkunft darf Berechtigungen, Importkontingente, Updatebefugnis, Speicherung, Entfernen und Anzeigebezeichnungen beeinflussen, schaltet aber niemals ein anderes Raum-/Ansichtsschema oder andere Rendererfunktionen frei. Skripte, Plugins, dynamische Bibliotheken und ausführbare Dateien gehören nicht zum Format. Für jede Herkunft gelten dieselben Prüfungen auf sichere Pfade, Integrität, Ressourcenbudgets, strukturelle Dekodierung, vollständige Referenzauflösung und Mindestversion.

Diese Anleitung beschreibt den vollständigen Paketrahmen und die Basismanifeste. Die Feldreferenz erläutert die optionalen Funktionen von Ansichten und Räumen einschließlich Dateien, Grenzen, Standardwerten und Mindestversionen. Das Schema des Paketrahmens und Herkunftsschema beschreiben die JSON-Struktur. Packer und Validator prüfen zusätzlich Dateibytes und feldübergreifende Regeln. Ein JSON Schema allein kann kein Archiv prüfen und nicht nachweisen, dass die Darstellung auf Apple Vision Pro angenehm ist.

Mit einem funktionsfähigen vollständigen Paket beginnen

Klonen oder laden Sie das öffentliche Werkzeug-Repository. Führen Sie diese Befehle im Hauptverzeichnis des Repositorys unter macOS aus. Erforderlich sind Python 3.9 oder neuer und eine Xcode-Installation mit xcrun usdchecker und xcrun usdcat. Die grundlegende Prüfung verwendet die Python-Standardbibliothek, /usr/bin/sips für die vollständige Bilddekodierung sowie Xcodes usdchecker und usdcat für Modelle. Erweiterte Prüfungen für Wolken, Wasserreflexionen/-kontakte und sonnenfreie Himmel benötigen zusätzlich NumPy und Pillow: python3 -m pip install numpy pillow.

python3 examples/locusplace/build_examples.py /absolute/path/to/locusplace-examples
python3 tools/validate_locusplace.py --current-app-version 1.4.4 /absolute/path/to/locusplace-examples/view-only.locusplace
python3 tools/validate_locusplace.py --current-app-version 1.4.4 /absolute/path/to/locusplace-examples/room-only.locusplace
python3 tools/validate_locusplace.py --current-app-version 1.4.4 /absolute/path/to/locusplace-examples/combined.locusplace

Der Zielordner darf noch nicht existieren oder muss leer sein. Diese winzigen synthetischen Beispiele prüfen das Format. Farbverlauf und Würfel sind keine fertige Landschaft oder ein fertiger Raum in Produktionsqualität. Ihr Quellcode und die erzeugten Inhalte stehen unter Apache-2.0. Siehe die Beispielanweisungen.

--current-app-version gibt an, auf welche Locus-Version sich die Prüfung bezieht; dadurch wird weder die installierte App aktualisiert noch eine Funktion freigeschaltet. Die Werkzeuge verwenden vorsichtshalber den Standardwert 1.0.0; geben Sie die Zielversion ausdrücklich an. Vollständige Importe erfordern mindestens Locus 1.2.1; neuere Felder haben jeweils eigene Mindestversionen. Die Boden- und Mittelgrundeinstellungen für Räume benötigen einen unterstützenden Build ab 1.4.4. Diese Anleitung behauptet nicht, dass ein solcher Build bereits im App Store erhältlich ist.

Entpacken Sie für ein eigenes Paket ein Beispiel in einen bearbeitbaren Ordner oder erstellen Sie die unten gezeigte Struktur. Ersetzen Sie Dateien und Herkunftsangaben, verwenden Sie eigene stabile IDs und schreiben Sie die Ausgabe außerhalb dieses Ordners:

python3 tools/pack_locusplace.py --current-app-version 1.4.4 MyEditablePlace MyPlace.zip
python3 tools/validate_locusplace.py --current-app-version 1.4.4 --json MyPlace.zip

Der Packer berechnet die Felder neu: files und contentHash, prüft das Archiv und erstellt erst danach die Ausgabedatei. Vorhandene Ausgabedateien werden nicht überschrieben. Der bearbeitbare Quellordner bleibt unverändert. Importieren Sie das Ergebnis über Orte → Importieren → Ansicht importieren oder Raum importieren → Dateien. Wählen Sie einen Importweg für einen im Paket enthaltenen Inhaltstyp. Ein kombiniertes Paket installiert seine Inhalte gemeinsam. Auch eine direkte öffentliche HTTPS-URL zur ZIP-Datei ist möglich. Prüfen Sie jeden erstellten Sitz, Effekt, jede Lichtquelle und jeden Ton auf Apple Vision Pro, bevor Sie einen fertigen Ort weitergeben.

Archivstruktur

example.locusplace
├── locusplace.json
└── catalog/
    ├── destinations/<destination-id>/
    │   ├── destination.json
    │   ├── provenance.json
    │   └── ...
    ├── spaces/<space-id>/
    │   ├── space.json
    │   ├── provenance.json
    │   └── ...
    └── experiences/<experience-id>/
        └── experience.json

Jeder reguläre Archiveintrag außer der Datei locusplace.json muss aufgeführt sein in files. Jede deklarierte Datei muss vorhanden sein. Erlaubt sind nur die drei bekannten Katalogsammlungen. Jede Datei muss zu einer Paket-ID gehören, die in folgendem Feld deklariert ist: contents. Package-v2-Manifeste bleiben gegenüber unbekannten Feldern vorwärtskompatibel. Unbekannte Felder im Paketrahmen, nicht unterstützte Formatversionen, Sammlungen und Inhaltsmodi werden jedoch sicher abgewiesen. Für Herkunftsangaben gilt das veröffentlichte Schema.

Ein reines Ansichts- oder Raumarchiv installiert wiederverwendbare Kataloginhalte. Nach der Katalogauflösung erzeugt Locus die Standardkombinationen: jede Ansicht mit „Ihr Raum“ sowie jede Ansicht mit jedem Raum, der eine Ansichtsöffnung besitzt. Eine explizite Experience ersetzt nur ihre benannte Kombination und kann auf Inhalte desselben Archivs oder auf eine stabile ID im integrierten bzw. importierten Katalog verweisen.

locusplace.json

{
  "formatVersion": 1,
  "packageID": "place.example-combined",
  "contentVersion": "1.0.0",
  "minimumAppVersion": "1.0.0",
  "contents": {
    "destinationIDs": ["destination.example-view"],
    "spaceIDs": ["space.example-room"],
    "experienceIDs": ["experience.example-combined"]
  },
  "files": [
    {
      "path": "catalog/destinations/destination.example-view/destination.json",
      "byteCount": 214,
      "sha256": "<64 lowercase hex characters>"
    }
  ],
  "contentHash": "<64 lowercase hex characters>"
}

packageID und alle Inhalts-IDs sind stabile ASCII-Kennungen mit höchstens 128 Bytes. Sie beginnen mit einem Buchstaben oder einer Ziffer. Danach sind nur Buchstaben, Ziffern sowie ., _und -. Versionsnummern bestehen aus genau drei numerischen Bestandteilen. Ändern sich die Bytes, muss ein Update dieselben deklarierten Inhalts-IDs behalten und die folgende Version erhöhen: contentVersion. Der erneute Import desselben contentHash ist eine idempotente Operation ohne Änderung.

contentHash ist der SHA-256 aller nach Unicode-Pfad sortierten Dateieinträge. Jeder Eintrag liefert diese UTF-8-Bytes:

path NUL decimal-byteCount NUL lowercase-sha256 NUL

Dieser Hash ist unabhängig von JSON-Leerraum und der Reihenfolge der ZIP-Mitglieder. Der Validator liest außerdem jede deklarierte Datei als Datenstrom und prüft ihre tatsächliche Byteanzahl, ZIP-CRC und SHA-256.

Feldreferenz des Paketrahmens

Package-v2-Metadaten im ZIP

Der vollständige Paketrahmen verwendet formatVersion: 1; jedes destination.json, space.json und experience.json verwendet formatVersion: 2. Die Room-Versionsnummern v1–v10 in der Referenz des flachen Kompatibilitätsformats gehören zur separaten flachen space.json -Eingabe. Ändern Sie niemals ein vollständiges space.json auf Version 10, um gebackene Lichtschichten zu nutzen. In vollständigen Paketen aktivieren typisierte Felder die optionalen Funktionen; abgesichert werden sie durch minimumAppVersion.

Alle Dateipfade eines Pakets sind relativ zum Ordner ihres Manifests, nicht zur ZIP-Wurzel. Jede Referenz muss auf eine reguläre Datei innerhalb dieses Pakets zeigen. Die Basismanifeste von Package v2 erlauben vorwärtskompatible Metadaten; einzelne Funktionsprofile können jedoch geschlossene Feldmengen vorgeben. Verlassen Sie sich nicht darauf, dass ein unbekanntes Feld dargestellt wird. Der äußere Paketrahmen weist unbekannte Felder zurück; Herkunftsangaben müssen dem veröffentlichten Schema entsprechen.

Das Koordinatensystem ist rechtshändig, verwendet Meter, +Y nach oben und −Z nach vorn. Quaternionen stehen in der Reihenfolge [x, y, z, w]. Eine Transformation kann folgende Felder enthalten: translationMeters (drei endliche Zahlen), orientationXYZW (vier endliche Zahlen mit einer von null verschiedenen Länge) und scale (drei endliche positive Zahlen).

Ansicht: destination.json

{
  "formatVersion": 2,
  "id": "destination.example-view",
  "title": "Example View",
  "panorama": {
    "path": "panorama.jpg",
    "projection": "equirectangular",
    "width": 8192,
    "height": 4096,
    "initialYawDegrees": 0
  },
  "provenance": "provenance.json"
}

Vollständige ZIPs akzeptieren die von diesem Programm tatsächlich verarbeiteten Felder sowie ausdrücklich beibehaltene Metadaten wie sourceImage, sofern sich deren Inhalt als typisierte Daten innerhalb der Ressourcenlimits prüfen lässt. midground gehört zum gemeinsamen Laufzeitvertrag und erfordert minimumAppVersion >= 1.2.1. depthLayers, splatund der ältere Block audio bleiben reserviert oder veraltet und haben keinen aktuellen Laufzeitverbraucher. Deshalb weist diese App-Version sie unabhängig von ihrer Herkunft zurück, statt ungeprüfte Dateipfade zu akzeptieren. Sobald eine spätere Version eine dieser Funktionen implementiert, muss sie Dateireferenzen, Typ- und Budgetprüfungen, Laufzeitverbraucher und Mindestversion in den gemeinsamen Vertrag aufnehmen. Es darf kein separater Schalter für öffentliche Importe hinzukommen.

12.288×6.144 (12K) wird empfohlen, ist aber keine Pflicht. Niedrigere Auflösungen wie 8.192×4.096, 6.144×3.072 oder 4.096×2.048 sind gültig, sofern sie exakt 2:1 sind und mit ihren tatsächlichen dekodierten Abmessungen angegeben werden. Skalieren Sie ein kleineres Bild nicht nur hoch, um 12K anzugeben: Es entstehen keine neuen Details, nur höherer Speicherbedarf.

Die Panoramakoordinaten sind festgelegt: u = 0.5 ist Winkel 0 und die anfängliche Vorwärtsrichtung/Welt −Z; u nimmt nach Osten in Richtung +X zu; die Naht liegt bei u = 0/1bei einem Winkel von ±180°; die oberste Bildzeile zeigt den Zenit. initialYawDegrees dreht das Bild innerhalb dieses Koordinatensystems, definiert es aber nicht neu.

Optionale Beleuchtung einer Ansicht:

{
  "environment": {
    "imageBasedLight": "thumbnail.jpg",
    "skyGainEV": 0,
    "exposureEV": 0,
    "horizonPitchDegrees": 0,
    "colorGrade": {"contrast": 1.15, "saturation": 1.2},
    "directSun": {"enabled": false, "illuminanceLux": 5000}
  }
}

Die Farbanpassung betrifft nur das angezeigte SDR-Panorama. Sie verwendet dieselbe Textur erneut und macht aus der Ansicht weder HDR noch stellt sie im Ausgangsbild fehlende Lichterdetails wieder her. Auch eine deaktivierte Sonne kann einen Wert von 5000 Lux tragen, damit Sonnenlicht hinzufügen mit der App-Standardstärke startet, ohne den im Paket festgelegten Aus-Zustand zu ändern.

visibleSkyHDR und hdrManifest sind veraltet und werden abgewiesen. Eine EXR-Datei außerhalb des USDZ darf weder die sichtbare Ansicht noch das Raumbeleuchtungsbild liefern. OpenEXR bleibt für Raumtexturen innerhalb des USDZ erlaubt und wird dort geprüft.

Raum: space.json

{
  "formatVersion": 2,
  "id": "space.example-room",
  "title": "Example Room",
  "scene": "scene.usdz",
  "thumbnail": "thumbnail.jpg",
  "caption": "A quiet house arranged around a sunlit courtyard.",
  "previewCamera": {
    "yawDegrees": -28,
    "pitchDegrees": -10,
    "zoom": 1.0
  },
  "seatedOrigin": {
    "translationMeters": [0, 0, 0],
    "orientationXYZW": [0, 0, 0, 1]
  },
  "safeHeadVolume": {
    "centerMeters": [0, 1.2, 0],
    "sizeMeters": [1.2, 0.6, 1.2]
  },
  "destinationOpenings": [
    {
      "id": "front",
      "transform": {
        "translationMeters": [0, 1.2, -2],
        "orientationXYZW": [0, 0, 0, 1]
      },
      "widthMeters": 4,
      "heightMeters": 2.5
    }
  ],
  "collision": {"mode": "embedded"},
  "teleportCatalog": {"path": "teleport-points.json", "houseID": "example-room"},
  "quality": {
    "status": "unverified",
    "triangleCount": 0,
    "materialCount": 0,
    "entityCount": 0,
    "maxTextureDimension": 0
  },
  "provenance": "provenance.json"
}

Das USDZ verwendet Meter, ein rechtshändiges Koordinatensystem und +Y nach oben. Es enthält nur unterstützte USD-, Textur- und Audiodaten für die Laufzeit. USDZ-Mitglieder müssen unkomprimiert gespeichert sein. Der Validator lädt die tatsächliche USD-Szene, löst ihre Ebenen auf und zählt Geometrie; kleine oder auf null gesetzte quality -Qualitätswerte können ein zu großes Modell nicht verbergen.

Erforderliche Teleport-JSON-Datei (das gewählte Haus muss mindestens einen Punkt enthalten):

{
  "houses": {
    "example-room": [
      {
        "id": "work-desk",
        "title": "Work desk",
        "anchorXZ": [0.5, 0.5],
        "sourceFloorOffset": 0,
        "eyeHeight": 1.15,
        "yawRadians": 0
      }
    ]
  }
}

anchorXZ besteht aus zwei endlichen normierten Werten im Bereich 0...1; sourceFloorOffset ist endlich und nicht negativ in den Maßeinheiten des erstellten Modells; eyeHeight ist positiv, endlich und in Metern angegeben; yawRadians ist eine endliche Modelldrehung um +Y im Weltkoordinatensystem. Punkt-IDs sind eindeutig und Titel nicht leer.

Experience: experience.json

{
  "formatVersion": 2,
  "id": "experience.example-combined",
  "title": "Example Room · Example View",
  "destinationID": "destination.example-view",
  "spaceID": "space.example-room",
  "supportedModes": ["virtual-space"],
  "composition": {
    "destinationOpeningID": "front",
    "destinationYawDegrees": 0,
    "destinationPitchDegrees": 0,
    "destinationExposureOffsetEV": 0
  },
  "compatibility": {
    "minimumViewerVersion": "1.0.0",
    "requiredCapabilities": ["world-tracking"]
  }
}

ZIPs mit nur einer Ansicht oder nur einem Raum installieren wiederverwendbare Inhalte und nehmen an den Standardkombinationen teil. Eine explizite Experience ist nur nötig, um für eine Kombination Öffnung, Ausrichtung, Belichtung, Titel, Modus oder Kompatibilität zu überschreiben. Referenzen können auf dasselbe Archiv oder auf integrierte bzw. bereits installierte stabile IDs zeigen. Nicht auflösbare Referenzen führen zur Ablehnung des gesamten Imports.

Optionale Funktionen und übersetzte Bezeichnungen

Ergänzen Sie optionale Felder im Manifest der zugehörigen Ansicht oder des Raums und legen Sie jede referenzierte Datei neben diesem Manifest ab. Die Feldreferenz beschreibt Medien und Masken, Ton und Raummusik, Mittelgrund und Wind, Wasser, Himmel, Wolken, Sonnenbahn, Himmelskörper, nahen Orbit, schwarze Löcher, Punktlichter, GPU-Begleittexturen, Sitze und Gruppen, Licht, Animationen, Videoflächen, Partikel und gebackene Lichtschichten. Sie definiert außerdem localizations, provenanceDetailsowie die folgenden Einstellungen des Raums: viewGroundFloorOffsetMeters, viewGroundKeepOutund viewMidgroundVisibility Einstellungen.

Diese optionalen Felder gehören beispielsweise in ein ansonsten vollständiges Raummanifest und erfordern im Paketrahmen minimumAppVersion: "1.4.4" oder neuer:

{
  "viewGroundFloorOffsetMeters": 0.2,
  "viewGroundKeepOut": false,
  "viewMidgroundVisibility": "terrainOnly"
}

Ihre Bedeutung bleibt für importierte, integrierte und Bibliotheksinhalte gleich. Funktionskennungen der Bibliothek in der Feldreferenz gehören zu Bibliotheksangeboten. Fügen Sie kein erfundenes Feld requiredCapabilities in locusplace.json. Der Import vollständiger Pakete prüft die Mindestversion der App und den typisierten Inhalt selbst.

Erforderliche Herkunftsangaben

Jede importierte Destination und jeder Space verweist auf ein JSON-Dokument mit Herkunftsangaben. Es nennt Autor oder Agentur, entweder eine Lizenz oder einen Vorbehalt aller Rechte, gewünschte Urheberangaben, Änderungen, die Nutzung von KI und gegebenenfalls den KI-Anbieter. URLs zur Quelle oder Originaldatei sind optional, müssen aber HTTPS verwenden und dürfen weder Zugangsdaten noch Fragment enthalten. Fehlende, zu große oder ungültige Herkunftsangaben führen zur Ablehnung des gesamten Imports. Siehe Herkunftsreferenz.

{
  "formatVersion": 1,
  "creatorOrAgency": "Your name or studio",
  "sourcePageURL": "https://example.com/project",
  "originalAssetURL": "https://example.com/original",
  "license": {
    "identifier": "YOUR-LICENSE-ID",
    "name": "Your license name",
    "url": "https://example.com/license"
  },
  "requestedCredit": "Credit line requested by the creator",
  "modificationNotes": "Converted and packaged for Locus.",
  "aiGenerated": false
}

Das Dokument darf höchstens 64 KiB groß sein. Übernehmen Sie nach einem Austausch der Dateien nicht die Herkunftsangaben einer Vorlage. Die Repository-Lizenz und die Lizenz Ihrer Inhalte sind getrennte Angaben.

Das ZIP dient zur Laufzeitauslieferung, nicht als Sicherung der Erstellungsdateien. Jede Nutzdatei muss über ein bekanntes Package-v2-Dateifeld erreichbar sein. Nicht referenzierte Dateien werden selbst dann zurückgewiesen, wenn sie in locusplace.json.files. .blend, .blend1, .blend2, .fbx, .obj, .mtl, .gltfund .glb werden auch dann abgewiesen, wenn sie deklariert sind. Bewahren Sie solche Quelldateien außerhalb des ZIPs auf. Ein Raum liefert das endgültige USDZ; eine paketierte Ansicht das endgültige 2:1-Panorama und optional ein kleines 2:1-JPEG/PNG für die Raumbeleuchtung.

Sicherheit und Ressourcenlimits

Die Prüfung untersucht Bytes, nicht Dateiendungen. Abgewiesen werden Pfadtraversierung, absolute oder nicht kanonische Pfade, Rückwärtsschrägstriche, Steuerzeichen, Kollisionen durch Groß-/Kleinschreibung oder Unicode, Symlinks, doppelte Einträge, verschlüsselte Daten, nicht deklarierte Dateien, falsche Hashes, nicht unterstützte Manifeste, fehlerhafte Bilder, ungültige EXR-Texturen in USDZ, fehlerhafte USDZ-Strukturen, komprimierte USDZ-Mitglieder und nicht unterstützte USDZ-Dateitypen. Raumlimits werden anhand der vom System tatsächlich geladenen USD-Szene geprüft; die selbst angegebenen Qualitätsmesswerte sind nur Erstellungsmetadaten und können diese Zählwerte nicht reduzieren.

Die Liste zulässiger Bildformate auf Byteebene ist verbindlich: importierte Panoramen und Rasterfelder sourceImage, thumbnailund imageBasedLight müssen JPEG oder PNG sein. USDZ-Texturen dürfen JPEG, PNG oder OpenEXR sein. Andere von ImageIO dekodierbare Formate werden nicht stillschweigend akzeptiert, sondern abgewiesen. Auch 3D-Erstellungsformate außerhalb des USDZ sind verboten. Ein USDZ darf ausschließlich USD/USDA/USDC, JPEG, PNG, OpenEXR, M4A, WAV und MP3 enthalten.

Dateien und URLs als Importquelle

Für Ansichten akzeptiert die Importseite ein JPG-, PNG- oder HEIC-Bild aus Fotos, Dateien oder einer direkten öffentlichen HTTPS-URL. Locus wandelt das Bild in ein Package-v2-Paket mit genau einer Destination um und prüft und installiert es über denselben Validator und die atomare Installation. Dateien und URLs akzeptieren auch vollständige Package-v2-ZIPs für Ansichten und Räume, einschließlich kombinierter Pakete mit dem vom Besucher gewählten Inhaltstyp. Bestehende flache ZIPs bleiben Kompatibilitätseingaben. Ein fehlerhaftes Archiv mit locusplace.json wird als ungültiges vollständiges Paket abgewiesen. Es gibt keinen Rückfall auf den flachen Parser. URL-Importe weisen Zugangsdaten, Fragmente, localhost, .localund DNS-Antworten mit nicht öffentlichen Adressen ab. Ein Hostname wird pro Anfrage einmal aufgelöst. Jede zurückgegebene Adresse muss öffentlich sein. Die TLS-Verbindung wird zu genau dieser numerischen IP-Adresse aufgebaut, während der ursprüngliche Hostname authentifiziert wird. Jede Weiterleitung wiederholt diese Auflösung und Adressbindung vor einer neuen Verbindung. Höchstens fünf Weiterleitungen sind erlaubt; deklarierte und tatsächlich heruntergeladene Datenmengen sind begrenzt.

Prüfung und Katalogauflösung erfolgen in einem nicht öffentlichen Zwischenverzeichnis auf demselben Volume. Eine bibliotheksweite beratende Sperre serialisiert Inventarprüfung, Kontingentprüfung und Übernahme. Erstinstallationen verwenden eine exklusive atomare Umbenennung; Updates einen atomaren Verzeichnistausch. Bei jedem Fehler wird das Zwischenverzeichnis entfernt und das installierte Paket bleibt unverändert.

Paketprüfung und Beispiele

Die folgenden Befehle verwalten den vollständigen Package-v2-Paketrahmen für Veröffentlichungen und vollständige Importe. Die älteren flachen Werkzeuge bleiben dokumentiert in der locus-asset-format.md.

Prüfen Sie beide Dateiendungen ohne Installation:

python3 tools/validate_locusplace.py --current-app-version 1.4.4 MyPlace.locusplace
python3 tools/validate_locusplace.py --current-app-version 1.4.4 MyPlace.zip
python3 tools/validate_locusplace.py --current-app-version 1.4.4 --json MyPlace.locusplace

Der Python-Code verwendet die Standardbibliothek sowie macOS ImageIO über /usr/bin/sipsund die USD-Werkzeuge usdchecker und usdcat (mit Xcode bzw. dessen Befehlszeilenwerkzeugen installiert). Nach der strukturellen JPEG- oder PNG-Prüfung dekodiert ImageIO alle Bildpixel. Die EXR-Prüfung betrifft ausschließlich Texturen innerhalb von USDZ-Dateien. Die USD-Werkzeuge laden die tatsächliche USD-Szene des Raums, lösen ihre Ebenen auf und vermessen sie. Bei einem Fehler endet das Programm mit einem Fehlercode. Es prüft Archiv, Integrität, Package v2, Herkunftsangaben, Bilder/EXR und USDZ. Für die Installation und die Auflösung von Referenzen zwischen Katalogen bleibt der visionOS-Importer maßgeblich.

Packen Sie einen bearbeitbaren Ordner in eine gewöhnliche ZIP-Datei. Dabei werden alle Integritätsdaten neu berechnet; die Datei wird nur erstellt, wenn der Validator sie akzeptiert:

python3 tools/pack_locusplace.py --current-app-version 1.4.4 MyEditablePlace MyPlace.zip

Erzeugen Sie echte Beispielarchive mit nur einer Ansicht, nur einem Raum sowie kombinierten Inhalten in einem temporären oder ignorierten Ordner und prüfen Sie sie:

python3 examples/locusplace/build_examples.py /tmp/locusplace-examples
for package in /tmp/locusplace-examples/*.locusplace; do
  python3 tools/validate_locusplace.py --current-app-version 1.4.4 "$package"
done

Die Beispiele werden aus Quellcode erzeugt, ohne private Dateien herunterzuladen oder kostenpflichtige Dienste aufzurufen. Generator und erwartete Struktur stehen in der Beispiel-README.