1. Home
  2. Knowledge Base
  3. Advanced Configuration and Development
  4. Programming Puzzle Scripts

Programming Puzzle Scripts

Many puzzles can be created using just events, effect sequences, and solved conditions. However, when more advanced logic is needed, you can enable scripting by checking the “Use custom script” option within the puzzle settings.

You can write your scripts using standard JavaScript, but keep in mind that some modern syntax features may not be supported. For example, string building should use simple concatenation ("Score: " + value) instead of template literals (`Score: ${value}`). Stick to basic JavaScript constructs like variables, functions, conditionals, and loops to ensure your scripts run reliably.

When you click “Edit,” you are taken to the script editor, and a script skeleton is automatically generated. See the example below:

JavaScript
function isReady() {
    // This function is used by the game logic to verify that the puzzle is properly prepared,
    // such as ensuring attributes are removed and the initial state is correctly set.

    // Your code here -------------------------

    return false; // or true
}

function isSolved() {
    // The game logic checks this function to determine for the puzzle to be solved

    // Your code here -------------------------

    return false; // or true
}

function onReset() {
    // Puzzle is reset  

    // Your code here -------------------------

}

function onActivate() {
    // Puzzle is activated, 

    // Your code here ------------------------- 

}

function onTimeTick(ms) {
    // You can check conditions here at regular intervals using 'ms' as a time reference.
    // Note: 'ms' does not reference the game start time.
    // This function is called approximately every 50 ms.
    // Reminder: The puzzle must be active to receive events here.


    // Your code here ------------------------- 
}

function onEvent(objectId, state, ms) {
    // Handle state change events from input objects.
    // Note: The puzzle must be active to receive these events. 
    //       For example, if a switch is triggered before the puzzle is active,
    //       the event will not be received here. 
    //       To address this, also check the initial state of switches 
    //       in the onActivate method using getState().

    // Your code here ------------------------- 

}

Let’s take a look at this script. The functions shown here will be called by the system and need to be implemented.

The following two functions are continuously polled by the system in a fast loop to actively monitor their conditions:

  • isReady – This function is polled while the game is not running, to check whether the puzzle is properly prepared. You should implement any necessary checks here to confirm that the puzzle is ready to start..
  • isSolved – This function is polled continuously while the game is running and the puzzle is active. Return true when the puzzle has reached its solved state.

The following functions will be called as events:

  • onActivate – Called when the game is running and this task becomes active. Activation is usually triggered by another task reaching the “completed” state.
  • onReset – Called when the game is reset, or when this task is manually reset.
  • onTimeTick(ms) – Called every 50 milliseconds. The ms parameter is not tied to game time but can be used as a reference to measure elapsed time between events.
  • onEvent(objectId, state, ms) – Called whenever any object in the game changes state. This may include objects unrelated to the current puzzle, so you should check the objectId to determine if the event is relevant. The state parameter contains the current state of the specified object, and ms shares the same time reference as in onTimeTick.

Important note: You can add log statements to your script for debugging purposes—these will appear in the Logics Console. However, be cautious when logging inside isReady and isSolved, as these functions are called very frequently and can flood the console, potentially affecting performance. If you need to debug them, use a debug flag or limit how often logs are written, and make sure to remove or disable these logs before running the game for real.

The same caution applies to the timerTick event—only log meaningful changes or state transitions to avoid excessive output.

Using control functions

The following JavaScript-style functions are available for use in ERC escape room scripts. They allow you to control outputs, lighting, media, and interface elements during gameplay.

By using the startTimeSecs parameter, you can create precise effect sequences at runtime. For example, to simulate a thunderstorm, you could flash the lights and then play a thunder sound half a second later. You don’t have to manage the timing yourself, just schedule both effects with different start times, and the system will handle the sequence automatically.

The following JavaScript control functions are available for use in your escape room scripts. These are injected into the script runtime by the ERC

JavaScript
// Output functions
setActive(name, startTimeSecs)
setInactive(name, startTimeSecs)
setValue(name, startTimeSecs, intValue)
pulse(name, startTimeSecs, durationSecs)
pulseTrain(name, startTimeSecs, durationSecs, repeatInterval)

// Actuator functions
setPercentage(name, startTimeSecs, percentage)
transitionPercentage(name, startTimeSecs, percentage, durationSecs)

// Light control functions
setLight(name, startTimeSecs, rgbColor, temperature, intensity)
transitionLight(name, startTimeSecs, rgbColor, temperature, intensity, durationSecs)

// Multimedia controll functions
playMedia(name, startTimeSecs, mediaFile, startPosSecs, volume, loop)
stopMedia(name, startTimeSecs, volume, durationSecs)
fadeVolume(name, startTimeSecs, volume, durationSecs)
showImage(name, startTimeSecs, mediaFile)
showView(name, startTimeSecs)
showText(name, startTimeSecs, text)
hide(name, startTimeSecs)

// Launch a trigger
launchTrigger(name, startTimeSecs, repeatCount, repeatInterval)
cancelTrigger(name, startTimeSecs)

// Play a HUE scene
playScene(name, startTimeSecs, scene)

// Execute a custom function
execute(name, startTimeSecs, customParams)

Reading Object State

Returns the current value of an object, whether it’s an Input, Sensor, or RFID object. For outputs, it returns the last value that was set, allowing you to check what the system most recently did

JavaScript
// Get the current state of an object
getState(objectId)

Logging

Logs a message to the Logic Console, visible during script execution. Ideal for:

  • Debugging logic
  • Inspecting object state
  • Monitoring script behavior in real-time
JavaScript
// Produce a log message
console.log(msg)
Was this article helpful?
Yes No