How Room TVs work

A Room can declare up to four TVs in complete Package v2 (the legacy flat Room ZIP format cannot carry tvs). Each TV turns one flat 16:9 screen quad in scene.usdz into an interactive surface in Virtual Space.

Worked Gallery example: Hilltop Villa. See Hilltop Villa in the Gallery (and its upcoming 1.0.17 Package v2 archive plus Blender source listed on that page for Locus 1.5.0). It pairs two contrasting TVs in one Room: a 98-inch living-room fireplace painting art TV (living-tv / TV_Screen_Living) and a 65-inch dark-glass Sky Room TV upstairs (sky-room-tv / TV_Screen_Sky_Room).
Two ways to use a TV. Give the screen dark glass for a classic wall or console TV, or map a painting texture onto the quad for an art TV that blends into the room until you turn it on.

Option 1 · AI workflow

Ask your AI agent with the Room skill

If you build Rooms with Make your own Room and the public Room-building skill (build-original-locus-room), the skill already includes the screen geometry, seat alignment, and validation steps for TVs.

  1. Clone the public repository and open it in an agent session that can run Blender and Xcode’s command-line tools.
  2. Name the TV’s size, room placement, and viewing seat. Tell the agent whether you want a wall screen, a console TV, or a fireplace art TV, and keep the space under the screen clear for the remote.
  3. Let the agent build, check, and package the Room as a complete .locusplace archive.
Prompt for your agentBuild a cosy media room with the build-original-locus-room skill: a deep sofa facing a 75-inch TV on the opposite wall about three metres away, a low walnut console under the TV, warm wall lamps, and a large window to one side.
Prompt for your agentAdd a 65-inch art TV above the fireplace facing the main seating area, showing an oil painting when it is off, and keep the mantle below clear for the remote.

To inspect a working reference before making your own, run the Example Media Room generator:

python3 examples/media-room/build_media_room.py /tmp/media-room
python3 tools/check_room.py --current-app-version 1.4.9 \
  --renders /tmp/media-room-renders /tmp/media-room/media-room.locusplace

Option 2 · Manual 3D

Model the screen quad in your 3D scene

In Blender or any USDZ pipeline, each TV screen is a separate, clearly named mesh object:

Package v2

Declare tvs in space.json

Set "minimumAppVersion": "1.4.9" (or later) in locusplace.json, then add a top-level tvs array to space.json with 1 to 4 entries:

{
  "tvs": [
    {
      "id": "living-tv",
      "displayName": "Living Room TV",
      "entityName": "TV_Screen_Living"
    },
    {
      "id": "sky-room-tv",
      "displayName": "Sky Room TV",
      "entityName": "TV_Screen_Sky_Room"
    }
  ],
  "localizations": {
    "zh-Hans": {
      "tvTitles": {
        "living-tv": "客厅电视",
        "sky-room-tv": "玻璃房电视"
      }
    }
  }
}
FieldRule
idRequired, unique in tvs, 1–64 bytes of lowercase letters, digits, and hyphens ([a-z0-9-]).
displayNameRequired, non-blank, at most 200 UTF-8 bytes. Shown in the Play on TV menu.
entityNameRequired, unique across tvs, non-blank, at most 200 UTF-8 bytes. Must match the exact mesh-bearing object in scene.usdz.
localizations.<lang>.tvTitlesOptional translations keyed by each TV’s id.

Verify

Pack, check, and test on Apple Vision Pro

Pack your complete Package v2 directory and run both the package validator and the macOS Room checker with --current-app-version 1.4.9 (or later):

python3 tools/pack_locusplace.py --current-app-version 1.4.9 \
  /absolute/path/to/MyRoomDir /absolute/path/to/MyRoom.locusplace

python3 tools/check_room.py --current-app-version 1.4.9 \
  --renders /absolute/path/to/my-room-renders \
  /absolute/path/to/MyRoom.locusplace

tools/check_room.py verifies that every screen is one flat two-triangle quad, is not nested inside another bound entity, has 16:9 proportions, non-emissive off-state materials, clean UVs, and a nearby facing seat. Fix any errors or warnings in the 3D source before importing.

  1. Transfer the packed .locusplace to iCloud Drive or AirDrop it to Apple Vision Pro.
  2. Import via Places → Import → Import a Room → Files, then open it in Virtual Space.
  3. Sit in every TV-facing seat. Look at the screen, pinch to turn it on, test Play on TV from Locus Browser and Open in Window, and verify remote reach and viewing comfort.

Design tips and limits