Scripting Saida Engine

// scripts/spinner.js — the smallest useful script.
// Attach it to any node, then press Play.

exportProperty("degreesPerSecond", 90.0);

let angle = 0.0;

function onReady() {
    console.log("[Spinner] " + node.getName() + " is up");
}

function onUpdate(dt) {
    angle += props.degreesPerSecond * dt * 0.017453292;  // degrees -> radians
    // A yaw quaternion: rotate around Y by `angle`.
    node.setRotation(0.0, Math.sin(angle * 0.5), 0.0, Math.cos(angle * 0.5));
}

{
  "type": "Area",
  "name": "DoorToArena",
  "enabled": true,
  "behaviours": [
    {
      "type": "ScriptBehaviour",
      "enabled": true,
      "script": "scripts/door.js",
      "hotReload": true,
      "properties": {
        "targetScene": "scenes/arena.scene"
      }
    }
  ],
  "groups": ["doors"]
}

// scripts/platform.js — a platform that shuttles along one axis.

exportProperty("axis", "x");        // "x" | "y" | "z"
exportProperty("span", 5.0);        // metres either side of the rest position
exportProperty("period", 5.0);      // seconds for a full there-and-back

let origin = null;
let phase = 0.0;

function onReady() {
    const p = node.getPosition();
    origin = { x: p.x, y: p.y, z: p.z };
}

function onUpdate(dt) {
    if (origin === null) return;
    const period = props.period > 0.05 ? props.period : 0.05;
    phase += (dt / period) * Math.PI * 2.0;
    const offset = Math.sin(phase) * props.span;
    const axis = props.axis;
    node.setPosition(origin.x + (axis === "x" ? offset : 0.0),
                     origin.y + (axis === "y" ? offset : 0.0),
                     origin.z + (axis === "z" ? offset : 0.0));
}

// Fail loudly at startup when the scene is missing something the script
// cannot work without. Pong3D does exactly this for its five nodes.
function requireGroup(group) {
    const found = tree.firstInGroup(group);
    if (found === null) throw new Error("Pong: no node in group '" + group + "'");
    return found;
}

function onReady() {
    ball = requireGroup("ball");
    playerPaddle = requireGroup("paddle_player");
    scoreText = requireGroup("pong_score");
}

// A reference kept across frames can outlive its node. valid() is the only
// call that answers instead of throwing, so it goes first.
function onUpdate() {
    if (car !== null && !car.valid()) {
        car = null;
        report("the car went away");
        return;
    }
    // ... safe to use `car` from here
}

// scripts/pickup.js — a relic on an Area node.
// The Area emits "bodyEntered" with the other node's NAME.

exportProperty("points", 1);

let collected = false;

function onReady() {
    const gameState = tree.autoload("GameState");
    if (gameState === null) throw new Error("GameState autoload is missing");

    node.on("bodyEntered", function (who) {
        if (collected || who !== "Player") return;
        collected = true;
        audio.play("pickup");
        const total = gameState.call("addRelics", props.points);
        console.log("[Pickup] " + node.getName() + " collected — relics=" + total);
        node.queueFree();
    });
}

// A Blackboard behaviour on this node (or on a descendant) turns these three
// calls into shared, typed state that the StateMachine behaviour also reads.
function onReady() {
    node.setData("alertLevel", 0);
    node.setData("hasKey", false);

    // "changed" is a reflected signal on Blackboard: the payload is the key.
    node.on("changed", function (key) {
        if (key === "alertLevel") console.log("alert -> " + node.getData(key));
    });
}

{
  "schema": 2,
  "version": 2,
  "scene": {
    "type": "Scene",
    "name": "Arena",
    "children": [ "..." ],

    "connections": [
      {
        "from": 13224595248972440569,
        "signal": "bodyEntered",
        "to": 14116644317509485334,
        "slot": "damage"
      }
    ]
  }
}

{
  "schema": 1,
  "version": 1,
  "name": "Witness Game",
  "engineVersion": "0.1.0",
  "mainScene": "scenes/hub.scene",
  "audio": {
    "aliases": {
      "pickup": "assets/audio/pickup.ogg",
      "save": "assets/audio/save.ogg"
    }
  },
  "autoloads": {
    "GameState": "scripts/game_state.mjs"
  }
}

// scripts/game_state.mjs (excerpt) — an autoload starts before the scene's
// own nodes exist, so the HUD cannot be resolved once and kept forever.

let hud = null;

function resolveHud() {
    if (hud !== null && hud.score.valid()) return hud;
    const scoreText = tree.firstInGroup("hud_score");
    if (scoreText === null) return null;
    hud = { score: scoreText, health: tree.firstInGroup("hud_health") };
    return hud;
}

export function onReady() {
    // The HUD belongs to the scene, which is not up yet when an autoload runs.
    time.every(0.2, refresh);
}

// scripts/player.js (excerpt) — a muzzle flash that switches itself off, and
// a pooled impact that parks itself out of sight afterwards.
function fire() {
    if (muzzle !== null) {
        muzzle.setEnabled(true);
        time.wait(0.06, function () { muzzle.setEnabled(false); });
    }
}

function popImpact(x, y, z) {
    const fx = impacts[impactCursor % impacts.length];
    impactCursor += 1;
    fx.setPosition(x, y, z);
    fx.setEnabled(true);
    time.wait(0.25, function () {
        fx.setEnabled(false);
        fx.setPosition(0.0, -200.0, 0.0);
    });
}

// A tween hands its callback the eased value, 0 -> 1.
time.tween(0.4, function (t) { node.setPosition(0.0, t * 2.0, 0.0); }, "outBack");

// scripts/driver.js (excerpt) — the nearest vehicle whose COLLIDER the player
// can reach, not whose origin is close: a van is four metres long, so measuring
// to its centre would let someone open it from inside its own bonnet.
function reachableCar(p) {
    const me = p.getPosition();
    const hits = physics.overlapSphere(me, REACH);
    let best = null;
    let bestDistance = 0.0;
    for (let i = 0; i < hits.length; i += 1) {
        const h = hits[i];
        if (!h.valid() || !h.isInGroup("vehicle")) continue;
        const d = distance(me, h.getPosition());
        if (best === null || d < bestDistance) { best = h; bestDistance = d; }
    }
    return best;
}

// scripts/player.js (excerpt) — the camera ray has to start PAST the player:
// ignoreSelf does not cover a CharacterBody's inner body, so a ray from the
// camera would report the player's own capsule at nearly zero distance.
const p = node.getPosition();
const ahead = (p.x - cam.x) * dir.x + (p.y - cam.y) * dir.y + (p.z - cam.z) * dir.z;
const clearance = Math.max(0.0, ahead) + 0.8;
const origin = {
    x: cam.x + dir.x * clearance,
    y: cam.y + dir.y * clearance,
    z: cam.z + dir.z * clearance
};
const seen = physics.raycast(origin, dir, props.range, { ignoreSelf: true });

// scripts/player.js (excerpt) — footsteps and landing, read from the
// controller's own published state rather than re-derived from positions.
function onUpdate(dt) {
    const state = node.characterState();
    if (state === null) return;

    if (state.grounded && state.speed > 1.2) {
        stepTimer -= dt * (state.speed / 5.0);
        if (stepTimer <= 0.0) {
            stepTimer = 0.36;
            audio.play(stepFlip ? "step_a" : "step_b");
        }
    }
    if (!state.grounded) {
        wasAirborne = true;
    } else if (wasAirborne) {
        wasAirborne = false;
        audio.play("land");
    }
}

// scripts/enemy.js (excerpt) — the engine's Character behaviour owns the
// animation and the capsule; this script owns the intent. That intent is in
// world space while setMoveInput is camera-relative, so the solver is suspended
// and the script integrates the body itself.
function onReady() {
    player = tree.firstInGroup("player");
    // This script writes the velocity directly, so the built-in solver must not
    // also be writing it — they would fight every frame.
    node.characterSolver(false);
}

function onUpdate(dt) {
    const grounded = node.isOnFloor();
    if (grounded && verticalSpeed < 0.0) verticalSpeed = 0.0;
    verticalSpeed -= props.gravity * dt;

    const a = node.getPosition();
    const b = player.getPosition();
    let dx = b.x - a.x;
    let dz = b.z - a.z;
    const flat = Math.sqrt(dx * dx + dz * dz);
    if (flat > 1e-3) {
        dx /= flat;
        dz /= flat;
        node.characterFace(dx, dz, false);
    }
    node.setVelocity(dx * props.speed, verticalSpeed, dz * props.speed);
}

// scripts/driver.js (excerpt) — one driver script holds at most one car.
// A character and a vehicle read the SAME movement actions, so exactly one of
// them may be listening: 32 parked cars would otherwise race to answer the same
// key press.
function onReady() {
    input.bindKey("Interact", "F");
    const all = tree.nodesInGroup("vehicle");
    for (let i = 0; i < all.length; i += 1) {
        all[i].vehicleInput(false);
        all[i].vehicleHandbrake(true);
    }
}

function enter(p, target) {
    car = target;
    // The camera follows a GROUP, so handing the car that membership is what
    // carries the view across.
    p.removeFromGroup("camera_target");
    car.addToGroup("camera_target");
    p.setVelocity(0.0, 0.0, 0.0);
    p.setEnabled(false);
    car.vehicleHandbrake(false);
}

function onUpdate() {
    if (car === null) return;
    // The very actions the character would have read, spent on the car instead.
    const move = input.vector("MoveLeft", "MoveRight", "MoveBackward", "MoveForward");
    car.vehicleDrive(move.y, move.x);
    car.vehicleHandbrake(input.isHeld("Jump"));
}

// scripts/game_state.mjs (excerpt) — the engine stores an opaque string, so
// the game owns its own format.
const SLOT = "verdance";

function readBest() {
    const raw = storage.load(SLOT);
    if (raw === null) return 0;
    try {
        return Number(JSON.parse(raw).best) || 0;
    } catch (_) {
        return 0;
    }
}

function persistBest() {
    if (score > best) best = score;
    if (!storage.save(SLOT, JSON.stringify({ best: best }))) {
        const failure = storage.lastError();
        console.warn("[GameState] save failed: " + failure.status + " " + failure.message);
    }
}

// Visibility is synchronous; durability is not. Await the flush before quitting.
async function saveAndQuit() {
    persistBest();
    await storage.flush();
    tree.quit();
}

// Nothing here blocks, and nothing returns a promise: ask on one frame, poll
// the handle on a later one.
let doorMesh = null;

function onReady() {
    doorMesh = assets.load("assets/models/vault_door.glb", "high");
}

function onUpdate() {
    if (doorMesh === null) return;
    if (doorMesh.ready()) {
        console.log("vault door ready, " + doorMesh.size() + " bytes");
        doorMesh = null;
    } else if (doorMesh.failed()) {
        console.error("vault door failed: " + doorMesh.error());
        doorMesh = null;
    }
}

// scripts/lib/math2d.mjs
export function clamp(value, low, high) {
    if (value < low) return low;
    if (value > high) return high;
    return value;
}

// scripts/turret.mjs — the specifier is project-relative and resolved next to
// the importing file. It may not leave the project root.
import { clamp } from "lib/math2d.mjs";

export function onUpdate(dt) {
    yaw = clamp(yaw + dt, -1.2, 1.2);
}

// ui/main_menu.js — a WebCanvas document script. This context has `document`
// and `tree`, and nothing else: no node, no time, no input.
const playButton = document.getElementById("play-button");
const statusCopy = document.getElementById("status-copy");
let launchRequested = false;

function beginJourney() {
    if (launchRequested) return;
    launchRequested = true;
    statusCopy.textContent = "OPENING THE WILDS";
    if (!tree.changeScene("scenes/verdance.scene")) {
        launchRequested = false;
        statusCopy.textContent = "THE WILDS COULD NOT BE OPENED";
    }
}

playButton.addEventListener("click", beginJourney);
document.getElementById("quit-button").addEventListener("click", function () {
    tree.quit();
});

// scripts/trigger.js — a one-shot volume. The first time the player enters it,
// one named function on the autoload is called. Level progression then lives in
// the scene's layout rather than in a distance check somewhere else.

exportProperty("call", "");

let gameState = null;
let fired = false;

function onReady() {
    gameState = tree.autoload("GameState");
    if (gameState === null) throw new Error("GameState autoload is missing");

    node.on("bodyEntered", function (who) {
        if (fired || who !== "Player" || props.call === "") return;
        fired = true;
        gameState.call(props.call);
    });
}

// scripts/door.js — a doorway between the street and an interior cell.
// The volume is one-way: it moves the player to its destination and then
// ignores them until they have left, so standing in a doorway does not bounce
// them back and forth.

exportProperty("toX", 0.0);
exportProperty("toY", 0.0);
exportProperty("toZ", 0.0);

let inside = false;

function onReady() {
    node.on("bodyEntered", function (who) {
        if (who !== "Player" || inside) return;
        const player = tree.firstInGroup("player");
        if (player === null) return;
        inside = true;
        player.setPosition(props.toX, props.toY, props.toZ);
        // The character keeps its momentum across the move, which would carry it
        // straight back through the door it arrived in.
        player.setVelocity(0.0, 0.0, 0.0);
    });
    node.on("bodyExited", function (who) {
        if (who === "Player") inside = false;
    });
}

// scripts/platform.js (excerpt) — a StaticBody does not carry a rider, so the
// platform hands its own frame delta to whoever is standing on it. Otherwise
// the player slides off the moment it starts moving.
const delta = offset - previous;
previous = offset;

if (player === null || Math.abs(delta) < 1e-6) return;
const here = node.getPosition();
const p = player.getPosition();
const dx = p.x - here.x;
const dz = p.z - here.z;
const above = p.y - here.y;
if (dx * dx + dz * dz > props.carryRadius * props.carryRadius) return;
if (above < 0.0 || above > props.carryHeight) return;

player.setPosition(p.x + (axis === "x" ? delta : 0.0),
                   p.y + (axis === "y" ? delta : 0.0),
                   p.z + (axis === "z" ? delta : 0.0));

// scripts/prompt.js — an adaptive prompt attached to a UITextNode. The label
// follows the last active device; before any activity ("none"), the keyboard
// prompt is the default.

const LABELS = {
    "keyboard-mouse": "Move: WASD",
    "gamepad": "Move: Left Stick",
    "touch": "Move: Swipe"
};
const DEFAULT_LABEL = LABELS["keyboard-mouse"];

let last = null;

function refresh() {
    const device = String(input.lastActiveDevice());
    if (device === last) return;
    last = device;
    node.setText(LABELS[device] || DEFAULT_LABEL);
}

function onReady() {
    refresh();
    time.every(0.1, refresh);
}