Room and View ZIP reference

Locus 1.2.1 and later. Import complete Package v2 from Files or a direct public HTTPS URL through either the View or Room entrypoint. Locus accepts the same ZIP bytes with a .zip or .locusplace filename.

Complete Package v2

complete-place.zip
├── locusplace.json
└── catalog/
    ├── destinations/<destination-id>/destination.json
    ├── spaces/<space-id>/space.json
    └── experiences/<experience-id>/experience.json   # optional

Keep locusplace.json and catalog/ directly at the ZIP root, with no outer wrapper folder. The nested catalog/destinations/, catalog/spaces/, and optional catalog/experiences/ paths are required structure. A View import must include a requested View; a Room import must include a requested Room. Supported Experiences may be bundled with that content.

The envelope preserves stable content IDs and declares packageID, contentVersion, minimumAppVersion, the content inventory, every file's byte count and SHA-256, and contentHash. Reimporting unchanged content is idempotent; changed content under the same package ID needs a newer content version and the same declared content IDs.

Supported complete packages preserve View media and masks, sourceImage, View-owned USDZ midground scenery and renderer-owned water (including wind-swayed props and shallow-water surf), View and Room sound, Room animations, video surfaces, illuminated surfaces, particle effects, baked light layers, seat groups, provenance, and supported Experiences. Locus verifies safe paths, the exact file inventory, hashes, resource limits, required capabilities, and minimum app version. A malformed archive containing locusplace.json is rejected and never falls back to the flat compatibility importer.

One pure-data contract. In the same Locus binary, supported Room and View data has the same rendering meaning whether it is bundled, downloaded from the Library, or installed from a complete public ZIP. Packages may contain typed media and USD/USDZ assets, but never scripts, plugins, dynamic libraries, or executable extensions. Future content capabilities join this common contract instead of a separate public-import allowlist. Read the boundary and extension rule.

Reference and compatibility tools

Complete and compatibility format referencePackage v2 structure, identity and updates, 1.3.0 water, sky, celestial and orbital authoring, 1.4 black holes, rings and surface data, legacy/simple layouts, limits, and checks.Celestial v2 schemaMachine-readable celestial body geometry, cloud-shell, and sun-disc fields from 1.3.0, plus 1.4 gas-giant flow, oblate bodies and rings.Near-orbit v2 schemaMachine-readable orbital View fields, including optional surface tiles. The format reference links both profile versions.Black hole v1 schemaMachine-readable black hole View fields for Locus 1.4. The black hole tutorial bakes and validates a complete View.Flat compatibility validatorChecks a legacy/simple Room or View ZIP; it does not validate complete Package v2.Flat compatibility packerCreates a deterministic legacy/simple ZIP and validates it.Provenance schemaCreator, rights, credit, changes, and AI disclosure.

Legacy/simple Room files

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

This flat compatibility format receives a new UUID on every import. Every file is required. A Room must contain at least one usable entry seat. The thumbnail is supplied by the author; Locus does not capture one during import.

Legacy/simple View files

view.zip
├── view.json
├── provenance.json
├── panorama.jpg
├── thumbnail.jpg
└── lighting.jpg       # optional

view.json can set direction, visible brightness, Room-lighting intensity, horizon pitch, contrast, saturation, and optional sunlight. The panorama is a complete 2:1 equirectangular image.

Complete Room examples

All three downloads use Room v5, with explicit rendering roles and spotlight directions. Updated September 5, 2026.

Requires Room v5 support. Early Locus 1.1.0 builds (1–3) do not support these ZIPs. Room v5 is supported from Locus 1.1.0 build 4, including Locus 1.1.1. Check your build in Settings → Help & About → About Locus.

Not the in-app 1.1.5 or 1.2.0 Rooms. App Store built-ins and Library revisions for Locus 1.1.5 add sofa and lounge seats plus hideable desk groups; Locus 1.2.0 further groups related seats in the Seats picker with authored seat groups. These downloadable ZIPs stay on the September 5 desk-seat packages so authors can study the base Room v5 contract, without lounge seats, Hide Desk, or seat groups. For lounge seats and Hide Desk, see the format reference; for seat groups, see the seat groups reference.

Atrium Loft2 desk seats · 10.1 MB.Courtyard Gallery3 desk seats · 10.7 MB.Horizon Atelier3 desk seats · 12.9 MB.

Using an older build? Download a previous compatible version: Atrium Loft, Courtyard Gallery, Horizon Atelier.

Experimental Room animation sample

Cloud Fan Pavilion is a free Room you can download in Locus Places that demonstrates experimental animation metadata and playback. Its continuous Plant Breeze, animation switch, speed control, and replay interval behavior may change.

Try Cloud Fan PavilionInstructions, rights notices, and the 22.2 MB download.

Find it free in LocusOpen Places, choose Rooms, and download Cloud Fan Pavilion.

Room integration guide

The Room integration guide explains the USDZ, entity, seat, desk, safety, material, optional lighting, and experimental animation contracts without prescribing a modeling workflow. Import and enter the exact result before sharing it.

Source and licensing

Publishing these documentation, sample skill, and validation tools does not publish the private Locus app source or change the app's license. Locus-authored example assets use the terms described on the asset rights page.