@rpgm-tools/neo-angband-core 0.10.0

package/dist/guard.js

@@ -0,0 +1,65 @@
+/**
+ * Overflow-guarded integer arithmetic, ported from reference/src/z-util.c
+ * (Angband 4.2.6): add_guardi/sub_guardi coerce to the 32-bit int range and
+ * add_guardi16/sub_guardi16 to the signed 16-bit range when the exact result
+ * would overflow.
+ *
+ * The object power/pricing engine and the curse-attribute merge rely on these
+ * saturating semantics (a curse can push a bonus to the INT16 rail, and the
+ * curse-power delta arithmetic saturates at INT32), so the port reproduces the
+ * clamping exactly rather than letting JS doubles run unbounded.
+ */
+/** INT_MAX (32-bit signed). */
+export const INT_MAX = 2147483647;
+/** INT_MIN (32-bit signed). */
+export const INT_MIN = -2147483648;
+/** INT16_MAX. */
+export const INT16_MAX = 32767;
+/** INT16_MIN. */
+export const INT16_MIN = -32768;
+/** UINT32_MAX: the saturating ceiling for chunk->obj_rating / mon_rating. */
+export const UINT32_MAX = 4294967295;
+/**
+ * my_stristr (z-util.c:441): a case-insensitive substring search, returning
+ * whether `pattern` occurs anywhere in `string`. The C compares `toupper` per
+ * character; case-folding both sides is the same test for the ASCII data the
+ * gamedata files carry.
+ *
+ * Given a real counterpart rather than inlined a third time: it was already
+ * inlined at mon/bind.ts (raceByName's substring fallback) and MISSING at
+ * world/trap.ts's lookupTrap, which used a case-SENSITIVE `includes` where
+ * trap.c:57 uses my_stristr. Latent there only because every shipped trap desc
+ * and every call-site literal happens to be lower case today.
+ */
+export function myStristr(string, pattern) {
+    return string.toLowerCase().includes(pattern.toLowerCase());
+}
+/** add_guardi: a + b coerced into [INT_MIN, INT_MAX] on overflow. */
+export function addGuardi(a, b) {
+    if (a < 0) {
+        return b >= 0 || (b > INT_MIN && a >= INT_MIN - b) ? a + b : INT_MIN;
+    }
+    return b <= 0 || a <= INT_MAX - b ? a + b : INT_MAX;
+}
+/** sub_guardi: a - b coerced into [INT_MIN, INT_MAX] on overflow. */
+export function subGuardi(a, b) {
+    if (a < 0) {
+        return b <= 0 || a >= INT_MIN + b ? a - b : INT_MIN;
+    }
+    return b >= 0 || a <= INT_MAX + b ? a - b : INT_MAX;
+}
+/** add_guardi16: a + b coerced into [-32768, 32767] on overflow. */
+export function addGuardi16(a, b) {
+    if (a < 0) {
+        return b >= 0 || (b > INT16_MIN && a >= INT16_MIN - b) ? a + b : INT16_MIN;
+    }
+    return b <= 0 || a <= INT16_MAX - b ? a + b : INT16_MAX;
+}
+/** sub_guardi16: a - b coerced into [-32768, 32767] on overflow. */
+export function subGuardi16(a, b) {
+    if (a < 0) {
+        return b <= 0 || a >= INT16_MIN + b ? a - b : INT16_MIN;
+    }
+    return b >= 0 || a <= INT16_MAX + b ? a - b : INT16_MAX;
+}
+//# sourceMappingURL=guard.js.map

package/dist/guard.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"guard.js","sourceRoot":"","sources":["../src/guard.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,+BAA+B;AAC/B,MAAM,CAAC,MAAM,OAAO,GAAG,UAAU,CAAC;AAClC,+BAA+B;AAC/B,MAAM,CAAC,MAAM,OAAO,GAAG,CAAC,UAAU,CAAC;AACnC,iBAAiB;AACjB,MAAM,CAAC,MAAM,SAAS,GAAG,KAAK,CAAC;AAC/B,iBAAiB;AACjB,MAAM,CAAC,MAAM,SAAS,GAAG,CAAC,KAAK,CAAC;AAChC,6EAA6E;AAC7E,MAAM,CAAC,MAAM,UAAU,GAAG,UAAU,CAAC;AAErC;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,SAAS,CAAC,MAAc,EAAE,OAAe;IACvD,OAAO,MAAM,CAAC,WAAW,EAAE,CAAC,QAAQ,CAAC,OAAO,CAAC,WAAW,EAAE,CAAC,CAAC;AAC9D,CAAC;AAED,qEAAqE;AACrE,MAAM,UAAU,SAAS,CAAC,CAAS,EAAE,CAAS;IAC5C,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;QACV,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,GAAG,OAAO,IAAI,CAAC,IAAI,OAAO,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC;IACvE,CAAC;IACD,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,OAAO,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC;AACtD,CAAC;AAED,qEAAqE;AACrE,MAAM,UAAU,SAAS,CAAC,CAAS,EAAE,CAAS;IAC5C,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;QACV,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,OAAO,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC;IACtD,CAAC;IACD,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,OAAO,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC;AACtD,CAAC;AAED,oEAAoE;AACpE,MAAM,UAAU,WAAW,CAAC,CAAS,EAAE,CAAS;IAC9C,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;QACV,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,GAAG,SAAS,IAAI,CAAC,IAAI,SAAS,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;IAC7E,CAAC;IACD,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,SAAS,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;AAC1D,CAAC;AAED,oEAAoE;AACpE,MAAM,UAAU,WAAW,CAAC,CAAS,EAAE,CAAS;IAC9C,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;QACV,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,SAAS,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;IAC1D,CAAC;IACD,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,SAAS,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;AAC1D,CAAC"}

package/dist/host/args.d.ts

@@ -0,0 +1,129 @@
+/**
+ * main.c's command line, ported.
+ *
+ * `main()` (reference/src/main.c:342-491) is not platform-specific code - it is
+ * the shared entry point every front end without its own `main` uses, and its
+ * option loop is the only place the `arg_*` globals are ever set:
+ *
+ *   arg_wizard      (ui-game.c:79)   -w
+ *   arg_graphics    (ui-prefs.c)     -g
+ *   arg_name        (ui-prefs.c:41)  -u<who>
+ *   arg_force_name  (ui-birth.c:97)  -f
+ *   ANGBAND_SYS     (init.c:84)      -m<sys>
+ *
+ * Those five reach thirteen call sites between them, and `-f` alone reaches
+ * eight. The text census sees only ONE of them (ui-player.c:1250, "You are not
+ * allowed to change your name!") because the rest are branches rather than
+ * strings, so "add the message" would have been the wrong-shaped fix: what is
+ * missing is the switch that makes any of it reachable.
+ *
+ * Parsing is pure. The three things upstream does at parse time that touch the
+ * world - printing usage, listing savefiles, creating a `-d` directory - are
+ * reported as OUTCOMES for the front end to carry out, because only the front
+ * end has a console and a filesystem. Nothing here quits or writes.
+ */
+import type { HostDir } from "./io.js";
+/** option.h:23. Upstream truncates -u<who> into a buffer of this size. */
+export declare const PLAYER_NAME_LEN = 32;
+/**
+ * change_path_values (main.c:209-227), in upstream's order - which is the order
+ * the usage text lists them in.
+ *
+ * `setgidOk` is carried even though this port has no setgid build, because the
+ * flag is what decides whether a directory appears in the usage listing at all
+ * on such a build, and dropping it would quietly delete that behaviour. The
+ * three false entries are the ones a multi-user install must not let a player
+ * redirect: scores, save and panic.
+ */
+export declare const CHANGE_PATH_VALUES: readonly {
+    readonly name: string;
+    readonly setgidOk: boolean;
+}[];
+/** A display module, as `modules[]` (main.c:63-95) describes one. */
+export interface LaunchModule {
+    /** The name `-m` matches, and the value ANGBAND_SYS takes. */
+    readonly name: string;
+    /** The one-line help the usage text prints beside it. */
+    readonly help: string;
+}
+/** The `arg_*` globals, gathered. */
+export interface LaunchArgs {
+    /** -c: play_game(GAME_SELECT). Overrides -n, per the usage text. */
+    readonly selectGame: boolean;
+    /** -n: play_game(GAME_NEW). */
+    readonly newGame: boolean;
+    /** -w: arg_wizard, passed to savefile_load (ui-game.c:733). */
+    readonly wizard: boolean;
+    /**
+     * -g: arg_graphics. 0 is "not requested"; upstream's default when the switch
+     * IS given is 2, which graphics.txt maps to Adam Bolt's tiles.
+     */
+    readonly graphics: number;
+    /** -u<who>: arg_name, truncated to PLAYER_NAME_LEN. */
+    readonly name: string;
+    /** -f: arg_force_name. The eight-call-site one. */
+    readonly forceName: boolean;
+    /** -m<sys>: ANGBAND_SYS. Null leaves init.c's "xxx". */
+    readonly module: string | null;
+    /** -d<dir>=<path>, last one wins per directory. */
+    readonly dirs: Readonly<Partial<Record<string, string>>>;
+    /** Everything after `--`, which upstream hands to the module's init. */
+    readonly subopts: readonly string[];
+}
+export declare const DEFAULT_LAUNCH_ARGS: LaunchArgs;
+/**
+ * What the front end must do next. Upstream's three non-returning paths become
+ * three outcomes rather than a `quit()` inside a parser.
+ */
+export type LaunchOutcome = 
+/** Ordinary start. */
+{
+    readonly kind: "run";
+    readonly args: LaunchArgs;
+}
+/** -l: print the savefile list, then exit(0). Args parsed so far are kept. */
+ | {
+    readonly kind: "list-saves";
+    readonly args: LaunchArgs;
+}
+/** `goto usage`: print these lines, then quit(NULL). */
+ | {
+    readonly kind: "usage";
+    readonly lines: readonly string[];
+}
+/** quit_fmt(): print this and stop. */
+ | {
+    readonly kind: "quit";
+    readonly message: string;
+};
+export interface LaunchParseOptions {
+    /** modules[], in the order they are tried. */
+    readonly modules?: readonly LaunchModule[];
+    /** Current directory defaults, printed in the usage text's -d listing. */
+    readonly dirDefaults?: Readonly<Partial<Record<string, string>>>;
+    /**
+     * Is this a setgid build? Upstream's usage text hides the three non-setgid_ok
+     * directories on one, and change_path refuses them outright.
+     */
+    readonly setgid?: boolean;
+}
+/** The usage text (main.c:461-489), verbatim, with the two runtime listings. */
+export declare function launchUsage(opts?: LaunchParseOptions): readonly string[];
+/**
+ * main.c's option loop (main.c:380-491).
+ *
+ * `argv` is upstream's argv MINUS the program name, which is what HostIo.argv()
+ * reports - so the loop starts at 0 here where upstream starts at 1.
+ */
+export declare function parseLaunchArgs(argv: readonly string[], opts?: LaunchParseOptions): LaunchOutcome;
+/**
+ * The `-d` names, as the five host directories this port actually has.
+ *
+ * Upstream has thirteen directories; five of them are writable and modelled by
+ * HostDir, and the other eight are read-only game data that this port compiles
+ * in rather than reading from disk. A `-d gamedata=...` is therefore accepted
+ * and parsed - the switch exists and reports honestly - but only these five can
+ * be acted on, and `hostDirOverrides` is what a front end applies.
+ */
+export declare function hostDirOverrides(args: LaunchArgs): Readonly<Partial<Record<HostDir, string>>>;
+//# sourceMappingURL=args.d.ts.map

package/dist/host/args.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"args.d.ts","sourceRoot":"","sources":["../../src/host/args.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAGH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAEvC,0EAA0E;AAC1E,eAAO,MAAM,eAAe,KAAK,CAAC;AAElC;;;;;;;;;GASG;AACH,eAAO,MAAM,kBAAkB,EAAE,SAAS;IACxC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;CAC5B,EAcA,CAAC;AAEF,qEAAqE;AACrE,MAAM,WAAW,YAAY;IAC3B,8DAA8D;IAC9D,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,yDAAyD;IACzD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED,qCAAqC;AACrC,MAAM,WAAW,UAAU;IACzB,oEAAoE;IACpE,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAC;IAC7B,+BAA+B;IAC/B,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,+DAA+D;IAC/D,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IACzB;;;OAGG;IACH,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,uDAAuD;IACvD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,mDAAmD;IACnD,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B,wDAAwD;IACxD,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,mDAAmD;IACnD,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC;IACzD,wEAAwE;IACxE,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;CACrC;AAED,eAAO,MAAM,mBAAmB,EAAE,UAUjC,CAAC;AAEF;;;GAGG;AACH,MAAM,MAAM,aAAa;AACvB,sBAAsB;AACpB;IAAE,QAAQ,CAAC,IAAI,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAA;CAAE;AACrD,8EAA8E;GAC5E;IAAE,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAA;CAAE;AAC5D,wDAAwD;GACtD;IAAE,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAA;CAAE;AAC/D,uCAAuC;GACrC;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC;AAExD,MAAM,WAAW,kBAAkB;IACjC,8CAA8C;IAC9C,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS,YAAY,EAAE,CAAC;IAC3C,0EAA0E;IAC1E,QAAQ,CAAC,WAAW,CAAC,EAAE,QAAQ,CAAC,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC;IACjE;;;OAGG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC;CAC3B;AA2BD,gFAAgF;AAChF,wBAAgB,WAAW,CAAC,IAAI,GAAE,kBAAuB,GAAG,SAAS,MAAM,EAAE,CAsB5E;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAC7B,IAAI,EAAE,SAAS,MAAM,EAAE,EACvB,IAAI,GAAE,kBAAuB,GAC5B,aAAa,CA2Hf;AAED;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,UAAU,GACf,QAAQ,CAAC,OAAO,CAAC,MAAM,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC,CAAC,CAO5C"}

package/dist/host/args.js

@@ -0,0 +1,251 @@
+/**
+ * main.c's command line, ported.
+ *
+ * `main()` (reference/src/main.c:342-491) is not platform-specific code - it is
+ * the shared entry point every front end without its own `main` uses, and its
+ * option loop is the only place the `arg_*` globals are ever set:
+ *
+ *   arg_wizard      (ui-game.c:79)   -w
+ *   arg_graphics    (ui-prefs.c)     -g
+ *   arg_name        (ui-prefs.c:41)  -u<who>
+ *   arg_force_name  (ui-birth.c:97)  -f
+ *   ANGBAND_SYS     (init.c:84)      -m<sys>
+ *
+ * Those five reach thirteen call sites between them, and `-f` alone reaches
+ * eight. The text census sees only ONE of them (ui-player.c:1250, "You are not
+ * allowed to change your name!") because the rest are branches rather than
+ * strings, so "add the message" would have been the wrong-shaped fix: what is
+ * missing is the switch that makes any of it reachable.
+ *
+ * Parsing is pure. The three things upstream does at parse time that touch the
+ * world - printing usage, listing savefiles, creating a `-d` directory - are
+ * reported as OUTCOMES for the front end to carry out, because only the front
+ * end has a console and a filesystem. Nothing here quits or writes.
+ */
+import { ALL_HOST_DIRS } from "./raw.js";
+/** option.h:23. Upstream truncates -u<who> into a buffer of this size. */
+export const PLAYER_NAME_LEN = 32;
+/**
+ * change_path_values (main.c:209-227), in upstream's order - which is the order
+ * the usage text lists them in.
+ *
+ * `setgidOk` is carried even though this port has no setgid build, because the
+ * flag is what decides whether a directory appears in the usage listing at all
+ * on such a build, and dropping it would quietly delete that behaviour. The
+ * three false entries are the ones a multi-user install must not let a player
+ * redirect: scores, save and panic.
+ */
+export const CHANGE_PATH_VALUES = [
+    { name: "scores", setgidOk: false },
+    { name: "gamedata", setgidOk: true },
+    { name: "screens", setgidOk: true },
+    { name: "help", setgidOk: true },
+    { name: "pref", setgidOk: true },
+    { name: "fonts", setgidOk: true },
+    { name: "tiles", setgidOk: true },
+    { name: "sounds", setgidOk: true },
+    { name: "icons", setgidOk: true },
+    { name: "user", setgidOk: true },
+    { name: "save", setgidOk: false },
+    { name: "panic", setgidOk: false },
+    { name: "archive", setgidOk: true },
+];
+export const DEFAULT_LAUNCH_ARGS = {
+    selectGame: false,
+    newGame: false,
+    wizard: false,
+    graphics: 0,
+    name: "",
+    forceName: false,
+    module: null,
+    dirs: {},
+    subopts: [],
+};
+/**
+ * atoi, for `-g`.
+ *
+ * DEAD BY CONSTRUCTION, and ported anyway. main.c:409-411 reads a numeric suffix
+ * into arg_graphics - but the loop's trailing `if (*arg) goto usage;`
+ * (main.c:491) then fires on that very suffix, so `-g2` prints the usage text
+ * and quits and the parsed number can never be observed. Only a bare `-g`
+ * survives, leaving the hard-coded 2. That is upstream's behaviour, warts
+ * included, so it is what this reproduces - and the tests assert the usage path
+ * rather than the number, which is the part a player can actually reach. It is
+ * kept visible instead of dropped so the wart is not mistaken for a port bug
+ * later.
+ */
+function atoi(s) {
+    const m = /^[ \t\n\v\f\r]*([+-]?[0-9]+)/.exec(s);
+    if (!m)
+        return 0;
+    const n = Number(m[1]);
+    return Number.isSafeInteger(n) ? n : 0;
+}
+/** my_strcpy into a buffer of `len`: copy, truncating to len-1 characters. */
+function strncpy(s, len) {
+    return s.length < len ? s : s.slice(0, len - 1);
+}
+/** The usage text (main.c:461-489), verbatim, with the two runtime listings. */
+export function launchUsage(opts = {}) {
+    const lines = [
+        "Usage: angband [options] [-- subopts]",
+        "  -c             Select savefile with a menu; overrides -n",
+        "  -n             Start a new character (WARNING: overwrites default savefile without -u)",
+        "  -l             Lists all savefiles you can play",
+        "  -w             Resurrect dead character (marks savefile)",
+        "  -g             Request graphics mode",
+        "  -u<who>        Use your <who> savefile",
+        "  -d<dir>=<path> Override a specific directory with <path>. <path> can be:",
+    ];
+    for (const v of CHANGE_PATH_VALUES) {
+        if (opts.setgid === true && !v.setgidOk)
+            continue;
+        lines.push(`    ${v.name} (default is ${opts.dirDefaults?.[v.name] ?? ""})`);
+    }
+    lines.push("                 Multiple -d options are allowed.");
+    /* No `-s`: upstream's sound switch is inside #ifdef SOUND and this port has no
+     * sound module, so the switch is absent for the same reason it is absent from
+     * a --disable-sound build - not as an omission. */
+    lines.push("  -m<sys>        Use module <sys>, where <sys> can be:");
+    for (const m of opts.modules ?? [])
+        lines.push(`     ${m.name}   ${m.help}`);
+    return lines;
+}
+/**
+ * main.c's option loop (main.c:380-491).
+ *
+ * `argv` is upstream's argv MINUS the program name, which is what HostIo.argv()
+ * reports - so the loop starts at 0 here where upstream starts at 1.
+ */
+export function parseLaunchArgs(argv, opts = {}) {
+    let selectGame = false;
+    let newGame = false;
+    let wizard = false;
+    let graphics = 0;
+    let name = "";
+    let forceName = false;
+    let module = null;
+    const dirs = {};
+    let subopts = [];
+    let args = true;
+    const usage = () => ({ kind: "usage", lines: launchUsage(opts) });
+    const gathered = () => ({
+        selectGame,
+        newGame,
+        wizard,
+        graphics,
+        name,
+        forceName,
+        module,
+        dirs,
+        subopts,
+    });
+    for (let i = 0; args && i < argv.length; i++) {
+        const whole = argv[i] ?? "";
+        /* `if (*arg++ != '-') goto usage;` - an argument not starting with a dash,
+         * including an empty one, is a usage error rather than a positional. */
+        if (whole[0] !== "-")
+            return usage();
+        /* `switch (*arg++)`: the switch letter, then whatever follows it. */
+        const letter = whole[1] ?? "";
+        const rest = whole.slice(2);
+        switch (letter) {
+            case "c":
+                selectGame = true;
+                break;
+            case "l":
+                /* list_saves(); exit(0) - immediately, so later switches are never
+                 * examined, and an earlier -u has already been applied. */
+                return { kind: "list-saves", args: gathered() };
+            case "n":
+                newGame = true;
+                break;
+            case "w":
+                wizard = true;
+                break;
+            case "g":
+                graphics = 2;
+                if (rest !== "")
+                    graphics = atoi(rest);
+                break;
+            case "u": {
+                if (rest === "")
+                    return usage();
+                name = strncpy(rest, PLAYER_NAME_LEN);
+                /* `continue`: the trailing *arg check is skipped, which is how a suffix
+                 * is allowed here and not on -w. The savefile itself is set by the
+                 * caller, since that needs the save directory. */
+                continue;
+            }
+            case "f":
+                forceName = true;
+                break;
+            case "m":
+                if (rest === "")
+                    return usage();
+                module = rest;
+                continue;
+            case "d": {
+                /* change_path (main.c:236-271). */
+                if (rest === "")
+                    return { kind: "quit", message: "Try '-d<dir>=<path>'." };
+                /* strtok on "=": the name is up to the first '=', the path is the next
+                 * token - so a second '=' and anything after it is dropped, and a
+                 * missing '=' leaves the path undefined (strtok returns NULL, and
+                 * string_make(NULL) yields an empty directory). */
+                const eq = rest.indexOf("=");
+                const dirName = eq < 0 ? rest : rest.slice(0, eq);
+                const dirPath = eq < 0 ? "" : rest.slice(eq + 1).split("=")[0] ?? "";
+                /* my_stricmp: the match is case-insensitive. */
+                const entry = CHANGE_PATH_VALUES.find((v) => v.name.toLowerCase() === dirName.toLowerCase());
+                if (!entry) {
+                    return { kind: "quit", message: `Unrecognised -d parameter ${dirName}` };
+                }
+                if (opts.setgid === true && !entry.setgidOk) {
+                    return {
+                        kind: "quit",
+                        message: `Can't redefine path to ${dirName} dir on multiuser setup`,
+                    };
+                }
+                dirs[entry.name] = dirPath;
+                continue;
+            }
+            case "-":
+                /* The `--` terminator: the rest of the command line belongs to the
+                 * module's init, and the loop stops. */
+                subopts = argv.slice(i + 1);
+                args = false;
+                break;
+            default:
+                return usage();
+        }
+        /* `if (*arg) goto usage;` (main.c:491). This is what makes `-g2` a usage
+         * error, and `--x` too. */
+        if (rest !== "")
+            return usage();
+    }
+    /* `if (args) { argc = 1; argv[1] = NULL; }`: without an explicit `--`, nothing
+     * is passed on to the module. */
+    if (args)
+        subopts = [];
+    return { kind: "run", args: gathered() };
+}
+/**
+ * The `-d` names, as the five host directories this port actually has.
+ *
+ * Upstream has thirteen directories; five of them are writable and modelled by
+ * HostDir, and the other eight are read-only game data that this port compiles
+ * in rather than reading from disk. A `-d gamedata=...` is therefore accepted
+ * and parsed - the switch exists and reports honestly - but only these five can
+ * be acted on, and `hostDirOverrides` is what a front end applies.
+ */
+export function hostDirOverrides(args) {
+    const out = {};
+    for (const d of ALL_HOST_DIRS) {
+        const v = args.dirs[d];
+        if (typeof v === "string")
+            out[d] = v;
+    }
+    return out;
+}
+//# sourceMappingURL=args.js.map

package/dist/host/args.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"args.js","sourceRoot":"","sources":["../../src/host/args.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAGzC,0EAA0E;AAC1E,MAAM,CAAC,MAAM,eAAe,GAAG,EAAE,CAAC;AAElC;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAGzB;IACJ,EAAE,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,KAAK,EAAE;IACnC,EAAE,IAAI,EAAE,UAAU,EAAE,QAAQ,EAAE,IAAI,EAAE;IACpC,EAAE,IAAI,EAAE,SAAS,EAAE,QAAQ,EAAE,IAAI,EAAE;IACnC,EAAE,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,IAAI,EAAE;IAChC,EAAE,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,IAAI,EAAE;IAChC,EAAE,IAAI,EAAE,OAAO,EAAE,QAAQ,EAAE,IAAI,EAAE;IACjC,EAAE,IAAI,EAAE,OAAO,EAAE,QAAQ,EAAE,IAAI,EAAE;IACjC,EAAE,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,IAAI,EAAE;IAClC,EAAE,IAAI,EAAE,OAAO,EAAE,QAAQ,EAAE,IAAI,EAAE;IACjC,EAAE,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,IAAI,EAAE;IAChC,EAAE,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,KAAK,EAAE;IACjC,EAAE,IAAI,EAAE,OAAO,EAAE,QAAQ,EAAE,KAAK,EAAE;IAClC,EAAE,IAAI,EAAE,SAAS,EAAE,QAAQ,EAAE,IAAI,EAAE;CACpC,CAAC;AAmCF,MAAM,CAAC,MAAM,mBAAmB,GAAe;IAC7C,UAAU,EAAE,KAAK;IACjB,OAAO,EAAE,KAAK;IACd,MAAM,EAAE,KAAK;IACb,QAAQ,EAAE,CAAC;IACX,IAAI,EAAE,EAAE;IACR,SAAS,EAAE,KAAK;IAChB,MAAM,EAAE,IAAI;IACZ,IAAI,EAAE,EAAE;IACR,OAAO,EAAE,EAAE;CACZ,CAAC;AA4BF;;;;;;;;;;;;GAYG;AACH,SAAS,IAAI,CAAC,CAAS;IACrB,MAAM,CAAC,GAAG,8BAA8B,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IACjD,IAAI,CAAC,CAAC;QAAE,OAAO,CAAC,CAAC;IACjB,MAAM,CAAC,GAAG,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IACvB,OAAO,MAAM,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;AACzC,CAAC;AAED,8EAA8E;AAC9E,SAAS,OAAO,CAAC,CAAS,EAAE,GAAW;IACrC,OAAO,CAAC,CAAC,MAAM,GAAG,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,GAAG,CAAC,CAAC,CAAC;AAClD,CAAC;AAED,gFAAgF;AAChF,MAAM,UAAU,WAAW,CAAC,OAA2B,EAAE;IACvD,MAAM,KAAK,GAAa;QACtB,uCAAuC;QACvC,4DAA4D;QAC5D,0FAA0F;QAC1F,mDAAmD;QACnD,4DAA4D;QAC5D,wCAAwC;QACxC,0CAA0C;QAC1C,4EAA4E;KAC7E,CAAC;IACF,KAAK,MAAM,CAAC,IAAI,kBAAkB,EAAE,CAAC;QACnC,IAAI,IAAI,CAAC,MAAM,KAAK,IAAI,IAAI,CAAC,CAAC,CAAC,QAAQ;YAAE,SAAS;QAClD,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,IAAI,gBAAgB,IAAI,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;IAC/E,CAAC;IACD,KAAK,CAAC,IAAI,CAAC,mDAAmD,CAAC,CAAC;IAChE;;uDAEmD;IACnD,KAAK,CAAC,IAAI,CAAC,wDAAwD,CAAC,CAAC;IACrE,KAAK,MAAM,CAAC,IAAI,IAAI,CAAC,OAAO,IAAI,EAAE;QAAE,KAAK,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,IAAI,MAAM,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC;IAC7E,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,eAAe,CAC7B,IAAuB,EACvB,OAA2B,EAAE;IAE7B,IAAI,UAAU,GAAG,KAAK,CAAC;IACvB,IAAI,OAAO,GAAG,KAAK,CAAC;IACpB,IAAI,MAAM,GAAG,KAAK,CAAC;IACnB,IAAI,QAAQ,GAAG,CAAC,CAAC;IACjB,IAAI,IAAI,GAAG,EAAE,CAAC;IACd,IAAI,SAAS,GAAG,KAAK,CAAC;IACtB,IAAI,MAAM,GAAkB,IAAI,CAAC;IACjC,MAAM,IAAI,GAAoC,EAAE,CAAC;IACjD,IAAI,OAAO,GAAsB,EAAE,CAAC;IACpC,IAAI,IAAI,GAAG,IAAI,CAAC;IAEhB,MAAM,KAAK,GAAG,GAAkB,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,WAAW,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACjF,MAAM,QAAQ,GAAG,GAAe,EAAE,CAAC,CAAC;QAClC,UAAU;QACV,OAAO;QACP,MAAM;QACN,QAAQ;QACR,IAAI;QACJ,SAAS;QACT,MAAM;QACN,IAAI;QACJ,OAAO;KACR,CAAC,CAAC;IAEH,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,IAAI,IAAI,CAAC,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QAC7C,MAAM,KAAK,GAAG,IAAI,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;QAC5B;gFACwE;QACxE,IAAI,KAAK,CAAC,CAAC,CAAC,KAAK,GAAG;YAAE,OAAO,KAAK,EAAE,CAAC;QACrC,qEAAqE;QACrE,MAAM,MAAM,GAAG,KAAK,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;QAC9B,MAAM,IAAI,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;QAE5B,QAAQ,MAAM,EAAE,CAAC;YACf,KAAK,GAAG;gBACN,UAAU,GAAG,IAAI,CAAC;gBAClB,MAAM;YAER,KAAK,GAAG;gBACN;2EAC2D;gBAC3D,OAAO,EAAE,IAAI,EAAE,YAAY,EAAE,IAAI,EAAE,QAAQ,EAAE,EAAE,CAAC;YAElD,KAAK,GAAG;gBACN,OAAO,GAAG,IAAI,CAAC;gBACf,MAAM;YAER,KAAK,GAAG;gBACN,MAAM,GAAG,IAAI,CAAC;gBACd,MAAM;YAER,KAAK,GAAG;gBACN,QAAQ,GAAG,CAAC,CAAC;gBACb,IAAI,IAAI,KAAK,EAAE;oBAAE,QAAQ,GAAG,IAAI,CAAC,IAAI,CAAC,CAAC;gBACvC,MAAM;YAER,KAAK,GAAG,CAAC,CAAC,CAAC;gBACT,IAAI,IAAI,KAAK,EAAE;oBAAE,OAAO,KAAK,EAAE,CAAC;gBAChC,IAAI,GAAG,OAAO,CAAC,IAAI,EAAE,eAAe,CAAC,CAAC;gBACtC;;kEAEkD;gBAClD,SAAS;YACX,CAAC;YAED,KAAK,GAAG;gBACN,SAAS,GAAG,IAAI,CAAC;gBACjB,MAAM;YAER,KAAK,GAAG;gBACN,IAAI,IAAI,KAAK,EAAE;oBAAE,OAAO,KAAK,EAAE,CAAC;gBAChC,MAAM,GAAG,IAAI,CAAC;gBACd,SAAS;YAEX,KAAK,GAAG,CAAC,CAAC,CAAC;gBACT,mCAAmC;gBACnC,IAAI,IAAI,KAAK,EAAE;oBAAE,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,uBAAuB,EAAE,CAAC;gBAC3E;;;mEAGmD;gBACnD,MAAM,EAAE,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;gBAC7B,MAAM,OAAO,GAAG,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;gBAClD,MAAM,OAAO,GAAG,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,GAAG,CAAC,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;gBACrE,gDAAgD;gBAChD,MAAM,KAAK,GAAG,kBAAkB,CAAC,IAAI,CACnC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,WAAW,EAAE,KAAK,OAAO,CAAC,WAAW,EAAE,CACtD,CAAC;gBACF,IAAI,CAAC,KAAK,EAAE,CAAC;oBACX,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,6BAA6B,OAAO,EAAE,EAAE,CAAC;gBAC3E,CAAC;gBACD,IAAI,IAAI,CAAC,MAAM,KAAK,IAAI,IAAI,CAAC,KAAK,CAAC,QAAQ,EAAE,CAAC;oBAC5C,OAAO;wBACL,IAAI,EAAE,MAAM;wBACZ,OAAO,EAAE,0BAA0B,OAAO,yBAAyB;qBACpE,CAAC;gBACJ,CAAC;gBACD,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,OAAO,CAAC;gBAC3B,SAAS;YACX,CAAC;YAED,KAAK,GAAG;gBACN;wDACwC;gBACxC,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;gBAC5B,IAAI,GAAG,KAAK,CAAC;gBACb,MAAM;YAER;gBACE,OAAO,KAAK,EAAE,CAAC;QACnB,CAAC;QAED;mCAC2B;QAC3B,IAAI,IAAI,KAAK,EAAE;YAAE,OAAO,KAAK,EAAE,CAAC;IAClC,CAAC;IAED;qCACiC;IACjC,IAAI,IAAI;QAAE,OAAO,GAAG,EAAE,CAAC;IAEvB,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,QAAQ,EAAE,EAAE,CAAC;AAC3C,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,gBAAgB,CAC9B,IAAgB;IAEhB,MAAM,GAAG,GAAqC,EAAE,CAAC;IACjD,KAAK,MAAM,CAAC,IAAI,aAAa,EAAE,CAAC;QAC9B,MAAM,CAAC,GAAG,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QACvB,IAAI,OAAO,CAAC,KAAK,QAAQ;YAAE,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;IACxC,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC"}

package/dist/host/bridge.d.ts

@@ -0,0 +1,61 @@
+/**
+ * RawFs across a process boundary, with both ends defined in one file.
+ *
+ * WHY THIS EXISTS
+ *
+ * On the desktop build the filesystem and the game are in different processes:
+ * Electron's renderer is sandboxed (no node:fs), and the main process is where
+ * the real files are. So the game's host has to make a call across that gap.
+ *
+ * The client and the server are written here together, deliberately. A hand-
+ * written pair on either side of an IPC channel is two things that must agree
+ * about op names and argument order forever, and nothing checks that they do -
+ * exactly the drift the RawFs/RawFsHost split exists to prevent. Here, one file
+ * owns the wire format.
+ *
+ * WHY SYNCHRONOUS
+ *
+ * z-file.c is synchronous, and so is every caller of it. `prefs_save` writes
+ * inside a menu handler; the panic-save writes from a signal handler; the game
+ * loop reads a pref file inline. Making the host async would push `await` up
+ * through the whole command layer and change the game's control flow to suit the
+ * transport - the same mistake, in a new place, as letting the browser decide
+ * what a file is. The writes here are a few kilobytes to a local disk.
+ *
+ * WHY THE CLIENT COERCES EVERYTHING
+ *
+ * The transport can fail in ways a function call cannot: the channel may not be
+ * registered, the other end may be a different version, the reply may be
+ * undefined. Every result is therefore narrowed to the type RawFs promises, and
+ * anything unexpected becomes that operation's FAILURE value rather than an
+ * exception. That is z-file.c's discipline - file_open returns NULL, it does not
+ * die - and it is what keeps a broken bridge from throwing halfway through a save.
+ */
+import { HostDir } from "./io.js";
+import type { RawFs } from "./raw.js";
+/**
+ * One synchronous round trip: an operation name and its arguments in, whatever
+ * the far end returned out. Deliberately untyped, because it is a wire.
+ */
+export type RawFsTransport = (op: string, args: readonly unknown[]) => unknown;
+/** The operation names on the wire. Exported so a host can log or gate them. */
+export declare const RAW_FS_OPS: readonly ["displayPath", "isFile", "readText", "writeText", "unlink", "rename", "mtime", "listFiles"];
+export type RawFsOp = (typeof RAW_FS_OPS)[number];
+/** Whether a value is one of init.c's five writable directories. */
+export declare function isHostDir(v: unknown): v is HostDir;
+/**
+ * The CLIENT half: a RawFs that forwards every call over a transport. Used in
+ * the sandboxed renderer, where `send` is a synchronous IPC call.
+ */
+export declare function rawFsOverTransport(send: RawFsTransport): RawFs;
+/**
+ * The SERVER half: turns a real RawFs into a transport handler. Used in the
+ * trusted process.
+ *
+ * Every argument is validated here, because they arrive from the renderer and
+ * the renderer is the untrusted side. An unknown op or a malformed argument list
+ * returns that operation's failure value rather than throwing, so a hostile or
+ * buggy caller cannot take down the main process.
+ */
+export declare function serveRawFs(raw: RawFs): RawFsTransport;
+//# sourceMappingURL=bridge.d.ts.map

package/dist/host/bridge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bridge.d.ts","sourceRoot":"","sources":["../../src/host/bridge.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAEH,OAAO,EAAY,OAAO,EAAE,MAAM,SAAS,CAAC;AAE5C,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,UAAU,CAAC;AAEtC;;;GAGG;AACH,MAAM,MAAM,cAAc,GAAG,CAAC,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,OAAO,EAAE,KAAK,OAAO,CAAC;AAE/E,gFAAgF;AAChF,eAAO,MAAM,UAAU,uGASb,CAAC;AAEX,MAAM,MAAM,OAAO,GAAG,CAAC,OAAO,UAAU,CAAC,CAAC,MAAM,CAAC,CAAC;AAElD,oEAAoE;AACpE,wBAAgB,SAAS,CAAC,CAAC,EAAE,OAAO,GAAG,CAAC,IAAI,OAAO,CAQlD;AAUD;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,cAAc,GAAG,KAAK,CA8C9D;AAED;;;;;;;;GAQG;AACH,wBAAgB,UAAU,CAAC,GAAG,EAAE,KAAK,GAAG,cAAc,CAsDrD"}