Custom Views and Rooms

Formats supported in this version

Import action	Accepted input	Where it can come from
Import a View	One complete 2:1 equirectangular `.jpg`/`.jpeg`, `.png`, or `.heic` image	Photos, Files, or a direct public HTTPS image URL
Import a Room	One `.locusplace` or ordinary `.zip` archive containing at least one Room	Files or a direct public HTTPS archive URL

A Room archive may be Room-only, or it may also carry the View and Experience that pair with that Room. Use the Import a Room action for either form.

Try a complete Room

Download the Locus-authored Demo Room, save it to Files, then choose Import a Room in Locus. The Room has two work seats and two desks, and it can be paired with any compatible View in your library.

Download Demo RoomImport-ready Room-only package · 7.7 MB ZIP.

Room archive layout

my-room.locusplace
├── locusplace.json
└── catalog/
    ├── spaces/<room-id>/              # required
    │   ├── space.json
    │   ├── provenance.json
    │   └── scene.usdz
    ├── destinations/<view-id>/        # optional paired View
    │   ├── destination.json
    │   ├── provenance.json
    │   └── panorama.jpg
    └── experiences/<experience-id>/   # optional pairing
        └── experience.json

The `.zip` and `.locusplace` filename extensions use the same bytes and rules. At least one ID in contents.spaceIDs is required by the current Room import action. The archive must not contain an extra parent folder, symlinks, undeclared files, authoring sources such as `.blend`, or paths outside the declared packages.

Required envelope metadata

Field	What it means
`formatVersion`	The archive contract version. V1 is `1`.
`packageID`	A stable ID for this install/update stream.
`contentVersion`	Three-part version increased when bytes change under the same IDs.
`minimumAppVersion`	The oldest Locus version allowed to import the archive.
`contents`	The View, Room, and Experience IDs owned by the archive.
`files`	A generated inventory containing path, byte count, and SHA-256 for every payload file.
`contentHash`	The SHA-256 identity of the canonical payload inventory.

Provenance is part of the package

Every imported View and Room needs a provenance.json document. It records who made the asset and what can truthfully be said about it.

Field	Examples
Creator and source	`creatorOrAgency`, `sourcePageURL`
Rights	`license.identifier`, `license.name`, `license.url`, `requestedCredit`
Changes and AI	`modificationNotes`, `aiGenerated`, and `aiProvider` when AI was used
Package identity	Stable content IDs and `contentVersion` in the package manifests and archive envelope

Do not invent an author or license. Unknown or incomplete mandatory provenance fails validation. Public-domain or CC0 material should still preserve its known creator or agency and source.

Create and validate a Room package

Generate the reproducible Room examples.
Unzip room-only.locusplace or combined.locusplace into a normal directory and replace the USDZ and any paired panorama.
Edit the Package-v2 manifests and complete provenance.json truthfully.
Run the packer to regenerate file sizes and hashes.
Run the validator before importing the finished archive through Import a Room.

python3 examples/build_examples.py /tmp/locusplace-examples
python3 tools/pack_locusplace.py MyEditablePlace MyPlace.zip
python3 tools/validate_locusplace.py MyPlace.zip

Download the validatorStandard-library Python; image decoding uses macOS ImageIO, and Room validation needs Xcode USD tools.Download the packerCalculates integrity fields, refuses overwrite, and publishes only after validation.Archive JSON SchemaMachine-readable envelope fields and limits.Provenance JSON SchemaMachine-readable source, rights, credit, and modification fields.

Asset guidance

Direct View import

Use one complete JPEG, PNG, or HEIC panorama with a strict 2:1 equirectangular projection. A recommended size is 12,288 × 6,144. Forward is panorama u = 0.5, world −Z; the seam is yaw ±180°.

Room package

Use a self-contained, meter-scale USDZ with +Y up. Declare a seated origin, a safe head volume, destination openings, collision behavior, and measured quality metadata. Keep `.blend`, GLB, source textures, and other authoring assets outside the runtime ZIP.

Optional paired View and Experience

A Room archive may include a JPEG or PNG View and an Experience that references stable View and Room IDs and declares its supported mode. Import the finished archive through Import a Room.

Complete technical reference

Read the public archive and Package-v2 field reference for validation limits, lighting-EXR constraints, USDZ rules, examples, and security behavior.