Building a Simple Game with the SimVX Editor¶
This tutorial walks through building a 2D game scene using the SimVX editor. Each step has been validated with automated tests to ensure the editor is functional.
Prerequisites¶
# Install in dev mode
uv pip install -e packages/core -e packages/graphics -e packages/editor
# Launch the editor
uv run python -m simvx.editor.main
# Or: from simvx.editor.app import launch; launch()
Step-by-Step Tutorial¶
Step 1: Launch the Editor¶
Action: Run the editor. A window appears with:
Menu bar at top: File, Edit, Scene, View, Tools, Help
Toolbar below: Move/Rotate/Scale buttons, Play/Pause/Stop, 3D/2D toggle
Scene Tree panel (left): shows the node hierarchy with a “Root” node
Viewport (center): 3D preview area
Inspector panel (right): property editor (empty until a node is selected)
Status bar (bottom): mouse position and selection info
Bottom tabs: Console, Code, Files, Animation
Verify:
[x] The editor window opens without errors
[x] All panels are visible and labeled
[x] The Scene Tree shows a single “Root” node
[x] The undo stack is empty
[x] The editor is not in play mode
Tests: TestStep1_LaunchEditor (10 tests)
Step 2: Add a Game Node¶
Action: Click the “+” button in the Scene Tree header. The Add Node dialog appears.
In the dialog:
You see a list of 12 node types (Node, Node2D, Node3D, Camera3D, etc.)
There’s a filter text field at the top
Click “Node2D” in the list
Result: A new Node2D appears under Root in the Scene Tree.
Verify:
[x] Clicking “+” opens the Add Node dialog
[x] The dialog shows all 12 available types
[x] Clicking a type creates the node and closes the dialog
[x] The new node appears in the Scene Tree
[x] The new node gets selected after creation
[x] The operation is recorded in the undo stack
Tests: TestStep2_AddNodes (8 tests), TestAddNodeDialogInteraction (3 tests)
Step 3: Rename the Node¶
Action: With the Node2D selected, press F2 to open the rename overlay.
The rename field appears with the current name highlighted
Type “Game”
Press Enter to confirm
Result: The node is renamed from “Node2D” to “Game” in the Scene Tree.
Verify:
[x] F2 key opens the rename overlay
[x] Typing a name and pressing Enter renames the node
[x] The tree view updates to show the new name
[x] Renaming is undoable with Ctrl+Z
Tests: TestStep3_RenameNodes (7 tests), TestUndoRedoViaUI (3 tests)
Step 4: Add Child Nodes¶
Action: With “Game” selected, click “+” again.
Select “Node2D” from the dialog
The new node appears under Game (as a child)
Press F2, type “Player”, press Enter
Select “Game” again in the tree
Click “+” and add another “Node2D”
Rename it to “Enemy”
Select “Game”, add a “Camera3D”
Result: Your scene tree looks like:
Root
└─ Game (Node2D)
├─ Player (Node2D)
├─ Enemy (Node2D)
└─ Camera3D
Verify:
[x] Nodes are added as children of the selected node
[x] If nothing is selected, nodes go under Root
[x] Multiple nodes can be added sequentially
[x] Each add is a separate undo operation
Tests: TestStep2_AddNodes::test_add_node_under_selected_parent
Step 5: Select a Node and View Properties¶
Action: Click on “Player” in the Scene Tree.
Result: The Inspector panel updates to show:
Type label: “Node2D”
Name field: “Player”
Node section: Visible checkbox
Transform section: Position (X, Y), Rotation, Scale (X, Y)
Verify:
[x] Clicking a tree item updates the inspector
[x] Inspector shows the correct type name
[x] Inspector shows the correct node name
[x] Transform section appears for spatial nodes
[x] Node section appears with visibility toggle
[x] Switching selection updates the inspector
Tests: TestStep4_SelectionInspector (9 tests)
Step 6: Edit Transform Properties¶
Action: In the Inspector, change the Player’s position:
Click on the Position X spinbox
Type 100 or use the increment buttons
Change Position Y to 300
Result: The Player node’s position updates to (100, 300).
Verify:
[x] Position widgets exist for 2D nodes
[x] Initial values match the node’s position (0, 0)
[x] Changing a value updates the node immediately
[x] Position changes are undoable with Ctrl+Z
[x] 3D transforms work similarly with X, Y, Z components
[x] Rotation and Scale can also be edited
Tests: TestStep5_EditTransforms (7 tests), TestSpinBoxInteraction (2 tests)
Step 7: Undo and Redo¶
Action: Try the undo/redo system:
Press Ctrl+Z to undo the last position change
Press Ctrl+Shift+Z to redo it
Undo multiple times to step back through all changes
Redo to restore them
Verify:
[x] Ctrl+Z undoes the last operation
[x] Ctrl+Shift+Z redoes an undone operation
[x] Multiple undos can be chained
[x] Undo works for: add node, rename, property change, delete, duplicate
Tests: TestStep6_UndoRedo (6 tests), TestKeyboardShortcuts (5 tests)
Step 8: Delete and Duplicate Nodes¶
Action:
Select “Enemy” in the tree
Press Delete key — Enemy is removed
Press Ctrl+Z — Enemy is restored
Select “Player”
Use the context menu (right-click) → Duplicate — creates “Player_copy”
Select “Player_copy” and press Delete to remove it
Verify:
[x] Delete key removes the selected node
[x] Cannot delete the root node
[x] Delete clears the selection
[x] Deleting is undoable
[x] Duplicate creates a copy with “_copy” suffix
[x] Duplicate is undoable
[x] Right-click context menu appears with all options
Tests: TestStep7_DeleteDuplicate (7 tests), TestContextMenu (2 tests)
Step 9: Copy and Paste¶
Action:
Select “Player”
Right-click → Copy (or Ctrl+C)
Select “Game”
Right-click → Paste (or Ctrl+V) — creates “Player_paste” under Game
Verify:
[x] Copy stores the node in the clipboard
[x] Paste creates a new node from the clipboard
[x] Pasted node gets “_paste” suffix
[x] Paste is undoable
Tests: TestStep8_CopyPaste (3 tests)
Step 10: Save the Scene¶
Action:
Press Ctrl+S to save
If no path is set, the Save As dialog appears
Navigate to your project directory
Enter filename: “game.py”
Click Save
Result: Scene is saved to disk as a Python source file — the scene tree, properties, and attached scripts round-trip as a Node subclass.
Verify:
[x] Save creates a Python (
.py) file on disk[x] Save clears the “modified” flag
[x] Save remembers the path for future saves
[x] The path is stored in
current_scene_path
Tests: TestStep9_SaveLoad (6 tests)
Step 11: Load a Scene¶
Action:
Press Ctrl+N to create a new empty scene
Press Ctrl+O to open the file dialog
Navigate to and select “game.py”
Click Open
Result: The saved scene is loaded with all nodes restored.
Verify:
[x] New Scene clears everything (nodes, selection, undo)
[x] Open Scene loads nodes from the Python scene file
[x] Loading clears the undo stack
[x] Loaded scene has all the original nodes
Tests: TestStep9_SaveLoad (6 tests)
Step 12: Custom Properties¶
If you create a custom node class with Property descriptors:
from simvx.core import Node2D, Property
class Player(Node2D):
speed = Property(5.0, range=(0, 20))
health = Property(100, range=(0, 200))
name_tag = Property("hero")
is_alive = Property(True)
mode = Property("walk", enum=["walk", "run", "idle"])
The Inspector will automatically create the right widget for each property:
Type |
Widget |
|---|---|
|
Slider |
|
SpinBox |
|
CheckBox |
|
TextEdit |
|
DropDown |
Color tuple |
ColorPicker |
|
Multi-SpinBox row |
Tests: TestStep12_CustomProperties (5 tests)
Step 13: Play Mode¶
Action:
Press F5 (or click Play) to enter play mode
Press F7 (or click Pause) to toggle pause
Press F6 (or click Stop) to exit play mode
Result: The scene is serialized before play, and restored when stopped.
Verify:
[x] Play enters play mode and emits signal
[x] Pause toggles the paused state
[x] Stop restores the scene to pre-play state
[x] Stop when not playing is a no-op
Tests: TestStep10_PlayMode (5 tests)
Step 14: Inspector Section Collapse¶
Action: Click on a section header (e.g., “Transform”) to collapse it.
Result: The section rows hide. Click again to expand.
Tests: TestStep14_SectionCollapseExpand (3 tests)
Step 15: Gizmo and Viewport Mode¶
Action:
Click Move/Rotate/Scale buttons in the toolbar to change gizmo mode
Press Q to cycle through modes
Click 3D/2D buttons to switch viewport mode
Tests: TestStep15_GizmoMode (3 tests), TestStep16_ViewportMode (3 tests)