sci2-ts 0.0.0-stage → 0.2.2

package/packages/content/src/target.d.ts

@@ -0,0 +1,80 @@
+/**
+ * What the compiler needs to know about the game it builds for: which classes rooms
+ * subclass, where the system objects live (globals) and how messages are numbered. The
+ * compiler itself knows nothing about any particular game.
+ */
+export interface Target {
+    /** The class new rooms subclass: the game's own room class. */
+    roomClass: string;
+    /** Property values every room gets unless the YAML overrides them. */
+    roomDefaults: Record<string, number>;
+    /** Global variable numbers (SCI's script 0 locals). */
+    globals: {
+        ego: number;
+        game: number;
+        curRoom: number;
+        /** The Messager instance whose `say:` shows a message. */
+        messager: number;
+        /** The narrator object (what unknown talker numbers fall back to). */
+        narratorObject: number;
+        /** The Sound object playing the music, and the one for sound effects. */
+        music: number;
+        sound: number;
+    };
+    /** Message talker number for narration (no speaker). */
+    narrator: number;
+    /** Message talker number for the hero (`Hero:` lines, and the topics they pick). */
+    heroTalker: number;
+    /**
+     * Talker numbers from here up are characters defined by compiled rooms: the game asks
+     * the current room's `findTalker:` for them (needs the target's support patch).
+     */
+    firstRoomTalker: number;
+    /** A character without a portrait: a plain text box, this class and properties. */
+    voice: {
+        class: string;
+        props: Record<string, number>;
+    };
+    /**
+     * A character with a portrait view: loop 0 the bust, loop 1 mouth shapes, loop 2 eyes
+     * (cel 0 open), all cels the same size so the parts line up. The talker class gets
+     * `init: mouth bust eyes frame`; parts are a View (bust) and Props at `at`.
+     */
+    portrait: {
+        class: string;
+        props: Record<string, number>;
+        at: [number, number];
+        frameSignal: number;
+        partSignal: number;
+    };
+    /**
+     * Conversations: an instance of this class runs a menu of topics for a thing (e.g. a
+     * Teller with `init: client modNum sayNoun verb rootNoun`; topic labels are messages at
+     * rootNoun/verb/cond, answers at sayNoun/verb/cond).
+     */
+    teller: {
+        class: string;
+        props: Record<string, number>;
+        verb: number;
+    };
+    /** The class that cycles a prop's cels forever (<<animate x forever>>, cycle: forward). */
+    forwardCycle: string;
+    /** Verb number for "said on arrival" messages. */
+    narrationVerb: number;
+    /** Verb names as used in Yarn node titles (lower case) -> verb numbers. */
+    verbs: Record<string, number>;
+    /** Message file version written in new message files. */
+    messageVersion: number;
+    /**
+     * Flags (Yarn's true/false variables): procedures `set`, `clear`, `test` (export numbers
+     * of `script`, each taking the flag number), and the range a mod may use.
+     */
+    flags: {
+        script: number;
+        set: number;
+        clear: number;
+        test: number;
+        first: number;
+        last: number;
+    };
+}

package/packages/content/src/target.js

@@ -0,0 +1 @@
+export {};

package/packages/content/src/target.ts

@@ -0,0 +1,60 @@
+/**
+ * What the compiler needs to know about the game it builds for: which classes rooms
+ * subclass, where the system objects live (globals) and how messages are numbered. The
+ * compiler itself knows nothing about any particular game.
+ */
+export interface Target {
+  /** The class new rooms subclass: the game's own room class. */
+  roomClass: string;
+  /** Property values every room gets unless the YAML overrides them. */
+  roomDefaults: Record<string, number>;
+  /** Global variable numbers (SCI's script 0 locals). */
+  globals: {
+    ego: number;
+    game: number;
+    curRoom: number;
+    /** The Messager instance whose `say:` shows a message. */
+    messager: number;
+    /** The narrator object (what unknown talker numbers fall back to). */
+    narratorObject: number;
+    /** The Sound object playing the music, and the one for sound effects. */
+    music: number;
+    sound: number;
+  };
+  /** Message talker number for narration (no speaker). */
+  narrator: number;
+  /** Message talker number for the hero (`Hero:` lines, and the topics they pick). */
+  heroTalker: number;
+  /**
+   * Talker numbers from here up are characters defined by compiled rooms: the game asks
+   * the current room's `findTalker:` for them (needs the target's support patch).
+   */
+  firstRoomTalker: number;
+  /** A character without a portrait: a plain text box, this class and properties. */
+  voice: { class: string; props: Record<string, number> };
+  /**
+   * A character with a portrait view: loop 0 the bust, loop 1 mouth shapes, loop 2 eyes
+   * (cel 0 open), all cels the same size so the parts line up. The talker class gets
+   * `init: mouth bust eyes frame`; parts are a View (bust) and Props at `at`.
+   */
+  portrait: { class: string; props: Record<string, number>; at: [number, number]; frameSignal: number; partSignal: number };
+  /**
+   * Conversations: an instance of this class runs a menu of topics for a thing (e.g. a
+   * Teller with `init: client modNum sayNoun verb rootNoun`; topic labels are messages at
+   * rootNoun/verb/cond, answers at sayNoun/verb/cond).
+   */
+  teller: { class: string; props: Record<string, number>; verb: number };
+  /** The class that cycles a prop's cels forever (<<animate x forever>>, cycle: forward). */
+  forwardCycle: string;
+  /** Verb number for "said on arrival" messages. */
+  narrationVerb: number;
+  /** Verb names as used in Yarn node titles (lower case) -> verb numbers. */
+  verbs: Record<string, number>;
+  /** Message file version written in new message files. */
+  messageVersion: number;
+  /**
+   * Flags (Yarn's true/false variables): procedures `set`, `clear`, `test` (export numbers
+   * of `script`, each taking the flag number), and the range a mod may use.
+   */
+  flags: { script: number; set: number; clear: number; test: number; first: number; last: number };
+}

package/packages/content/src/yarn.d.ts

@@ -0,0 +1,90 @@
+/**
+ * Yarn Spinner's file format (https://docs.yarnspinner.dev), the part rooms use so far:
+ *
+ *   title: wisp.talk        <- headers, `key: value`, until ---
+ *   ---
+ *   Golden pods hang from the rock.     <- a line; `Speaker: text` names who says it
+ *   <<if $met_wisp>>                    <- conditions on true/false variables:
+ *       They hum when you're near.         not, and, or, ==, !=, (...), true, false
+ *   <<else>>
+ *       They're silent.
+ *   <<endif>>
+ *   <<set $looked to true>>
+ *   -> Who are you?                     <- a choice; its body is indented below it
+ *       Wisp: A memory of this place.
+ *   -> Sing for me <<if $met_wisp>>     <- a choice only offered when its condition holds
+ *       Wisp: Not yet.
+ *   // a comment
+ *   ===
+ *
+ * Other commands (<<walk hero 110 160>>, <<wait 2>>...) are kept as name + arguments for
+ * the compiler to check. Choices inside choices or inside <<if>> are rejected with the
+ * line they're on, until the compiler supports them.
+ */
+export interface YarnNode {
+    title: string;
+    headers: Record<string, string>;
+    body: YarnItem[];
+    /** Where the node starts, for error messages. */
+    line: number;
+}
+export type YarnItem = YarnLine | YarnChoice | YarnSet | YarnIf | YarnCommand;
+/** Any other <<command arg arg ...>>; the compiler knows which exist (walk, wait, ...). */
+export interface YarnCommand {
+    kind: "command";
+    name: string;
+    args: string[];
+    line: number;
+}
+export interface YarnLine {
+    kind: "line";
+    speaker?: string;
+    text: string;
+    line: number;
+}
+export interface YarnChoice {
+    kind: "choice";
+    text: string;
+    /** Only offered when this holds. */
+    when?: YarnExpr;
+    body: YarnItem[];
+    line: number;
+}
+export interface YarnSet {
+    kind: "set";
+    name: string;
+    value: YarnExpr;
+    line: number;
+}
+export interface YarnIf {
+    kind: "if";
+    /** `if` and `elseif` branches in order; a final `else` has no condition. */
+    branches: {
+        when?: YarnExpr;
+        body: YarnItem[];
+    }[];
+    line: number;
+}
+/** Boolean expressions over variables (each a flag). */
+export type YarnExpr = {
+    kind: "var";
+    name: string;
+} | {
+    kind: "const";
+    value: boolean;
+} | {
+    kind: "not";
+    of: YarnExpr;
+} | {
+    kind: "and" | "or";
+    a: YarnExpr;
+    b: YarnExpr;
+};
+export declare class YarnError extends Error {
+    readonly file: string;
+    readonly line: number;
+    constructor(file: string, line: number, message: string);
+}
+export declare function parseYarn(source: string, file?: string): YarnNode[];
+/** `$a and not ($b or $c == false)`: Yarn's boolean operators, both spellings. */
+export declare function parseExpr(source: string, fail: (why: string) => never): YarnExpr;

package/packages/content/src/yarn.js

@@ -0,0 +1,214 @@
+export class YarnError extends Error {
+    file;
+    line;
+    constructor(file, line, message) {
+        super(`${file}:${line}: ${message}`);
+        this.file = file;
+        this.line = line;
+    }
+}
+/** Trailing #tags (Yarn's line ids and metadata) don't belong to the text. */
+const stripTags = (s) => s.replace(/(\s+#[^\s#]+)+\s*$/, "");
+const indentOf = (s) => /^[ \t]*/.exec(s)[0].replace(/\t/g, "    ").length;
+export function parseYarn(source, file = "<yarn>") {
+    const nodes = [];
+    const lines = source.split(/\r?\n/);
+    let i = 0;
+    const fail = (line, why) => {
+        throw new YarnError(file, line, why);
+    };
+    while (i < lines.length) {
+        // Headers.
+        const start = i + 1;
+        const headers = {};
+        for (; i < lines.length && lines[i].trim() !== "---"; i++) {
+            const raw = lines[i].trim();
+            if (!raw || raw.startsWith("//"))
+                continue;
+            const m = /^([A-Za-z_][\w.-]*)\s*:\s*(.*)$/.exec(raw);
+            if (!m)
+                fail(i + 1, `expected a header (key: value) or ---, got "${raw}"`);
+            headers[m[1]] = m[2].trim();
+        }
+        if (i >= lines.length) {
+            if (Object.keys(headers).length)
+                fail(start, "node has no body: expected --- after its headers");
+            break;
+        }
+        const title = headers.title;
+        if (!title)
+            fail(start, "node has no title: header");
+        if (nodes.some((n) => n.title === title))
+            fail(start, `a node called "${title}" already exists`);
+        i++; // ---
+        // The body's lines up to ===, then parsed into a tree.
+        const body = [];
+        let closed = false;
+        for (; i < lines.length; i++) {
+            const raw = lines[i].trim();
+            if (raw === "===") {
+                closed = true;
+                i++;
+                break;
+            }
+            if (!raw || raw.startsWith("//"))
+                continue;
+            body.push({ text: raw, indent: indentOf(lines[i]), line: i + 1 });
+        }
+        if (!closed)
+            fail(start, `node "${title}" isn't closed with ===`);
+        const parser = new BodyParser(body, fail);
+        nodes.push({ title: title, headers, body: parser.block(-1, false, false, []), line: start });
+        if (parser.at < body.length) {
+            const extra = body[parser.at];
+            fail(extra.line, `unexpected ${extra.text.split(/\s/)[0]} (no <<if>> is open)`);
+        }
+    }
+    return nodes;
+}
+class BodyParser {
+    lines;
+    fail;
+    at = 0;
+    constructor(lines, fail) {
+        this.lines = lines;
+        this.fail = fail;
+    }
+    /**
+     * Items until a line indented at most `parentIndent` (the end of a choice's body) or, in
+     * an <<if>>, one of `stopAt` (elseif/else/endif).
+     */
+    block(parentIndent, inChoice, inIf, stopAt) {
+        const items = [];
+        let choiceIndent;
+        while (this.at < this.lines.length) {
+            const { text, indent, line } = this.lines[this.at];
+            if (indent <= parentIndent)
+                break;
+            const command = /^<<\s*(\w+)\s*(.*?)\s*>>$/.exec(text);
+            if (command && stopAt.includes(command[1]))
+                break;
+            this.at++;
+            if (text.startsWith("->")) {
+                if (inChoice)
+                    this.fail(line, "choices inside choices aren't supported yet");
+                if (inIf)
+                    this.fail(line, "choices inside <<if>> aren't supported yet (use -> text <<if $x>>)");
+                if (choiceIndent !== undefined && indent !== choiceIndent)
+                    this.fail(line, "choices in a group must line up");
+                choiceIndent = indent;
+                let rest = stripTags(text.slice(2).trim());
+                let when;
+                const cond = /^(.*?)\s*<<\s*if\s+(.+?)\s*>>$/.exec(rest);
+                if (cond) {
+                    rest = cond[1];
+                    when = parseExpr(cond[2], (why) => this.fail(line, why));
+                }
+                if (!rest)
+                    this.fail(line, "a choice needs text after ->");
+                items.push({ kind: "choice", text: rest, when, body: this.block(indent, true, false, []), line });
+                continue;
+            }
+            if (command) {
+                const [, name, args] = command;
+                if (name === "set") {
+                    const m = /^\$([A-Za-z_]\w*)\s*(?:to|=)\s*(.+)$/.exec(args);
+                    if (!m)
+                        this.fail(line, "expected <<set $name to true>> (or false, or a condition)");
+                    items.push({ kind: "set", name: m[1], value: parseExpr(m[2], (why) => this.fail(line, why)), line });
+                }
+                else if (name === "if") {
+                    items.push(this.ifBlock(args, line, indent, inChoice));
+                }
+                else if (["elseif", "else", "endif"].includes(name)) {
+                    this.fail(line, `<<${name}>> without an <<if>>`);
+                }
+                else {
+                    items.push({ kind: "command", name: name, args: args ? args.split(/[\s,]+/).filter(Boolean) : [], line });
+                }
+                continue;
+            }
+            if (text.startsWith("<<"))
+                this.fail(line, `expected <<command ...>>, got "${text}"`);
+            const clean = stripTags(text);
+            const m = /^([A-Za-z][\w ]*?)\s*:\s+(.+)$/.exec(clean);
+            items.push(m ? { kind: "line", speaker: m[1], text: m[2], line } : { kind: "line", text: clean, line });
+        }
+        return items;
+    }
+    ifBlock(firstCond, line, indent, inChoice) {
+        const fail = (why) => this.fail(line, why);
+        const branches = [{ when: parseExpr(firstCond, fail), body: [] }];
+        // An <<if>>'s body is whatever comes before its <<elseif>>/<<else>>/<<endif>>, at any
+        // indentation deeper than the enclosing choice (Yarn doesn't require indenting it).
+        for (;;) {
+            branches[branches.length - 1].body = this.block(inChoice ? indent - 1 : -1, inChoice, true, ["elseif", "else", "endif"]);
+            const next = this.lines[this.at];
+            const command = next && /^<<\s*(\w+)\s*(.*?)\s*>>$/.exec(next.text);
+            if (!command)
+                this.fail(line, "<<if>> without <<endif>>");
+            this.at++;
+            if (command[1] === "endif")
+                return { kind: "if", branches, line };
+            if (branches.at(-1).when === undefined)
+                this.fail(next.line, `<<${command[1]}>> after <<else>>`);
+            if (command[1] === "else")
+                branches.push({ body: [] });
+            else
+                branches.push({ when: parseExpr(command[2], (why) => this.fail(next.line, why)), body: [] });
+        }
+    }
+}
+/** `$a and not ($b or $c == false)`: Yarn's boolean operators, both spellings. */
+export function parseExpr(source, fail) {
+    const tokens = source.match(/\$[A-Za-z_]\w*|&&|\|\||==|!=|[()!]|[A-Za-z_]\w*|\S/g) ?? [];
+    let p = 0;
+    const peek = () => tokens[p];
+    const take = () => tokens[p++];
+    const word = (t, ...names) => t !== undefined && names.includes(t.toLowerCase());
+    const or = () => {
+        let a = and();
+        while (word(peek(), "or", "||"))
+            (take(), (a = { kind: "or", a, b: and() }));
+        return a;
+    };
+    const and = () => {
+        let a = compare();
+        while (word(peek(), "and", "&&"))
+            (take(), (a = { kind: "and", a, b: compare() }));
+        return a;
+    };
+    const compare = () => {
+        const a = unary();
+        if (word(peek(), "==", "!=", "is", "eq", "neq")) {
+            const op = take().toLowerCase();
+            const b = unary();
+            // a == b is (a and b) or (not a and not b).
+            const same = { kind: "or", a: { kind: "and", a, b }, b: { kind: "and", a: { kind: "not", of: a }, b: { kind: "not", of: b } } };
+            return op === "!=" || op === "neq" ? { kind: "not", of: same } : same;
+        }
+        return a;
+    };
+    const unary = () => {
+        const t = take();
+        if (t === undefined)
+            fail(`incomplete condition "${source}"`);
+        if (word(t, "not", "!"))
+            return { kind: "not", of: unary() };
+        if (t === "(") {
+            const e = or();
+            if (take() !== ")")
+                fail(`missing ) in "${source}"`);
+            return e;
+        }
+        if (word(t, "true", "false"))
+            return { kind: "const", value: t.toLowerCase() === "true" };
+        if (t.startsWith("$"))
+            return { kind: "var", name: t.slice(1) };
+        return fail(`unexpected "${t}" in "${source}" (variables are $name; numbers and text aren't supported yet)`);
+    };
+    const e = or();
+    if (p < tokens.length)
+        fail(`unexpected "${tokens[p]}" in "${source}"`);
+    return e;
+}