# Scenes and the editor

> Levels are text files of entities, and the editor is code in your game that edits them while it runs.

A scene is a set of entities saved to a file. There's no per-type save code: every reflected component on an entity tagged `SceneEntityTag` is saved and loaded by the same generic code. Add a field to a component, and it's in your scenes.

## Loading a scene

Loading the level:

```
SceneSystem scenes;
scene_system_create(&scenes, world, assets, &alloc);
SceneHandle level = scene_load_file(&scenes, "my_game/main.hzt");
```

Loading is asynchronous: the entities appear a few frames later, once their assets are in. Systems don't care, they just start matching when the entities exist. `scene_unload` removes the scene's entities again.

Scenes are saved as `.hzt` text: a small manifest plus chunks of entities. They diff well in git, and you can edit them by hand.

## The editor

Kaigen doesn't have an editor application. The editor is code that runs inside your game, on top of the same world, so what you edit is the game itself, running.

The templates already have it wired up: press **F1** to open it and **F5** to save the scene. In it you get:

- a hierarchy of the scene's entities and an inspector for every reflected component,
- move, rotate and scale gizmos (**W**, **E**, **R**), with undo and redo,
- an asset browser and a console,
- a command prompt that runs the same commands `--commands` does.

The editor is made of parts (`ecs_editor_default_init` puts all of them together), so you can also build your own tools out of them: a level editor for your game, a tuning panel, a material editor. See `hz/src/engine/ecs/ecs_editor/`.

## Authored and runtime data

Saving writes what the components hold *right now*. If a system is animating a door when you press save, the half-open door is what's saved. So keep the two apart:

- The authored values (what the designer sets) go in a reflected component that's saved.
- Runtime state (timers, things you computed, handles to loaded assets) goes in its own component, registered with `scene_register_not_saveable`.

The template does this with its `SolidBox` tag: the scene only says "this entity is a solid box", and a system adds the physics collider when the entity appears.

## Worth knowing

- Saving writes the `.hzt`. Run `hz/hzbuild cook` (or any build) to cook it before the next run picks it up.
- A component that isn't reflected is silently dropped from the scene.
- Handles (to models, materials, other assets) are never saved. Save the asset path, and have a system turn it into a handle after loading.
- When you add a field to a component, existing scenes load it as zero.

The API is in `hz/src/engine/scene/scene.h`.
