Overview

Klive IDE has a scripting system with a JavaScript-like syntax. When you create files with the .ksx extension, the IDE considers them script files and allows you to run them.

Note: The scripting system is new in the IDE and will evolve with every release. Though I strive to keep compatibility with older versions, you may find some breaking changes.

Get acquainted with the scripting system! Follow these steps to create and run your first script:

Open an existing Klive project, or create a new one.
With the New file context menu, add a new script file, myScript.ksx, to the project's root.
After you add it, Klive displays the empty file in the code editor:

Type this code into the editor:

Output.writeLine("Hello from Klive IDE!");

The script window's header has two icons, as the following figure shows. Click the first one (Run this script file) to start the script.

It starts the script and displays its output in a new document, the script output window:

Running the Script

The scripting system uses a compiler to convert the script into an internal format, and then the scripting engine runs the code. The code runs asynchronously, so you can cancel the run even if you create an infinite loop.

A script can run in one of these locations:

The IDE process. Scripts running here access the IDE infrastructure through built-in objects; they can execute complex tasks (such as building the project) that require accessing the project system.
The Emulator process. These scripts can control the emulator and automate it through objects. For example, you can execute the next Z80 instruction, pause, and examine the Z80 register values to search for a particular condition. According to this condition, your script can decide how to go on.

By default, the script runs in the IDE process. You can change the host to the emulator by adding the "emu" string literal at the top of the script. For example, the following code will run in the emulator:

"emu";
Output.writeLine("Hello from Klive IDE!");

Note: Though the script runs in the emulator, it forwards its output to the IDE. You can display and examine the script output in the IDE window.

Script Output

The scripting engine has an output pane in the Tool panel. This pane displays messages related to running scripts, such as starting and completing them. If compiling a script results in an error, the error is displayed here, too:

Each script has a pane displaying its output. When you start a script, the IDE immediately shows its output pane and refreshes it according to the script's output. If you run a script multiple times, each run has its separate output pane.

Let's assume you run this script:

for (let i = 0; i < 1000; i++) {
  Output.writeLine("Message item #" + i);
  delay(100);
}

The script output refreshes the pane as the for-loop generates new output items. In the header, it displays the number of output lines and the status of the script (Running):

You can click the icon buttons in the header to execute a particular task. These icons from the left to right provide these functions:

Stop. You can cancel a running script. The script's state changes to "Stopped".
Open Script File. Clicking this button opens the script file in the code editor.
Clear script output. You can immediately clear the script's output (even if it is still running).
Copy to clipboard. The current script output (plain text) is copied to the clipboard; you can paste it into other apps.
Turn on/off autoscrolling. As the script output appends, the pane scrolls automatically to the bottom. You can use this button to turn this behavior on or off.

Scripting History

The IDE sidebar contains a Scripting tab where you can expand the Scripting History panel to list the scripts run since the IDE started:

Each item represents a run. The first icon indicates the host (the tool icon represents scripts running in the IDE, and the display icon refers to the emulator-hosted scripts). The second icon tells you the status of a particular script.

The script file's name is followed by its running time; the IDE refreshes this information automatically.

When you click an item, the IDE opens the related script output.

Structs Scripting Syntax