simvx.editor.play_mode

Play Mode — Run/pause/stop lifecycle for in-editor game preview.

Manages scene serialization/restoration, camera switching, input routing, and per-frame process/physics updates during play mode. The game runs in a separate SceneTree with isolated input state so editor and game input never interfere.

Usage: play_mode = PlayMode(editor_state) play_mode.start() # F5 — serialize scene, begin processing play_mode.toggle_pause() # F7 — pause/resume processing play_mode.stop() # F6 — restore pre-play scene state

# Called each frame by the editor's main loop:
play_mode.update(dt)

Module Contents

Classes

PlayMode

Manages the run/pause/stop lifecycle for previewing games in the editor.

Data

log

API

simvx.editor.play_mode.log

‘getLogger(…)’

class simvx.editor.play_mode.PlayMode(state: simvx.editor.state.State)

Manages the run/pause/stop lifecycle for previewing games in the editor.

The game scene runs in an isolated SceneTree with its own input state. The editor’s process loop calls update(dt) every frame to drive the game cooperatively (no threading).

Initialization

start(on_tree_created=None) → None

Begin play mode (triggered by F5).

Serializes the current scene so it can be restored on stop, creates an isolated game tree with its own input state, and calls ready() on all game nodes.

Args: on_tree_created: Optional callback fn(game_root) invoked after the game tree is constructed but before ready() is called. Used by the editor to load scripts onto the cloned tree.

set_hot_reload_enabled(enabled: bool) → None

Enable or disable script hot-reload during play mode.

Updates :attr:State.hot_reload_enabled AND, when a play session is active, the live :class:HotReloadManager so the change takes effect immediately without restarting PlayMode.

toggle_pause() → None

Toggle pause during play mode (triggered by F7).

When paused, process/physics updates are skipped but the scene continues to render so the user can inspect the frozen state.

stop() → None

Stop play mode and restore the pre-play scene (triggered by F6).

Destroys the game tree and input state, deserializes the saved snapshot back into the editor’s scene tree.

start_detached() → None

Start the game in a separate OS window via subprocess.

stop_detached() → None

Stop the detached game window if running.

property is_detached: bool

Whether a detached game process is running.

attach_profiler(profiler: simvx.core.debug.profiler.FrameProfiler | None) → None

Attach (or detach) a :class:FrameProfiler for play-mode metrics.

When attached, :meth:update times each phase (physics, process, ui, total) and samples per-node timings into the profiler. The profiler also drives the editor’s profiler panel.

property profiler: simvx.core.debug.profiler.FrameProfiler | None

update(dt: float) → None

Per-frame update, called by the editor’s process loop.

When playing and not paused, swaps game input state into the Input singleton, processes the game tree, then restores editor input. This lets game scripts use Input.is_action_pressed() etc. transparently.

forward_input_to_game(event_type: str, **kwargs) → None

Forward an input event from the viewport to the game’s isolated Input.

Called by the editor when the user interacts within the viewport during play mode. Events are buffered in the game’s input state and become visible to game scripts on the next update() call.

Also queues a corresponding ui_input() call on the game tree so that UI widgets (buttons, text fields, etc.) receive properly routed events with focus, hover, and hit-testing.

Args: event_type: One of "key", "mouse_button", "mouse_move", "scroll", "char". **kwargs: Event-specific data (see below).

Key events: key=int, pressed=bool, key_name=str (optional) Mouse button: button=int, pressed=bool Mouse move: x=float, y=float Scroll: dx=float, dy=float Char events: char=str

should_route_input_to_game() → bool

Return True when viewport input events should be forwarded to the game.

Editor-global shortcuts (F5/F6/F7) are always processed by the editor regardless of this flag.

property game_tree: simvx.core.SceneTree | None

The game’s isolated SceneTree, or None when not playing.

property game_input: simvx.editor.play_mode._GameInputState | None

The game’s isolated input state, or None when not playing.

property game_texture_id: int | None

Bindless texture ID of the game viewport, or None if not available.

Returns a valid texture ID when the game viewport renderer is active and ready. The viewport panel checks this to decide whether to display a GPU-rendered game view or fall back to wireframe.

property game_viewport

The GameViewportRenderer instance, or None.

create_game_viewport(engine, width: int, height: int) → None

Create the offscreen game viewport renderer.

Called by Root when play mode starts and a graphics engine is available.

resize_game_viewport(width: int, height: int) → None

Resize the offscreen game viewport.

destroy_game_viewport() → None

Destroy the offscreen game viewport renderer.

get_active_camera() → simvx.core.Camera3D | None

Return the camera that should drive the viewport.

During play mode the game’s own Camera3D is used. Outside of play mode the editor’s orbit camera is returned.

get_border_colour() → tuple[float, float, float, float] | None

Return a viewport border colour indicating the current play state.

• Green (0.2, 0.8, 0.2, 1.0) – game is running.

• Orange (1.0, 0.6, 0.0, 1.0) – game is paused.

• None – editor is in normal (stopped) mode.

property elapsed_time: float

Seconds elapsed since play mode started.

property frame_count: int

Number of frames processed since play mode started.

property is_active: bool

Convenience: True when the game is playing (paused or not).