Scripts and mini-games

When you need scripts

Almost everything in a novella is built without code: lines, choices, Actions steps, conditions, extensions. A script is for when you want something of your own — a mini-game, an unusual calculation, a mechanic the settings don’t have.

Scripts are written in JavaScript. Everything the engine can do is available through the engine object: variables, the stage, sound, notifications. For example, these two lines give the reader gold and tell them so:

engine.vars.gold += 10 — followed by engine.ui.notify('Gold +10'). The gold variable has to exist in the Vars tab.

Where code goes

The Script step on the Basic tab of the Actions block runs code at its point in the timeline. Next to the step you choose when it runs: “In the lane”, “On entry” — when entering the node, before the lines — or “On exit” when leaving it.

The same enter and exit scripts show up in the node’s Parameters, in the “Scripts (JS)” section: the “onOpen” and “onClose” buttons edit those same steps.

The Custom JS node is a separate script node on the graph. Its code opens with the “Edit the code” button on the node card.

The init script is the first row of the Scripts tab, marked “on entry”. It runs every time a reader enters the novella: a new game, a continue, a restart. It can’t be deleted or renamed.

1. Select a node and press Action under the timeline.
2. On the Basic tab press Script — the editor opens.
3. Write the code or insert it from the palette on the right.
4. Press Play and go through the node.

The editor and the palette

To the right of the code is the palette of engine functions. Clicking a row inserts a ready piece of code where the cursor is. The groups are Variables, Scene & nodes, Camera & effects, Sound, Signals, Events, Mini-games and more; installed extensions add their own. There’s a search by name and description on top. The full list of what the engine can do is the palette itself.

Next to the code is a live 9:16 preview: the script runs there on the same engine as for the reader, you can play a mini-game right in it, and the backdrop, camera and music are noted in the log. The run button restarts the script, the auto box restarts it on every edit, and the log underneath shows what happened. If the code has an error, it appears in the preview bar with a ⛔ sign.

“Import a script…” above the palette brings in a module from the Scripts tab, and Expand opens the editor full screen.

Ready-made mini-games

The palette’s Mini-games group has six games you insert whole: Catch the coins, Perfect hit, Find the pair, Repeat the pattern, Dodge and Combination lock. Each one holds the reader until the round is over and ends by itself — on time, attempts or a loss.

The game writes its result into a variable: Catch the coins puts points in score, Perfect hit puts hits in hits, Find the pair puts moves in moves. Create a variable with the same ID in the Vars tab, and you can branch the story on it with an ordinary Condition node.

1. Select the screen where the game will be and open its Parameters.
2. In the “Scripts (JS)” section press “onOpen”.
3. In the palette open Mini-games and click a game — the whole code goes in.
4. Play a round in the preview next to it, then go through the scene in Play.

Modules and skills

The Scripts tab holds the novella’s code in folders. The Script button creates a module: shared code you bring into any script with the line import "Folder/name". The same folders can hold images and sounds for mini-games — they don’t clutter the Library among your backdrops. Rename a folder or module and the import path changes, so update it.

A Skill is a recipe folder for the AI agent: a Name, “When to use”, “Agent instructions” and tags, with scripts, images and sounds inside. The agent finds the right skill by its description.

Platform skills at the top of the tab are always available to the agent — no install needed. They’re read-only; to rework one for yourself, use “Copy to edit”.

Is it safe

A script runs on the reader’s side, but inside a closed sandbox. From there it can’t reach the page around it or the reader’s account: the engine hands a script only its own controls — variables, the stage, sound, the interface.

Images from code load only from the platform’s addresses and your library; an outside address simply won’t load. That way an image can’t be used to send a reader’s data to another site.

FAQ

Do I need to know how to code? Not for the ready-made mini-games: they go in whole from the palette. For your own mechanic, you can ask the agent.

My script doesn’t work — where’s the error? In the preview next to the code: the error appears in its bar with a ⛔ sign, and the log shows what managed to run.

A reader is stuck on a mini-game — why? A game holds the screen until it ends. The ready-made ones release the reader themselves; your own game has to do the same — call engine.flow.unlock().

Where are all the engine’s functions? In the palette to the right of the code: a click inserts an example, and the search looks through names and descriptions.

Can I delete init? No, every novella has one. If you don’t need it, leave it empty.