@rpgm-tools/neo-angband-core 0.10.0

package/dist/gen/util.js

@@ -0,0 +1,1553 @@
+/**
+ * Dungeon generation utilities, ported from reference/src/gen-util.c and the
+ * gen-room.c geometry helpers (Angband 4.2.6), plus the dun_data-style
+ * bookkeeping structure from generate.h and the low-level monster/object
+ * placement wiring.
+ *
+ * DIVERGENCES BY DESIGN (ledgered in parity/ledger/gen-framework.yaml):
+ * - The upstream Chunk stores objects and traps as pointer piles on each
+ *   square; this port's Chunk only stores a monster index and no object or
+ *   trap handles (those domains attach later via world integration). During
+ *   generation we therefore track placed objects, placed monsters, and trap
+ *   grids on the Gen context and mirror monster occupancy into the Chunk's
+ *   mon array so square_isempty / square_canputitem behave exactly as
+ *   upstream for placement decisions.
+ * - place_trap only records the grid (no trap object is created; the trap
+ *   domain is not ported).
+ * - Monster group/escort spawning (mon-make.c place_new_monster /
+ *   place_friends / place_new_monster_group) is ported; group indices are
+ *   allocated from a per-generation counter and recorded on each monster's
+ *   group_info, and the live GameState rebuilds its group structures from
+ *   them at start (the savefile-loading path of monster_group_assign).
+ *   Unique cur_num tracking is kept level-local so a unique appears at most
+ *   once per level without mutating the shared registry. The shared count is
+ *   established once at the populate boundary by countMonsterRaces; see the
+ *   note at the placement site below for why it must not also be bumped here.
+ */
+import { FEAT, ORIGIN, RF, SQUARE } from "../generated/index.js";
+import { DDGRID, DDGRID_DDD, distance, loc, locDiff, locEq, locSum, } from "../loc.js";
+import { featIsBright, featIsFloor, featIsPassable, featIsSmooth, featIsTrapHolding, } from "../world/chunk.js";
+import { pickTrapKind } from "../game/trap.js";
+import { GET_ANGLE_TO_GRID } from "../world/project.js";
+import { makeGold, makeObject } from "../obj/make.js";
+import { createMonster } from "../mon/make.js";
+import { createMimickedObject } from "../game/mon-place.js";
+import { createDrop } from "../game/mon-death.js";
+import { MON_GROUP } from "../mon/types.js";
+import { scatterExt } from "../world/scatter.js";
+/* ------------------------------------------------------------------ *
+ * Keypad direction helpers (z-type.h / cave.c next_grid).
+ * ------------------------------------------------------------------ */
+export const DIR_NONE = 5;
+export const DIR_N = 8;
+export const DIR_S = 2;
+export const DIR_E = 6;
+export const DIR_W = 4;
+export const DIR_NE = 9;
+export const DIR_NW = 7;
+export const DIR_SE = 3;
+export const DIR_SW = 1;
+/** next_grid: the neighbour of grid in keypad direction dir. */
+export function nextGrid(grid, dir) {
+    const d = DDGRID[dir];
+    return loc(grid.x + d.x, grid.y + d.y);
+}
+/** grid_to_i / i_to_grid (index <-> location in a width-w area). */
+export function gridToI(grid, w) {
+    return grid.y * w + grid.x;
+}
+export function iToGrid(i, w) {
+    return loc(i % w, Math.trunc(i / w));
+}
+/** shuffle: Knuth shuffle, faithful RNG order. */
+export function shuffle(rng, arr, n) {
+    for (let i = 0; i < n; i++) {
+        const j = rng.randint0(n - i) + i;
+        const k = arr[j];
+        arr[j] = arr[i];
+        arr[i] = k;
+    }
+}
+/**
+ * The mutable state a level builder threads through room allocation,
+ * tunneling and stair placement. One per generation attempt.
+ */
+export class Dun {
+    constants;
+    /** Centres of placed rooms (index is the room number). */
+    cent = [];
+    centN = 0;
+    /** Marked entrance points, per room, plus a reverse lookup by grid. */
+    ent = [];
+    entN = [];
+    /** ent2room[y * width + x] = room index, or -1. */
+    ent2room = new Int32Array(0);
+    /** Candidate door / wall-piercing / tunnel grids for the current tunnel. */
+    door = [];
+    doorN = 0;
+    wall = [];
+    wallN = 0;
+    tunn = [];
+    tunnN = 0;
+    /** Block grid dimensions and counts. */
+    blockHgt = 1;
+    blockWid = 1;
+    rowBlocks = 0;
+    colBlocks = 0;
+    /** room_map[by][bx] = block reserved. */
+    roomMap = [];
+    pitNum = 0;
+    quest = false;
+    persist = false;
+    /** Persistent-level connection info (empty for non-persistent levels). */
+    join = [];
+    oneOffAbove = [];
+    oneOffBelow = [];
+    currJoin = null;
+    nstairRoom = 0;
+    /**
+     * dun->profile->name (set once per generation attempt, generate.c L1157).
+     * Read by help_greater_vault (gen-room.c L3099), which rejects a further 2/3
+     * of greater-vault attempts on any profile that is not "classic". Assigned by
+     * makeGen (gen/cave.ts) alongside profileTun/profileStr; "" in bare
+     * unit-test Gen contexts, which behaves like any other non-classic profile.
+     */
+    profileName = "";
+    /**
+     * Whether an adjacent persistent level already exists above/below this one
+     * (gen-chunk.c:147 chunk_find_adjacent). Only consulted under `persist`, by
+     * handle_level_stairs (gen-cave.c:959-966): when the neighbour exists its
+     * staircase rooms already seed dun.join here, so alloc_stairs is skipped for
+     * that direction. Off by default, leaving the non-persistent path unchanged. */
+    hasAdjacentAbove = false;
+    hasAdjacentBelow = false;
+    constructor(constants) {
+        this.constants = constants;
+    }
+    get levelRoomMax() {
+        return this.constants.levelRoomMax;
+    }
+    get levelDoorMax() {
+        return this.constants.levelDoorMax;
+    }
+    get wallPierceMax() {
+        return this.constants.wallPierceMax;
+    }
+    get tunnGridMax() {
+        return this.constants.tunnGridMax;
+    }
+    get levelPitMax() {
+        return this.constants.levelPitMax;
+    }
+    /** reset_entrance_data: clear per-room entrances and the reverse lookup. */
+    resetEntranceData(c) {
+        for (let i = 0; i < this.levelRoomMax; i++) {
+            this.entN[i] = 0;
+            this.ent[i] = [];
+        }
+        this.ent2room = new Int32Array(c.height * c.width).fill(-1);
+    }
+}
+const ZERO_TUNNEL = { rnd: 0, chg: 0, con: 0, pen: 0, jct: 0 };
+const ZERO_STREAMER = { den: 0, rng: 0, mag: 0, mc: 0, qua: 0, qc: 0 };
+/**
+ * The generation context: the chunk under construction plus the RNG, feature
+ * registry, constants, dun bookkeeping, and the placement side-tables the
+ * upstream Chunk stores directly. Passed to every builder and placement
+ * helper.
+ */
+export class Gen {
+    c;
+    rng;
+    reg;
+    constants;
+    dun;
+    objDeps;
+    monDeps;
+    trapKinds;
+    objects = [];
+    monsters = [];
+    /** Optional RNG-neutral diagnostics for the S-3 pit residual. */
+    pitTelemetry = {
+        attempts: { pit: 0, nest: 0 },
+        selected: { pit: {}, nest: {} },
+        empty: { pit: 0, nest: 0 },
+    };
+    /** grid index -> square holds a generated object. */
+    objOccupied = new Set();
+    /** grid index -> square holds a trap (player trap for gen purposes). */
+    trapGrids = new Set();
+    /**
+     * Traps whose kind and power were chosen at generation time (place_trap).
+     * Populated only when trapKinds are threaded in; the populate path prefers
+     * these to trapGrids so the pick / power draws are not spent twice.
+     */
+    traps = [];
+    /** Doors rolled locked at generation (grid + 1d7 lock power). */
+    lockedDoors = [];
+    /**
+     * Stair connectors of the finished level (generate.c:1203-1214 chunk->join):
+     * every staircase grid + its feature. A persistent-level dungeon feeds the
+     * NEXT level's get_join_info from these so up/down stairs line up across
+     * depths. Populated by generateLevel; consumed only when persistent levels
+     * are wired (gap 9.4).
+     */
+    joins = [];
+    /** ridx of uniques already placed on this level. */
+    placedUniques = new Set();
+    monCounter = 0;
+    groupCounter = 0;
+    /** The player start, set by the cave builder via new_player_spot. */
+    playerSpot = null;
+    /**
+     * p->upkeep->light_level (gen-cave.c:1594-1596): a builder asking the level to
+     * be revealed on arrival. Only labyrinth_gen sets it, for a "known" labyrinth;
+     * cave_generate consumes it with `wiz_light(chunk, p, false)` and clears it
+     * (generate.c:1255-1258). Because `chunk` is not yet `cave` at that point,
+     * that call reduces to a pure SQUARE_GLOW pass (square_memorize /
+     * square_know_pile / square_forget all short-circuit on `c != cave`).
+     */
+    lightLevel = false;
+    /**
+     * msg() for the handful of generation-time messages upstream prints to the
+     * player: new_player_spot's placement failure (gen-util.c:422) is UNgated -
+     * unlike the cheat_room restart narration - so it must reach a real player.
+     * Set by the cave builder from CaveBuildContext; absent in bare unit-test Gen
+     * contexts, which then generate silently.
+     */
+    msg;
+    /** Current tunnel/streamer parameters (set by the cave builder). */
+    profileTun = ZERO_TUNNEL;
+    profileStr = ZERO_STREAMER;
+    constructor(c, rng, reg, constants, dun, 
+    /** Object-make dependencies, or null to skip object placement. */
+    objDeps, 
+    /** Monster-placement dependencies, or null to skip monster placement. */
+    monDeps, 
+    /**
+     * The trap kind table (trap_info). When present, place_trap picks the kind
+     * and rolls the power at generation time (gap 9.2). Live boot always
+     * supplies this; null is bare unit-test Gen contexts only (marker-only).
+     */
+    trapKinds = null) {
+        this.c = c;
+        this.rng = rng;
+        this.reg = reg;
+        this.constants = constants;
+        this.dun = dun;
+        this.objDeps = objDeps;
+        this.monDeps = monDeps;
+        this.trapKinds = trapKinds;
+    }
+    get depth() {
+        return this.c.depth;
+    }
+    idx(grid) {
+        return grid.y * this.c.width + grid.x;
+    }
+    /** square_istrap-ish: a generated trap occupies this grid. */
+    hasTrap(grid) {
+        return this.trapGrids.has(this.idx(grid));
+    }
+    /** square_object-ish: a generated object occupies this grid. */
+    hasObject(grid) {
+        return this.objOccupied.has(this.idx(grid));
+    }
+    markTrap(grid) {
+        this.trapGrids.add(this.idx(grid));
+    }
+    /** Attach a generated object; mirrors floor_carry + list_object. */
+    addObject(grid, obj) {
+        this.objects.push({ grid, obj });
+        this.objOccupied.add(this.idx(grid));
+    }
+    /** Assign a fresh monster index (upstream indices start at 1). */
+    nextMonIndex() {
+        return ++this.monCounter;
+    }
+    /**
+     * monster_group_index_new for generation: a fresh group index. The live
+     * GameState rebuilds its group structures from these at start.
+     */
+    nextGroupIndex() {
+        return ++this.groupCounter;
+    }
+    attachMonster(grid, mon, index) {
+        mon.grid = grid;
+        mon.midx = index;
+        this.c.setMon(grid, index);
+        this.monsters.push({ grid, mon, index });
+        if (mon.race.flags.has(RF.UNIQUE)) {
+            this.placedUniques.add(mon.race.ridx);
+        }
+    }
+    uniqueAlreadyPlaced(race) {
+        return this.placedUniques.has(race.ridx);
+    }
+    /**
+     * The same test, pre-bound for handing straight to getMonNum. Generation
+     * passes this so the allocation table stops offering a unique that is already
+     * on the level, which is what C gets for free by bumping race->cur_num at
+     * placement time (see the note in placeNewMonsterOne below).
+     */
+    uniquePlaced = (race) => this.placedUniques.has(race.ridx);
+}
+/* ------------------------------------------------------------------ *
+ * Square predicates that the upstream generation code needs and which are
+ * not (or cannot be) on the Chunk because they depend on generated objects
+ * and traps.
+ * ------------------------------------------------------------------ */
+/** square_isopen: floor with no monster. */
+export function squareIsOpen(g, grid) {
+    return g.c.isFloor(grid) && g.c.mon(grid) === 0;
+}
+/** square_isempty: open with no object and no player trap. */
+export function squareIsEmpty(g, grid) {
+    if (!g.c.inBounds(grid))
+        return false;
+    if (g.hasTrap(grid))
+        return false;
+    return squareIsOpen(g, grid) && !g.hasObject(grid);
+}
+/** square_isarrivable: reachable landing spot. */
+export function squareIsArrivable(g, grid) {
+    if (g.c.mon(grid) !== 0)
+        return false;
+    if (g.hasTrap(grid))
+        return false;
+    if (g.c.isFloor(grid))
+        return true;
+    if (g.c.isStairs(grid))
+        return true;
+    return false;
+}
+/** square_canputitem: object-holding, untrapped, unoccupied. */
+export function squareCanPutItem(g, grid) {
+    if (!g.c.isObjectHolding(grid))
+        return false;
+    if (g.hasTrap(grid))
+        return false;
+    return !g.hasObject(grid);
+}
+/** square_isroom (SQUARE_ROOM flag). */
+export function squareIsRoom(c, grid) {
+    return c.sqinfoHas(grid, SQUARE.ROOM);
+}
+/** square_isvault (SQUARE_VAULT flag). */
+export function squareIsVault(c, grid) {
+    return c.sqinfoHas(grid, SQUARE.VAULT);
+}
+/** square_isno_stairs (SQUARE_NO_STAIRS flag). */
+export function squareIsNoStairs(c, grid) {
+    return c.sqinfoHas(grid, SQUARE.NO_STAIRS);
+}
+/** square_iswall_outer (cave-square.c L514): the SQUARE_WALL_OUTER flag alone. */
+export function squareIswallOuter(c, grid) {
+    return c.sqinfoHas(grid, SQUARE.WALL_OUTER);
+}
+/** square_is_granite_with_flag. */
+export function squareIsGraniteWithFlag(c, grid, flag) {
+    return c.isGranite(grid) && c.sqinfoHas(grid, flag);
+}
+/** square_isstrongwall: mineral wall or permanent. */
+export function squareIsStrongWall(c, grid) {
+    return c.isMineralWall(grid) || c.isPerm(grid);
+}
+/** count_neighbors: matches among the (up to 9) neighbours in ddd order. */
+export function countNeighbors(c, grid, test, under) {
+    const dlim = under ? 9 : 8;
+    let count = 0;
+    for (let d = 0; d < dlim; d++) {
+        const off = DDGRID_DDD[d];
+        const g = loc(grid.x + off.x, grid.y + off.y);
+        if (!c.inBounds(g))
+            continue;
+        if (test(c, g))
+            count++;
+    }
+    return count;
+}
+/** square_num_walls_adjacent: cardinal wall neighbours. */
+export function squareNumWallsAdjacent(c, grid) {
+    let k = 0;
+    for (const dir of [DIR_S, DIR_N, DIR_E, DIR_W]) {
+        if (c.isWall(nextGrid(grid, dir)))
+            k++;
+    }
+    return k;
+}
+/** square_num_walls_diagonal: diagonal wall neighbours. */
+export function squareNumWallsDiagonal(c, grid) {
+    let k = 0;
+    for (const dir of [DIR_SE, DIR_NW, DIR_NE, DIR_SW]) {
+        if (c.isWall(nextGrid(grid, dir)))
+            k++;
+    }
+    return k;
+}
+/** square_suits_stairs_well. */
+export function squareSuitsStairsWell(g, grid) {
+    if (squareIsVault(g.c, grid) || squareIsNoStairs(g.c, grid))
+        return false;
+    return (squareNumWallsAdjacent(g.c, grid) === 3 &&
+        squareNumWallsDiagonal(g.c, grid) === 4 &&
+        squareIsEmpty(g, grid));
+}
+/** square_suits_stairs_ok. */
+export function squareSuitsStairsOk(g, grid) {
+    if (squareIsVault(g.c, grid) || squareIsNoStairs(g.c, grid))
+        return false;
+    return (squareNumWallsAdjacent(g.c, grid) === 2 &&
+        squareNumWallsDiagonal(g.c, grid) === 4 &&
+        squareIsEmpty(g, grid));
+}
+/* ------------------------------------------------------------------ *
+ * Randomised rectangular search (cave_find_init / get_grid / cave_find).
+ * ------------------------------------------------------------------ */
+/**
+ * A left-to-right, top-to-bottom index list drawn in a uniformly random
+ * order without replacement, exactly as cave_find_get_grid() does.
+ */
+export class CaveFinder {
+    order;
+    n;
+    stride;
+    x0;
+    y0;
+    next = 0;
+    constructor(topLeft, bottomRight) {
+        const dx = bottomRight.x - topLeft.x;
+        const dy = bottomRight.y - topLeft.y;
+        this.n = dx < 0 || dy < 0 ? 0 : (dx + 1) * (dy + 1);
+        this.stride = dx + 1;
+        this.x0 = topLeft.x;
+        this.y0 = topLeft.y;
+        this.order = new Array(this.n);
+        for (let i = 0; i < this.n; i++)
+            this.order[i] = i;
+    }
+    /** cave_find_reset (gen-util.c L187): restart the scan from the first grid. */
+    reset() {
+        this.next = 0;
+    }
+    /** Draw the next random grid, or null when exhausted. */
+    get(rng) {
+        if (this.next >= this.n)
+            return null;
+        const j = rng.randint0(this.n - this.next) + this.next;
+        const k = this.order[j];
+        this.order[j] = this.order[this.next];
+        this.order[this.next] = k;
+        this.next++;
+        return loc((k % this.stride) + this.x0, Math.trunc(k / this.stride) + this.y0);
+    }
+}
+/** cave_find_in_range: first grid in the rectangle satisfying pred. */
+export function caveFindInRange(c, rng, topLeft, bottomRight, pred) {
+    const finder = new CaveFinder(topLeft, bottomRight);
+    for (;;) {
+        const grid = finder.get(rng);
+        if (!grid)
+            return null;
+        if (pred(c, grid))
+            return grid;
+    }
+}
+/** cave_find: first grid in the whole chunk satisfying pred. */
+export function caveFind(c, rng, pred) {
+    return caveFindInRange(c, rng, loc(0, 0), loc(c.width - 1, c.height - 1), pred);
+}
+/** find_empty: a random empty square anywhere in the chunk. */
+export function findEmpty(g) {
+    return caveFind(g.c, g.rng, (_c, grid) => squareIsEmpty(g, grid));
+}
+/** find_nearby_grid: a fully-in-bounds grid within +/- yd, xd of centre. */
+export function findNearbyGrid(c, rng, centre, yd, xd) {
+    return caveFindInRange(c, rng, loc(centre.x - xd, centre.y - yd), loc(centre.x + xd, centre.y + yd), (cc, grid) => cc.inBoundsFully(grid));
+}
+/* ------------------------------------------------------------------ *
+ * Directions (correct_dir / rand_dir).
+ * ------------------------------------------------------------------ */
+function cmp(a, b) {
+    return a < b ? -1 : a > b ? 1 : 0;
+}
+/** correct_dir: a cardinal step from grid1 toward grid2 (random if diagonal). */
+export function correctDir(rng, grid1, grid2) {
+    let ox = cmp(grid2.x, grid1.x);
+    let oy = cmp(grid2.y, grid1.y);
+    if (ox !== 0 && oy !== 0) {
+        if (rng.randint0(100) < 50)
+            oy = 0;
+        else
+            ox = 0;
+    }
+    return loc(ox, oy);
+}
+/** rand_dir: a random cardinal offset. */
+export function randDir(rng) {
+    return DDGRID_DDD[rng.randint0(4)];
+}
+/* ------------------------------------------------------------------ *
+ * Geometry helpers (gen-room.c fill/draw/mark, set_marked_granite).
+ * ------------------------------------------------------------------ */
+/** generate_room: mark a rectangle as room (and lit, if light). */
+export function generateRoom(c, y1, x1, y2, x2, light) {
+    for (let y = y1; y <= y2; y++) {
+        for (let x = x1; x <= x2; x++) {
+            c.sqinfoOn(loc(x, y), SQUARE.ROOM);
+            if (light)
+                c.sqinfoOn(loc(x, y), SQUARE.GLOW);
+        }
+    }
+}
+/** generate_mark: set a sqinfo flag over a rectangle. */
+export function generateMark(c, y1, x1, y2, x2, flag) {
+    for (let y = y1; y <= y2; y++) {
+        for (let x = x1; x <= x2; x++) {
+            c.sqinfoOn(loc(x, y), flag);
+        }
+    }
+}
+/** fill_rectangle: set a feature over a rectangle, optionally marking. */
+export function fillRectangle(c, y1, x1, y2, x2, feat, flag) {
+    for (let y = y1; y <= y2; y++) {
+        for (let x = x1; x <= x2; x++)
+            c.setFeat(loc(x, y), feat);
+    }
+    if (flag)
+        generateMark(c, y1, x1, y2, x2, flag);
+}
+/** draw_rectangle: set a feature around the border of a rectangle. */
+export function drawRectangle(c, y1, x1, y2, x2, feat, flag, overwritePerm) {
+    for (let y = y1; y <= y2; y++) {
+        if (overwritePerm || !c.isPerm(loc(x1, y)))
+            c.setFeat(loc(x1, y), feat);
+        if (overwritePerm || !c.isPerm(loc(x2, y)))
+            c.setFeat(loc(x2, y), feat);
+    }
+    if (flag) {
+        generateMark(c, y1, x1, y2, x1, flag);
+        generateMark(c, y1, x2, y2, x2, flag);
+    }
+    for (let x = x1; x <= x2; x++) {
+        if (overwritePerm || !c.isPerm(loc(x, y1)))
+            c.setFeat(loc(x, y1), feat);
+        if (overwritePerm || !c.isPerm(loc(x, y2)))
+            c.setFeat(loc(x, y2), feat);
+    }
+    if (flag) {
+        generateMark(c, y1, x1, y1, x2, flag);
+        generateMark(c, y2, x1, y2, x2, flag);
+    }
+}
+function fillXrange(c, y, x1, x2, feat, flag, light) {
+    for (let x = x1; x <= x2; x++) {
+        const grid = loc(x, y);
+        c.setFeat(grid, feat);
+        c.sqinfoOn(grid, SQUARE.ROOM);
+        if (flag)
+            c.sqinfoOn(grid, flag);
+        if (light)
+            c.sqinfoOn(grid, SQUARE.GLOW);
+    }
+}
+function fillYrange(c, x, y1, y2, feat, flag, light) {
+    for (let y = y1; y <= y2; y++) {
+        const grid = loc(x, y);
+        c.setFeat(grid, feat);
+        c.sqinfoOn(grid, SQUARE.ROOM);
+        if (flag)
+            c.sqinfoOn(grid, flag);
+        if (light)
+            c.sqinfoOn(grid, SQUARE.GLOW);
+    }
+}
+/** fill_circle: a filled disc of a feature (used by circular rooms). */
+export function fillCircle(c, y0, x0, radius, border, feat, flag, light) {
+    let last = 0;
+    let k = radius;
+    let r2i2k2 = 0;
+    for (let i = 0; i <= radius; i++) {
+        let b = border;
+        if (border && last > k)
+            b++;
+        fillXrange(c, y0 - i, x0 - k - b, x0 + k + b, feat, flag, light);
+        fillXrange(c, y0 + i, x0 - k - b, x0 + k + b, feat, flag, light);
+        fillYrange(c, x0 - i, y0 - k - b, y0 + k + b, feat, flag, light);
+        fillYrange(c, x0 + i, y0 - k - b, y0 + k + b, feat, flag, light);
+        last = k;
+        if (i < radius) {
+            r2i2k2 -= 2 * i + 1;
+            for (;;) {
+                const adj = 2 * k - 1;
+                if (Math.abs(r2i2k2 + adj) >= Math.abs(r2i2k2))
+                    break;
+                k--;
+                r2i2k2 += adj;
+            }
+        }
+    }
+}
+/** generate_plus: fill the cross lines of a rectangle. */
+export function generatePlus(c, y1, x1, y2, x2, feat, flag) {
+    const y0 = Math.trunc((y1 + y2) / 2);
+    const x0 = Math.trunc((x1 + x2) / 2);
+    for (let y = y1; y <= y2; y++)
+        c.setFeat(loc(x0, y), feat);
+    if (flag)
+        generateMark(c, y1, x0, y2, x0, flag);
+    for (let x = x1; x <= x2; x++)
+        c.setFeat(loc(x, y0), feat);
+    if (flag)
+        generateMark(c, y0, x1, y0, x2, flag);
+}
+/** generate_open: open all four sides of a rectangle. */
+export function generateOpen(c, y1, x1, y2, x2, feat) {
+    const y0 = Math.trunc((y1 + y2) / 2);
+    const x0 = Math.trunc((x1 + x2) / 2);
+    c.setFeat(loc(x0, y1), feat);
+    c.setFeat(loc(x1, y0), feat);
+    c.setFeat(loc(x0, y2), feat);
+    c.setFeat(loc(x2, y0), feat);
+}
+/** generate_hole: open one random side of a rectangle. */
+export function generateHole(rng, c, y1, x1, y2, x2, feat) {
+    const y0 = Math.trunc((y1 + y2) / 2);
+    const x0 = Math.trunc((x1 + x2) / 2);
+    switch (rng.randint0(4)) {
+        case 0:
+            c.setFeat(loc(x0, y1), feat);
+            break;
+        case 1:
+            c.setFeat(loc(x1, y0), feat);
+            break;
+        case 2:
+            c.setFeat(loc(x0, y2), feat);
+            break;
+        case 3:
+            c.setFeat(loc(x2, y0), feat);
+            break;
+    }
+}
+/** set_marked_granite: lay granite and optionally mark it. */
+export function setMarkedGranite(c, grid, flag) {
+    c.setFeat(grid, FEAT.GRANITE);
+    if (flag)
+        generateMark(c, grid.y, grid.x, grid.y, grid.x, flag);
+}
+/**
+ * set_bordering_walls: convert floor grids on the edge of a room to outer
+ * walls so no floor is adjacent to a non-floor, non-outer-wall grid.
+ */
+export function setBorderingWalls(c, y1, x1, y2, x2) {
+    const ry1 = Math.max(0, y1);
+    const ry2 = Math.min(c.height - 1, y2);
+    const rx1 = Math.max(0, x1);
+    const rx2 = Math.min(c.width - 1, x2);
+    const nx = rx2 - rx1 + 1;
+    const walls = new Array(nx * (ry2 - ry1 + 1)).fill(false);
+    for (let y = ry1; y <= ry2; y++) {
+        const adjy1 = Math.max(0, y - 1);
+        const adjy2 = Math.min(c.height - 1, y + 1);
+        for (let x = rx1; x <= rx2; x++) {
+            if (!c.isFloor(loc(x, y)))
+                continue;
+            const adjx1 = Math.max(0, x - 1);
+            const adjx2 = Math.min(c.width - 1, x + 1);
+            if (adjy2 - adjy1 !== 2 || adjx2 - adjx1 !== 2) {
+                walls[x - rx1 + nx * (y - ry1)] = true;
+            }
+            else {
+                let nfloor = 0;
+                for (let ay = adjy1; ay <= adjy2; ay++) {
+                    for (let ax = adjx1; ax <= adjx2; ax++) {
+                        if (c.isFloor(loc(ax, ay)))
+                            nfloor++;
+                    }
+                }
+                if (nfloor !== 9)
+                    walls[x - rx1 + nx * (y - ry1)] = true;
+            }
+        }
+    }
+    for (let y = ry1; y <= ry2; y++) {
+        for (let x = rx1; x <= rx2; x++) {
+            if (walls[x - rx1 + nx * (y - ry1)]) {
+                setMarkedGranite(c, loc(x, y), SQUARE.WALL_OUTER);
+            }
+        }
+    }
+}
+/**
+ * generate_starburst_room (gen-room.c L569): carve a rounded "starburst" of
+ * `feat` inside the rectangle (y1,x1)-(y2,x2). Ported verbatim, including the
+ * long/narrow-room subdivision recursion, the per-arc RNG draws, the
+ * make-denser randint1 for non-floor passable terrain, and the outer-wall
+ * marking pass. RNG draws are reproduced in exact upstream order and count.
+ * Used by the town builder (a town-sized FEAT_FLOOR starburst) and available
+ * to any builder needing lakes/caverns. Occupancy checks read the Gen (no
+ * monsters/objects exist yet during town layout, matching upstream).
+ */
+export function generateStarburstRoom(g, y1, x1, y2, x2, light, feat, specialOk) {
+    const c = g.c;
+    const rng = g.rng;
+    const reg = c.features;
+    /* Make certain the room does not cross the dungeon edge. */
+    if (!c.inBounds(loc(x1, y1)) || !c.inBounds(loc(x2, y2)))
+        return false;
+    /* Robustness -- test sanity of input coordinates. */
+    if (y1 + 2 >= y2 || x1 + 2 >= x2)
+        return false;
+    const height = 1 + y2 - y1;
+    const width = 1 + x2 - x1;
+    /* Handle long, narrow rooms by dividing them up. */
+    if (height > Math.trunc((5 * width) / 2) ||
+        width > Math.trunc((5 * height) / 2)) {
+        let tmpAy = y2;
+        let tmpAx = x2;
+        if (height > width)
+            tmpAy = y1 + Math.trunc((2 * height) / 3);
+        else
+            tmpAx = x1 + Math.trunc((2 * width) / 3);
+        generateStarburstRoom(g, y1, x1, tmpAy, tmpAx, light, feat, false);
+        let tmpBy = y1;
+        let tmpBx = x1;
+        if (height > width)
+            tmpBy = y1 + Math.trunc((1 * height) / 3);
+        else
+            tmpBx = x1 + Math.trunc((1 * width) / 3);
+        generateStarburstRoom(g, tmpBy, tmpBx, y2, x2, light, feat, false);
+        if (featIsFloor(reg, feat)) {
+            /* Extend a corridor between the two room centres. */
+            for (let y = Math.trunc((y1 + tmpAy) / 2); y <= Math.trunc((tmpBy + y2) / 2); y++) {
+                for (let x = Math.trunc((x1 + tmpAx) / 2); x <= Math.trunc((tmpBx + x2) / 2); x++) {
+                    c.setFeat(loc(x, y), feat);
+                }
+            }
+        }
+        else {
+            /* Otherwise fill any gap between the two starbursts. */
+            let tmpCy1;
+            let tmpCx1;
+            let tmpCy2;
+            let tmpCx2;
+            if (height > width) {
+                tmpCy1 = y1 + Math.trunc((height - width) / 2);
+                tmpCx1 = x1;
+                tmpCy2 = tmpCy1 - Math.trunc((height - width) / 2);
+                tmpCx2 = x2;
+            }
+            else {
+                tmpCy1 = y1;
+                tmpCx1 = x1 + Math.trunc((width - height) / 2);
+                tmpCy2 = y2;
+                tmpCx2 = tmpCx1 + Math.trunc((width - height) / 2);
+            }
+            generateStarburstRoom(g, tmpCy1, tmpCx1, tmpCy2, tmpCx2, light, feat, false);
+        }
+        return true;
+    }
+    /* Get a shrinkage ratio for large rooms, as the table is limited. */
+    let distConv;
+    if (width > 44 || height > 44) {
+        if (width > height)
+            distConv = Math.trunc((10 * width) / 44);
+        else
+            distConv = Math.trunc((10 * height) / 44);
+    }
+    else {
+        distConv = 10;
+    }
+    /* arc[i] = [first degree of arc, maximum effect distance in arc]. */
+    const arc = [];
+    let arcNum;
+    let makeCloverleaf = false;
+    if (specialOk && height > 10 && rng.randint0(20) === 0) {
+        arcNum = 12;
+        makeCloverleaf = true;
+    }
+    else {
+        arcNum = 8 + Math.trunc((height * width) / 80);
+        arcNum = arcNum + 3 - rng.randint0(7);
+        if (arcNum < 8)
+            arcNum = 8;
+        if (arcNum > 45)
+            arcNum = 45;
+    }
+    const y0 = y1 + Math.trunc(height / 2);
+    const x0 = x1 + Math.trunc(width / 2);
+    let degreeFirst = 0;
+    for (let i = 0; i < arcNum; i++) {
+        /* Get the first degree for this arc (before advancing degreeFirst). */
+        const arc0 = degreeFirst;
+        /* Get a slightly randomized start degree for the next arc. */
+        degreeFirst += Math.trunc((180 + rng.randint0(arcNum)) / arcNum);
+        if (degreeFirst < Math.trunc((180 * (i + 1)) / arcNum)) {
+            degreeFirst = Math.trunc((180 * (i + 1)) / arcNum);
+        }
+        if (degreeFirst > Math.trunc(((180 + arcNum) * (i + 1)) / arcNum)) {
+            degreeFirst = Math.trunc(((180 + arcNum) * (i + 1)) / arcNum);
+        }
+        const centerOfArc = degreeFirst + arc0;
+        let arc1 = 0;
+        if ((centerOfArc > 45 && centerOfArc < 135) ||
+            (centerOfArc > 225 && centerOfArc < 315)) {
+            arc1 = Math.trunc(height / 4) + rng.randint0(Math.trunc((height + 3) / 4));
+        }
+        else if (centerOfArc < 45 ||
+            centerOfArc > 315 ||
+            (centerOfArc < 225 && centerOfArc > 135)) {
+            arc1 = Math.trunc(width / 4) + rng.randint0(Math.trunc((width + 3) / 4));
+        }
+        else if (i !== 0) {
+            if (makeCloverleaf)
+                arc1 = 0;
+            else
+                arc1 = arc[i - 1][1] + 3 - rng.randint0(7);
+        }
+        /* Keep variability under control. */
+        if (!makeCloverleaf && i !== 0 && i !== arcNum - 1) {
+            const prev = arc[i - 1][1];
+            if (featIsSmooth(reg, feat)) {
+                if (arc1 > prev + 2)
+                    arc1 = prev + 2;
+                if (arc1 > prev - 2)
+                    arc1 = prev - 2;
+            }
+            else {
+                if (arc1 > Math.trunc((3 * (prev + 1)) / 2)) {
+                    arc1 = Math.trunc((3 * (prev + 1)) / 2);
+                }
+                if (arc1 < Math.trunc((2 * (prev - 1)) / 3)) {
+                    arc1 = Math.trunc((2 * (prev - 1)) / 3);
+                }
+            }
+        }
+        /* Neaten up the final arc by comparing it to the first. */
+        if (i === arcNum - 1) {
+            const first = arc[0][1];
+            if (Math.abs(arc1 - first) > 3) {
+                if (arc1 > first)
+                    arc1 -= rng.randint0(arc1 - first);
+                else if (arc1 < first)
+                    arc1 += rng.randint0(first - arc1);
+            }
+        }
+        arc[i] = [arc0, arc1];
+    }
+    /* Precalculate check distance. */
+    const distCheck = Math.trunc((21 * distConv) / 10);
+    /* Change grids between (and not including) the edges. */
+    for (let y = y1 + 1; y < y2; y++) {
+        for (let x = x1 + 1; x < x2; x++) {
+            const grid = loc(x, y);
+            /* Do not touch vault grids or occupied grids. */
+            if (squareIsVault(c, grid))
+                continue;
+            if (c.mon(grid) !== 0)
+                continue;
+            if (g.hasObject(grid))
+                continue;
+            const dist = distance(loc(x0, y0), grid);
+            if (dist >= distCheck)
+                continue;
+            /* Convert and reorient the grid for table access. */
+            const ny = 20 + Math.trunc((10 * (y - y0)) / distConv);
+            const nx = 20 + Math.trunc((10 * (x - x0)) / distConv);
+            if (ny < 0 || ny > 40 || nx < 0 || nx > 40)
+                continue;
+            const degree = GET_ANGLE_TO_GRID[ny][nx];
+            for (let i = arcNum - 1; i >= 0; i--) {
+                if (arc[i][0] <= degree) {
+                    const maxDist = arc[i][1];
+                    if (maxDist >= dist) {
+                        if (featIsFloor(reg, feat) || !featIsPassable(reg, feat)) {
+                            c.setFeat(grid, feat);
+                            if (featIsFloor(reg, feat))
+                                c.sqinfoOn(grid, SQUARE.ROOM);
+                            else
+                                c.sqinfoOff(grid, SQUARE.ROOM);
+                            if (light)
+                                c.sqinfoOn(grid, SQUARE.GLOW);
+                            else if (!featIsBright(reg, c.feat(grid))) {
+                                c.sqinfoOff(grid, SQUARE.GLOW);
+                            }
+                        }
+                        else {
+                            /* Non-floor passable terrain: place only over floor. */
+                            if (featIsSmooth(reg, feat)) {
+                                if (c.isFloor(grid))
+                                    c.setFeat(grid, feat);
+                            }
+                            else if (c.isFloor(grid) && rng.randint1(maxDist + 5) >= dist + 5) {
+                                c.setFeat(grid, feat);
+                            }
+                            if (light)
+                                c.sqinfoOn(grid, SQUARE.GLOW);
+                        }
+                    }
+                    /* Arc found; end search. */
+                    break;
+                }
+            }
+        }
+    }
+    /*
+     * If we placed floors or dungeon granite, all dungeon granite next to
+     * floors becomes outer wall.
+     */
+    if (featIsFloor(reg, feat) || feat === FEAT.GRANITE) {
+        for (let y = y1 + 1; y < y2; y++) {
+            for (let x = x1 + 1; x < x2; x++) {
+                const grid = loc(x, y);
+                if (!c.isFloor(grid))
+                    continue;
+                for (let d = 0; d < 8; d++) {
+                    const g1 = locSum(grid, DDGRID_DDD[d]);
+                    c.sqinfoOn(g1, SQUARE.ROOM);
+                    c.sqinfoOn(g1, SQUARE.NO_STAIRS);
+                    if (light)
+                        c.sqinfoOn(g1, SQUARE.GLOW);
+                    if (c.feat(g1) === FEAT.GRANITE) {
+                        setMarkedGranite(c, g1, SQUARE.WALL_OUTER);
+                    }
+                }
+            }
+        }
+    }
+    return true;
+}
+/* ------------------------------------------------------------------ *
+ * Feature placement (doors, rubble, stairs).
+ * ------------------------------------------------------------------ */
+export function placeRubble(g, grid) {
+    g.c.setFeat(grid, g.rng.oneIn(2) ? FEAT.RUBBLE : FEAT.PASS_RUBBLE);
+}
+export function placeSecretDoor(c, grid) {
+    c.setFeat(grid, FEAT.SECRET);
+}
+/** place_closed_door: one in four doors is locked to power 1d7. */
+export function placeClosedDoor(g, grid) {
+    g.c.setFeat(grid, FEAT.CLOSED);
+    /* square_set_door_lock: the lock is a trap on the live cave; record the
+     * rolled power so the game state can place the lock at start. */
+    if (g.rng.oneIn(4))
+        g.lockedDoors.push({ grid, power: g.rng.randint1(7) });
+}
+export function placeRandomDoor(g, grid) {
+    const tmp = g.rng.randint0(100);
+    if (tmp < 30)
+        g.c.setFeat(grid, FEAT.OPEN);
+    else if (tmp < 40)
+        g.c.setFeat(grid, FEAT.BROKEN);
+    else
+        placeClosedDoor(g, grid);
+}
+/**
+ * square_player_trap_allowed at generation time (trap.c:255): no existing
+ * trap, no object, and trap-holding terrain.
+ */
+function genPlayerTrapAllowed(g, grid) {
+    if (g.hasTrap(grid))
+        return false;
+    if (g.hasObject(grid))
+        return false;
+    return featIsTrapHolding(g.reg, g.c.feat(grid));
+}
+/**
+ * place_trap(c, grid, -1, c->depth) at generation time (trap.c:356): pick a
+ * random player trap kind by rarity and roll its power, spending both RNG
+ * draws in the generation stream (gap 9.2). Always records a GenTrap so
+ * populate can materialize without a second draw. When the trap kind table is
+ * not threaded in (bare unit-test Gen contexts only), records a grid marker
+ * alone; the live boot path always supplies trapKinds and populate asserts
+ * every marker has a descriptor.
+ */
+export function placeTrap(g, grid) {
+    if (!g.trapKinds) {
+        g.markTrap(grid);
+        return;
+    }
+    /* The -1 index means "choose a random player trap", so the terrain must
+     * be trap-allowed (trap.c:361-363). */
+    if (!genPlayerTrapAllowed(g, grid))
+        return;
+    const tidx = pickTrapKind(g.rng, g.trapKinds, g.c.depth, {
+        depth: g.c.depth,
+        maxDepth: g.constants.maxDepth,
+        isQuest: g.dun.quest,
+        persist: g.dun.persist,
+    });
+    if (tidx < 0)
+        return;
+    const kind = g.trapKinds[tidx];
+    const power = g.rng.randcalc(kind.power, g.c.depth, "randomise");
+    g.markTrap(grid);
+    g.traps.push({ grid, tidx, power });
+}
+/** place_stairs: choose the stair terrain honoring town / max-depth rules. */
+export function placeStairs(g, grid, quest, feat) {
+    if (!g.c.depth) {
+        g.c.setFeat(grid, FEAT.MORE);
+    }
+    else if (quest || g.c.depth >= g.constants.maxDepth - 1) {
+        g.c.setFeat(grid, FEAT.LESS);
+    }
+    else {
+        g.c.setFeat(grid, feat);
+    }
+}
+export function placeRandomStairs(g, grid, quest) {
+    const feat = g.rng.randint0(100) < 50 ? FEAT.LESS : FEAT.MORE;
+    if (squareCanPutItem(g, grid))
+        placeStairs(g, grid, quest, feat);
+}
+/* ------------------------------------------------------------------ *
+ * Object placement (place_object / place_gold), via ./obj.
+ * ------------------------------------------------------------------ */
+/**
+ * convert_depth_to_origin (obj-util.c L686): clamp a depth to a uint8
+ * origin_depth.
+ */
+export function convertDepthToOrigin(depth) {
+    if (depth < 0)
+        return 0;
+    if (depth > 255)
+        return 255;
+    return depth;
+}
+/** place_object: make and place an object, if object deps are available. */
+export function placeObject(g, grid, level, good, great, tval, origin) {
+    if (!g.c.inBounds(grid))
+        return;
+    if (!squareCanPutItem(g, grid))
+        return;
+    if (!g.objDeps)
+        return;
+    const rating = { value: 0 };
+    const obj = makeObject(g.rng, g.objDeps, level, good, great, false, tval, g.c.depth, rating);
+    if (!obj)
+        return;
+    /* gen-util.c L511-512: origin uses c->depth (the chunk depth), not level. */
+    obj.origin = origin;
+    obj.originDepth = convertDepthToOrigin(g.c.depth);
+    g.addObject(grid, obj);
+    /* place_object's obj_rating accumulation (gen-util.c L509-540). Draws no
+     * RNG: rating.value is a pure recomputation of make_object's *value. */
+    if (obj.artifact)
+        g.c.goodItem = true;
+    let r = rating.value;
+    if (r > 2_500_000)
+        r = 2_500_000;
+    else if (r < -2_500_000)
+        r = -2_500_000;
+    const scaled = Math.trunc(r / 100);
+    g.c.addToObjRating(scaled * scaled);
+}
+/** place_gold: make and place a money object. */
+export function placeGold(g, grid, level, origin) {
+    if (!g.c.inBounds(grid))
+        return;
+    if (!squareCanPutItem(g, grid))
+        return;
+    if (!g.objDeps)
+        return;
+    const money = makeGold(g.rng, g.objDeps, level, "any");
+    /* gen-util.c L560-561: gold origin_depth uses level, not c->depth. */
+    money.origin = origin;
+    money.originDepth = convertDepthToOrigin(level);
+    g.addObject(grid, money);
+}
+/* SET_* and TYP_* constants (generate.h). */
+export const SET_CORR = 0x01;
+export const SET_ROOM = 0x02;
+export const SET_BOTH = 0x03;
+export const TYP_RUBBLE = 0;
+export const TYP_TRAP = 1;
+export const TYP_GOLD = 2;
+export const TYP_OBJECT = 3;
+export const TYP_GOOD = 4;
+export const TYP_GREAT = 5;
+/** alloc_object: place one random entity in a corridor/room/either. */
+export function allocObject(g, set, typ, depth, origin) {
+    const finder = new CaveFinder(loc(1, 1), loc(g.c.width - 2, g.c.height - 2));
+    for (;;) {
+        const grid = finder.get(g.rng);
+        if (!grid)
+            return false;
+        const inRoom = squareIsRoom(g.c, grid);
+        const matched = (!!(set & SET_CORR) && !inRoom) || (!!(set & SET_ROOM) && inRoom);
+        if (squareIsEmpty(g, grid) && matched) {
+            switch (typ) {
+                case TYP_RUBBLE:
+                    placeRubble(g, grid);
+                    break;
+                case TYP_TRAP:
+                    placeTrap(g, grid);
+                    break;
+                case TYP_GOLD:
+                    placeGold(g, grid, depth, origin);
+                    break;
+                case TYP_OBJECT:
+                    placeObject(g, grid, depth, false, false, 0, origin);
+                    break;
+                case TYP_GOOD:
+                    placeObject(g, grid, depth, true, false, 0, origin);
+                    break;
+                case TYP_GREAT:
+                    placeObject(g, grid, depth, true, true, 0, origin);
+                    break;
+            }
+            return true;
+        }
+    }
+}
+/** alloc_objects: place num entities, returning the number not placed. */
+export function allocObjects(g, set, typ, num, depth, origin) {
+    let missed = 0;
+    for (let k = 0; k < num; k++) {
+        if (!allocObject(g, set, typ, depth, origin))
+            missed++;
+    }
+    return missed;
+}
+/* ------------------------------------------------------------------ *
+ * Stairs (alloc_stairs) and player placement (new_player_spot).
+ * ------------------------------------------------------------------ */
+/** alloc_stairs: place num stairs of a type near walls, honoring minsep. */
+export function allocStairs(g, feat, num, minsep, sepany, avoidList, quest) {
+    const c = g.c;
+    const av = [];
+    if (minsep > 0) {
+        const tester = (grid) => {
+            if (sepany)
+                return c.isStairs(grid);
+            return feat === FEAT.MORE ? c.isDownstairs(grid) : c.isUpstairs(grid);
+        };
+        for (let y = 0; y < c.height; y++) {
+            for (let x = 0; x < c.width; x++) {
+                const grid = loc(x, y);
+                if (tester(grid))
+                    av.push(grid);
+            }
+        }
+        for (const avc of avoidList) {
+            if (avc.feat !== feat)
+                av.push(avc.grid);
+        }
+    }
+    const finder = new CaveFinder(loc(1, 1), loc(c.width - 2, c.height - 2));
+    let i = 0;
+    let walls = 3;
+    while (i < num && walls >= 0) {
+        for (;;) {
+            if (i >= num)
+                break;
+            const grid = finder.get(g.rng);
+            if (!grid)
+                break;
+            if (!squareIsEmpty(g, grid) || squareNumWallsAdjacent(c, grid) !== walls) {
+                continue;
+            }
+            if (minsep > 0) {
+                let clash = false;
+                for (const a of av) {
+                    if (Math.abs(grid.y - a.y) <= minsep && Math.abs(grid.x - a.x) <= minsep) {
+                        clash = true;
+                        break;
+                    }
+                }
+                if (clash)
+                    continue;
+                av.push(grid);
+            }
+            placeStairs(g, grid, quest, feat);
+            i++;
+        }
+        if (i < num) {
+            walls--;
+            finder.reset();
+        }
+    }
+}
+/** find_start: a good starting location for the player (or stairs). */
+export function findStart(g) {
+    const finder = new CaveFinder(loc(1, 1), loc(g.c.width - 2, g.c.height - 2));
+    let grid = scanFinder(finder, g.rng, (gr) => squareSuitsStairsWell(g, gr));
+    if (grid)
+        return grid;
+    finder.reset();
+    grid = scanFinder(finder, g.rng, (gr) => squareSuitsStairsOk(g, gr));
+    if (grid)
+        return grid;
+    let walls = 6;
+    while (walls >= 0) {
+        finder.reset();
+        grid = scanFinder(finder, g.rng, (gr) => {
+            if (!squareIsEmpty(g, gr) ||
+                squareIsVault(g.c, gr) ||
+                squareIsNoStairs(g.c, gr)) {
+                return false;
+            }
+            const total = squareNumWallsAdjacent(g.c, gr) + squareNumWallsDiagonal(g.c, gr);
+            return total === walls;
+        });
+        if (grid)
+            return grid;
+        walls--;
+    }
+    return null;
+}
+function scanFinder(finder, rng, pred) {
+    for (;;) {
+        const grid = finder.get(rng);
+        if (!grid)
+            return null;
+        if (pred(grid))
+            return grid;
+    }
+}
+/**
+ * new_player_spot: choose the player start. Returns the location, or null on
+ * failure. createStair, if given, lays a stair on the start (the
+ * birth_connect_stairs upstream behavior); depends on player state so it is
+ * injected rather than read.
+ */
+export function newPlayerSpot(g, createStair = null) {
+    const grid = findStart(g);
+    if (!grid) {
+        /* gen-util.c:422. NOT gated on cheat_room - upstream always tells the
+         * player, then dumps the level (the dump is host-io) and re-rolls. */
+        g.msg?.("Failed to place player; please report.  Restarting generation.");
+        return null;
+    }
+    if (createStair === "down")
+        g.c.setFeat(grid, FEAT.MORE);
+    else if (createStair === "up")
+        g.c.setFeat(grid, FEAT.LESS);
+    return grid;
+}
+/* ------------------------------------------------------------------ *
+ * NO REACHABILITY PROMISE - deliberately.
+ *
+ * Nothing here guarantees the player can walk to a staircase, because upstream
+ * 4.2.6 does not: alloc_stairs (gen-util.c:629) picks any square_isempty grid
+ * and does not exclude vault interiors, while ensure_connectedness runs with
+ * allow_vault_disconnect = true at five of its six sites (gen-cave.c:1271, 2836,
+ * 3083, 3693, 3953; only 3464 passes false), so a vault the tunneller never
+ * joined can swallow a staircase. Measured on this port: 53 stranded levels in
+ * 520 (10.2%), overwhelmingly the UP stair, because a level gets 3-4 down stairs
+ * against only 1-2 up (gen-cave.c:958). 37 of the 53 had the orphaned stair
+ * inside SQUARE_VAULT.
+ *
+ * This was briefly a core guarantee (owner ruling 2026-07-25) and was withdrawn
+ * the next day once the owner learned the C really does strand floors:
+ *
+ *   "We can't fix bugs in the port. Those will belong in the bug fixes mod. I
+ *    only said those couldn't exist because I thought that was how the C
+ *    version worked. Core must retain all warts of the reference code."
+ *
+ * A mod that wants the guarantee repairs the finished level through the
+ * levelGenerated hook (mod/hooks.ts), which is handed the Gen and every
+ * placement primitive above (placeStairs, squareIsEmpty, squareIsNoStairs,
+ * squareNumWallsAdjacent) - so the repair needs nothing from core that a
+ * third-party level mod would not also need. gen.test.ts' CONTROL test pins the
+ * wart, and fails if the repair is ever moved back in here.
+ * ------------------------------------------------------------------ */
+/* ------------------------------------------------------------------ *
+ * Vault helpers (vault_objects / vault_traps).
+ * ------------------------------------------------------------------ */
+export function vaultObjects(g, grid, depth, num) {
+    for (; num > 0; num--) {
+        for (let i = 0; i < 11; i++) {
+            const near = findNearbyGrid(g.c, g.rng, grid, 2, 3);
+            if (!near)
+                continue;
+            if (!squareCanPutItem(g, near))
+                continue;
+            /* vault_objects (gen-util.c L839/L841): objects SPECIAL, gold VAULT. */
+            if (g.rng.randint0(100) < 75)
+                placeObject(g, near, depth, false, false, 0, ORIGIN.SPECIAL);
+            else
+                placeGold(g, near, depth, ORIGIN.VAULT);
+            break;
+        }
+    }
+}
+export function vaultTraps(g, grid, yd, xd, num) {
+    for (let i = 0; i < num; i++) {
+        for (let tries = 0; tries <= 5; tries++) {
+            const near = findNearbyGrid(g.c, g.rng, grid, yd, xd);
+            if (!near)
+                continue;
+            if (!squareIsEmpty(g, near))
+                continue;
+            placeTrap(g, near);
+            break;
+        }
+    }
+}
+/* ------------------------------------------------------------------ *
+ * Monster placement (mon-make placement half + gen-monster helpers).
+ *
+ * The place_new_monster family (one monster, same-race groups, friends and
+ * base-template escorts) is ported. Pit/nest monster theming (mon_restrict)
+ * is still simplified to any depth-appropriate monster; placement RNG order
+ * therefore diverges from upstream where theming would have restricted the
+ * table, and structural invariants plus per-seed determinism are asserted
+ * instead.
+ * ------------------------------------------------------------------ */
+/**
+ * place_new_monster_one, reduced to the generation-time subset: build the
+ * monster and attach it if the grid is free. The live-cave concerns (drops,
+ * update_mon) attach with their subsystems; object-mimic creation IS wired
+ * here (see below).
+ */
+function placeNewMonsterOne(g, grid, race, sleep, info, origin = ORIGIN.DROP) {
+    if (!g.c.inBounds(grid) || !squareIsEmpty(g, grid))
+        return false;
+    if (g.uniqueAlreadyPlaced(race))
+        return false;
+    /* Add to level feeling (mon-make.c place_new_monster_one L1112-1126).
+     * Draws no RNG. */
+    g.c.addToMonsterRating(race.level * race.level);
+    if (race.level > g.c.depth) {
+        g.c.addToMonsterRating((race.level - g.c.depth) * race.level * race.level);
+    }
+    const mon = createMonster(g.rng, race, {
+        sleep,
+        moveEnergy: g.constants.moveEnergy,
+        groupIndex: info.index,
+        groupRole: info.role,
+    });
+    g.attachMonster(grid, mon, g.nextMonIndex());
+    /* C bumps race->cur_num here (mon-make.c L1040-1041), and deliberately we do
+     * NOT. C places monsters straight into the live cave, so that increment is
+     * the only one; the port generates into a detached Gen and establishes the
+     * shared count once at the populate boundary (countMonsterRaces, from the
+     * level-change path). Incrementing here as well double-counts every monster
+     * on a fresh level, and since wipe_mon_list decrements only once per live
+     * monster on the way out, every descent leaks: a unique that reaches
+     * cur_num >= max_num is refused by get_mon_num (mon-make.c L257-258) for the
+     * rest of the game. The observable effect C gets from the early increment is
+     * that get_mon_num stops OFFERING a placed unique, and that is reproduced
+     * exactly by passing the level-local placed set to getMonNum instead.
+     * Asserted by "cur_num tracks the live monster count" in session/game.test.ts. */
+    /* Create the monster's drop, if any (mon-make.c place_monster L1044-1046):
+     * generation placement is the twin of place_new_monster_one -> place_monster,
+     * which draws mon_create_drop here (before mon_create_mimicked_object) when
+     * origin != 0. Every generation placement passes a nonzero origin, so the
+     * gate reduces to having object-make deps. The generated held pile rides on
+     * the Monster object through populateFromLevel into the live cave, where
+     * monster_death later drops it. thefts come from the shared lore store when
+     * the session threads it (g.monDeps.lore); absent, a never-stolen-from 0. */
+    if (g.objDeps && origin !== ORIGIN.NONE) {
+        createDrop({
+            rng: g.rng,
+            depth: g.c.depth,
+            makeDeps: g.objDeps,
+            lore: g.monDeps?.lore ?? null,
+        }, mon, origin);
+    }
+    /* Make mimics start mimicking (mon-make.c place_monster L1048-1051): the
+     * generation placement path is the twin of place_new_monster_one ->
+     * place_monster, so the mimic object is created here, just after
+     * mon_create_drop. Every vanilla mimic race carries no drops, so
+     * mon_create_drop above draws zero RNG for them - the mimic object's draws
+     * therefore land at the same generation-RNG position as upstream. Upstream's
+     * `origin` gate is implicit: generation placement always passes a nonzero
+     * origin (ORIGIN_DROP), so the gate reduces to a nonempty mimic_kinds. The
+     * object is parked on the Gen side-table (no live floor yet); session/game.ts
+     * populateFromLevel re-carries it via floor_carry and installs the monster
+     * with its mimicked_obj link, the generation midx matching the live midx it
+     * is re-assigned. Inert unless the generation supplies object-make deps. */
+    if (g.objDeps && race.mimicKinds.length > 0) {
+        createMimickedObject({
+            depth: g.c.depth,
+            rng: g.rng,
+            makeDeps: g.objDeps,
+            /* floor_carry during generation: the mimic monster sits on an empty
+             * floor grid (squareIsEmpty required no object), so the object parks
+             * with no stacking. Fails only on a non-object-holding grid, exactly
+             * as floor_carry's square_isobject_holding gate. */
+            carry: (cgrid, obj) => {
+                if (!g.c.isObjectHolding(cgrid))
+                    return false;
+                g.addObject(cgrid, obj);
+                return true;
+            },
+        }, mon);
+    }
+    return true;
+}
+/**
+ * place_new_monster_group: puddle up to `total` monsters of one race around
+ * grid, breadth first over the 8 neighbours of each placed monster.
+ */
+function placeNewMonsterGroup(g, grid, race, sleep, info, total, origin) {
+    total = Math.min(total, g.constants.monsterGroupMax);
+    /* Start on the monster. */
+    const locList = [grid];
+    /* Puddle monsters, breadth first, up to total. */
+    for (let n = 0; n < locList.length && locList.length < total; n++) {
+        for (let i = 0; i < 8 && locList.length < total; i++) {
+            const tryGrid = locSum(locList[n], DDGRID_DDD[i]);
+            /* Walls and monsters block flow. */
+            if (!squareIsEmpty(g, tryGrid))
+                continue;
+            if (placeNewMonsterOne(g, tryGrid, race, sleep, info, origin)) {
+                locList.push(tryGrid);
+            }
+        }
+    }
+    return true;
+}
+/** place_friends: place a friend or escort race near the original monster. */
+function placeFriends(g, grid, race, friendsRace, total, sleep, info, origin) {
+    /* Find the difference between current dungeon depth and monster level. */
+    const levelDifference = g.c.depth - friendsRace.level + 5;
+    /* Handle unique monsters. */
+    const isUnique = friendsRace.flags.has(RF.UNIQUE);
+    /* Make sure the unique hasn't been killed (or placed here) already. */
+    if (isUnique) {
+        if (friendsRace.curNum >= friendsRace.maxNum)
+            return false;
+        if (g.uniqueAlreadyPlaced(friendsRace))
+            return false;
+    }
+    /* More than 4 levels OoD, no groups allowed. */
+    if (levelDifference <= 0 && !isUnique)
+        return false;
+    /* Reduce group size within 5 levels of natural depth. */
+    if (levelDifference < 10 && !isUnique) {
+        const extraChance = (total * levelDifference) % 10;
+        total = Math.trunc((total * levelDifference) / 10);
+        /* Instead of flooring the group value, we use the decimal place
+         * as a chance of an extra monster. */
+        if (g.rng.randint0(10) > extraChance)
+            total += 1;
+    }
+    if (total > 0) {
+        /* Handle friends same as original monster. */
+        if (race.ridx === friendsRace.ridx) {
+            return placeNewMonsterGroup(g, grid, race, sleep, info, total, origin);
+        }
+        /* Find a nearby place to put the other groups. */
+        const spots = scatterExt(g.c, g.rng, 1, grid, g.constants.monsterGroupDist, false, (_c, gr) => squareIsOpen(g, gr));
+        if (spots.length > 0) {
+            const start = spots[0];
+            /* Place the monsters. */
+            let success = placeNewMonsterOne(g, start, friendsRace, sleep, info, origin);
+            if (total > 1) {
+                success = placeNewMonsterGroup(g, start, friendsRace, sleep, info, total, origin);
+            }
+            return success;
+        }
+    }
+    return false;
+}
+/**
+ * place_new_monster: place a monster of the given race at the given location,
+ * with its friends and escorts when `groupOk` is set. The first monster of a
+ * fresh group is its leader.
+ */
+export function placeNewMonster(g, grid, race, sleep, groupOk, groupInfo, origin = ORIGIN.DROP) {
+    if (!g.monDeps)
+        return false;
+    const info = { ...groupInfo };
+    /* If we don't have a group index already, make one; our first monster
+     * will be the leader. */
+    if (!info.index)
+        info.index = g.nextGroupIndex();
+    /* Place one monster, or fail. */
+    if (!placeNewMonsterOne(g, grid, race, sleep, info, origin))
+        return false;
+    /* We're done unless the group flag is set. */
+    if (!groupOk)
+        return true;
+    /* Go through friends flags. */
+    for (const friends of race.friends) {
+        if (g.rng.randint0(100) >= friends.percentChance)
+            continue;
+        /* Calculate the base number of monsters to place. */
+        const total = g.rng.damroll(friends.numberDice, friends.numberSide);
+        /* Set group role. */
+        info.role = friends.role;
+        /* Place them. */
+        if (friends.race) {
+            placeFriends(g, grid, race, friends.race, total, sleep, info, origin);
+        }
+    }
+    /* Go through the friends_base flags. */
+    for (const friendsBase of race.friendsBase) {
+        /* Check if we pass chance for the monster appearing. */
+        if (g.rng.randint0(100) >= friendsBase.percentChance)
+            continue;
+        const total = g.rng.damroll(friendsBase.numberDice, friendsBase.numberSide);
+        /* Prepare allocation table for the escort base (no uniques). */
+        g.monDeps.table.prep((r) => r.base === friendsBase.base && !r.flags.has(RF.UNIQUE));
+        /* Pick a random race, then reset the allocation table. */
+        const friendsRace = g.monDeps.table.getMonNum(g.rng, race.level, g.c.depth, g.uniquePlaced);
+        g.monDeps.table.prep(null);
+        /* Handle failure. */
+        if (!friendsRace)
+            break;
+        /* Set group role. */
+        info.role = friendsBase.role;
+        /* Place them. */
+        placeFriends(g, grid, race, friendsRace, total, sleep, info, origin);
+    }
+    return true;
+}
+/** pick_and_place_monster: place an appropriate monster (and group) at grid. */
+export function pickAndPlaceMonster(g, grid, depth, sleep, groupOkay = true, origin = ORIGIN.DROP) {
+    if (!g.monDeps)
+        return false;
+    const race = g.monDeps.table.getMonNum(g.rng, depth, g.c.depth, g.uniquePlaced);
+    if (!race)
+        return false;
+    const info = { index: 0, role: MON_GROUP.LEADER };
+    return placeNewMonster(g, grid, race, sleep, groupOkay, info, origin);
+}
+/** pick_and_place_distant_monster: place one monster far from the player. */
+export function pickAndPlaceDistantMonster(g, pgrid, dis, sleep, depth) {
+    if (!g.monDeps)
+        return false;
+    const c = g.c;
+    let attemptsLeft = 10_000;
+    /* pick_and_place_distant_monster (mon-make.c L1483-1520): the initial
+     * 10,000 is pre-decremented, giving exactly 9,999 location attempts. */
+    while (--attemptsLeft) {
+        const grid = loc(g.rng.randint0(c.width), g.rng.randint0(c.height));
+        if (!squareIsEmpty(g, grid))
+            continue;
+        if (c.info(grid).has(SQUARE.MON_RESTRICT))
+            continue;
+        if (distance(grid, pgrid) <= dis)
+            continue;
+        return pickAndPlaceMonster(g, grid, depth, sleep);
+    }
+    return false;
+}
+/** vault_monsters: place num sleeping monsters near a grid. */
+export function vaultMonsters(g, grid, depth, num) {
+    if (!g.c.inBounds(grid))
+        return;
+    for (let k = 0; k < num; k++) {
+        for (let i = 0; i < 9; i++) {
+            const near = scatterExt(g.c, g.rng, 1, grid, 1, true, (cc, gr) => squareIsEmpty(g, gr));
+            if (near.length === 0)
+                continue;
+            /* vault_monsters (gen-util.c L914): ORIGIN_DROP_SPECIAL. */
+            pickAndPlaceMonster(g, near[0], depth, true, true, ORIGIN.DROP_SPECIAL);
+            break;
+        }
+    }
+}
+/* spread_monsters lives in gen/gen-monster.ts (the faithful themed port); the
+ * simplified copy that once shadowed it here has been removed (gap 9.8). */
+/* ------------------------------------------------------------------ *
+ * Shared helpers re-exported for builders.
+ * ------------------------------------------------------------------ */
+export { loc, locSum, locDiff, locEq, distance };
+//# sourceMappingURL=util.js.map