KAG Script Basics

import { Tabs, TabItem, Aside, Badge } from '@astrojs/starlight/components';

KAG scenarios are plain text files (.ks) that can embed Rhai expressions for conditional logic, variable mutation, and dynamic text.

---

KAG Script Basics

A .ks file is processed line-by-line. Each line is one of:

Line type	Example	Meaning
Text	Hello, world!	Printed to the message window
Label	*start	Jump target
Speaker shorthand	#Alice	Sets the speaker name for the next text block
Block tag	[wait time=500]	Inline tag (must be the only content on the line)
Line tag	@jump target=*start	@ is syntactic sugar for […]
Comment	; this is a comment	Ignored by the interpreter

Line tag shorthand

@tag attr=value is exactly equivalent to [tag attr=value]. Prefer @ for tags that occupy a whole line; prefer […] when a tag is embedded mid-line.

Labels

*my_label

Labels are * followed by an identifier. Labels are used as jump targets for [jump], [call], [link], etc.

Speaker shorthands

#Alice
This text is attributed to Alice.

The #Name shorthand sets the current speaker name. The name is reset after the next text block is emitted.

---

Variable Scopes

KAG exposes four variable maps as Rhai global objects:

Name	Scope	Persistence	Use case
f	Game flags	Saved with the game	Story flags, counters, choices made
sf	System flags	Saved separately from game saves	Config, global unlocks
tf	Transient flags	Not saved — reset on load	Temporary per-scene values
mp	Macro parameters	Set at macro call site	Pass-through inside [macro] bodies

Access and mutate them like Rhai object maps:

f.visited_village = true;
sf.bgm_volume = 0.8;
tf.temp_counter = tf.temp_counter + 1;

Save/Load behaviour

tf (transient flags) are not persisted across saves. Never store information that must survive a save/load cycle in tf.

Clearing variables

Tag	Effect
[clearvar]	Clears all f entries
[clearsysvar]	Clears all sf entries

---

Rhai Expression Embedding

[eval] — Execute

Runs a Rhai script without producing any output.

[eval exp="f.score = f.score + 10;"]
[eval exp="f.name = mp.player_name;"]

Side-effects (variable mutations) are persisted into the scope.

[emb] — Embed as text

Evaluates the expression and injects the result into the current message stream.

Your score is [emb exp="f.score"] points!

Note

If evaluation fails, an empty string is substituted (errors are swallowed).

[trace] — Debug log

Evaluates the expression and writes the result to the debug log. No visible output.

[trace exp="f.score"]

Entity expressions (&expr)

Any attribute value prefixed with & is evaluated as a Rhai expression at runtime:

[jump target=&"*" + f.next_scene]
[bg storage=&"bg/" + sf.theme + "/bg01.jpg"]

Macro parameter references (%key / %key|default)

Inside a [macro] body, %key is substituted with the value passed at the call site. An optional default follows |:

[macro name=say_hello]
Hello, %name|stranger!
[endmacro]

[say_hello name=Alice]