regolith-ui/docs/dd.md

Regolith

Regolith is a retained mode GUI framework written in C99. It is built for native desktop applications and for game user interfaces, and it compiles to Linux, Windows, macOS, and WebAssembly. It uses no webview and no web backend.

Goals

• A clean C API that other languages such as Odin and Zig can bind directly.
• A retained document tree that loads from disk.
• Lua as the document language and as a full runtime API, so an application can be written entirely in Lua after initialization.
• Easy initialization, with a small number of calls to get a window and a document on screen.
• Independence from any single platform or renderer.

Inspiration

RmlUi is the main inspiration. Its document model, styling separation, data binding, animations, and event bubbling are the parts I want. Regolith aims for those ideas with a C API and a simpler event model. HTML and CSS parity is not a goal.

Architecture

Regolith is split into layers. Each layer depends only on the ones below it.

• core: node tree, style resolution, events, data bindings, animation, and text. Pure C99. No Lua types and no Clay types appear in its public API.
• layout adapter: the only code that touches Clay. It walks the retained tree each frame, emits Clay calls, and reads back computed layout.
• lua module: the document loader and the Lua API. It is a thin layer over the C API.
• backend interface: a struct of function pointers defined in the main header. It creates and updates textures, draws batches of colored and textured quads, and sets the scissor rect.
• default backend: SDL3 and OpenGL.
• null backend: records the quad list instead of drawing, used for headless tests.

The C API is the source of truth. Every capability exists in C first, and the Lua binding exposes it without adding behavior of its own.

Dependencies

All dependencies are vendored in third_party/ and built by Regolith's own CMake, so native and WASM builds use identical versions.

• Lua 5.4 for documents and scripting
• Clay for layout and render commands
• stb_truetype and stb_rect_pack for fonts and atlas packing

SDL3 is the only external dependency, and only the default backend uses it.

Layout

Clay provides layout. Regolith exposes a Clay-flavored property vocabulary (sizing, padding, gap, align, direction). Every node is a box with a direction. Node types use Godot-style names such as Panel, Label, Button, HBox, VBox, and ScrollContainer, where HBox and VBox are shorthand for a box with a fixed direction.

Text

The core owns all text handling. It loads fonts, caches glyph metrics, packs glyphs into a single-channel atlas, and measures strings for Clay. The backend receives the atlas as a texture and draws glyphs as textured quads. Rasterization happens at logical size multiplied by display scale, so the font API carries a scale factor from the start. The text module sits behind a small interface so a shaper can replace it later. Shaping, bidirectional text, and color emoji are out of scope for the first versions.

Rendering

The core never calls a backend. Each frame rg_render returns a draw list made of texture operations (create, update region, destroy) followed by batches of colored and textured quads with scissor rects. A backend is any code that consumes that list. The SDL3 and OpenGL backend is the default, and the null backend records the list for headless tests. A WASM host can consume the list from JavaScript. The shipped backends share a small convenience interface, and the core does not depend on it.

Viewport and scale

All API coordinates are logical pixels. The host calls rg_set_viewport(ctx, w, h, scale) when the window resizes or the display scale changes. A scale change invalidates the glyph atlas and glyphs are rasterized again at the new size.

Documents

Documents are Lua files. Node constructors such as VBox, Label, and Button return plain descriptor tables containing a type, properties, and children. A separate step realizes the descriptor tree into live nodes through the C API. Descriptors are pure data, which keeps them easy to print and debug and allows hot reload to reconcile a new tree against the live one by id or key.

Each document runs in its own _ENV that provides the node constructors and helpers. A document is free to contain arbitrary Lua logic, including frontend-only behavior and calls to the host application. The same _ENV mechanism provides sandboxing, which is an option at initialization. A sandboxed state omits io, os, debug, and arbitrary load, and installs an instruction-count hook to stop runaway scripts.

Both authoring surfaces exist. The call style (VBox { Label { text = "Hi" } }) is the primary form. The builder style (create a node, set properties, append it to a parent) is the same C API exposed to Lua and is used for dynamic content.

Styling

Styles are Lua tables with a small selector engine. Supported selectors are type, class, id, the state pseudo-classes :hover, :focus, :active, and :disabled, and a child combinator. The cascade orders by specificity and then declaration order. There is no !important. Components are Lua functions that return descriptor tables, and shared appearance comes from classes. Style resolution runs only when classes, state, or tree structure change.

Data binding

A binding is a callback with userdata attached to a node property. The data model is a keyed store with version counters, and a binding re-evaluates only when a key it depends on has a newer version than its last evaluation. In Lua the model is a proxy table whose __newindex bumps the version. Dependencies are declared as explicit keys. Automatic dependency tracking is a later improvement.

Animation

Property changes can transition over time, similar to CSS transitions. The retained tree stores the previous value, and the interpolated value is fed into layout each frame. Keyframes and coroutine-driven sequences come later.

Events

Events bubble and have no capture phase. The fixed set is click, hover enter, hover leave, focus, blur, change, key, and custom named events. A handler is either a Lua function or a string name. A string name pushes an event into a polled queue, so C, Zig, and Odin users consume events without callbacks across the FFI boundary.

API conventions

• One public header, regolith.h, with the implementation in ordinary .c files compiled into a static or shared library.
• regolith_lua.h and regolith_sdl3.h are separate optional headers, so lua_State and SDL types never appear in the main header.
• Fixed-width integer types, plain structs, no bitfields, no variadics, and no static inline in the public header.
• Every public function is marked RG_API and prefixed with rg_.
• Enums are an int typedef with named constants.
• Nodes are referenced by opaque handles made of an index and a generation, never by raw pointers.
• The user can supply an allocator, and internal allocation uses arenas.

Context and ownership

All state lives in an rg_context, which is created with rg_create and passed explicitly to every call. There are no hidden globals. A context owns its node tree, style data, data model, event queue, text atlas, layout state, and, when the Lua module is attached, its own lua_State. This allows headless tests, multiple windows, and multiple Lua states in one process. The user-supplied allocator is set in the config struct at creation and is used for all internal allocation, including Lua and Clay. A context is not thread safe. It is used from one thread at a time, and separate contexts are fully independent.

Main loop

The host owns the main loop. Regolith never blocks and never creates a window loop of its own. Each frame the host pushes input events, calls rg_update with a delta time, then calls rg_render to get a draw list that it hands to a backend. This is the same shape on native and on WASM, where the browser calls the host back once per frame.

Input

The core accepts platform-neutral input events and never polls a platform API. The event kinds are pointer move, pointer button, scroll, key, and text. Key codes are Regolith's own enum and the SDL3 backend translates into them. Gamepad navigation will be added as a semantic layer (up, down, left, right, accept, cancel) that drives focus movement, so a game can map any device to it.

Errors and logging

Functions that can fail return an int status where zero is success and negative values are errors. rg_last_error(ctx) returns the message for the most recent failure on that context. The config carries a log callback, a log level, and a userdata pointer. The default callback writes to stderr and the default level is trace, so logging is verbose until I lower it. Lua errors such as syntax errors and handler failures are logged and never replace the live tree, so a broken save during hot reload leaves the last good tree on screen.

Testing

ctest runs the smoke tests. The core smoke test installs a counting allocator and fails if any bytes are live after rg_destroy. Every allocation, including Lua's, goes through the context allocator.

Build and environment

The build system is CMake with Ninja. Development happens on NixOS using direnv and flakes, and the devShell provides CMake, Ninja, pkg-config, clang, clang-tools, SDL3, Emscripten, and lua-language-server. Emscripten's cache directory is set to .emscripten-cache inside the project. WASM builds go through emcmake into build-wasm/. Sources live in a flat src/ with no generated files, so Zig and Odin users can compile them with their own toolchain.

Milestone 1

A main.lua builds a VBox of Label and Button nodes. A stylesheet with classes and a :hover state styles them. Layout runs through Clay and draws through the SDL3 and OpenGL backend with stb_truetype text. A button click fires both a Lua handler and a named event in the polled queue. One transition eases a button background on hover. A data-bound label shows a counter that the button increments.

Text inputs and scrolling follow in milestone 2, along with focus handling.

Open questions

• Node handle format.
• Property system: how properties are named, typed, and stored.