Skip to content

Cereal // Documentation

Getting Started

Installation

  1. Create a new GitHub repository and use the Script-Template repository as a template.
  2. Clone your project: git clone https://github.com/Your-Org/Script-Repo-Name.git
  3. Open the project in your preferred IDE. We recommend using IntelliJ IDEA for easier troubleshooting.

Configuring Template

Update the contents for some several files:

  1. In settings.gradle.kts, update rootProject.name with your scripts name.
  2. In .idea/.name, update the file content to your scripts name.
  3. Update package_name, name, and version in src/main/resources/manifest.json.

Rename the package com.cereal.script.sample to something you prefer. The package name uniquely identifies your script on Cereal and can't be changed after uploading it to the Developer Console.

Usage

  1. The repository contains a SampleScript class, which is the starting point for Cereal to execute your script. Remove any boilerplate code from that class that you don't need and rename the script to something more descriptive. Do the same for SampleConfiguration.
  2. In the onStart function, check if all the necessary information is valid before a script should start. Return true to start the script normally or false to stop the script from running. Reasons for stopping could be an invalid license, invalid user configuration, or anything else that requires validation.
  3. Implement the functionality of your script using the execute function, which requires a ExecutionResult as a return value. ExecutionResult is a sealed class containing multiple sub-values:
    • Loop: Notifies Cereal that the task needs to rerun the execute function with a delay in milliseconds.
    • Success: Notifies Cereal that the task has finished successfully without an error.
    • Error: Notifies Cereal that the task has been finished with an error. All three states can be given a message that will be shown in Cereal as feedback for the user.
  4. In the onFinish function, it's possible to do some last operation before a task is ending. ie: Send out a notification to the user to inform a task has been stopped.
  5. Verify that your script is working properly by running the included test (see TestSampleScript.kt).

Additional Notes

For further assistance and troubleshooting, refer to the Cereal Documentation or reach out to the Cereal community on Discord.

Happy scripting with Cereal!