Rendering, FPS & Frame Scheduling
How Koya decides when to render, how FPS is chosen, and how Wayland frame callbacks are used.
Render-on-change (what it means for you) #
Koya automatically detects when your UI visually changes and only redraws then. If your JS updates text, sprites, layout, animations, colours, etc., Koya will render. If nothing changes, it won't burn frames.
Debug logs (enable --verbose):
[ui-hash]per-root element when its hash changes[win-hash]when the window's combined hash changes[win-render] reason=forcedfor non-hash reasons (e.g., first frame/resize)
How frames are scheduled #
Koya uses Wayland frame callbacks under the hood. After a present, it asks the compositor to call back for the next frame. If your UI doesn't change, Koya won't present a new frame. Input events still flow even when nothing is redrawn.
Dynamic FPS #
Koya adapts to your displays. It targets the highest refresh rate across all Koya windows so animations look smooth on high-Hz monitors (120/144/240 Hz+), while still not rendering when nothing changes.
Tips for JS authors #
- Update your UI state normally (e.g., set text, sprite frames, layout). Koya tracks changes automatically.
- Animations advance on each frame; if an element is animating, frames will be produced.
- For static bars/dashboards, Koya sleeps between changes — good for battery and fans.
Notes #
- Resizes and scale changes always trigger a redraw.
- Input continues even when no redraws happen.