Maker (World & Scene Editor) — Pro Guide & Reference

Maker is Small World's standalone, browser-based 3D scene and environment editor (/tools/maker.html). Built specifically for digital artists and power users, Maker closes the gap between procedural engine development and visual scene composition — no more hand-written scene layout files, just a low-latency, keyboard-driven workflow.

+-------------------------------------------------------------------------------------------------------+
|  Header: [Maker - Small World]   [📷1][📷2]..[📷9]   [🧲 0.50m][[][]]   [⬇ Floor]   [Save/Status]      |
+-------------------+---------------------------------------------------------------+-------------------+
| Hierarchy & Add   | Viewport & interactive tools                                  | Inspector         |
| - Scene tree      | - Orbit camera & 9 quick view bookmarks (1-9 / Ctrl+1-9)      | - Transform       |
| - Primitives      | - Always-on-top transform gizmo (W: Move / E: Rotate / R: Sc) |   (X/Y/Z nudge)   |
| - Lights          | - Camera-cardinal keyboard nudging (arrows / PageUp/Down)     | - Materials (PBR) |
| - Prefabs (thumb) | - Dynamic snapping (0.1m - 2.0m / 15° / 0.25)                 |   (Rough/Metal/α) |
| - ASCII map import| - 2D marquee selection & cyan/amber cluster highlighting      | - Behaviors       |
|                   | - Pivot-relative multi-object group transforms                |   (factory batch) |
+-------------------+---------------------------------------------------------------+-------------------+
| Footer: Autosave status (all changes saved to scene.gltf / 500ms debounce)                             |
+-------------------------------------------------------------------------------------------------------+

1. Power-user ergonomics & fast keyboard nudging

Maker is built around a "hands on the keyboard" philosophy, heavily inspired by professional digital-art and 3D-modeling packages (Blender, Photoshop, Unreal Engine).

Camera-cardinal directional nudging

Moving objects via the arrow keys is camera-perspective-aware:

XZ-plane ground movement: pressing $\uparrow$, $\downarrow$, $\leftarrow$, or $\rightarrow$ computes the camera's dominant cardinal orientation in world space in real time (North, East, South, West).
- $\uparrow$ always moves the selection away from the viewer (into image depth).
- $\downarrow$ always moves the selection toward the viewer.
- $\rightarrow$ always moves the selection visually to the right.
- $\leftarrow$ always moves the selection visually to the left.
Height movement (Y axis):
- Shift + $\uparrow$ or Page Up: moves selected objects by the active grid snap increment upward (+Y).
- Shift + $\downarrow$ or Page Down: moves selected objects by the active grid snap increment downward (-Y).

The arrow keys adapt dynamically to the active gizmo mode or keyboard modifier:

Mode / modifier	Arrow key action	Step size
Move mode (`W`) (default)	Shift position (XZ / Y with Shift)	Current grid snap (`0.1m` – `2.0m`)
Rotate mode (`E`) or `Alt + arrows`	Rotate yaw (Y) / pitch (X)	Angle snap ($15^\circ$ / $\pi / 12$)
Scale mode (`R`) or `Alt + Shift + arrows`	Scale object (uniform / axis)	Scale snap ($0.25$)

Snap to floor (`End` / `⬇ Floor`)

Pressing End (or clicking ⬇ Floor) computes the exact lower world-space bounding-box bound (min.y) for the entire current selection (single object or multi-selection cluster) and moves it vertically so its bottom edge sits exactly flush with Y = 0 (the world floor plane).

2. Dynamic snapping system & grid-resolution stepping

Snapping is enabled by default in Maker, to ensure clean, modular scene construction without microscopic gaps or misalignments.

Instant toggle: press X or click 🧲 Snap to toggle snapping on/off on the fly.
Quick grid-stepping hotkeys:
- [: Finer grid — steps down through resolutions (2.0m $\rightarrow$ 1.0m $\rightarrow$ 0.5m $\rightarrow$ 0.25m $\rightarrow$ 0.1m).
- ]: Coarser grid — steps up through resolutions (0.1m $\rightarrow$ 0.25m $\rightarrow$ 0.5m $\rightarrow$ 1.0m $\rightarrow$ 2.0m).
Precision parameters:
- Translation snap: default 0.5m (adjustable from 0.1m to 2.0m).
- Rotation snap: fixed $15^\circ$ ($0.2618\text{ rad}$) angle quantization.
- Scale snap: fixed 0.25 step multiples.

3. Multi-selection, marquee selection & pivot-relative clusters

Maker supports full multi-object workflows with full parity between viewport and hierarchy interactions.

                    [Primary: cyan wireframe] (active inspector & pivot anchor)
                              |
                              +--- [Secondary: amber wireframe]
                              +--- [Secondary: amber wireframe]

Selection mechanics

Single selection: left-click an object in the viewport or click a row in the hierarchy panel.
Additive multi-selection: hold Shift, Ctrl, or Cmd while clicking objects in the viewport or rows in the hierarchy panel to add/remove them from the selection set.
2D marquee selection: click and drag over an empty area of the viewport to draw a 2D marquee box (.maker-marquee-box). Maker projects all scene-object bounding volumes through the camera's view-projection matrix into screen space to select everything inside the box. Hold Shift while dragging to extend the current selection additively.

Primary vs. secondary objects

Primary object (cyan highlight): the main anchor of the selection. It determines what appears in the property inspector, and serves as the 3D center pivot for gizmo transforms.
Secondary objects (amber highlight): further members of the multi-selection cluster.

Pivot-relative cluster transforms

When rotating or scaling a multi-selection with the gizmo, transforms are performed relative to the primary object's world-space pivot point — this keeps the cluster's spatial relationships intact, instead of rotating each object around its own local axis.

Batch operations

Batch duplicate (Ctrl+D): deep-clones all selected objects, material properties, and attached behaviors, offsets them cleanly in the scene, and wraps this in a single undo transaction.
Batch delete (Del / Backspace): moves all selected objects into the soft-delete trash bin in a reversible step.
Batch grouping (Ctrl+G): computes the 3D centroid of all selected objects, creates a new parent Object3D group at that centroid, and reparents the children under it while preserving their exact world matrices.
Batch behaviors: adding a behavior from the palette automatically instantiates and attaches fresh, isolated behavior instances to all selected objects in one atomic operation.

4. Always-on-top transform gizmo

The Maker transform gizmo provides standard translation (W), rotation (E), and scaling (R) directly in the 3D viewport.

Occlusion-proof rendering: rendered with depthTest: false and depthWrite: false, so transform handles, rotation rings, and scale boxes stay fully visible even when objects are positioned inside dense geometry or behind large meshes.
Interactive highlighting: handles highlight on hover and snap to active drag axes.
Dynamic alignment: stays anchored to the world position of the primary selected object.

5. 3D light gizmos & selection range volumes

Abstract scene emitters (PointLight, DirectionalLight, SpotLight, AmbientLight) have dedicated, industry-standard visual markers in the 3D viewport:

Pickable visual glyphs (billboards):
- 💡 PointLight: glowing octahedron core in light.color (or yellow). Always billboarded to face the camera.
- ☀️ DirectionalLight: sun disc with a direction arrow showing the light angle.
- 🔦 SpotLight: mini emitter cone along the spotlight's target vector.
- 🌐 AmbientLight: wireframe sphere representing the sky's ambient lighting.
Direct 3D raycasting: clicking a light glyph in the 3D viewport selects the light, attaches the transform gizmo, and opens its properties (Color, Intensity, Distance, Decay, Angle) in the property inspector.
Dynamic selection range volumes:
- When a PointLight is selected, Maker draws a wireframe sphere showing its falloff range (distance).
- When a SpotLight is selected, Maker renders a wireframe cone showing its exact cone angle (angle) and range (distance). Adjusting the parameters in the inspector scales the visual cone in real time!
No export overhead: all light helper objects live in an isolated, editor-only container and are automatically excluded from scene saves and runtime builds.

6. Prefab pipeline & isolated 3D thumbnail renders

Maker provides a complete, self-contained pipeline for creating and placing prefabs.

[Hierarchy selection] ---> [Save prefab] ---> 1. Isolate object subtree
                                              2. Reframe to 3/4 camera angle
                                              3. Render isolated thumbnail (.thumb.json)
                                              4. Save glTF scene graph (.gltf)

Creating prefabs: select any object or a grouped hierarchy in the scene, type a prefab name in the prefab palette, and click Save Selection.
Automated isolated thumbnail generation:
- Maker temporarily hides the transform gizmo, highlight boxes, and all unrelated scene objects, while keeping scene lighting (AbstractLight) intact.
- Recursively computes the bounding sphere of the prefab subtree.
- Automatically positions the snapshot camera at an optimal $3/4$ isometric angle (1, 0.75, 1), tightly framed around the object.
- Captures an offscreen render into an accompanying thumbnail (prefabs/<name>.thumb.json).
- Fully restores viewport camera, orbit-controller state, and scene visibility without interrupting the user.
Prefab placement: clicking any prefab thumbnail or name in the prefab palette places a fresh instance directly at the viewport focus center in the scene.

9 instant session bookmarks (`1`–`9` & `Ctrl+1`–`9`)

Recall view: press number keys 1 through 9 (or click the toolbar buttons 📷1–📷9) to instantly animate the camera to a saved viewpoint.
Save view: press Ctrl+1 through Ctrl+9 (or right-click a bookmark button 📷1–📷9) to save the current camera position, pitch, yaw, and orbit target into that slot. Slots with saved views are highlighted with an active border.

Rotate view (orbit): right-click + drag, middle-click + drag, Alt + left-drag, or macOS Ctrl + left-drag.
Pan view: Shift + right-/middle-drag.
Zoom view: mouse wheel or Ctrl + mouse wheel.
Scroll-zoom decoupling: scrolling inside the hierarchy, object palette, or property inspector is strictly isolated (stopPropagation()), preventing unintended viewport zooming while navigating long UI lists.

8. ASCII level & dungeon map import

Maker includes a built-in ASCII tilemap converter (MapImportPanel.ts) for quick retro level design and dungeon blocking, feeding GridLevelBuilder through Maker's own default legend (AsciiMapLegend.ts) — deliberately its own small palette rather than an import of the MapGenerator tool's internal palette, though it reuses the same characters/colors so a map painted in MapGenerator still looks recognizable once imported:

ASCII source:              3D world generation:
##########                 W / G -> Wall block (2m tall)
#.P...+...E#               .     -> Floor tile (implicit, no marker)
#..b.......#               +     -> Door marker
##########                  P     -> Player-start marker
                            E     -> Enemy marker
                            b     -> Barrel marker
                            l     -> Torch marker
                            T     -> Lava marker
                            ~     -> Slime marker
                            I     -> Item marker
                            O     -> Secret marker

Paste your text layout into the ASCII import dialog to instantly generate a 3D level with aligned wall blocks, floor tiles, and marker cubes for doors, enemies, items, and the player start — a fast, editable base to refine by hand afterward in Maker, not a finished level.

9. Persistence & the glTF 2.0 `SW_*` extension engine

Maker uses the browser's native File System Access API (showDirectoryPicker) for direct local workspace binding, without uploading data to external servers.

Frictionless autosave: every edit (transform change, color adjustment, hierarchy reorder, prefab creation) triggers a debounced (~500ms) write-through directly to scene.gltf.
SW_* glTF metadata extensions: non-standard engine data is stored cleanly in glTF 2.0's extensions vendor namespace via a pluggable extension registry (see docs/adr/0017-gltf-extension-plugin-registry.md). Currently implemented:
- SW_prefab_instance: provenance-only record of which Maker prefab a node was instantiated from.
- SW_stage_zone: a 2.5D StageZone's points and display name (see docs/adr/0016-2-5d-stage-zones-as-a-gltf-extension.md), giving it a scene-graph presence via StageZoneMarker.
- A node's material is written through native glTF pbrMetallicRoughness rather than a custom extension, since StandardMaterial's fields map onto it directly. Behaviors and physics data are not currently round-tripped through the glTF file (WorldWriter's scope is still Phase 0: hierarchy, transforms, one material per mesh, and position-only geometry).
Portability: the generated scene.gltf files can be opened directly in Blender, Babylon.js, Three.js, or loaded straight into the Small World game runtime via GltfLoader.

10. Non-destructive undo/redo & soft-delete engine

All scene mutations are tracked on an atomic UndoStack:

Undo / redo: Ctrl+Z to undo, Ctrl+Shift+Z (or Ctrl+Y) to redo.
Soft-delete architecture: deleting an object or hierarchy branch moves it into a scene-external _trashBin container instead of immediately releasing its WebGL/WebGPU buffers. This guarantees instant, stutter-free restoration on undo without GPU hitching.

11. Master keyboard shortcut quick reference

Category	Shortcut	Action
Tools & modes	`W`	Move/translation tool
	`E`	Rotation tool
	`R`	Scale tool
	`X`	Toggle snapping on/off
	`[`	Decrease grid snap step (finer: $0.1\text{m}$)
	`]`	Increase grid snap step (coarser: $2.0\text{m}$)
Transform & nudge	$\leftarrow$ $\rightarrow$ $\uparrow$ $\downarrow$	Move selection along the camera-cardinal XZ plane
	`Shift` + $\uparrow$ / $\downarrow$ or `PageUp` / `PageDown`	Move selection along the Y axis (height)
	`Alt` + arrows	Rotate selection by angle snap ($15^\circ$)
	`Alt` + `Shift` + arrows	Scale selection by scale snap ($0.25$)
	`End`	Snap to floor: drop selection flush onto $Y = 0$ floor
Selection & graph	`Left-click`	Select single object
	`Shift` / `Ctrl` / `Cmd` + click	Toggle/additive multi-selection
	`Drag on empty space`	2D marquee selection
	`Ctrl+F` / `Cmd+F`	Focus hierarchy filter: live search & filtering of scene objects by name (`Enter` selects, `Esc` clears)
	`F2` / hierarchy `double-click`	Rename object inline: edit name in the hierarchy row (`Enter` applies, `Esc` cancels)
	Property panel `name field` / title `double-click`	Direct rename: edit object name at the top of the property inspector
	`Ctrl+D`	Duplicate selection (atomic batch)
	`Ctrl+G`	Group selection at centroid
	`Del` / `Backspace`	Delete selection
History	`Ctrl+Z`	Undo
	`Ctrl+Shift+Z` / `Ctrl+Y`	Redo
Camera bookmarks	`1` – `9`	Recall camera bookmark 1–9
	`Ctrl+1` – `Ctrl+9` / right-click button	Save camera bookmark 1–9
Viewport navigation	`Right-drag` / `Middle-drag`	Rotate view (orbit)
	`Alt` + left-drag / macOS `Ctrl` + left-drag	Rotate view (artist-friendly)
	`Shift` + right-/middle-drag	Pan view
	`Mouse wheel`	Zoom in/out

Maker (World & Scene Editor) — Pro Guide & Reference

1. Power-user ergonomics & fast keyboard nudging

Camera-cardinal directional nudging

Snap to floor (`End` / `⬇ Floor`)

2. Dynamic snapping system & grid-resolution stepping

3. Multi-selection, marquee selection & pivot-relative clusters

Selection mechanics

Primary vs. secondary objects

Pivot-relative cluster transforms

Batch operations

4. Always-on-top transform gizmo

5. 3D light gizmos & selection range volumes

6. Prefab pipeline & isolated 3D thumbnail renders

7. Camera bookmarks & viewport navigation

9 instant session bookmarks (`1`–`9` & `Ctrl+1`–`9`)

Multi-button mouse navigation (orbit & pan)

8. ASCII level & dungeon map import

9. Persistence & the glTF 2.0 `SW_*` extension engine

10. Non-destructive undo/redo & soft-delete engine

11. Master keyboard shortcut quick reference

Maker (World & Scene Editor) — Pro Guide & Reference ​

1. Power-user ergonomics & fast keyboard nudging ​

Camera-cardinal directional nudging ​

Modal transform hotkeys ​

Snap to floor (End / ⬇ Floor) ​

2. Dynamic snapping system & grid-resolution stepping ​

3. Multi-selection, marquee selection & pivot-relative clusters ​

Selection mechanics ​

Primary vs. secondary objects ​

Pivot-relative cluster transforms ​

Batch operations ​

4. Always-on-top transform gizmo ​

5. 3D light gizmos & selection range volumes ​

6. Prefab pipeline & isolated 3D thumbnail renders ​

7. Camera bookmarks & viewport navigation ​

9 instant session bookmarks (1–9 & Ctrl+1–9) ​

Multi-button mouse navigation (orbit & pan) ​

8. ASCII level & dungeon map import ​

9. Persistence & the glTF 2.0 SW_* extension engine ​

10. Non-destructive undo/redo & soft-delete engine ​

11. Master keyboard shortcut quick reference ​

Maker (World & Scene Editor) — Pro Guide & Reference

1. Power-user ergonomics & fast keyboard nudging

Camera-cardinal directional nudging

Modal transform hotkeys

Snap to floor (`End` / `⬇ Floor`)

2. Dynamic snapping system & grid-resolution stepping

3. Multi-selection, marquee selection & pivot-relative clusters

Selection mechanics

Primary vs. secondary objects

Pivot-relative cluster transforms

Batch operations

4. Always-on-top transform gizmo

5. 3D light gizmos & selection range volumes

6. Prefab pipeline & isolated 3D thumbnail renders

7. Camera bookmarks & viewport navigation

9 instant session bookmarks (`1`–`9` & `Ctrl+1`–`9`)

Multi-button mouse navigation (orbit & pan)

8. ASCII level & dungeon map import

9. Persistence & the glTF 2.0 `SW_*` extension engine

10. Non-destructive undo/redo & soft-delete engine

11. Master keyboard shortcut quick reference