mirror of
https://github.com/Toastconcern/FrameStudio.git
synced 2026-10-28 23:03:21 +01:00
ToastconcernandClaude Opus 5.5
6d0b4fcd2f
Frame Studio - Gaussian splats (PLY, SPZ v2-v4), PLY vertex colours, panorama skies - Copy, cut, paste and duplicate for objects, splats and world items - Walkable-area rebake moved off the UI thread; viewport one frame sooner; refresh-locked pacing (FS_PACE=timer for the old one) - Fixed: bundle thumbnail use-after-free crash, auto-save deleting environments, saves into scratch copies, edits lost on non-ASCII paths, unopenable manifests with inf/nan, bundle save data loss, opening a home marking it changed, gizmo NaN, long paths, many malformed-file crashes - Updater verifies sha256, journals the swap and never leaves the exe missing Frame Home - Seats turn you to face their way - Draw batching (Hand Tutorials up to ~20% less GPU time), cut-out EQUAL pass, late head-pose read before submit - Proper queue-family hand-over to the compositor layer; layer descriptor generations and seqlocked slots; structural SPIR-V check - Fixed: hangs/crashes on damaged .fenv files and shaders, render-pass validation error, sync hazard in the foveation smoothing pass, unverified update downloads, half-done installs Tests: tests_loco/env_share/spv_check wired into CMake (FRAME_TESTS) and CI. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01VsaXGU27gsrXjDoFtyFJP9
207 lines
14 KiB
Markdown
207 lines
14 KiB
Markdown
# 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](getting-started.md).
|
||
|
||
## The window
|
||
|
||
Frame Studio is laid out the way Blender works: the window is split into **areas**, each showing one editor, with
|
||
a header along its top.
|
||
|
||
```
|
||
┌────────────────────────────────────────────────────────────────────────────┐
|
||
│ ◎ File Edit Headset Window Help │ Layout Walking Headset │ home name │ top bar
|
||
├──────────────────────────────────────────────────────┬─────────────────────┤
|
||
│ ▣▾ Arrange▾ View Select Add Object Global▾ ◈ ◯◯◯▾ │ ☰▾ As in the File▾ 🔍 │
|
||
│ ┌──┐ ● home › selection (axes) │ ▾ Root │
|
||
│ │✥ │ 🔍 │ ▾ folder 👁 │
|
||
│ │⟳ │ 3D VIEWPORT ✋ │ object 👁 │ Outliner
|
||
│ │⤢ │ 👤 ├─────────────────────┤
|
||
│ │✎ │ ⤢ │ 🔧▾ Object │
|
||
│ └──┘ │ ■ │ ▾ Object │
|
||
│ (toolbar: T) (sidebar: N) ▸ │ 👣│ Location … │ Properties
|
||
├──────────────────────────────────────────────────────┤ ▣ │ ▾ Surface │
|
||
│ 🕐▾ Playback▾ ⏮ ▶ ⏭ 12.0 / 60.0 s 🔊 │ ▤ │ … │
|
||
│ 0 5 10 ▮12.0 15 20 25 30 … │ ⌂ │ │ Timeline
|
||
├──────────────────────────────────────────────────────┴─────────────────────┤
|
||
│ 🖱 Select 🖱 Rotate View 🖱 Context Menu / Fly 182 objects | 60 fps │ status bar
|
||
└────────────────────────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
| Area | What it's for |
|
||
|---|---|
|
||
| **3D Viewport** | the home as the headset draws it. Its header has the mode (Arrange or Draw Floor), the **View**, **Select**, **Add** and **Object** menus, the gizmo's orientation (Global or Local), the world layer and the shading (Wireframe, Solid, Material, more in ▾). Inside it: the toolbar (T), the axes and navigation buttons, and the sidebar (N) |
|
||
| **Outliner** | everything in the home: its objects (as the file lays them out, or by kind) and its world items, with an eye to hide each |
|
||
| **Properties** | settings, in tabs down its left edge: **Object** (what you selected), **World** (where you can walk), **Environment** (name, picture, sound, headset settings), **Bundle**, **Headset** |
|
||
| **Timeline** | plays the home's animations and sound; click or drag in it to scrub through the loop |
|
||
|
||
**Rearranging areas.** Drag the gutter between two areas to resize them. To move an area, drag the **editor button**
|
||
at the left of its header (the icon with ▾) and drop it on another area: onto its middle to stack them as tabs, or
|
||
onto an edge to split that area. Click the editor button to show a different editor in that area. **Window > Reset
|
||
Layout** puts everything back; **Ctrl+Space** fills the window with the 3D Viewport until you press it again.
|
||
|
||
**Workspaces.** The tabs in the top bar switch between layouts made for a job: **Layout** (everything), **Walking**
|
||
(a big view with Properties on the World tab) and **Headset** (Properties on the Headset tab). Studio remembers
|
||
your layout between runs.
|
||
|
||
**Themes.** **Window > Theme** recolours the whole interface, from dark to light, using the palette from the MetaDB
|
||
site. The choice is saved and comes back next time.
|
||
|
||
## Opening a home
|
||
|
||
- **File > Open...** (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 > Import > Vista...** gives a footprint its vista; **File > Import > 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, Alt + left-drag, or drag the axes gizmo in the top-right corner |
|
||
| Snap to a view (top, front, side...) | click an axis ball on the gizmo (or the Numpad: 1/3/7 front/side/top, Ctrl for the opposite) |
|
||
| 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 | the person button under the axes, P, or Numpad 0 |
|
||
| Frame the selection / everything | F or Numpad . / Home (or double-click a row in the Outliner) |
|
||
|
||
Press **F1** (Help > Controls) for the full list.
|
||
|
||
## Selecting and editing objects
|
||
|
||
1. Click an object in the 3D view or the Outliner. Properties switches to its **Object** tab.
|
||
2. Pick a tool in the toolbar on the left of the view (or press its key) and drag the gizmo:
|
||
- **Move** (G), **Rotate** (R), **Scale** (S). Hold Ctrl to snap.
|
||
- **Global** / **Local** in the header 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 Object 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 Outliner's eye buttons hide objects or whole folders. **Select > Reveal Hidden** (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.
|
||
- **Object > Auto-generate Walkable Surfaces** (in the 3D Viewport's header) 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 Object 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, the brush in the toolbar, or the **Draw Floor** mode in the header): 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
|
||
|
||
**Add** (in the 3D Viewport's header, or Shift+A over the view) 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; you sit facing the way its arrow points; 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 |
|
||
| **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 Object tab. **Object > 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 Outliner
|
||
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](environments-and-fenv.md).
|
||
|
||
## Bundles
|
||
|
||
A bundle (`.fbundle`) packs several saved environments into one file, to share or install together. Use the
|
||
**File > Bundle** or the **Bundle** tab in Properties: **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](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.
|
||
- **This PC** (Linux): **Install Frame Home on This PC** makes your environments SteamVR's environment on the
|
||
computer Studio runs on.
|
||
- 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 > Preferences...**: Studio's own (3D view resolution, anti-aliasing, texture size and filtering) and the
|
||
headset's (read from and written to the Frame).
|
||
- **Viewport shading** (the buttons and ▾ at the right of the 3D Viewport's header): Material (as the headset draws
|
||
it), Solid, Wireframe, and in ▾ **GPU Cost**, **Overdraw** and **Leave Out** (hide whole kinds of objects).
|
||
- **Window > Home Report...**: what the home is made of and what may be slow.
|
||
- **Headset > Headset Debug...**: the same views, on the headset.
|
||
- **View** (in the 3D Viewport's header): the toolbar and sidebar, framing, the numpad viewpoints, **Local View**
|
||
(show only the selection) and **Show Everything**.
|
||
- **Edit > Menu Search...** (F3): find any command by typing part of its name.
|
||
|
||
## Updates
|
||
|
||
Studio checks GitHub for a newer **Latest build** a few seconds after it starts and every 6 hours after that. When
|
||
there is one, an orange **Update Available** button shows in the top bar. Click it, then **Download and Install**:
|
||
Studio downloads the build for your computer and puts it in place of the copy you're running. **Restart Now** opens
|
||
the new one (it asks about unsaved changes first). **Help > Check for Updates...** checks right away.
|
||
|
||
If Studio's folder can't be written to (Program Files, for example), nothing is changed and the window offers the
|
||
download page instead. A copy you built yourself doesn't update itself.
|
||
|
||
## 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 tool | B | draw floor |
|
||
| Shift+A | add menu at the mouse | X | delete (asks first); Delete: right away |
|
||
| H / Alt+H | hide / reveal hidden | Alt+A, Esc | select nothing |
|
||
| Numpad . / Home | frame selected / all | Numpad 0, P | player view |
|
||
| Numpad 1 / 3 / 7 | front / right / top (Ctrl: the other side) | Numpad /, I | show only selected |
|
||
| W | world layer | Space | play / pause |
|
||
| T / N | toolbar / sidebar | Ctrl+Space | maximize the 3D Viewport |
|
||
| F3 | menu search: every command by name | F1 | controls |
|