sci2-ts 0.0.0-stage → 0.2.1

package/packages/sci/src/script/opcodes.js

@@ -0,0 +1,45 @@
+const op = (name, ...operands) => ({ name, operands });
+const base = [
+    // 0x00–0x16: arithmetic and comparison. Binary ops combine the stack top with acc.
+    op("bnot"), op("add"), op("sub"), op("mul"), op("div"), op("mod"), op("shr"), op("shl"),
+    op("xor"), op("and"), op("or"), op("neg"), op("not"), op("eq?"), op("ne?"), op("gt?"),
+    op("ge?"), op("lt?"), op("le?"), op("ugt?"), op("uge?"), op("ult?"), op("ule?"),
+    // 0x17–0x1e: branches and the stack
+    op("bt", "R"), op("bnt", "R"), op("jmp", "R"), op("ldi", "S"), op("push"), op("pushi", "S"), op("toss"), op("dup"),
+    // 0x1f–0x25: calls. The last operand is the argument frame size in bytes.
+    op("link", "W"),
+    op("call", "R", "U"), // local procedure
+    op("callk", "W", "U"), // kernel (interpreter built-in)
+    op("callb", "W", "U"), // export of script 0
+    op("calle", "W", "W", "U"), // export of another script
+    op("ret"),
+    op("send", "W"), // send messages to the object in acc
+    // 0x26–0x2f: objects
+    op("dummy26"), op("dummy27"),
+    op("class", "W"), // acc = class object
+    op("dummy29"),
+    op("self", "W"), op("super", "W", "U"), op("&rest", "W"),
+    op("lea", "W", "W"), op("selfID"), op("dummy2f"),
+    // 0x30–0x38: properties of the current object (operand = property offset in bytes)
+    op("pprev"), op("pToa", "W"), op("aTop", "W"), op("pTos", "W"), op("sTop", "W"),
+    op("ipToa", "W"), op("dpToa", "W"), op("ipTos", "W"), op("dpTos", "W"),
+    // 0x39–0x3f
+    op("lofsa", "W"), op("lofss", "W"), // address of a heap object/string
+    op("push0"), op("push1"), op("push2"), op("pushSelf"), op("dummy3f"),
+];
+/**
+ * 0x40–0x7f: variable access, generated from a pattern:
+ *   bits 0-1: g(lobal) l(ocal) t(emp) p(aram)
+ *   bit 2:    a = acc, s = stack
+ *   bit 3:    i = indexed by acc
+ *   bits 4-5: l(oad), s(tore), + (increment), - (decrement)
+ */
+const varOps = Array.from({ length: 64 }, (_, i) => {
+    const kind = "gltp"[i & 3];
+    const target = i & 4 ? "s" : "a";
+    const indexed = i & 8 ? "i" : "";
+    const action = ["l", "s", "+", "-"][i >> 4];
+    return op(`${action}${target}${kind}${indexed}`, "W");
+});
+export const opcodes = [...base, ...varOps];
+export const varKind = (opcode) => opcode >= 0x40 ? ["global", "local", "temp", "param"][opcode & 3] : undefined;

package/packages/sci/src/script/opcodes.ts

@@ -0,0 +1,72 @@
+/**
+ * SCI bytecode. Each instruction's first byte is `opcode << 1 | size`: when the low bit is
+ * set, "sized" operands are 1 byte instead of 2.
+ *
+ * Operand kinds:
+ *   W  sized unsigned (word or byte)      S  sized signed
+ *   R  sized signed, relative to the next instruction (jump/call target)
+ *   B  always 1 byte                     U  always 2 bytes
+ *
+ * SCI2 quirk, found by measuring: the argument-frame operand of call/callk/callb/calle/super
+ * is always 16-bit, even in the byte form; send and self frames follow the size bit.
+ * (SCI0–1.1 used a fixed byte.) Decoding it as a byte leaves a stray 0x00, which shows up
+ * as thousands of bogus `bnot` instructions.
+ */
+export type OperandKind = "W" | "S" | "R" | "B" | "U";
+
+export interface OpcodeInfo {
+  name: string;
+  operands: OperandKind[];
+}
+
+const op = (name: string, ...operands: OperandKind[]): OpcodeInfo => ({ name, operands });
+
+const base: OpcodeInfo[] = [
+  // 0x00–0x16: arithmetic and comparison. Binary ops combine the stack top with acc.
+  op("bnot"), op("add"), op("sub"), op("mul"), op("div"), op("mod"), op("shr"), op("shl"),
+  op("xor"), op("and"), op("or"), op("neg"), op("not"), op("eq?"), op("ne?"), op("gt?"),
+  op("ge?"), op("lt?"), op("le?"), op("ugt?"), op("uge?"), op("ult?"), op("ule?"),
+  // 0x17–0x1e: branches and the stack
+  op("bt", "R"), op("bnt", "R"), op("jmp", "R"), op("ldi", "S"), op("push"), op("pushi", "S"), op("toss"), op("dup"),
+  // 0x1f–0x25: calls. The last operand is the argument frame size in bytes.
+  op("link", "W"),
+  op("call", "R", "U"), // local procedure
+  op("callk", "W", "U"), // kernel (interpreter built-in)
+  op("callb", "W", "U"), // export of script 0
+  op("calle", "W", "W", "U"), // export of another script
+  op("ret"),
+  op("send", "W"), // send messages to the object in acc
+  // 0x26–0x2f: objects
+  op("dummy26"), op("dummy27"),
+  op("class", "W"), // acc = class object
+  op("dummy29"),
+  op("self", "W"), op("super", "W", "U"), op("&rest", "W"),
+  op("lea", "W", "W"), op("selfID"), op("dummy2f"),
+  // 0x30–0x38: properties of the current object (operand = property offset in bytes)
+  op("pprev"), op("pToa", "W"), op("aTop", "W"), op("pTos", "W"), op("sTop", "W"),
+  op("ipToa", "W"), op("dpToa", "W"), op("ipTos", "W"), op("dpTos", "W"),
+  // 0x39–0x3f
+  op("lofsa", "W"), op("lofss", "W"), // address of a heap object/string
+  op("push0"), op("push1"), op("push2"), op("pushSelf"), op("dummy3f"),
+];
+
+/**
+ * 0x40–0x7f: variable access, generated from a pattern:
+ *   bits 0-1: g(lobal) l(ocal) t(emp) p(aram)
+ *   bit 2:    a = acc, s = stack
+ *   bit 3:    i = indexed by acc
+ *   bits 4-5: l(oad), s(tore), + (increment), - (decrement)
+ */
+const varOps = Array.from({ length: 64 }, (_, i) => {
+  const kind = "gltp"[i & 3]!;
+  const target = i & 4 ? "s" : "a";
+  const indexed = i & 8 ? "i" : "";
+  const action = ["l", "s", "+", "-"][i >> 4]!;
+  return op(`${action}${target}${kind}${indexed}`, "W");
+});
+
+export const opcodes: readonly OpcodeInfo[] = [...base, ...varOps];
+
+export type VarKind = "global" | "local" | "temp" | "param";
+export const varKind = (opcode: number): VarKind | undefined =>
+  opcode >= 0x40 ? (["global", "local", "temp", "param"] as const)[opcode & 3] : undefined;

package/packages/sci/src/script/script.d.ts

@@ -0,0 +1,56 @@
+/** Object property slots common to every object (SCI1.1/SCI2 layout, in words). */
+export declare const ObjectSlot: {
+    readonly Magic: 0;
+    readonly Size: 1;
+    readonly PropDict: 2;
+    readonly MethDict: 3;
+    readonly ClassScript: 4;
+    readonly Species: 5;
+    readonly Super: 6;
+    readonly Info: 7;
+    readonly Name: 8;
+};
+export interface Method {
+    selector: number;
+    /** Code offset in the script resource. */
+    offset: number;
+}
+export interface ScriptObject {
+    /** Offset of the object in the heap resource. */
+    offset: number;
+    name: string;
+    isClass: boolean;
+    species: number;
+    superclass: number;
+    /** Raw property values, including the header slots above. */
+    properties: number[];
+    /** Selector id per property; only present on classes (instances use their class's). */
+    propSelectors?: number[];
+    methods: Method[];
+}
+export interface Export {
+    index: number;
+    offset: number;
+    /** Objects live in the heap; procedures are code in the script. Offset 0 = unused slot. */
+    kind: "object" | "code" | "empty";
+}
+/**
+ * A loaded script: bytecode and dictionaries in the script resource, data (locals,
+ * objects, strings) in the heap resource of the same number. SCI3 later merged the two.
+ */
+export interface Script {
+    number: number;
+    code: Uint8Array;
+    heap: Uint8Array;
+    exports: Export[];
+    locals: number[];
+    objects: ScriptObject[];
+}
+/** Reads a NUL-terminated Latin-1 string. */
+export declare function readString(data: Uint8Array, offset: number): string;
+/**
+ * Script resource:  +0 u16 relocation table offset | +6 u16 export count | +8 u16 exports
+ * Heap resource:    +0 u16 relocation table offset | +2 u16 local count | locals |
+ *                   objects (each starts with 0x1234) until a 0 word | strings
+ */
+export declare function parseScript(number: number, code: Uint8Array, heap: Uint8Array): Script;

package/packages/sci/src/script/script.js

@@ -0,0 +1,63 @@
+/** Object property slots common to every object (SCI1.1/SCI2 layout, in words). */
+export const ObjectSlot = {
+    Magic: 0, // 0x1234
+    Size: 1, // property count
+    PropDict: 2, // script offset: selector id per property (classes only)
+    MethDict: 3, // script offset: u16 count, then (selector, code offset) pairs
+    ClassScript: 4,
+    Species: 5, // class number; 0xFFFF on instances
+    Super: 6, // superclass number
+    Info: 7, // flags; 0x8000 = class
+    Name: 8, // heap offset of the name string
+};
+const OBJECT_MAGIC = 0x1234;
+const INFO_CLASS = 0x8000;
+/** Reads a NUL-terminated Latin-1 string. */
+export function readString(data, offset) {
+    let end = offset;
+    while (end < data.length && data[end] !== 0)
+        end++;
+    return new TextDecoder("latin1").decode(data.subarray(offset, end));
+}
+/**
+ * Script resource:  +0 u16 relocation table offset | +6 u16 export count | +8 u16 exports
+ * Heap resource:    +0 u16 relocation table offset | +2 u16 local count | locals |
+ *                   objects (each starts with 0x1234) until a 0 word | strings
+ */
+export function parseScript(number, code, heap) {
+    const cv = new DataView(code.buffer, code.byteOffset, code.byteLength);
+    const hv = new DataView(heap.buffer, heap.byteOffset, heap.byteLength);
+    const heapWord = (o) => hv.getUint16(o, true);
+    const codeWord = (o) => cv.getUint16(o, true);
+    const localCount = heapWord(2);
+    const locals = Array.from({ length: localCount }, (_, i) => heapWord(4 + i * 2));
+    const objects = [];
+    for (let pos = 4 + localCount * 2; pos + 2 <= heap.length && heapWord(pos) === OBJECT_MAGIC;) {
+        const size = heapWord(pos + 2);
+        const properties = Array.from({ length: size }, (_, i) => heapWord(pos + i * 2));
+        const isClass = (properties[ObjectSlot.Info] & INFO_CLASS) !== 0;
+        const methDict = properties[ObjectSlot.MethDict];
+        const methods = Array.from({ length: codeWord(methDict) }, (_, i) => ({
+            selector: codeWord(methDict + 2 + i * 4),
+            offset: codeWord(methDict + 4 + i * 4),
+        }));
+        const propDict = properties[ObjectSlot.PropDict];
+        objects.push({
+            offset: pos,
+            name: readString(heap, properties[ObjectSlot.Name]),
+            isClass,
+            species: properties[ObjectSlot.Species],
+            superclass: properties[ObjectSlot.Super],
+            properties,
+            propSelectors: isClass ? Array.from({ length: size }, (_, i) => codeWord(propDict + i * 2)) : undefined,
+            methods,
+        });
+        pos += size * 2;
+    }
+    const objectOffsets = new Set(objects.map((o) => o.offset));
+    const exports = Array.from({ length: codeWord(6) }, (_, index) => {
+        const offset = codeWord(8 + index * 2);
+        return { index, offset, kind: offset === 0 ? "empty" : objectOffsets.has(offset) ? "object" : "code" };
+    });
+    return { number, code, heap, exports, locals, objects };
+}

package/packages/sci/src/script/script.ts

@@ -0,0 +1,111 @@
+/** Object property slots common to every object (SCI1.1/SCI2 layout, in words). */
+export const ObjectSlot = {
+  Magic: 0, // 0x1234
+  Size: 1, // property count
+  PropDict: 2, // script offset: selector id per property (classes only)
+  MethDict: 3, // script offset: u16 count, then (selector, code offset) pairs
+  ClassScript: 4,
+  Species: 5, // class number; 0xFFFF on instances
+  Super: 6, // superclass number
+  Info: 7, // flags; 0x8000 = class
+  Name: 8, // heap offset of the name string
+} as const;
+
+const OBJECT_MAGIC = 0x1234;
+const INFO_CLASS = 0x8000;
+
+export interface Method {
+  selector: number;
+  /** Code offset in the script resource. */
+  offset: number;
+}
+
+export interface ScriptObject {
+  /** Offset of the object in the heap resource. */
+  offset: number;
+  name: string;
+  isClass: boolean;
+  species: number;
+  superclass: number;
+  /** Raw property values, including the header slots above. */
+  properties: number[];
+  /** Selector id per property; only present on classes (instances use their class's). */
+  propSelectors?: number[];
+  methods: Method[];
+}
+
+export interface Export {
+  index: number;
+  offset: number;
+  /** Objects live in the heap; procedures are code in the script. Offset 0 = unused slot. */
+  kind: "object" | "code" | "empty";
+}
+
+/**
+ * A loaded script: bytecode and dictionaries in the script resource, data (locals,
+ * objects, strings) in the heap resource of the same number. SCI3 later merged the two.
+ */
+export interface Script {
+  number: number;
+  code: Uint8Array;
+  heap: Uint8Array;
+  exports: Export[];
+  locals: number[];
+  objects: ScriptObject[];
+}
+
+/** Reads a NUL-terminated Latin-1 string. */
+export function readString(data: Uint8Array, offset: number): string {
+  let end = offset;
+  while (end < data.length && data[end] !== 0) end++;
+  return new TextDecoder("latin1").decode(data.subarray(offset, end));
+}
+
+/**
+ * Script resource:  +0 u16 relocation table offset | +6 u16 export count | +8 u16 exports
+ * Heap resource:    +0 u16 relocation table offset | +2 u16 local count | locals |
+ *                   objects (each starts with 0x1234) until a 0 word | strings
+ */
+export function parseScript(number: number, code: Uint8Array, heap: Uint8Array): Script {
+  const cv = new DataView(code.buffer, code.byteOffset, code.byteLength);
+  const hv = new DataView(heap.buffer, heap.byteOffset, heap.byteLength);
+  const heapWord = (o: number) => hv.getUint16(o, true);
+  const codeWord = (o: number) => cv.getUint16(o, true);
+
+  const localCount = heapWord(2);
+  const locals = Array.from({ length: localCount }, (_, i) => heapWord(4 + i * 2));
+
+  const objects: ScriptObject[] = [];
+  for (let pos = 4 + localCount * 2; pos + 2 <= heap.length && heapWord(pos) === OBJECT_MAGIC; ) {
+    const size = heapWord(pos + 2);
+    const properties = Array.from({ length: size }, (_, i) => heapWord(pos + i * 2));
+    const isClass = (properties[ObjectSlot.Info]! & INFO_CLASS) !== 0;
+
+    const methDict = properties[ObjectSlot.MethDict]!;
+    const methods = Array.from({ length: codeWord(methDict) }, (_, i) => ({
+      selector: codeWord(methDict + 2 + i * 4),
+      offset: codeWord(methDict + 4 + i * 4),
+    }));
+
+    const propDict = properties[ObjectSlot.PropDict]!;
+    objects.push({
+      offset: pos,
+      name: readString(heap, properties[ObjectSlot.Name]!),
+      isClass,
+      species: properties[ObjectSlot.Species]!,
+      superclass: properties[ObjectSlot.Super]!,
+      properties,
+      propSelectors: isClass ? Array.from({ length: size }, (_, i) => codeWord(propDict + i * 2)) : undefined,
+      methods,
+    });
+    pos += size * 2;
+  }
+
+  const objectOffsets = new Set(objects.map((o) => o.offset));
+  const exports = Array.from({ length: codeWord(6) }, (_, index): Export => {
+    const offset = codeWord(8 + index * 2);
+    return { index, offset, kind: offset === 0 ? "empty" : objectOffsets.has(offset) ? "object" : "code" };
+  });
+
+  return { number, code, heap, exports, locals, objects };
+}

package/packages/sci/src/script/sexpr.d.ts

@@ -0,0 +1,45 @@
+/**
+ * The reader for SCI script source: parenthesised lists, with a few kinds of atom.
+ *
+ *   (send obj x: 1)      a list                  [buf 3]   an array element (or declaration)
+ *   foo  x:  y?  &rest   symbols                  42 -7 $1F %101 `a   numbers
+ *   "text" {text}        strings                  #init     a selector
+ *   @buf  @[buf i]       a variable's address, an element's   ; ...  a comment, to the end of the line
+ */
+export type Node = {
+    kind: "list";
+    items: Node[];
+    line: number;
+} | {
+    kind: "index";
+    items: Node[];
+    line: number;
+} | {
+    kind: "sym";
+    name: string;
+    line: number;
+} | {
+    kind: "num";
+    value: number;
+    line: number;
+} | {
+    kind: "str";
+    value: string;
+    line: number;
+} | {
+    kind: "sel";
+    name: string;
+    line: number;
+} | {
+    kind: "addr";
+    name: string;
+    index?: Node;
+    line: number;
+};
+export declare class ReadError extends Error {
+    readonly line: number;
+    constructor(message: string, line: number);
+}
+export declare function read(text: string): Node[];
+/** A node as source text again, for error messages. */
+export declare function show(n: Node): string;

package/packages/sci/src/script/sexpr.js

@@ -0,0 +1,151 @@
+export class ReadError extends Error {
+    line;
+    constructor(message, line) {
+        super(`line ${line}: ${message}`);
+        this.line = line;
+    }
+}
+const DELIMITERS = new Set([..."()[]{}\";"]);
+const isSpace = (c) => c === " " || c === "\t" || c === "\r" || c === "\n";
+export function read(text) {
+    let p = 0, line = 1;
+    const top = [];
+    const stack = [];
+    const add = (n) => (stack.length ? stack[stack.length - 1].node.items : top).push(n);
+    while (p < text.length) {
+        const c = text[p];
+        if (c === "\n") {
+            line++;
+            p++;
+            continue;
+        }
+        if (isSpace(c)) {
+            p++;
+            continue;
+        }
+        if (c === ";") {
+            while (p < text.length && text[p] !== "\n")
+                p++;
+            continue;
+        }
+        if (c === "(" || c === "[") {
+            const node = { kind: c === "(" ? "list" : "index", items: [], line };
+            add(node);
+            stack.push({ node, close: c === "(" ? ")" : "]" });
+            p++;
+            continue;
+        }
+        if (c === ")" || c === "]") {
+            const open = stack.pop();
+            if (!open)
+                throw new ReadError(`unexpected ${c}`, line);
+            if (open.close !== c)
+                throw new ReadError(`expected ${open.close} to close the ${open.close === ")" ? "(" : "["} on line ${open.node.line}, got ${c}`, line);
+            p++;
+            continue;
+        }
+        if (c === '"' || c === "{") {
+            const end = c === '"' ? '"' : "}";
+            const start = line;
+            let value = "";
+            p++;
+            for (;;) {
+                if (p >= text.length)
+                    throw new ReadError("string never ends", start);
+                const ch = text[p];
+                if (ch === end) {
+                    p++;
+                    break;
+                }
+                if (ch === "\n")
+                    line++;
+                if (ch === "\\") {
+                    const n = text[p + 1] ?? "";
+                    if (n === "n")
+                        value += "\n";
+                    else if (n === "t")
+                        value += "\t";
+                    else if (/[0-9a-fA-F]/.test(n) && /[0-9a-fA-F]/.test(text[p + 2] ?? "")) {
+                        value += String.fromCharCode(parseInt(text.slice(p + 1, p + 3), 16));
+                        p++;
+                    }
+                    else
+                        value += n;
+                    p += 2;
+                    continue;
+                }
+                value += ch;
+                p++;
+            }
+            add({ kind: "str", value, line: start });
+            continue;
+        }
+        if (c === "`") {
+            // A character: `a is 97; `^a is control-A; `#4 is a key with a scan code (not supported).
+            const ch = text[p + 1];
+            if (ch === undefined)
+                throw new ReadError("` needs a character", line);
+            if (ch === "^" && text[p + 2] && !isSpace(text[p + 2])) {
+                add({ kind: "num", value: text[p + 2].toUpperCase().charCodeAt(0) - 64, line });
+                p += 3;
+            }
+            else {
+                add({ kind: "num", value: ch.charCodeAt(0), line });
+                p += 2;
+            }
+            continue;
+        }
+        let e = p;
+        while (e < text.length && !isSpace(text[e]) && !DELIMITERS.has(text[e]))
+            e++;
+        const token = text.slice(p, e);
+        p = e;
+        add(atom(token, line));
+    }
+    if (stack.length)
+        throw new ReadError(`( never closed`, stack[stack.length - 1].node.line);
+    return addresses(top);
+}
+/** `@` then `[buf i]` is one thing: the address of an element. */
+function addresses(nodes) {
+    const out = [];
+    for (let i = 0; i < nodes.length; i++) {
+        const n = nodes[i];
+        const next = nodes[i + 1];
+        if (n.kind === "sym" && n.name === "@" && next?.kind === "index" && next.items.length === 2 && next.items[0].kind === "sym") {
+            out.push({ kind: "addr", name: next.items[0].name, index: addresses([next.items[1]])[0], line: n.line });
+            i++;
+            continue;
+        }
+        if (n.kind === "list" || n.kind === "index")
+            out.push({ ...n, items: addresses(n.items) });
+        else
+            out.push(n);
+    }
+    return out;
+}
+function atom(token, line) {
+    if (/^-?\d+$/.test(token))
+        return { kind: "num", value: Number(token), line };
+    if (/^-?\$[0-9a-fA-F]+$/.test(token))
+        return { kind: "num", value: (token.startsWith("-") ? -1 : 1) * parseInt(token.replace(/^-?\$/, ""), 16), line };
+    if (/^%[01]+$/.test(token))
+        return { kind: "num", value: parseInt(token.slice(1), 2), line };
+    if (token.startsWith("#") && token.length > 1)
+        return { kind: "sel", name: token.slice(1), line };
+    if (token.startsWith("@") && token.length > 1)
+        return { kind: "addr", name: token.slice(1), line };
+    return { kind: "sym", name: token, line };
+}
+/** A node as source text again, for error messages. */
+export function show(n) {
+    switch (n.kind) {
+        case "list": return `(${n.items.map(show).join(" ")})`;
+        case "index": return `[${n.items.map(show).join(" ")}]`;
+        case "sym": return n.name;
+        case "num": return String(n.value);
+        case "str": return JSON.stringify(n.value);
+        case "sel": return `#${n.name}`;
+        case "addr": return n.index ? `@[${n.name} ${show(n.index)}]` : `@${n.name}`;
+    }
+}