Toastconcern--FrameStudio/docs/studio-guide.md

Frame Studio guide

Frame Studio opens a home, shows it the way the Steam Frame draws it, and lets you change it: move, hide or delete its objects, decide where you can walk, add spawn points, seats and sounds, and save it as a .fenv environment for the headset. This guide walks through the window and the everyday tasks. To install Studio, see getting-started.md.

The window

┌───────────────────────────────────────────────────────────────────────────┐
│ File  Edit  View  World  Bundle  Headset  Debug  Help         menu bar     │
├────┬──────────────┬──────────────────────────────┬────────────────────────┤
│ ✥  │ EXPLORER     │                              │ Selected World Env… … │
│ ⟳  │ Filter…      │                              │ ───────────────────── │
│ ⤢  │ ▾ Root       │          3D VIEW             │      INSPECTOR         │
│ ✎  │   ▾ folder   │                              │  (the chosen tab's     │
│ ── │     object   │                              │   settings)            │
│ ◍  │ ▾ World      │                              │                        │
│ ☺  │   Spawns …   │                              │                        │
│ ⌗  │              │                              │                        │
├────┴──────────────┴──────────────────────────────┴────────────────────────┤
│ ❚❚ Pause  ───────────●─────────────────  12.0 / 60.0 s          Sound on   │
│ Home name · format · selection · fps                      Frame: sent …    │
└───────────────────────────────────────────────────────────────────────────┘

Part	Where	What it's for
Tool strip	left edge	the transform tools, Draw Floor, and how the gizmo and the camera behave
Explorer	left	everything in the home: its objects (in the file's own folders, or grouped by kind) and its world items
3D view	middle	the home as the headset draws it, with the gizmo and the walkable area on top
Inspector	right	settings, in tabs: Selected, World, Environment, Bundle, Headset
Timeline	bottom	plays the home's animations and sound; drag to scrub through the loop
Status bar	very bottom	the home's name and format, what's selected, the frame rate, and whether the headset has it

Drag the thin lines between the Explorer, the 3D view and the Inspector to make any of them wider.

Opening a home

• File > Open Home... (Ctrl+O), or drop a file on the window. It opens:
  • a Meta home (.apk). A footprint (the room) and its vista (the world outside) are opened together: pick both in the file dialog, or open the footprint and Studio offers the vistas beside it;
  • a Frame environment (.fenv);
  • models from Blender or Unity (.glb, .gltf, .fbx, .obj).
• File > My Environments lists what you have saved; File > Open Recent lists what you had open.
• File > Add Vista... gives a footprint its vista; File > Add Models... places models into the home.
• A big home asks after a while whether to keep waiting; Stop Loading cancels.

Moving around in the 3D view

Do this	With
Orbit	middle-drag, or Alt + left-drag
Pan	Shift + middle-drag
Zoom	mouse wheel, or Ctrl + middle-drag
Fly	hold the right mouse button + W A S D, Q / E down / up (wheel: speed, Shift: 4x)
Look from where you'd stand	Player view in the tool strip, P, or Numpad 0
Frame the selection / everything	F / Home (or double-click a row in the Explorer)

Press F1 (Help > Controls) for the full list.

Selecting and editing objects

1. Click an object in the 3D view or the Explorer. The Inspector switches to Selected.
2. Pick a tool in the tool strip (or press its key) and drag the gizmo:
   • Move (G), Rotate (R), Scale (S). Hold Ctrl to snap.
   • The globe / cube button switches the gizmo between the world's axes and the object's own.
3. Or type exact values in Location, Rotation and Scale in the Selected tab.
4. In the same tab: Visible, Reset (back to where the home had it), Only This (hide everything else, I), and Delete (X).

The Explorer's eye buttons hide objects or whole folders. Edit > Unhide All (Alt+H) brings them back. Every change can be undone with Ctrl+Z and redone with Ctrl+Shift+Z.

Where you can walk

Frame Home works out where you can walk from the home's shapes: floors you can reach from the start, under enough headroom, and nothing in the way. The 3D view shows it: green is walkable, blue are small gaps it bridges, orange are edges, grey are floors you can't reach. W shows or hides it.

• The World tab shows the area's size and its settings (step height, headroom, body radius). The presets Open, Standard and Careful set them for you.
• World > Auto-generate Walkable Surfaces gives every mesh a surface: walkable where it's flat, blocking where it's steep. A summary shows what it did; Undo in it takes back just that run.
• Per object, the Surface buttons in the Selected tab decide what it is for the player: Auto (decided by its shape), Surface (walk on its flat parts, bump into its steep ones), Collider (you can't walk through it), Walk through (ignored). Right-clicking an object offers the same.
• Draw Floor (B, or the brush in the tool strip): select an object, then drag over it to paint walkable floor onto it, even on furniture. Shift+drag erases; [ and ] change the brush size. Fill Flat Faces paints every face of it that's flat enough at once.

World items

World > Add at the View's Centre places items where the camera looks:

Item	What it does on the headset
Spawn Point	where you start, facing the way it faces
Seat	a place to sit: point at it and pull the trigger; its "stand up here" ring is where you get up
Teleport Hotspot	a spot the teleport arc snaps to
Surface	a box you can scale into a floor, a step or a wall
Wall Spot	where SteamVR's panels dock
Invisible Wall	stops you; never drawn on the headset. Scale and turn it to fit; where it stands is no longer walkable
Gravity Zone	inside it, "down" is the zone's own: a direction, or any surface you stand on

Select an item to move it with the gizmo or type its values in the Selected tab. World > Clear World Layer removes them all.

Meta's own homes have invisible walls too, round their play space (Cascadia, Space Station, Desert Terrace, Haven). Frame Studio and Frame Home read them as invisible walls, so you can't walk out past them. Select one in the Explorer to delete it, or set its Role to Surface, if you want to go further in that home.

The environment: name, picture, sound

The Environment tab, top to bottom:

• Environment: the name it shows on the headset, its picture (Choose..., or a view taken when you save), and what it's made of.
• Sound: the home's own ambience and a background sound of your own (MP3, Ogg, Opus, WAV or FLAC), with their volumes. Drop a sound file on the window to add it. Save Its Sound... keeps the home's ambience as an Ogg file.
• World settings: its own headset settings: resolution, foveation, MSAA and frame rate. Calculate Best Settings walks it on the headset and keeps the sharpest settings that hold 120 fps.

Saving

Command	Does
File > Save (Ctrl+S)	saves into My Environments (Documents/Frame Studio/Environments); a saved .fenv saves into itself
File > Save As... (Ctrl+Shift+S)	saves a copy anywhere; Save goes there from then on
File > Auto-saved Versions	every 5 minutes with unsaved changes, a version is kept (the last 10)
File > Faster Saving	packs on all CPU cores: about 3x quicker, about 1% bigger
File > Leave Out What Can't Be Seen	drops geometry nobody can see from anywhere they can stand, so the headset draws less
File > Revert to Original	the home as it shipped, without your changes

Saved environments are baked: everything the headset needs, already in its own format. See environments-and-fenv.md.

Bundles

A bundle (.fbundle) packs several saved environments into one file, to share or install together. Use the Bundle menu or the Bundle tab: New Bundle, add environments (the open one, from My Environments, or any .fenv), Save Bundle..., and Install on Steam Frame.... Opening a .fbundle lists what's in it; double-click one to open it, or Unpack into My Environments. See bundles.md.

Sending it to the headset

The Headset tab (or the Headset menu):

• Send to Frame makes the open environment the headset's current one, saved or not.
• Install Frame Home puts Frame Home itself on the headset, with the environments and bundles you list under Environments to install. Restore SteamVR's Environment takes it off again.
• The Headset field is the headset's address: an SSH alias such as frame, or steamos@<address>. See headset-setup.md and install-frame-home.md.

Settings and tools

• Edit > Settings...: Studio's own (3D view resolution, anti-aliasing, texture size and filtering) and the headset's (read from and written to the Frame).
• Debug: views that show how the home is built and what it costs (Wireframe, Meshes, GPU Cost, Overdraw), Leave Out to hide whole kinds of objects, Home Report... (what the home is made of and what may be slow) and Headset Debug... (the same views on the headset).
• View: Show Only Selected (I), The Home's Meshes, World Layer (W) and Show Everything.

Keyboard shortcuts

Key	Does	Key	Does
Ctrl+O	open	Ctrl+S	save
Ctrl+Shift+S	save as	Ctrl+Z / Ctrl+Shift+Z	undo / redo
G / R / S	move / rotate / scale	B	draw floor
H / Alt+H	hide / unhide all	X, Delete	delete
F / Home	frame selected / all	P, Numpad 0	player view
I	show only selected	W	world layer
Esc	deselect	F1	controls