Overview

Kicklet code is used wherever Kicklet needs dynamic text or automation: custom command responses, periodic messages, alert messages, global command feedback, and stream titles. Code can send chat messages, branch with normal JavaScript, loop over data, and call Kicklet helpers for points, counters, variables, active viewers, moderation, songs, and external services.

Engine v2 is the current engine for new commands and messages. Engine v1 remains available for existing templates that use the older Go template syntax.

Choosing a Version

Engine v2

Recommended for new commands and new message templates.

Uppercase greetingAdvanced Script

const name = text.upper("world");
async.messages.send(`Hello ${name}!`);

v2 examples are written as Advanced Script. Use normal JavaScript and send chat output with async.messages.send(...), messages.send(...), or messages.reply(...).

The visual response builder uses template source internally. See Template Syntax Reference when you need to inspect generated source or work with importTemplate(...).

Engine v1

This engine uses Go template syntax for the rendered text. JavaScript is embedded inside the template and values are read back with script.Var or script.Call.

Hello {{upper "world"}}!

Advanced Script

Engine v2

Use Advanced Script when a command should calculate values, update state, call integrations, or send one or more chat messages.

Random numberAdvanced Script

const luckyNumber = random.int(1, 100);
async.messages.send(`Lucky number: ${luckyNumber}`);

Alice pointsAdvanced Script

const balance = points.get("alice");
const currency = points.currency();

async.messages.send(`Alice has ${balance} ${currency}`);

Prepared random valueAdvanced Script

const roll = random.int(1, 100);
async.messages.send(`Prepared value: ${roll}.`);

Use messages.reply(...) when the response should explicitly reply to the triggering command message.

Send roll and replyAdvanced Script

const roll = random.int(1, 100);
async.messages.send(`Rolled ${roll}.`);
messages.reply(`Replying with ${roll}.`);

async.messages.send(...) queues a chat message without waiting for the backend send result. Use messages.send(...) when code needs the created message object before continuing. See Chat Messages for reply handling, return values, and send limits.

Engine v1

Plain template:

Hello {{upper "world"}}!

For JavaScript, wrap the visible output in <template> and the JavaScript in <script>. The template can read JavaScript variables with script.Var or call functions with script.Call.

<template>
Prepared value: {{script.Var "roll"}}.
</template>

<script>
let roll = Math.floor(Math.random() * 100) + 1;
</script>

Read a JavaScript variable:

<template>
Hello {{script.Var "worldVariable"}}!
</template>

<script>
let worldVariable = "world";
</script>

<template>
Hello {{script.Call "name"}}!
</template>

<script>
function name() {
  return "world";
}
</script>

Debugging Code

Engine v2

Use console.log(...) while testing code in the Advanced Editor. Log entries appear in the tester output and include the source location when Kicklet can map the call back to your code.

Log and send rollAdvanced Script

const roll = random.int(1, 100);
console.log("roll", roll);
async.messages.send(`Rolled ${roll}.`);

console.log(...) is for debugging only. It is not a chat output function and production runs do not send these logs to chat. Use async.messages.send(...), messages.send(...), or messages.reply(...) when the bot should post a visible message.

Engine v1

Use console.log(...) inside the JavaScript <script> block while testing a v1 template in the Advanced Editor. Log entries appear in the tester output.

<template>
Rolled {{script.Var "roll"}}.
</template>

<script>
let roll = Math.floor(Math.random() * 100) + 1;
console.log("roll", roll);
</script>

console.log(...) is for debugging only. It is not a chat output function and production runs do not send these logs to chat. Use template output when the bot should post a visible message.