Getting Started with TUIX Core

This guide shows the standard v0.5 flow: initialize the engine, register builders, create/select a scene, start input for interactive apps, create widgets, run frames, and clean up.

Recommended Reading Order

1. Install TUIX Core and verify imports.
2. Build the first widget example.
3. Read Widgets, Layout API, and Input Handling before composing larger screens.

Prerequisites

• Python 3.10 or newer.
• A terminal with ANSI escape support.
• Cython 0.29 or newer and a C compiler only when building from source.

Import Pattern

from tuix.core import engine, builders, scenes, registry, objects, buffers, input

Standard Workflow

1. Call engine.init().
2. Call builders.register_standard() before creating objects.
3. Create a scene with scenes.init_scene("Main") and select it with scenes.select_scene("Main") or registry.registry.current_scene_name.
4. Start input.listen() for interactive widgets.
5. Create objects with objects.create_object(...).
6. Run engine.main_loop() once per frame.
7. Stop input and shut the engine down during cleanup.

Minimal Example

from tuix.core import engine, builders, scenes, objects, input

engine.init()
builders.register_standard()

scenes.init_scene('Main')
scenes.select_scene('Main')
input.listen()

uid = objects.create_object(builders.TEXT, 'Main', 0.5, 0.1, 0.05, 0.05)
obj = objects.get_object_by_uid(uid)
objects.tuix_text_set_text(obj, 'Hello from TUIX 0.5')
objects.tuix_text_set_fg(obj, 120, 220, 160)

for _ in range(5):
    engine.main_loop()

input.stop()
engine.shutdown()

What Happens Each Frame

• Input is read from native queues and routed to focused, captured, modal, or hitmap-picked widgets.
• Geometry is resolved from proportional modifiers, parent layout results, layout slots, and grid placements.
• Builders update state and provide pixels, often using persistent pixel buffers.
• The compositor clips viewports, builds a hitmap, merges buffers, and the renderer writes terminal-visible differences.