Introduction

The Language Reference describes how to write and ship a visual novel with Kagari: the concepts of the engine, the language, its special types and attributes, the tools and the runtime. The diagnostics of the compiler have their own section, Diagnostics.

What Kagari is

Kagari is a visual novel engine. It consists of:

• a language, close to Rust, in which the whole game is written: the story, its presentation, and the game system around it (title screen, menus, saves, settings);
• a compiler, the kagari command, that checks a project, analyzes its story and builds it into one .kagari file plus asset archives;
• a runtime that plays the built game on Windows, macOS and Linux.

The parts of a game differ in the kind of function they are written in:

The compiler checks which kind may call which. Because the story is made only of pushdown fn, and Turing-complete code can enter it only by starting an entry scene, the compiler can answer questions about the story that no tool can answer for arbitrary code: whether every choice offers an option, whether a scene can be reached, whether a step shows the same screen however it is reached. Philosophy: Analyzable by Construction explains why; the rest of the game stays free to compute.

Who this reference is for

The reference is for studios that make games with Kagari: scenario writers who write scenes, scripters who stage them, and engineers who build the game system and ship the game. It assumes basic programming knowledge. Knowing Rust helps, since the language reuses Rust’s syntax and many of its rules; Differences from Rust lists where Kagari departs from it.

How this reference is organized

Readers new to Kagari should read the Overview and Core Concepts in order, then use the Syntax part as a reference. Each concept chapter links to the syntax it uses.

A first look

static mut VISITED_A: bool = false;

const STALL_A: ImageAsset = asset("bg/stall_a.png");

enum Ending { Normal }

#[scene]
#[entry]
pushdown fn Day1() -> Ending {
    s!(t!["The school festival starts today."]);
    StallA();
    StallA();
    Ending::Normal
}

#[scene]
pushdown fn StallA() {
    if VISITED_A {
        s!(t!["The stall is already packing up."]);
        return;
    }
    VISITED_A = true;
    s!(who = "Hanako", render = at_stall_a, t!["Welcome to stall A!"]);
}

const fn at_stall_a(mut screen: Screen) -> Screen {
    screen.background().change(STALL_A).apply_animation(fade(ms(500)));
    screen
}

• Day1 is an entry scene: the game system starts the story there, and its return value tells the system which ending was reached.
• Each s!(…) is a step, a point where the story stops and waits for the player. t![…] is its text, and who names the speaker.
• StallA() calls the scene StallA; the story continues after the call when the scene returns. The second visit shows the other line.
• VISITED_A is a story variable: global state of one run of the story, of a finite type.
• at_stall_a is a render function: it says how the screen changes when its step is entered, here a half-second crossfade to a new background.

A complete game also has a fn main that describes the game system and a project around the sources. kagari init creates both from a template:

kagari init my-game
cd my-game
kagari build
kagari-desktop-runtime target/v0

Conventions

• Tentative marks design that is not settled yet: names, defaults and edge-case rules that may change in a later version.
• Code blocks tagged kis are plain code, valid in both .kis and .kix files. Code blocks tagged kix use forms such as s!(…), choice!{…} and t![…], which are allowed only in .kix files.
• Step always means a point where the story waits for player input: an s!(…) or a choice!{…}. Everything between two steps runs without waiting.
• σ (“sigma”) is the narrative state: the position in the story, the call stack with the locals of each frame, and the story variables.
• Diagnostics are named by their code, such as E5003 or W5004; Diagnostics lists them all.
• A studio is the team that writes a game; the engine is the runtime that plays it.

Other sections

• The Tutorial takes you from installing Kagari to a first game.
• The STD Reference documents every item of the standard library std: the screen, animations, audio, text, the system, saves and UI.
• Diagnostics lists every diagnostic the compiler reports.
• The Kagari Develop Guide (in the repository) is for contributors to Kagari itself: the design decisions, compiler internals, file formats and runtime internals.