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.81 in the current source. Callback code runs outside Mutter's compositor thread; keep event callbacks short and nonblocking.

API domains

• Windows: snapshots, window actions, menu and focus contexts.
• Focus and activation: focus policy, history, activation tokens, and trusted contexts.
• Workspaces and monitors: state, operations, and privacy screens.
• Layer surfaces: shell surface snapshots and policy.
• Input: devices, sources, and orientation lock.
• Input handlers: handle local pointer, keyboard, and gesture events.
• Text insertion: insert text into a focused Wayland client.
• Window snapping: arrange a window from a trusted focus context.
• 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.
• Permissions and privacy: policy, grants, privacy, and location.
• 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 detached snapshots. Runtime mutations return an Operation handle and complete asynchronously. See Errors and results and shared runtime types.

Subscribe with gnoblin.events.on(name, callback) or the gnoblin.on alias. 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.snapshot() returns a detached copy of the Lua configuration view. Use gnoblin.settings for immutable reads of committed settings.

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.