Room guide · About 15 minutes
Add a TV to your Room.
Turn a flat screen in your Room model into a TV that visitors can look at, pinch to wake, and watch web pages on—either with the Room-building skill or in your own 3D tool.
Needs Locus 1.4.9 or later · Complete Package v2How 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.
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).- Every TV starts off. There is no author setting to start a TV on or load a default URL.
- Look and pinch to turn on. A visitor looks at the screen in Virtual Space and pinches to open the TV and its remote below the screen.
- Send pages from Locus Browser. Use Play on TV in a Browser window to play a page on a named TV, and Open in Window to bring it back.
- Virtual Space only. Room TVs are part of the 3D Room model and are not shown in Room Portal.
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.
- Clone the public repository and open it in an agent session that can run Blender and Xcode’s command-line tools.
- 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.
- Let the agent build, check, and package the Room as a complete
.locusplacearchive.
Build 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.
Add 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.locusplaceOption 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:
- One flat 16:9 quad. Model the screen as its own named object holding a single four-vertex, two-triangle flat plane at least 0.3 m tall.
- Clean 0–1 UVs. Map
ufrom left to right when seated in front of the screen andvfrom bottom to top, with normals facing the viewer. - Keep it separate from other bindings. Do not nest the screen inside an entity named in
lighting,ambientAnimations,videoSurfaces,spatialAdaptation, or another TV. - Avoid coplanar overlap. Place the screen quad a few millimetres in front of its bezel, backing plate, or wall so there is no z-fighting.
- Author the off-state material. Use dark glass or an artwork image on a non-emissive
UsdPreviewSurface(zero emission, so it looks off when you arrive). - Leave room for the remote and a seat. Place at least one teleport seat in front of the TV (within roughly 45° of the screen’s normal) and keep shelves or tall props out of the space just under the screen.
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": "玻璃房电视"
}
}
}
}| Field | Rule |
|---|---|
id | Required, unique in tvs, 1–64 bytes of lowercase letters, digits, and hyphens ([a-z0-9-]). |
displayName | Required, non-blank, at most 200 UTF-8 bytes. Shown in the Play on TV menu. |
entityName | Required, unique across tvs, non-blank, at most 200 UTF-8 bytes. Must match the exact mesh-bearing object in scene.usdz. |
localizations. | Optional 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.locusplacetools/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.
- Transfer the packed
.locusplaceto iCloud Drive or AirDrop it to Apple Vision Pro. - Import via Places → Import → Import a Room → Files, then open it in Virtual Space.
- 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
- Maximum 4 TVs per Room. Each TV needs a distinct
idand a distinctentityName. - No audio or video asset files are needed. Unlike
videoSurfaces(which loop a packaged.mp4), TVs stream live web content and have noluminaireGroupID. - Size against the viewing distance. At a 2.5–3 m sofa distance, a 65–75 inch diagonal screen feels natural without crowding the room’s proportions.