Runtime Expression GitHub

TurboWarp custom extension

Make state actionable.

Read Temporary Variables with safe, JavaScript-like conditions—then broadcast only when a condition changes from false to true or back again.

Set it up See the behavior
condition state == "ready"
state = "ready" true
register watcher conditional broadcast…
false → true broadcast

Kamishibai DSL 4.0 bundle

Use this reference for the bundled expression blocks

In the combined runtime palette, click the documentation button immediately below the Runtime Expression member heading. Its condition, dynamic broadcast, expression syntax, limits, and error behavior remain exactly as documented here. The bundle adds only a member namespace and the extension's identifying icon.

01 · Start here

Ready in three steps.

Runtime Expression reads variables provided by TurboWarp's Temporary Variables extension. Load both extensions, then write conditions using the runtime variable names already in your project.

1

Load Temporary Variables

Add TurboWarp's Temporary Variables extension first. Runtime Expression uses its runtime variables as condition inputs.

2

Load Runtime Expression

Add dist/runtime-expression.js as a custom extension and enable Run extension without sandbox when prompted.

3

Write a condition

Use a bare name such as state, or vars["current state"] for names with spaces or non-ASCII characters.

Unsandboxed access is required. The extension needs direct access to the TurboWarp VM to read Temporary Variables and start broadcast hats. Only load extension files from a source you trust.

Version-pinned extension URL 
https://cdn.jsdelivr.net/npm/@kubohiroya/turbowarp-runtime-expression@0.4.0/dist/runtime-expression.js

02 · Boolean reporter

A safe answer, right now.

The condition block parses a limited expression, looks up referenced runtime variables, and returns a Boolean. It never uses eval or new Function.

What happens when the condition block runs
Runtime values state = "ready"
score = 12
Restricted parser state == "ready" && score > 10
true Boolean result

Gate a script

condition 
state == "ready" && lives > 0

Use the Boolean result directly inside an if block.

Check a missing variable

condition 
nextScene === undefined

A runtime variable that does not exist reads as undefined.

Use any variable name

condition 
vars["current state"] == "ready"
&& vars["得点"] >= 10

The exact vars["name"] form handles spaces and Unicode.

03 · Conditional broadcasts

Broadcast the transition—not the noise.

Register a named watcher once. Runtime Expression remembers the initial result and checks referenced values each VM frame. A message is sent only when the Boolean result crosses between false and true.

State changes and their messages
false not ready
false → true broadcast the true message
true → false broadcast the false message
true ready
false → false and true → true send nothing
Event What Runtime Expression does
Register Evaluates once to remember the initial state. No message is sent.
Referenced value changes Re-evaluates on the next frame; unrelated variables are ignored.
Result changes Sends the true or false message for that transition.
Same ID registered again Atomically replaces the previous watcher and its remembered state.
Positive timeout expires Removes the watcher silently. Zero or less means no timeout.
Unregister / project start / stop Removes the watcher. Unregistering an unknown ID has no effect.

One frame, one final state

Several updates before the next VM frame are coalesced. The watcher sees the final values on that frame, avoiding a burst of intermediate messages.

ID is the control handle

Choose a stable ID such as level-ready. Use the same ID to replace or unregister that watcher later.

04 · Composition API

Use the same evaluator without Scratch blocks.

Applications that own their state can import the pure evaluator directly. It does not read Scratch, the DOM, network, storage, or Temporary Variables.

TypeScript / ESM 
import {createRuntimeExpressionComposition} from
  '@kubohiroya/turbowarp-runtime-expression/composition';

const expressions = createRuntimeExpressionComposition();
const ready = expressions.evaluateCondition(
  'state === "ready" && score >= 10',
  {state: 'ready', score: 10}
);

expressions.releaseAll();

Fail-closed inputs

Only own enumerable string, finite-number, and Boolean values are accepted. Unknown or invalid values produce stable errors.

Bounded and reusable

The evaluator shares the restricted parser and bounded cache. releaseAll() clears cached expressions without invalidating the instance.

05 · Expression language

Familiar on purpose. Limited for safety.

The syntax resembles JavaScript comparisons and arithmetic, but it is not JavaScript. Keep expressions focused on calculating a value from runtime variables.

Supported

  • Finite numbers, quoted strings, true, false, null, undefined
  • !, unary + and -
  • + - * / %
  • == != === !== < <= > >=
  • && and || with short-circuit behavior
  • Parentheses and exact vars["name"] lookup

Rejected

  • Assignments and updates
  • Function or method calls
  • General property access and optional chaining
  • new, arrays, and object literals
  • Template strings
  • Expressions beyond built-in length, token, or nesting limits
score >= 10 state !== "paused" !gameOver coins % 2 == 0 a && (b || c)

06 · Troubleshooting

When a condition surprises you.

Most problems come from extension order, string quoting, or a watcher being cleared by the project lifecycle. These checks cover the usual cases.

“Temporary Variables” error

Load the Temporary Variables extension before running a condition or registering a watcher.

Text does not compare correctly

Quote string values: write state == "ready", not state == ready. The unquoted word is another variable name.

No message after registration

That is expected. Registration stores the initial result silently. Change the condition across false/true to send a message.

Watcher stopped after Start or Stop

Project start and stop clear every registration. Register watchers again from your startup scripts.

Name contains spaces or Japanese

Use the exact lookup form, for example vars["current state"] or vars["得点"].

Syntax error

Reduce the expression to one comparison, check quotes and parentheses, then add each logical clause back one at a time.