Studio guide, License section in the README, Controls text for the Surface buttons

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-29 00:02:23 +01:00 · 2026-10-21 12:26:54 -05:00
1 parent 5b449908e4
commit 73f879db6d
@@ -98,3 +98,16 @@ and the CI: [docs/building.md](docs/building.md).
 | `tools/`, `tests_loco/` | Test and measuring tools, movement tests |
 | `third_party/` | Vendored libraries (each with its own license) |
 | `docs/` | The guides |
+
+## License
+
+Frame Studio and Frame Home are licensed under the **GNU Affero General Public License v3.0**: see [LICENSE](LICENSE).
+You may use, study, change and share them; if you share a changed version, or run one for others over a network,
+its source must be available under the same license.
+
+Vendored libraries in `third_party/` keep their own licenses (in each folder). The home loaders in `third_party/qhe`
+started from Quest Home Editor and keep its MIT license for the original code; see
+[third_party/qhe/LICENSE.md](third_party/qhe/LICENSE.md).
+
+Neither license covers Meta's homes or other assets: Frame Studio only works with files you already have, and no
+Meta content is included in this repository or its downloads.
@@ -8,7 +8,7 @@
 | [Using Frame Home](using-frame-home.md) | The Environments panel, adding environments, moving around, every setting |
 | [Environments and .fenv](environments-and-fenv.md) | The `.fenv` format, converting homes with `fenv-tool`, per-world settings and tuning |
 | [Performance](performance.md) | How Frame Home reaches 120 fps, checking it, fixing stutter, Studio's own pacing |
-| [Frame Studio guide](studio-guide.md) | The Studio window, tools and panels (being written) |
+| [Frame Studio guide](studio-guide.md) | The Studio window, tools and panels |
 | [Bundles](bundles.md) | Several environments in one `.fbundle` file (being written) |
 | [Building from source](building.md) | Building on each system, the CI, the headset side, the repository layout |
 | [Troubleshooting](troubleshooting.md) | Symptoms and fixes, logs, the self-test |
@@ -1,6 +1,161 @@
 # Frame Studio guide

-This guide is being written. It will walk through Frame Studio's window: the editor layout with its docked panels,
-the tools for moving, hiding and deleting objects, shaping the walkable area, adding seats, sounds and a picture, and
-the world settings. Until it is ready, [getting-started.md](getting-started.md) covers a first walkthrough by menu
-name, and **Help > Controls** (F1) in Studio lists every shortcut.
+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](getting-started.md).
+
+## The window
+
+```
+┌───────────────────────────────────────────────────────────────────────────┐
+│ File  Edit  View  World  Headset  Debug  Help                 menu bar     │
+├────┬──────────────┬──────────────────────────────┬────────────────────────┤
+│ ✥  │ EXPLORER     │                              │ Selected World Envir… │
+│ ⟳  │ 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**, **Sound**, **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 |
+| **Gravity Zone** | inside it, "down" is the zone's own: a direction, any surface you stand on, or a planet's pull |
+| **Planet** | a sphere you can walk all the way round |
+
+Select an item to move it with the gizmo or type its values in the Selected tab. **World > Clear World Layer**
+removes them all.
+
+## The environment: name, picture, sound
+
+- **Environment** tab: the name it shows on the headset, its picture (**Choose...**, or a view taken when you
+  save), what it's made of, and 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.
+- **Sound** tab: the home's own ambience and a background sound of your own (MP3, Ogg, Opus, WAV or FLAC). Drop a
+  sound file on the window to add it. **Save Its Sound...** keeps the home's ambience as an Ogg file.
+
+## 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](environments-and-fenv.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 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](headset-setup.md) and [install-frame-home.md](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 |
@@ -6587,7 +6587,7 @@ struct Studio {
            {"Hide / unhide all", "H / Alt + H"}, {"Delete", "X or Delete"}, {"Undo / redo", "Ctrl + Z / Ctrl + Shift + Z"},
            {"Open / save edits", "Ctrl + O / Ctrl + S"}, {"Show only selected", "I (I or Esc shows everything)"},
            {"Show / hide world layer", "W (each kind: View \u203a Show, or the eyes in the explorer)"},
-            {"Floor / wall from a mesh", "Object panel \u203a Surface, or right-click it"},
+            {"Floor / wall from a mesh", "Inspector \u203a Selected \u203a Surface, or right-click it"},
            {"Every mesh walkable where flat, blocking where steep", "World \u203a Auto-generate Walkable Surfaces"},
            {"Deselect", "Esc"}};
        if (ImGui::BeginTable("keys", 2, ImGuiTableFlags_RowBg | ImGuiTableFlags_SizingFixedFit)) {