Bring your architecture into Locus.

Start with a working Room

Each download is a complete Room v5 ZIP, updated September 5, 2026. Import it with a compatible Locus build, or unpack it to study the materials and public metadata beside the finished USDZ.

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

The Locus-authored parts are reusable under CC BY 4.0; embedded Poly Haven textures remain CC0. See the credits and license details.

Choose the delivery contract

Complete Package v2 is the canonical feature-complete import format in Locus 1.2.1 and later. Its ZIP root directly contains locusplace.json and catalog/, and a Room lives under catalog/spaces/<space-id>/. Use it for stable IDs and in-place updates, sound, animations, video surfaces, seat groups, provenance, and supported bundled Experiences.

The current public Room builder, scaffolder, packer, validator, and downloadable Room examples still produce the legacy/simple flat compatibility format below. They do not author or validate complete Package v2. Each flat import receives a new UUID.

Legacy/simple delivery contract

Deliver one flat compatibility ZIP with exactly five root files:

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

• scene.usdz is self-contained, meter-scale, +Y up, and uses world -Z as forward.
• space.json describes the Room. It has a display name but no authored asset ID; Locus assigns a new UUID on every flat import.
• teleport-points.json declares at least one usable seat.
• provenance.json truthfully records creator, rights, credit, changes, and AI use.
• thumbnail.jpg is authored with the Room; Locus does not generate it during import.

Keep editable sources, textures, caches, and interchange files outside the ZIP. Every entity referenced by metadata must have one stable, unique name in the delivered USDZ.

Openings and seats

Every Room declares exactly one viewOpenings entry. It is a logical connection to the selected Locus View; it does not cut the USDZ. Model windows and other architectural openings in the source geometry. Coordinates use right-handed meters, +Y up, -Z forward, and quaternions in [x, y, z, w] order.

Each teleport point defines an eye position and facing direction. anchorXZ is normalized into the exported Room bounds; sourceFloorOffset identifies its level; eyeHeight is measured from that floor. Seat IDs are part of the Room interface, so keep them stable across revisions.

Optional spatial adaptation

spatialAdaptation connects semantic parts of your USDZ to Locus features:

A mapped desk entity should be the tabletop itself or a tightly bounded slab. Do not include chairs, lamps, legs, computers, or loose props beneath it; Locus uses the entity's bounds to derive surface height, footprint, and orientation.

Optional lighting interface

Lighting metadata tells Locus which exported emissive meshes and bounded runtime sources belong to each visitor-facing control. It does not prescribe how to model, shade, or bake the Room.

The shared indirect layer is scaled by 2^overallEV. Individual light switches, temperature, color, and brightness remain local controls and do not recolor that shared bounce. Keep glass, water, transmissive materials, fixture glow meshes, and recognizable fixture-specific halos out of the shared indirect receiver subtree; direct proxies own local pools of light.

Room v3 enforces a maximum of 12 authored proxies, 4 active proxies at any seat, 1 shadow-casting proxy, 10,000 lumens per proxy, and a brightness range within -4…+1 EV. These are safety limits, not target values.

Preserve your material design

Locus uses the supported PBR materials, textures, UVs, and transforms in your exported USDZ. Names such as glass, furniture size, and imported Room identity do not choose material presets. Correct material and export problems in the editable source, then rebuild the Room ZIP.

Room v5 adds explicit rendering.softenedReflectionEntities and rendering.uiFadeEntities. Use the first only when you want a View reflection with horizontal scene detail removed; it does not reflect the Room interior. Use the second to permit selected furniture to fade while blocking a visitor window. Omitted roles grant neither behavior.

Every v5 spotlight declares a unit direction in exported Room coordinates, such as [0.6, -0.8, 0]. Its anchor supplies position only. These fields require a v5-capable Locus build. Use the optional USD model audit to check exported references and supported shaders. Read the supported materials, defaults, and migration rules before exporting.

Experimental ambient animations

Room v4 can connect animation clips already embedded in the USDZ to named visitor controls. Each ambientAnimations entry identifies one entity and one animation, plus its initial switch, speed range, and replay interval range.

Visitors can turn all of a Room's experimental animations on or off with the Room motion tile in Quick Controls. In Settings → Motion → Room they can switch each animation, change its experimental speed and interval, then save those values for this Room on the current device. An interval of 0–0 repeats immediately; different minimum and maximum values select a fresh random pause after every completed play.

Build the smallest working Room

The minimal Room builder starts from an empty Blender scene and creates one desk, one calibrated seat, two walls, a roof, and one controlled pendant. It needs Blender 5.2 and Python 3 on macOS. Clone or download this repository so the builder can use the bundled metadata scaffolder; no external models, textures, or MCP connection are needed.

1. From the repository root, run the builder with an output path that does not already exist. It saves the editable Blender file, a self-contained USDZ, a thumbnail, and six seated review images.
2. Inspect every image in review/. Correct the source if scale, seat direction, clearance, or tabletop usability is wrong.
3. Run the public packer and validator, then import the exact ZIP through Places → Import → Import a Room → Files.
4. Select Minimal Reading Room in Places, pair it with a View, and enter Virtual Space. Try the Reading Desk seat, the Room lights tile in Quick Controls, and Light & Picture → Room. Real-table alignment and comfort require 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

Use your Blender executable's absolute path if blender is not on PATH. The builder and packer refuse to overwrite existing output. Keep the editable source and review images outside the five-file ZIP. The complete runtime interaction reference explains how seats, safety, collision bookkeeping, measured quality, desk mapping, and author permissions connect to the app.

Pack, validate, then import the compatibility ZIP

Keep the five source files in one directory and run the public flat-format tools on 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

1. Resolve every warning or error from the USDZ exporter and public validator.
2. In Locus, choose Import a Room and select the exact validated ZIP.
3. Pair the Room with a View and enter it on Apple Vision Pro.
4. Try every seat, optional desk mapping, rendering role, and light control you declared.
5. Correct the source and rebuild the ZIP; do not patch the final archive by hand.

Build with an AI assistant

Give the public sample skill and your brief to an AI coding agent that can run local scripts and inspect images. With Blender installed, the default route uses Python to create an original Room, set up materials, render review images, and export the model in the background. It can then connect seats and optional lights, scaffold the five delivery files for the compatibility format, and validate the exact flat ZIP. You can still use another professional 3D workflow if you prefer.

Headless authoring still includes visual review. Saved renders help the agent catch modeling and material problems; the final in-app check on Apple Vision Pro confirms how the Room looks and feels in Locus. If the agent cannot operate a suitable 3D tool or inspect images, it must explain which work remains incomplete.