Rhai Scripting Automation
Relevant source files
The following files were used as context for generating this wiki page:
Rhai Scripting Automation is a feature within the Kaleidux project that allows users to automate wallpaper logic and daemon behavior using Rhai, a tiny, cloud-native scripting language for Rust. This system enables high-level customization of wallpaper transitions, playback states, and monitor-specific logic without requiring re-compilation of the core daemon.
The scripting engine is integrated directly into the kaleidux-daemon, where it hooks into the main event loop to execute logic based on timed intervals or initial startup events. It serves as a bridge between user-defined logic and the daemon's internal IPC request system.
Sources: kaleidux-daemon/src/scripting.rs:1-67, README.md:27-35
Architecture and Integration
The scripting system is encapsulated within the ScriptManager struct, which maintains the Rhai execution environment. It is initialized during the daemon's startup sequence and persists throughout the lifecycle of the background service.
Component Structure
The ScriptManager consists of three primary components:
- Engine: The core Rhai engine responsible for evaluating scripts.
- AST: A compiled Abstract Syntax Tree of the loaded script, optimized for repeated execution.
- Scope: A persistent scope that allows variables and state to be maintained between script "ticks."
Sources: kaleidux-daemon/src/scripting.rs:8-12, kaleidux-daemon/src/main.rs:608-615
Data Flow and Execution
The script manager operates via a non-blocking architecture. It uses an asynchronous command channel (mpsc::UnboundedSender) to send requests back to the daemon's main loop. When a script function like next() is called within Rhai, the engine packages this into a kaleidux_common::Request and dispatches it through the channel.
The following diagram illustrates the interaction between the Script Manager and the Daemon:
The Script Manager executes script functions and translates them into internal commands sent via channels.
Sources: kaleidux-daemon/src/scripting.rs:14-43, kaleidux-daemon/src/main.rs:728-732
Scripting API and Functions
The Rhai engine is pre-configured with specific Rust functions exposed to the scripting environment. These functions allow the script to interact with the wallpaper daemon's state and monitor outputs.
Built-in Rhai Functions
| Function | Parameters | Description |
|---|---|---|
print | text: String | Logs a message to the daemon's info log with a [Script] prefix. |
next | output: String | Switches to the next wallpaper. Use "*" for all outputs or a specific monitor name. |
pause | None | Pauses video playback and wallpaper cycling timers. |
resume | None | Resumes video playback and wallpaper cycling timers. |
Sources: kaleidux-daemon/src/scripting.rs:18-40, kaleidux-daemon/src/main.rs:1030-1048
Script Entry Points
The engine looks for two specific function signatures within the user's Rhai script:
init(): Called once when the script is successfully loaded. Used for setup logic.on_tick(): Called repeatedly at a configurable interval defined in the daemon configuration.
Sources: kaleidux-daemon/src/scripting.rs:52-66
Configuration
Automation scripts are enabled and managed via the global configuration file. Users specify the location of their script and how frequently the daemon should poll the script for logic execution.
Configuration Parameters
| Key | Type | Default | Description |
|---|---|---|---|
script-path | Path | None | Absolute path to the .rhai automation script. |
script-tick-interval | Integer | 1 | The interval in seconds between executions of the on_tick function. |
Sources: config.example.toml:44-48, kaleidux-daemon/src/orchestration.rs:94-101
Script Lifecycle Management
The daemon handles the lifecycle of scripts from loading to periodic execution. If a script fails to compile or a function is missing, the daemon logs the error but continues to operate, ensuring that automation failures do not crash the rendering service.
Lifecycle of a Rhai script from initial load to periodic execution within the daemon.
Sources: kaleidux-daemon/src/scripting.rs:45-67, kaleidux-daemon/src/main.rs:728-732
Implementation Example
The implementation of the next function in scripting.rs demonstrates how Rhai calls are mapped to the internal Request enum used throughout Kaleidux:
let tx = cmd_tx.clone();
engine.register_fn("next", move |output: String| {
let (resp_tx, _) = oneshot::channel();
let out = if output == "*" { None } else { Some(output) };
let _ = tx.send((Request::Next { output: out }, resp_tx));
});
Sources: kaleidux-daemon/src/scripting.rs:23-28
Summary: Rhai Scripting Automation provides a flexible, run-time layer for desktop automation in Kaleidux. By exposing core daemon controls (next, pause, resume) to a simple scripting language, the system allows for complex behavior such as time-based wallpaper changes or context-aware transitions without modification of the Rust codebase.