Studio Guide

Rawframe Studio is the built-in visual editor for building worlds, testing mods, and debugging scripts. It provides a full scene editor with real-time play mode, terrain tools, and an integrated Luau debugger.

---

Overview

Studio is a purpose-built visual editor integrated directly into the engine. It provides a professional editor experience with:

• Scene Viewport — 3D scene view with entity picking, gizmos, and multiple draw modes
• Hierarchy Panel — Entity tree with search, drag-drop reparent, and context menus
• Inspector Panel — Property editing for transforms, physics, meshes, and materials
• Asset Browser — Navigate project assets, drag-drop meshes into the scene
• Console Panel — Log output with level filters and a Luau REPL
• Profiler — Real-time performance metrics (frame time, draw calls, memory)
• Luau Debugger — Breakpoints, step execution, variable inspection

---

Getting Started

Launch Studio from the build directory:

./rawframe_studio

Creating a Scene

1. File > New Scene to start with an empty world.
2. Use the Create menu (top menu bar) to add entities: primitives (cube, sphere, cylinder), lights, sound emitters, trigger volumes, and more.
3. Select entities by clicking in the viewport. Use the Hierarchy Panel to manage the entity tree.
4. Edit properties in the Inspector Panel — transform, physics body, mesh, material.
5. File > Save Scene (Ctrl+S) to save as .rfscene (JSON format).

Navigation

Action	Control
Orbit	Right-click + drag
Pan	Middle-click + drag
Zoom	Scroll wheel
Focus selection	F
Fly mode	Hold right-click + WASD

---

Gizmos and Transform Tools

Studio provides three transform gizmos, toggled with keyboard shortcuts:

Mode	Key	Description
Translate	W	Move entities along axes or planes
Rotate	E	Rotate around axes (circle handles)
Scale	R	Scale along axes or uniformly (center handle)

Snapping

Enable snap in the toolbar or hold Ctrl while dragging:

• Translate snap: 0.5 unit increments (configurable)
• Rotate snap: 15 degree increments
• Scale snap: 0.1 increments

Vertex Snap

Press V to toggle vertex snapping — the gizmo locks to the nearest mesh vertex within 2 meters.

---

Play Mode

Test your game without leaving the editor:

1. Press F5 (or the Play button) to enter play mode.
2. The editor creates a separate physics world and loads enabled mods.
3. Press F6 to pause/resume.
4. Press F5 again (or Stop) to exit — the scene returns to its pre-play state.

Play mode uses a dual-world architecture: the edit scene is preserved untouched. All physics simulation and script execution happen in a temporary copy.

Hot-Reload in Play Mode

Press Ctrl+Shift+R to force-reload all mod scripts during play mode. File changes are also detected automatically.

---

Terrain Editing

Studio includes a full terrain sculpt and paint system:

1. Create terrain: Create > Terrain > Flat Terrain
2. Press T to activate the terrain brush
3. Use the Terrain Panel to switch between sculpt and paint modes

Sculpt Modes

• Raise/Lower — Ctrl to invert
• Flatten — Level terrain to a target height
• Smooth — Average neighboring heights

Paint

Paint up to 4 splatmap layers (grass, dirt, rock, sand) with configurable brush falloff.

All terrain operations support undo/redo (Ctrl+Z / Ctrl+Y).

---

Debugging

Console Panel

The console shows engine log output with level filters (Info, Warning, Error). It includes a Luau REPL — type Luau code directly and execute it in the current play mode context.

Script Profiler

View > Profiler opens the profiler panel with:

• Frame time graph
• Draw call count
• Memory usage (per-subsystem)
• Script execution time (per-function)

Luau Debugger

View > Debugger opens the integrated debugger:

Key	Action
F9	Toggle breakpoint on current line
F10	Step over
F11	Step into
Shift+F11	Step out

The debugger shows the call stack, local variables, and upvalues at each frame.

---

Keyboard Shortcuts

General

Shortcut	Action
Ctrl+N	New scene
Ctrl+O	Open scene
Ctrl+S	Save scene
Ctrl+Z	Undo
Ctrl+Y	Redo
Ctrl+C / Ctrl+V	Copy / Paste
Ctrl+D	Duplicate
Delete	Delete selected
Ctrl+P	Command palette
G	Toggle grid
M	Measurement tool

Viewport

Shortcut	Action
W / E / R	Translate / Rotate / Scale gizmo
F	Focus selection
V	Vertex snap toggle
T	Terrain brush
Ctrl+1-9	Save camera bookmark
1-9	Recall camera bookmark

Play Mode

Shortcut	Action
F5	Play / Stop
F6	Pause / Resume
Ctrl+Shift+R	Force reload scripts

---

Editor Luau API (editor.*)

Studio exposes 13 Luau functions for scripting the editor itself. These work in the REPL and in editor scripts:

-- Select and manipulate entities
editor.select(entity_id)
local selected = editor.selected()

-- Create entities
local cube = editor.create("cube", "MyCube")
editor.set_transform(cube, {
    position = {0, 5, 0},
    rotation = {0, 45, 0},
    scale = {2, 2, 2}
})

-- Camera control
editor.camera_move_to(0, 10, -20)
editor.camera_look_at(0, 0, 0)

-- Undo/redo
editor.undo()
editor.redo()

-- Notifications
editor.notify("Build complete!")

See the API Playground for the full editor.* function list.

---

Multi-Viewport

Studio supports up to 4 simultaneous viewports with different camera angles:

• View > Viewport Layout to choose 1, 2, or 4 viewport arrangements
• Each viewport has its own camera (perspective or orthographic)
• Click a viewport to make it active for gizmo interaction

---

Prefab System

Save entity hierarchies as reusable prefabs:

1. Select an entity (and its children).
2. Inspector > Save as Prefab — saves as .rfprefab (JSON).
3. Drag from the Asset Browser to instantiate.

Prefabs support nested hierarchies and preserve all component data.