Toastconcern--FrameStudio/docs/using-frame-home.md

Using Frame Home on the headset

Once Frame Home is installed (see install-frame-home.md), your home is the Steam Frame's environment. It shows when no game is running, behind the Steam menu, and while games load.

The Environments panel

Frame Home adds a panel called Environments to the Steam menu. It starts with SteamVR on its own.

1. Open the Steam menu.
2. Choose Environments in the menu's bar.
3. Point at the panel with a controller and click.

The panel has three pages: Environments, Settings and Debug. Its top right shows whether Frame Home is running, with a button:

The panel says	The button	What it does
Frame Home is running	Restart Frame Home	Reloads the home from its file
Frame Home isn't running	Start Frame Home	Starts it now
Off: it failed to start twice	Turn Frame Home On	Clears the off switch and starts it

Choosing an environment

The Environments page shows a card for every environment on the headset, with its name, its kind and a thumbnail. The one you are in says "Showing now".

• Click a card to switch to it. Frame Home changes the environment live; you don't need to restart anything.
• Delete a card with its delete button. The panel asks first ("Delete ...?"). Deleting removes the file from the headset, its thumbnail and its unpacked copy.

The kinds you may see:

Kind	Meaning
Frame environment	A .fenv file
Frame environment, footprint + vista	A .fenv holding a room and the view outside it
Meta home	A Meta Quest home .apk
Meta home, footprint only / vista only	Half of a Meta home pair
Footprint + Vista	Two .apk files listed as a pair (see below)

From a terminal

Over SSH (ssh frame) you can do the same with the panel's program:

~/frame-home/bin/frame-switcher --list          # the environments; the current one is marked with *
~/frame-home/bin/frame-switcher --set 3         # switch, by number from --list or by file name
~/frame-home/bin/frame-switcher --delete NAME   # delete one, like the panel's delete button
~/frame-home/bin/frame-switcher --check-update  # is there a newer Frame Home on GitHub?
~/frame-home/bin/frame-switcher --update        # download and install it now

Updates

The panel checks GitHub for a newer Frame Home a minute after it starts and every 6 hours after that. When there is one, Update Frame Home shows at the top of the panel, beside Restart Frame Home. Click it: the headset downloads the new version and installs it, and Frame Home and the panel restart a few seconds later with "Frame Home is updated". Your environments and settings stay as they are. If it can't finish, the panel says why; ~/frame-home/logs/update.log has the details.

Adding environments

Every environment lives in ~/frame-home/envs on the headset. Ways to put one there:

• From Frame Studio: Headset > Send to Frame (the open home), or Headset > Install on Steam Frame... (any .fenv files).
• With the stand-alone installer: drop .fenv files on Install Frame Home.bat, or list them after install-frame-home.sh. See install-frame-home.md.
• By hand: copy the file into ~/frame-home/envs, for example scp my-home.fenv frame:frame-home/envs/.

The panel notices new files by itself. Then, in the background:

• Each new .fenv is unpacked ahead of time. A big one takes about ten seconds. After that, switching to it is as quick as switching back to one you have used before.
• Thumbnails are made while nobody is looking at Frame Home, for example while a game is running. Making one loads and draws the whole home, which would make the home you are standing in stutter. So a new environment can show without a picture for a while.

Meta home .apk files work too, but they load more slowly than a .fenv. Studio or fenv-tool converts them (see environments-and-fenv.md). To show a room .apk and its vista .apk together, add a line with both file names to ~/frame-home/pairs.txt:

haven2025.apk calming.apk

Moving around

Frame Home moves you the way Meta's homes do. You start at the home's spawn point, its floor on your real floor.

Control	What it does
Left stick	Walk in the direction you push it, relative to where you look. A light push strolls. Walls stop you and you slide along them; ramps and steps are followed.
Right stick left / right	Turn: snap turns (30, 45 or 90 degrees) or smooth turning, as set in Settings
Right stick forward	Aim a teleport arc from your right hand. A marker shows where you'll land. Let go to go there.
Point at a seat, pull the trigger	Sit in it. Seats near you show a faint marker that lights up when you point at it.
Walk, teleport or step away while seated	Stand up again

More details:

• The teleport arc stops at the first thing it meets. A floor or a seat is a landing; a wall, a ceiling or the side of furniture is not, unless it is low, then you land at its foot.
• Landing near a teleport hotspot snaps you onto it.
• Seated, you can still turn, but you stay put.
• Falling is real. If you fall further than the home's limit, you are put back at the spawn point.
• Some homes have gravity zones (walls you can walk up, small planets).
• With the Steam menu open, the controllers belong to the menu. Nothing moves you until you close it.

Settings

The Settings page has three groups. Frame Studio shows the same settings under Edit > Preferences..., in the "Steam Frame (Frame Home)" part, so you can change them from your computer too.

Settings are stored in ~/frame-home/settings.json on the headset. Frame Home reads it again whenever it changes.

Movement (applies right away)

Setting	Choices	Default	What it does
Walking	Off, Smooth	Smooth	Left stick walks you smoothly. Off: teleport only.
Teleport	Off, Instant, Slide	Instant	Right stick forward, aim, let go. Instant blinks you there; Slide glides there.
Turning	Snap, Smooth	Snap	What the right stick does left and right
Snap turn angle	30°, 45°, 90°	30°	How far each snap turn goes
Walking speed	Slow, Normal, Fast	Normal	How fast smooth walking moves you (1.4, 2 and 3 m/s)
Comfort vignette	Off, Gentle, Strong	Off	Darkens the edges of view while the stick moves or turns you. Helps if smooth walking makes you queasy.
Seat markers	Shown, Hidden	Shown	Markers on the seats near you. Hidden, pointing at a seat still finds it.

Environment (applies right away)

Setting	Choices	Default	What it does
Volume	Off, 25%, 50%, 75%, 100%	100%	All of the environment's sound
Animations	Play, Hold still	Play	Hold still stops the environment's moving parts; animated environments then cost less.

Graphics

The group's heading shows how Frame Home is doing right now: the GPU time a frame takes out of the time it has, the size drawn per eye and its resolution, and whether eye tracking is used. For example: "6.1 of 8.3 ms a frame, ... per eye (140%), eye tracking on". If it starts with "Too slow, lower Resolution", frames are late and the home stutters.

Setting	Choices	Default	What it does
Resolution	Auto, 80%, 100%, 120%, 140%	Auto	Share of SteamVR's recommended size per eye. Auto moves between 70% and 150% to keep every frame on time, sharper whenever the home is light enough.
Frame rate	Full, Half	Full	Half draws the environment every other frame and turns it with your head in between, as Meta's home does: each frame gets twice the GPU time.
Anti-aliasing	Off, 2x, 4x	4x	Smooths jagged edges. 4x looks best; lower is faster.
Texture filtering	4x, 8x, 16x	8x	Keeps floors and walls sharp at an angle. Higher looks better.
Foveated rendering	Off, Fixed, Eye tracked	Eye tracked	Full detail where you look, coarser toward the edges. The time this frees goes to resolution (with Auto). Fixed keeps the sharp area at the lens centre; Eye tracked follows your gaze.
Foveation strength	Gentle, Medium, Strong	Medium	How quickly detail falls off away from where you look
Keep cool	Off, 80°, 86°, 90°	86°	Above this temperature (°C), the edges of view give up a little detail at a time until the headset cools. Where you look stays sharp. A hot headset slows its GPU.
Behind the Steam menu	Half rate, Full rate	Full rate	With the menu open, the environment is only a backdrop. Half rate leaves more GPU to the menu and its apps.

Anti-aliasing, texture filtering and turning foveation on or off restart Frame Home. That takes a few seconds. The others apply at once.

With eye-tracked foveation, the heading says "eye tracking waiting for your eyes" until the headset sees your gaze.

Per-environment settings. An environment can carry its own resolution, foveation strength, anti-aliasing and frame rate, tuned for that home. While you are in it, those win over the settings above. See environments-and-fenv.md and performance.md.

The Debug page

The Debug page is for finding out why a home looks or runs wrong. Its settings are not kept: they switch off when Frame Home restarts.

Item	What it does
View	Normal, Wireframe (every triangle edge), Meshes (each in its own colour), GPU cost (green is cheap, red is costly), Overdraw (bright where surfaces pile up)
World layer	Shows where you can walk (green), surfaces and colliders, spawns, seats and gravity zones
See-through surfaces	Leave out glass, water, glow and fog, to see whether they're what's slow
Cut-out surfaces	Leave out leaves, grass and fences
Sky	Leave out the sky
Costliest meshes	The meshes that cost the GPU most, with their time
This environment	The environment's report: problems found, if any (also in ~/frame-home/logs/report.txt)
Save a Picture	Saves what you see to ~/frame-home/logs
Turn Debug Views Off	Back to normal

The GPU cost view times every draw, which makes the GPU a little slower while it is on.

Studio can show and change the same page from your computer: Headset > Headset Debug....