From 73f879db6d95c7f5987141e506cc8a3e60a9b71d Mon Sep 17 00:00:00 2001 From: Toastconcern Date: Wed, 21 Oct 2026 12:26:54 -0500 Subject: [PATCH] Studio guide, License section in the README, Controls text for the Surface buttons Co-Authored-By: Claude Opus 5.5 --- README.md | 13 ++++ docs/README.md | 2 +- docs/studio-guide.md | 163 +++++++++++++++++++++++++++++++++++++++++-- studio/studio.cpp | 2 +- 4 files changed, 174 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index 268fbd2..082c99a 100644 --- a/README.md +++ b/README.md @@ -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. diff --git a/docs/README.md b/docs/README.md index ba984bd..df6907d 100644 --- a/docs/README.md +++ b/docs/README.md @@ -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 | diff --git a/docs/studio-guide.md b/docs/studio-guide.md index e616c5c..e05d932 100644 --- a/docs/studio-guide.md +++ b/docs/studio-guide.md @@ -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@
`. + 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 | diff --git a/studio/studio.cpp b/studio/studio.cpp index 8293be7..004235d 100644 --- a/studio/studio.cpp +++ b/studio/studio.cpp @@ -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)) {