Lua Runtime API

Use the Lua runtime API to read compositor state, handle events, and request session actions from a shell integration.

The supervised Lua runtime is available in the standalone Gnoblin session. Its API version is 1.93 in the current source. Callback code runs outside Mutter's compositor thread; keep event callbacks short and nonblocking.

API domains

• Windows: live window objects, window actions, menu requests and grants.
• Find objects: select windows, workspaces, outputs and other objects by field or by predicate.
• Focus and activation: focus policy, history, activation tokens, and trusted contexts.
• Workspaces: state and operations.
• Outputs: display outputs, modes, and renderer state.
• Idle watches: run code when the session has had no input for a set time.
• Overrides: layer a setting or a window effect over the configuration, and take it back.
• Layer surfaces: shell surface snapshots and policy.
• Input: devices, sources, and orientation lock.
• Input handlers: handle local pointer, keyboard, and gesture events.
• Keyboard grabs: take every key for a shell, with composed text and a lease that expires.
• Grants: the proof of a user gesture that focus, move, resize, snap and text insertion need.
• Text insertion: insert text into a focused Wayland client.
• Window snapping: arrange a window from a trusted grant.
• Tablet-pad help: receive tablet help requests.
• Keyboard shortcuts: actions, capture, and bindings.
• Launch feedback: track application launch feedback.
• Session and runtime health: reload, session, and worker state.
• Privacy and location: privacy state and location policy.
• Authentication prompts: polkit authentication requests.
• Keyring and GPG prompts: secret prompts.
• Appearance and animations: color scheme and animation controls.
• Shared types and errors and results.
• Console: inspect the session with gnoblinctl lua.

Shared conventions

Read-only calls return live objects or detached snapshots. Runtime mutations return an Operation handle and complete asynchronously. See Operations, errors and timers and shared runtime types.

Subscribe with gnoblin.on(name, callback), or gnoblin.once(name, callback) for one event. See the event reference.

The local socket protocol for non-Lua clients is documented in the compositor bridge. For command-line use, see gnoblinctl.

Runtime identity and settings

gnoblin.settings is an immutable snapshot of active configuration values. Setting names use public snake_case, and revision identifies the committed snapshot. It becomes available after the initial configuration commits.

local focus_mode = gnoblin.settings.window_management.focus_mode
print(focus_mode, gnoblin.settings.revision)

gnoblin.settings.override(path, value) layers a value over one committed setting without changing this snapshot. See overrides.

gnoblin.snapshot() returns a detached copy of the configuration that the files loaded so far have built. It works only while the config loads; at run time it raises an error. Use gnoblin.settings to read committed settings.

gnoblin.config is not a settings table. It holds path(), default() and restore_default(), and assigning to it raises an error. Declare settings with gnoblin.configure.

At run time, the declaration calls return an Operation that succeeds when the compositor commits the change. These are gnoblin.configure, gnoblin.window_rule and gnoblin.animation.

gnoblin.version() returns an immutable record with string fields gnoblin, gnome, mutter, lua, api, git_remote, git_sha, and build_id. Missing values are returned as "unknown". User information, query strings, and fragments are removed from remote URLs.

Gnoblin reads share/gnoblin/version.ini. Set GNOBLIN_VERSION_METADATA_FILE to select another file. If it is unset or unreadable, Gnoblin checks the executable's installation prefix and then the system XDG data directories.