Scenes and the editor
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
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
--commandsdoes.
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. Runhz/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.