RiftScript v1

RiftScript is a small typed language compiled into the same bounded instructions as Visual logic. It is not JavaScript and cannot access the browser, network, files, secrets, dynamic evaluation, or capabilities outside the generated registry.

The first line is always the language compatibility directive:

riftscript 1;

An unsupported major version fails before compilation. Published immutable bundles retain validated instructions, so an old published Rift does not depend on a newer source compiler.

Variables and events

V1 variables have a declared scalar type and bounded literal default. Defaults become the Script component's initial variable values; they are not reset every time an event runs.

riftscript 1;

var collected: boolean = false;
var bonus: number = 10;
var effectName: string = "coin_pickup";

event player_touched {
  if (!collected) {
    collected = true;
    score.add(bonus);
    effects.play(effectName);
    world.destroy();
  }
}

Supported types are number, boolean, and string. Supported expressions are variable reads, literals, numeric +, typed ==, boolean !, parentheses, and deterministic random.int(min, max) with ordered 32-bit integer literal bounds.

Control flow and budgets

V1 supports if and if/else. It has no loops, recursion, user functions, threads, imports, reflection, collections, or dynamic capability lookup. Every compiled handler must also pass bytecode control-flow and stack verification. Creator instructions and capability commands share one fixed allowance across all handlers invoked in a simulation tick; stack and live memory ceilings apply to each invocation.

Capabilities and authority

The generated capability reference is the source of truth for names, parameter types, availability, and authority. Unknown names and incorrect argument types fail compilation. A server capability such as score.add remains authoritative even when its source was authored in the browser.

Capabilities may also restrict their event context. For example, a directed launch is valid only while handling the touching player:

event player_touched {
  player.launch(0, -600);
}

Literal launch values must remain between -2000 and 2000 with at least one non-zero axis. Dynamic values are checked again by headless publishing and the authoritative runtime. See Launch pads.

Formatting, diagnostics, and source maps

The formatter produces one canonical representation and is idempotent. Parser and type errors use stable RS diagnostic families:

• RS0xxx: source and structural budgets;
• RS1xxx: lexical, syntax, and language-version errors;
• RS2xxx: names, types, bounds, and capability errors;
• RS3xxx: invalid compiled-program output.
• RS4xxx: exact Visual/RiftScript conversion errors.

The compiler returns an instruction-to-source range map as authoring metadata. Runtime programs do not embed creator source. If a test run fails, Workshop shows the exact program, event, bytecode instruction, and source line/column when source is available. Open source at line … returns to edit mode and focuses that range.

RS3002 means the compiled handler failed bytecode verification or cannot fit the fixed VM instruction ceiling. Reduce repeated actions or branch size; this limit cannot be raised by creator code.

Visual logic conversion boundary

Visual logic and RiftScript share bytecode semantics. Use Convert to RiftScript on an attached Visual behavior to create typed canonical source without changing its compiled instructions. Use Convert to Visual when text contains only literal assignments, literal capability arguments, and variable-to-literal if conditions without else.

Random values, computed expressions, negation, else, and other text-only constructs cannot return to Visual logic yet. Workshop reports the unsupported source range and preserves the RiftScript. Both successful directions are one undoable editor command and verify exact bytecode equality before changing the document.

Workshop editor

Select an object and choose Add RiftScript to open the foreground text editor. Diagnostics update while you type; selecting one moves the cursor to its source offset. Format applies the canonical formatter. Compile & attach is enabled only when the source passes parsing, typing, capability, and budget checks.

Valid source is stored in editor-document v3 and autosaved with the draft. Only the compiled CreatorProgram and declared scalar defaults enter the runtime project snapshot. Compilation is one undoable editor command; invalid source does not mutate the project.

Press Ctrl+Space to open authoring suggestions, or use the Suggestions control. Tab accepts the first matching item. Capability names, typed arguments, authority labels, descriptions, and parameter hints come directly from the same registry used by analysis and generated documentation. Declared variables, scalar types, and bounded syntax snippets are also available. A suggestion only edits source text; it never bypasses compilation or executes creator input.