Engine API

The engine module owns process-level initialization, shutdown, one-frame execution, loop stats, and mouse capture.

Method	How to use it	Why it exists
engine.init() -> int	Call once before registering builders, creating scenes, or creating objects.	Initializes the native engine and registry so the C/Cython core is ready.
engine.shutdown() -> int	Call during cleanup after stopping input and finishing the render loop.	Releases process-level native state and registry resources.
engine.main_loop() -> None	Call once per frame in your application loop.	Runs input routing, layout, builder updates, compositing, and terminal rendering.
engine.get_core_loop_stats() -> dict	Read after frames when profiling or debugging frame behavior.	Exposes timing and state counters without poking native internals.
engine.mouse_capture_begin(uid: int) -> int	Call when a widget starts drag/capture interaction.	Keeps mouse events routed to the same UID across pointer movement.
engine.mouse_capture_end(uid: int) -> int	Call when the captured drag or pointer interaction ends.	Releases capture so normal hitmap/focus routing resumes.
engine.get_mouse_capture_uid() -> int	Use while debugging or coordinating widgets that may capture the mouse.	Reports which UID currently owns captured mouse routing.

Loop Stats Keys

get_core_loop_stats() may include frame_counter, batch_commit_ms, cache_refresh_ms, input_ms, routing_ms, buffer_ms, composite_ms, python_commit_ms, total_ms, composite_skipped, composite_forced, traversal_cache_hit, traversal_cache_miss, size_changed, has_input, has_scene, and has_subcycles.

Typical Usage

engine.init()
builders.register_standard()
scenes.init_scene('Main')
scenes.select_scene('Main')
input.listen()

while running:
    engine.main_loop()

input.stop()
engine.shutdown()