Engine API

The engine module (tuix.core.engine) provides three functions that control the lifecycle of the TUIX runtime.

engine.init()

from tuix.core import engine

result = engine.init()

Initializes the C core and the global registry. This is a two-phase call: tuix_init() followed by tuix_init_registry(). Must be called before any other TUIX operation.

engine.main_loop()

engine.main_loop()

Executes one frame of the rendering pipeline. Call this in a loop to drive the UI. Each call performs the following steps in the C core:

1. Read terminal dimensions (detect resize)
2. Commit pending batch commands
3. Cache active scene pointer (avoids string comparison per frame)
4. Execute subcycle handlers for all enabled widgets
5. Resolve geometry for each widget buffer
6. Call on_resize if terminal dimensions changed
7. Call build_content for each widget that needs redraw
8. Composite scene buffers into the final framebuffer
9. Stream-render changed rows to the terminal

engine.shutdown()

engine.shutdown()

Shuts down the engine and destroys the global registry. Frees all scenes, buffers, subcycles, and builders. Destroys the cross-platform lock. Call this as the last TUIX operation.

Typical Usage

from tuix.core import engine, builders

# Startup
engine.init()
builders.register_standard()

# ... create scenes, widgets, start input ...

# Render loop
while running:
    engine.main_loop()

# Shutdown
engine.shutdown()