Skip to content

Scripting API

Actions are driven by Scripts written in JavaScript. This page is the reference of the objects and functions available to a Script: write your Scripts in the Editor view, then run them as Actions from the Actions view. Before writing your own, check the Scripts library for an existing Script or an example to start from.

Additions made in Kratos v1.11 are marked with (v1.11).

Script header

The first comment lines of a Script define how it appears in Kratos:

// Name : Target in area to OSC
// Category : OSC
// Description : Send an OSC message when a target enters an area
field description
Name Name of the Script
Category Category of the Script, used to group Scripts (see Categories)
Description Short description of what the Script does

Types

type description
Boolean true / false
Integer Whole number
Double Decimal number
String Text
Color A color. It can be set with a hex string such as "#FF0000"
Vector3D Object with x, y, z properties (numbers). It can be set with { x: 1, y: 2, z: 3 } or [1, 2, 3]
Vector2D Object with x, y properties (numbers). It can be set with { x: 1, y: 2 } or [1, 2]

Vector3D and Vector2D can also be created with their constructors:

const v3 = new Vector3D(1, 2, 3)
const v2 = new Vector2D(1, 2)

Positions are in meters and speeds in meters per second, in Kratos world coordinates (see Coordinate systems).

Console

Use the console object to print messages in the Script console:

console.log("Hello", 42)       // Information message
console.warn("Careful")        // Warning message
console.error("Oops")          // Error message
console.debug("Details")       // Debug message
console.assert(x > 0, "x must be positive") // Error message if the condition is false
console.time("t")              // Start a timer...
console.timeEnd("t")           // ...and print the elapsed time
console.count("calls")         // Print how many times this counter was called
console.countReset("calls")    // Reset the counter
console.clear()                // Clear the console

The action object

The action object is the instance of the Action running the Script. You use it to add parameters and to react to the Action's events.

Parameters

Parameters are displayed in the Action and let users configure it without editing the Script. Available parameter types are:

Parameters can only be added at the top level of the Script, when it is loaded, not inside events or callbacks. Each parameter name must be unique inside an Action.

Each add... function takes either a name or a configuration object, and returns the parameter:

const speed = action.addDouble("Speed")

const gain = action.addDouble({
  name: "Gain",
  description: "Output gain",
  value: 1.0,      // Default value
  from: 0,
  to: 2,
  stepSize: 0.1,
  enabled: true,
  visible: true,
})
configuration key description
name Name of the parameter (required)
description Description of the parameter
value Default value
enabled Whether the parameter is enabled (default true)
visible Whether the parameter is visible (default true)
useSwitch Boolean only: use a switch instead of a checkbox
from, to Integer and Double only: minimum and maximum values
stepSize Integer and Double only: step value
enumValues Enum only: list of the possible values

All parameters have the following properties:

property type description access
name string Name of the parameter r
humanName string Label displayed in the interface (the name is used when empty) r/w
description string Description of the parameter r/w
value varies Value of the parameter (not available on Trigger) r/w
enabled boolean Whether the parameter is enabled r/w
visible boolean Whether the parameter is visible r/w
category string Section the parameter is displayed in, see Categories (v1.11) r/w

All parameters (except Trigger) also have an onChange event:

param.onChange((newValue) => {
  // Called when the value of the parameter changes
})

Categories

(v1.11) Give parameters a category to display them in titled sections, which helps with Actions that have many parameters. Set it with the category property or the setCategory() function:

const ip = action.addString("IP")
ip.category = "Network"

const port = action.addInt("Port")
port.setCategory("Network")

const gain = action.addDouble("Gain")
gain.setCategory("Output")
  • Parameters without a category are displayed first, without a section title.
  • Sections are ordered by the first appearance of their category in the Script, and parameters keep their declaration order inside each section.
  • A section whose parameters are all hidden is not displayed.

addBool

img

property type description access
useSwitch boolean Use a switch (true) or a checkbox (false) r/w
const enabledParam = action.addBool("Send position")
enabledParam.value = true
enabledParam.useSwitch = true
enabledParam.description = "Send the target position"

addInt

img

property type description access
from int Minimum value r/w
to int Maximum value r/w
step int Step value r/w
const channel = action.addInt("Channel")
channel.from = 1
channel.to = 512
channel.step = 1
channel.value = 10

In the configuration object the step key is stepSize, while the property of the parameter is step.

addDouble

img

property type description access
from double Minimum value r/w
to double Maximum value r/w
step double Step value r/w
const gain = action.addDouble("Gain")
gain.from = 0
gain.to = 10
gain.step = 0.1
gain.value = 5.5

addString

img

const address = action.addString("OSC address")
address.value = "/source/1/xyz"
address.description = "Address of the message" // Displayed as placeholder

addEnum

A drop-down list of values. The possible values are given with enumValues in the configuration object.

property type description access
value string Selected value r/w
index int Index of the selected value r/w
const mode = action.addEnum({
  name: "Mode",
  enumValues: ["Absolute", "Relative"],
  value: "Absolute",
})

mode.onChange(() => console.log(`Mode is now ${mode.value} (index ${mode.index})`))

addColor

img

const colorParam = action.addColor("Color")
colorParam.value = "#00FF00"

addVector3D

img

const offset = action.addVector3D("Offset")
offset.value = { x: 1, y: 2, z: 3 }
console.log(offset.value.x)

addVector2D

img

const size = action.addVector2D("Size")
size.value = { x: 1, y: 2 }

addTrigger

A button that runs a function when clicked. It has no value.

img

const reset = action.addTrigger("Reset")
reset.description = "Reset all targets"
reset.onTrigger(() => {
  // Called when the button is clicked
})

addTarget

img

const targetParam = action.addTarget("Target")
const target = targetParam.value

The value of this parameter is a Target object.

addActionArea

img

const areaParam = action.addActionArea("Area")
const area = areaParam.value

The value of this parameter is an ActionArea object.

addModule

img

const moduleParam = action.addModule("Module")
const module = moduleParam.value

The value of this parameter is a Module object.

Events

action.onEnable(() => {
  // Called when the Action is enabled
})

action.onUpdate((dt) => {
  // Called every frame while the Action is enabled
  // dt: time elapsed since the last frame, in milliseconds
})

action.onDisable(() => {
  // Called when the Action is disabled
})

If a Script throws an error, the Action is stopped and the error is displayed in the console.

The show object

The show object is the Show currently loaded in Kratos.

property type description access
name string Name of the Show r/w
trackers Tracker[] List of Trackers in the Show r
targets Target[] List of Targets in the Show r
show.getTracker(trackerUid) // Returns the Tracker with this uid, or null
show.getTarget(targetUid)   // Returns the Target with this uid, or null

Objects

Kratos objects are obtained from parameters or from the show object. They all share these properties and functions:

property type description access
uid int Unique identifier of the object r
isValid boolean false when no object is selected or the object no longer exists r
object.equals(other) // Returns true if other is the same object

Target

A Target as defined in the Target Patcher.

const target = action.addTarget("Target").value
property type description access
name string Name of the Target r/w
color Color Color of the Target r/w
trackerUid int Uid of the Tracker assigned to the Target (0 when none) r/w
manual boolean Whether the Target is in manual mode r/w
mode2D boolean Whether the Target is in 2D mode r/w
prediction int Prediction time (ms) r/w
smoothingTime int Smoothing time (ms) r/w
manualZ double Height (m) of the Target in manual mode r/w
validity double Validity of the Target (0 to 1) r
position Vector3D Position of the Target (m). Setting it moves the Target manually r/w
predictedPosition Vector3D Predicted position of the Target (m) r
speed Vector3D Speed of the Target (m/s) r/w
homePosition Vector3D Home Position of the Target (m) r/w
const target = action.addTarget("Target").value

action.onUpdate((dt) => {
  if(target.validity > 0.5) {
    const p = target.position
    console.log(`${target.name} is at ${p.x}, ${p.y}, ${p.z}`)
  }
})

To change a position, assign a whole new value (target.position = { x: 1, y: 2, z: 0 }). Changing a single component (target.position.x = 1) has no effect on the Target.

ActionArea

An area as defined in the Action Area section of Kratos.

const area = action.addActionArea("Area").value
property type description access
name string Name of the area r/w
enabled boolean Whether the area is enabled r/w
visible boolean Whether the area is visible r/w
type string Type of the area: "ActionArea", "SpawningArea", "TrackingArea", "KillingArea" r
position Vector3D Position of the area's origin corner (m) r/w
scale Vector3D Size of the area (m) r/w
rotation Vector3D Rotation of the area (degrees) r/w

Functions:

area.isInside(position)     // true if the position (Vector3D or Target) is inside the area. Always false when the area is disabled
area.worldToLocal(position) // Converts a world position to area coordinates (0 to 1 on each axis inside the area)
area.localToWorld(position) // Converts area coordinates back to a world position

Events:

area.onTargetBeginOverlap((target) => {
  // Called when a Target enters the area
})

area.onTargetEndOverlap((target) => {
  // Called when a Target leaves the area
})

Example:

const area = action.addActionArea("Area").value
const target = action.addTarget("Target").value

action.onUpdate((dt) => {
  if(area.isInside(target)) {
    const local = area.worldToLocal(target.position)
    console.log(`${target.name} is at ${Math.round(local.x * 100)}% of ${area.name}`)
  }
})

Module

A Module as defined in the Modules view.

const module = action.addModule("Module").value

All Modules have these properties:

property type description access
name string Name of the Module r/w
enabled boolean Whether the Module is enabled r/w
logIncoming boolean Whether the Module logs incoming messages r/w
logOutgoing boolean Whether the Module logs outgoing messages r/w
connectionState string Connection state of the Module r

Module parameters

(v1.11) Every parameter of a Module can be read and written directly as a property of the Module, using the parameter names listed below for each Module type:

const osc = action.addModule("OSC Module").value

action.onEnable(() => {
  osc.outputAddress = "192.168.1.20"
  osc.outputPort = 9000
  console.log(`Sending to ${osc.outputAddress}:${osc.outputPort}`)
})

Parameters that are disabled in the interface can still be changed from a Script.

PSN Module

See PSN Module.

parameter type description
output_enabled boolean Whether the PSN output is enabled
output_name string Name of the PSN output
output_ip string IP address of the PSN output
output_port int Port of the PSN output
output_ttl int TTL of the PSN output
output_frequency string Output frequency
output_id_offset string ID offset of the PSN output
output_send_only_valid boolean Whether only valid Targets are sent
input_enabled boolean Whether the PSN input is enabled
input_ip string IP address of the PSN input
input_port int Port of the PSN input
x_remap string X remap (X, Y, Z, -X, -Y, -Z)
y_remap string Y remap (X, Y, Z, -X, -Y, -Z)
z_remap string Z remap (X, Y, Z, -X, -Y, -Z)
offset Vector3D Offset applied to all Targets (m)

OSC Module

See OSC Module.

parameter type description
outputEnabled boolean Whether the OSC output is enabled
outputAddress string IP address of the OSC output
outputPort int Port of the OSC output
inputEnabled boolean Whether the OSC input is enabled
inputAddress string IP address of the OSC input
inputPort int Port of the OSC input

Sending messages:

module.send({
  address: "/source/1/xyz",
  args: [
    { type: "i", value: 123 },     // int
    { type: "f", value: 1.23 },    // float
    { type: "s", value: "hello" }, // string
  ]
})

Supported argument types are i (int), f (float), s (string), b (blob), and the value-less T (true), F (false), N (nil) and I (impulse).

Receiving messages:

module.onReceive((message) => {
  // message.address: OSC address
  // message.args: list of { type, value }
  console.log(`Received ${message.address}`)
})

Messages are only sent when the output is enabled, and only received when the input is enabled.

GrandMA2 Telnet Module

See GrandMA2 Module.

parameter type description
ip string IP address of the GrandMA2 station
port int Telnet port of the GrandMA2 station
userName string User name used to log in
userPassword string Password used to log in

Sending commands:

module.send("Go Executor 1.1")

KratOSC Module

See KratOSC Module.

parameter type description
inputEnabled boolean Whether the OSC input is enabled
inputAddress string IP address of the OSC input
inputPort int Port of the OSC input
outputEnabled boolean Whether the OSC output is enabled
outputAddress string IP address of the OSC output
outputPort int Port of the OSC output
feedbackPeriodMs int Feedback period (ms)

This Module cannot send messages from Scripts: it automatically sends feedback about Kratos to its listeners (see KratOSC).

HTTP Module

See HTTP Module.

parameter type description
baseAddress string Base URL of all requests
timeout int Request timeout in milliseconds (0 = no timeout)
authType string Authentication type: "None", "Basic", "Bearer"
authUsername string User name for Basic authentication
authPassword string Password for Basic authentication
authToken string Token for Bearer authentication

Sending requests:

// Generic request
module.request(method, address, body, resultType)
// method: "GET", "POST", "PUT", "PATCH" or "DELETE"
// address: path appended to the base address
// body: request body (optional, for POST / PUT / PATCH)
// resultType: "default", "raw", "json" or "xml" (optional)

// Shortcuts
module.get(address, resultType)
module.post(address, body, resultType)
module.put(address, body, resultType)
module.patch(address, body, resultType)
module['delete'](address, resultType) // 'delete' is a reserved word in JavaScript

Handling responses:

module.onResponse((statusCode, response, resultType) => {
  // statusCode: HTTP status code (200, 404...)
  // response: response body as a string
})

module.onError((errorCode, errorString) => {
  // errorString: readable error message
})

Example:

const http = action.addModule("HTTP Module").value

http.onResponse((statusCode, response, resultType) => {
  if(resultType === "json") {
    const data = JSON.parse(response)
    console.log(`Got ${data.name}`)
  }
})

http.onError((errorCode, errorString) => console.error(`HTTP error: ${errorString}`))

const fetchUser = action.addTrigger("Fetch user")
fetchUser.onTrigger(() => http.get("/api/users/1", "json"))

SpaceMouse Module

(v1.11) See SpaceMouse Module.

parameter type description
device string Selected SpaceMouse device
target Target Target controlled by the SpaceMouse
actionArea ActionArea Area the Target movement is limited to
pan2dMode boolean Pan a 2D camera view instead of moving a Target
focusedView int Camera view controlled in 2D mode (0 = none)
inputMovement string "Translation", "Rotation" or "Combined"
autoReleaseTarget boolean Switch the Target to manual mode when the SpaceMouse is moved
useAsCursor boolean Use the SpaceMouse as a cursor in 2D mode (for Quick Assign)
enableX, enableY, enableZ boolean Enable each axis
invertX, invertY, invertZ boolean Invert each axis
swapXY boolean Swap the X and Y axes
zAsZoom boolean Use the Z axis to zoom the focused camera view instead of moving the Target
button1Action, button2Action string "None", "Reset to Home", "Release Target" or "Quick Assign"
sensitivity3d double Sensitivity when moving a Target
sensitivity2d double Sensitivity in 2D mode
pan2dSpeedFollowsZoom boolean Adapt the 2D pan speed to the zoom level
inputCurve string "Linear", "Quadratic", "Cubic" or "S-Curve"
deadzoneX, deadzoneY, deadzoneZ double Dead zone of each axis

Functions:

module.resetPosition()        // Send the controlled Target to its Home Position
module.refreshDevices()       // Search again for connected SpaceMouse devices
module.quickassign()          // Quick Assign the controlled Target in the focused camera view
module.quickassign("Singer")  // Quick Assign the Target named "Singer"

Events:

module.onButton1(() => { /* Button 1 pressed */ })
module.onButton2(() => { /* Button 2 pressed */ })
module.onConnected(() => { /* Device connected */ })
module.onDisconnected(() => { /* Device disconnected */ })

Tracker

A Tracker created by the Kore AI (K SYSTEM Sense only). Trackers are obtained from the show object:

const tracker = show.getTracker(target.trackerUid) // Tracker assigned to a Target, or null
const firstTracker = show.trackers[0]
property type description access
position Vector3D Position of the Tracker (m) r/w
speed Vector3D Speed of the Tracker (m/s) r/w
validity double Validity of the Tracker (0 to 1) r/w
color Color Color of the Tracker r
age int Time since the Tracker was first detected (ms) (v1.11) r
poseKeypoints Vector3D[] Body keypoints of the Tracker, in local coordinates (m) r
worldPoseKeypoints Vector3D[] Body keypoints of the Tracker, in world coordinates (m) r
poseKeypointsNames string[] Names of the keypoints, in the same order as the keypoint lists r

Keypoint names are: nose, left_eye, right_eye, left_ear, right_ear, left_shoulder, right_shoulder, left_elbow, right_elbow, left_wrist, right_wrist, left_hip, right_hip, left_knee, right_knee, left_ankle, right_ankle. Keypoint lists are undefined when no body pose is available.

const target = action.addTarget("Target").value

action.onUpdate((dt) => {
  const tracker = show.getTracker(target.trackerUid)
  if(tracker) {
    const wrist = tracker.poseKeypointsNames.indexOf("left_wrist")
    const keypoints = tracker.worldPoseKeypoints
    if(keypoints)
      console.log(`Left wrist height: ${keypoints[wrist].z}`)
    console.log(`Tracker age: ${tracker.age} ms`)
  }
})