Scenes API

The scenes module (tuix.core.scenes) manages scene creation, destruction, and clearing.

scenes.init_scene(name)

from tuix.core import scenes

result = scenes.init_scene(b"main")

Parameter	Type	Description
name	bytes	Unique scene name

Returns	Description
int	0 on success, 1 if scene name already exists

Creates a new scene with the given name. Scenes use exponential growth for their internal buffer arrays (initial capacity 4, doubling on overflow). Duplicate names are rejected.

scenes.free_scene(name)

scenes.free_scene(b"main")

Parameter	Type	Description
name	bytes	Scene name to destroy

Destroys a scene and frees all its buffers and associated memory. The scene cannot be used after this call.

scenes.clear_scene(name)

scenes.clear_scene(b"main")

Parameter	Type	Description
name	bytes	Scene name to clear

Frees all buffers in the scene but keeps the scene structure allocated. Use this to remove all widgets from a scene without destroying the scene itself. New widgets can be added to the scene after clearing.

Example: Scene Switching

from tuix.core import scenes, registry

# Create two scenes
scenes.init_scene(b"menu")
scenes.init_scene(b"game")

# Start with menu
registry.registry.current_scene_name = b"menu"

# ... create widgets in both scenes ...

# Switch to game scene (instant, next frame renders it)
registry.registry.current_scene_name = b"game"

# Later, clean up
scenes.free_scene(b"menu")
scenes.free_scene(b"game")