Scene files

a node tree saved as Python source and loaded back

▶ Run in browser

Tags: basics scene-files serialisation change-scene

A small level is built in code, serialised to a .py scene file with SceneFile.from_runtime(root).save(path), and the emitted source is shown on screen. A keypress runs load_scene(path) and switches to the loaded tree with tree.change_scene(...); a second in-code scene then shows how state crosses a scene switch. Everything is written under tempfile.mkdtemp().

What it demonstrates

• SceneFile.from_runtime(root) emits a complete .py source file for a live tree; .save(path) writes it atomically. Scenes ARE Python source, so the file on disk is readable, diffable and hand-editable.

• load_scene(path) runs that file and instantiates its primary Node subclass. The emitted class holds structure only, so behaviour (input handling, HUD) is composed on by attaching a controller child before the switch.

• self.tree.change_scene(node) takes an INSTANTIATED Node: there is no path-based switch and no App.tree. Constructor arguments on the new root are how state (here: a load counter and the file path) crosses scenes.

• All file I/O happens under tempfile.mkdtemp(); the repo is never written to.

Controls: SPACE - advance: save/show -> load and switch -> in-code summary -> back ESC - Quit

Run: uv run python examples/features/basics/scene_files.py Headless self-check: uv run python examples/features/basics/scene_files.py –test

Source

"""Scene files: a node tree saved as Python source and loaded back

A small level is built in code, serialised to a ``.py`` scene file with
``SceneFile.from_runtime(root).save(path)``, and the emitted source is shown on
screen. A keypress runs ``load_scene(path)`` and switches to the loaded tree
with ``tree.change_scene(...)``; a second in-code scene then shows how state
crosses a scene switch. Everything is written under ``tempfile.mkdtemp()``.

# /// simvx
# tags = ["basics", "scene-files", "serialisation", "change-scene"]
# web = { root = "BuilderScene", width = 960, height = 540, responsive = true }
# ///

## What it demonstrates

- `SceneFile.from_runtime(root)` emits a complete `.py` source file for a live
  tree; `.save(path)` writes it atomically. Scenes ARE Python source, so the
  file on disk is readable, diffable and hand-editable.
- `load_scene(path)` runs that file and instantiates its primary Node subclass.
  The emitted class holds structure only, so behaviour (input handling, HUD) is
  composed on by attaching a controller child before the switch.
- `self.tree.change_scene(node)` takes an INSTANTIATED Node: there is no
  path-based switch and no `App.tree`. Constructor arguments on the new root
  are how state (here: a load counter and the file path) crosses scenes.
- All file I/O happens under `tempfile.mkdtemp()`; the repo is never written to.

Controls:
  SPACE - advance: save/show -> load and switch -> in-code summary -> back
  ESC   - Quit

Run: uv run python examples/features/basics/scene_files.py
Headless self-check: uv run python examples/features/basics/scene_files.py --test
"""

import tempfile
from pathlib import Path

from simvx.core import Input, Key, Node2D, SceneFile, Text2D, Vec2, load_scene
from simvx.graphics import App

WIDTH, HEIGHT = 960, 540

#: How many lines of the emitted source the builder screen shows before truncating.
MAX_SOURCE_LINES = 16

#: The stars the level is built from: (x, y, font_scale, colour).
STARS = [
    (240, 250, 3.0, (0.45, 0.80, 1.00, 1.0)),
    (430, 330, 2.0, (1.00, 0.55, 0.45, 1.0)),
    (560, 220, 4.0, (0.70, 1.00, 0.55, 1.0)),
    (720, 310, 2.5, (0.95, 0.80, 0.35, 1.0)),
]

_save_dir: Path | None = None


def save_dir() -> Path:
    """One throwaway directory per run, so nothing lands in the repo or cwd."""
    global _save_dir
    if _save_dir is None:
        _save_dir = Path(tempfile.mkdtemp(prefix="simvx_scene_files_"))
    return _save_dir


def build_level() -> Node2D:
    """The tree that gets serialised: pure data, Text2D nodes draw themselves.

    Text2D is used for every visible node because it is fully declarative
    (text, position, scale, colour are all Properties the emitter can write);
    the loaded scene therefore renders with no code of its own.
    """
    level = Node2D(name="Level")
    level.add_child(
        Text2D(
            name="Banner",
            text="Every node on this screen was read back from level.py",
            position=Vec2(WIDTH / 2, 100),
            font_scale=1.5,
            align="centre",
            colour=(1.0, 0.85, 0.35, 1.0),
        )
    )
    for i, (x, y, scale, colour) in enumerate(STARS):
        level.add_child(
            Text2D(name=f"Star{i}", text="*", position=Vec2(x, y), font_scale=scale, colour=colour)
        )
    return level


class BuilderScene(Node2D):
    """Builds the level in code, saves it as a scene file, and shows the source."""

    input_actions = {"advance": [Key.SPACE], "quit": [Key.ESCAPE]}

    def __init__(self, loads: int = 0, **kwargs):
        self._loads = loads
        super().__init__(**kwargs)

    def on_ready(self):
        # from_runtime emits source for the live tree; save writes it out and
        # returns the path. The level is built fresh each visit, never mounted
        # here: the stars only appear on screen once the FILE is loaded back.
        self._path = SceneFile.from_runtime(build_level()).save(save_dir() / "level.py")
        self._source_lines = self._path.read_text(encoding="utf-8").splitlines()

    def load_and_switch(self):
        # load_scene runs the file and instantiates its primary Node subclass.
        loaded = load_scene(self._path)
        # The emitted class is structure only, so behaviour is composed on:
        # a controller child gives the data scene input handling and a HUD.
        loaded.add_child(LoadedControls(self._loads + 1, self._path))
        # change_scene takes the instance itself; there is no switch-by-path.
        self.tree.change_scene(loaded)

    def on_update(self, dt: float):
        if Input.is_action_just_pressed("advance"):
            self.load_and_switch()
        elif Input.is_action_just_pressed("quit"):
            self.app.quit()

    def on_draw(self, renderer):
        renderer.draw_text("Scene files: the emitted source of the level tree", (20, 16), scale=2, colour=(1, 1, 1))
        renderer.draw_text(f"saved to {self._path}", (20, 52), colour=(0.55, 0.6, 0.7))
        shown = self._source_lines[:MAX_SOURCE_LINES]
        for i, line in enumerate(shown):
            renderer.draw_text(line[:100], (20, 88 + i * 24), colour=(0.55, 0.9, 0.6))
        hidden = len(self._source_lines) - len(shown)
        if hidden > 0:
            renderer.draw_text(f"... {hidden} more lines", (20, 88 + len(shown) * 24), colour=(0.45, 0.5, 0.55))
        renderer.draw_text(
            "SPACE: load_scene(path) and change_scene to it    ESC: quit",
            (20, HEIGHT - 30),
            colour=(0.6, 0.6, 0.6),
        )


class LoadedControls(Node2D):
    """Behaviour composed onto the loaded scene: HUD and the next switch."""

    def __init__(self, loads: int, path: Path, **kwargs):
        self._loads = loads
        self._path = path
        super().__init__(**kwargs)

    def to_summary(self):
        # Constructor arguments are how state crosses a scene switch: the load
        # counter and the file path ride into the next root here.
        self.tree.change_scene(SummaryScene(self._loads, self._path))

    def on_update(self, dt: float):
        if Input.is_action_just_pressed("advance"):
            self.to_summary()
        elif Input.is_action_just_pressed("quit"):
            self.app.quit()

    def on_draw(self, renderer):
        renderer.draw_text("This root came from load_scene(...)", (20, 16), scale=2, colour=(1, 1, 1))
        renderer.draw_text(
            "The banner and stars are Text2D nodes deserialised from disk; this HUD is a",
            (20, 52),
            colour=(0.55, 0.6, 0.7),
        )
        renderer.draw_text(
            "controller child attached to the loaded root before change_scene.",
            (20, 74),
            colour=(0.55, 0.6, 0.7),
        )
        renderer.draw_text(
            "SPACE: switch to an in-code scene, carrying state via constructor args    ESC: quit",
            (20, HEIGHT - 30),
            colour=(0.6, 0.6, 0.6),
        )


class SummaryScene(Node2D):
    """In-code scene whose constructor arguments arrived from the previous root."""

    input_actions = {"advance": [Key.SPACE], "quit": [Key.ESCAPE]}

    def __init__(self, loads: int = 0, path: Path | None = None, **kwargs):
        self._loads = loads
        self._path = path
        super().__init__(**kwargs)

    def back_to_builder(self):
        # The counter keeps riding: the builder shows the next load as loads+1.
        self.tree.change_scene(BuilderScene(self._loads))

    def on_update(self, dt: float):
        if Input.is_action_just_pressed("advance"):
            self.back_to_builder()
        elif Input.is_action_just_pressed("quit"):
            self.app.quit()

    def on_draw(self, renderer):
        renderer.draw_text("In-code scene: state carried by constructor args", (20, 16), scale=2, colour=(1, 1, 1))
        renderer.draw_text(
            f"level.py has been loaded {self._loads} time(s) this run.",
            (20, 70),
            colour=(0.95, 0.8, 0.35, 1.0),
        )
        renderer.draw_text(f"file: {self._path}", (20, 100), colour=(0.55, 0.6, 0.7))
        renderer.draw_text(
            "change_scene(node) takes an instantiated Node, so passing values to the new",
            (20, 150),
            colour=(0.55, 0.9, 0.6),
        )
        renderer.draw_text(
            "root's constructor is the whole state-transfer mechanism: no globals needed.",
            (20, 172),
            colour=(0.55, 0.9, 0.6),
        )
        renderer.draw_text(
            "SPACE: back to the builder (the counter rides along)    ESC: quit",
            (20, HEIGHT - 30),
            colour=(0.6, 0.6, 0.6),
        )


def _selftest() -> bool:
    """Headless: round-trip the scene file and walk the demo's own scene flow."""
    import shutil

    from simvx.core import SceneTree

    ok = True

    def check(label: str, passed: bool, detail: str) -> None:
        nonlocal ok
        ok = ok and passed
        print(f"{'ok  ' if passed else 'FAIL'} {label}: {detail}")

    # 1. Save: the emitted file is real Python source describing the tree.
    original = build_level()
    path = SceneFile.from_runtime(original).save(save_dir() / "level.py")
    text = path.read_text(encoding="utf-8")
    check("the scene file exists on disk", path.is_file(), str(path))
    check(
        "the source declares the primary class and its children",
        "class Level(" in text and "Banner" in text and "Star0" in text,
        f"{len(text.splitlines())} lines emitted",
    )

    # 2. Load: the round-tripped tree matches the one that was saved.
    loaded = load_scene(path)

    def snapshot(node):
        return sorted(
            (c.name, c.text, round(c.position.x, 3), round(c.position.y, 3), c.font_scale, tuple(c.colour))
            for c in node.children
        )

    check(
        "load_scene rebuilds the identical tree",
        type(loaded).__name__ == "Level" and snapshot(loaded) == snapshot(original),
        f"{len(loaded.children)} children round-tripped",
    )

    # 3. The demo's own flow, on a headless SceneTree: builder -> loaded ->
    # summary -> builder, with the load counter riding the constructor args.
    tree = SceneTree()
    builder = BuilderScene(name="Builder")
    tree.set_root(builder)
    tree.tick(1 / 60)
    check("the builder saved the file in on_ready", builder._path.is_file(), str(builder._path))

    builder.load_and_switch()
    tree.tick(1 / 60)
    controls = [c for c in tree.root.children if isinstance(c, LoadedControls)]
    check(
        "change_scene mounted the loaded instance",
        type(tree.root).__name__ == "Level" and len(controls) == 1,
        f"root is {type(tree.root).__name__} with {len(tree.root.children)} children",
    )

    controls[0].to_summary()
    tree.tick(1 / 60)
    check(
        "constructor args carried state into the in-code scene",
        isinstance(tree.root, SummaryScene) and tree.root._loads == 1 and tree.root._path == builder._path,
        f"root is {type(tree.root).__name__}, loads={getattr(tree.root, '_loads', None)}",
    )

    tree.root.back_to_builder()
    tree.tick(1 / 60)
    check(
        "the counter rides back into the builder",
        isinstance(tree.root, BuilderScene) and tree.root._loads == 1,
        f"loads={getattr(tree.root, '_loads', None)}",
    )

    shutil.rmtree(save_dir(), ignore_errors=True)
    print("SELFTEST:", "PASS" if ok else "FAIL")
    return ok


if __name__ == "__main__":
    import sys

    if "--test" in sys.argv:
        sys.exit(0 if _selftest() else 1)
    App(title="Scene Files", width=WIDTH, height=HEIGHT).run(BuilderScene())