# Scene files

a node tree saved as Python source and loaded back

```{raw} html
<a class="example-run-button" href="../demos/features_basics_scene_files.html">▶ Run in browser</a>


```

**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

```{literalinclude} ../../examples/features/basics/scene_files.py
:language: python
:linenos:
```