Skip to content

Core Concepts for Cereal Client Script Development

1. Script Structure

All Cereal client scripts are built around a core lifecycle with three main functions:

  • onStart(configuration, provider): Called when the script begins execution
  • execute(configuration, provider, statusUpdate): The main loop that runs repeatedly until completion
  • onFinish(configuration, provider): Final cleanup when script execution ends

2. Script Configuration

Scripts define their settings through a configuration interface that:

  • Extends ScriptConfiguration
  • Contains methods annotated with @ScriptConfigurationItem
  • Supports various data types: String, Boolean, Int, Float, Double, Enums, and nullable versions
  • Can define per-task values using valuePerTask = true
  • Can use custom state modifiers to dynamically control configuration properties

Example:

interface MyConfiguration : ScriptConfiguration {
    @ScriptConfigurationItem(
        keyName = "targetUrl",
        name = "Target URL",
        description = "The URL to process",
        isScriptIdentifier = true
    )
    fun targetUrl(): String
}

3. Component System

Scripts have access to various components through the ComponentProvider:

  • Logger: For debug and trace logging
  • Notification: Sending notifications (including Discord integration)
  • Preference: Persistent storage for script data
  • ScriptLauncher: Starting child scripts
  • UserInteraction: Display UI elements and gather user input
  • License: License validation utilities

Example:

// Log information
provider.logger().info("Processing started")

// Store persistent data
provider.preference().setInt("lastRunCount", count)

// Send notification
val notification = notification("Task completed") {
    title = "Completion Notice"
}
provider.notification().sendNotification(notification)

4. Execution Flow Control

Scripts use the ExecutionResult return value to control their execution:

  • Loop: Continue execution after a specified delay
  • Success: End execution with a success message
  • Error: End execution with an error message

Example:

// Continue execution after 1 second
return ExecutionResult.Loop("Processing in progress...", 1000)

// End successfully
return ExecutionResult.Success("Task completed successfully")

// End with error
return ExecutionResult.Error("Failed to connect to server")