@dreadwood-types/types 0.1.385 → 0.1.387

package/dist/skillingGiants.js

@@ -0,0 +1,597 @@
+/**
+ * Skilling Giants (James, 2026-10-28: "an equivalent of the stone bosses in a new design for skilling ... a new random spawn each time
+ * the user isn't expecting ... a HUGE tree spawning which doesn't attack, but must have its health reduced to 0 by all the players over
+ * a 5-10 minute window ... every interval it might give a bunch of xp, some logs in a loot box ... when it dies, loot boxes appear on the
+ * floor ... afkable ... but with some sort of click needed every now and then").
+ *
+ * A Giant is one enormous skilling node with a health bar, one per gathering skill: the Great Tree (Woodwork), the Great Shoal (Fishing),
+ * the Fallen Star (Mining), the Great Bloom (Foraging), the Great Cauldron (Potion Making). It appears without warning somewhere in a
+ * level band and never attacks. Every hit takes health and gives nothing; every PULSE (each tenth of its health, or every minute) pays
+ * every worker a lump of XP and drops one crate; every minute or two a CHORE lands on each worker (a sapling, a snagged line, a loose
+ * rock, a bramble, a boil-over) and their hits do nothing until they clear it; at 0 health it dies: crates and satchels scatter for a
+ * race, and everyone who really worked gets a satchel straight to the bag.
+ *
+ * Spec with the reasons: `dreadwoods-backend/SKILLING_GIANTS_SPEC.md`. This file is the pure half (bands, kinds, the pool rule, pulses,
+ * chores, scatter, satchels, chat lines, the view, the save), the way `windfall.ts` is for Windfall; the backend's `skillingGiantEvent.ts`
+ * runs it. Every number is a placeholder until the balance pass; the shapes (random spawn, nothing per hit, the chore rule, the caps)
+ * are what the tests pin.
+ */
+const SECOND = 1000;
+const MINUTE = 60 * SECOND;
+export const GIANT_KINDS = ['tree', 'shoal', 'star', 'bloom', 'cauldron'];
+export function isGiantKind(k) {
+    return typeof k === 'string' && GIANT_KINDS.includes(k);
+}
+export const GIANT_BAND_IDS = [1, 2, 3, 4];
+export const GIANT_KIND_INFO = {
+    tree: {
+        kind: 'tree', title: 'the Great Tree', skill: 'woodwork', skillName: 'Woodwork', tool: 'a hatchet or a saw', chore: 'sapling',
+        choreName: 'a sapling', choreFix: 'Chop the sapling at your feet', lands: 'has risen', pulse: 'shudders and drops a log crate', dies: 'has fallen', withers: 'has withered away',
+        // Windfall's great tree's scale: a poplar is 6.5 tall, so this one is about 16 (its crown fades over the players under it).
+        hitMs: 2400, footprint: 1, scale: 2.4,
+    },
+    shoal: {
+        kind: 'shoal', title: 'the Great Shoal', skill: 'fishing', skillName: 'Fishing', tool: 'a rod or a net', chore: 'snag',
+        choreName: 'a snagged line', choreFix: 'Tug your line free', lands: 'is churning', pulse: 'boils and a fish barrel washes up', dies: 'has sunk', withers: 'has slipped away',
+        hitMs: 3000, footprint: 1, scale: 2.6,
+    },
+    star: {
+        kind: 'star', title: 'the Fallen Star', skill: 'mining', skillName: 'Mining', tool: 'a pickaxe', chore: 'rock',
+        choreName: 'a loose rock', choreFix: 'Break the loose rock at your feet', lands: 'has struck the ground', pulse: 'cracks and sheds an ore crate', dies: 'has broken apart', withers: 'has cooled to dead stone',
+        hitMs: 4200, footprint: 1, scale: 3.0,
+    },
+    bloom: {
+        kind: 'bloom', title: 'the Great Bloom', skill: 'foraging', skillName: 'Foraging', tool: 'your hands', chore: 'bramble',
+        choreName: 'a bramble', choreFix: 'Cut the bramble round your boots', lands: 'has opened', pulse: 'sheds a basket of herbs', dies: 'has wilted', withers: 'has closed and gone to seed',
+        hitMs: 2000, footprint: 1, scale: 3.5,
+    },
+    cauldron: {
+        kind: 'cauldron', title: 'the Great Cauldron', skill: 'potionmaking', skillName: 'Potion Making', tool: 'a pestle and mortar', chore: 'boilover',
+        choreName: 'a boil-over', choreFix: 'Skim the boil-over off the brew', lands: 'is on the boil', pulse: 'bubbles over and a potion rack appears', dies: 'has boiled dry', withers: 'has gone cold',
+        hitMs: 3000, footprint: 1, scale: 3.0,
+    },
+};
+export const GIANT_BANDS = {
+    1: {
+        id: 1, band: 'levels 1-10', gate: 1,
+        names: { tree: 'Elderbough', shoal: 'the Oldwater Shoal', star: 'Ironfall', bloom: 'Briarcrown', cauldron: 'the Wildbrew Cauldron' },
+        resource: {
+            tree: { kind: 'poplarwood', unitXp: 8, rare: 'pinewood' },
+            shoal: { kind: 'rawrudd', unitXp: 10, rare: 'rawperch' },
+            star: { kind: 'copper', unitXp: 10, rare: 'iron' },
+            bloom: { kind: 'wildthyme', unitXp: 8, rare: 'watermint' },
+            cauldron: { kind: 'minicookingpotion', unitXp: 15, rare: 'miniexplorerpotion' },
+        },
+        styles: { tree: 'poplar', shoal: 'default', star: 'copper', bloom: 'default', cauldron: 'default' },
+    },
+    2: {
+        id: 2, band: 'levels 11-20', gate: 11,
+        names: { tree: 'Oakfather', shoal: 'the Silverrun Shoal', star: 'Emberfall', bloom: 'Thornqueen', cauldron: 'the Mossbrew Cauldron' },
+        resource: {
+            tree: { kind: 'sprucewood', unitXp: 22, rare: 'hazelwood' },
+            shoal: { kind: 'rawperch', unitXp: 25, rare: 'rawtench' },
+            star: { kind: 'iron', unitXp: 48, rare: 'coal' },
+            bloom: { kind: 'watermint', unitXp: 20, rare: 'bloodroot' },
+            cauldron: { kind: 'miniwoodworkpotion', unitXp: 24, rare: 'minienergypotion' },
+        },
+        styles: { tree: 'spruce', shoal: 'default', star: 'iron', bloom: 'default', cauldron: 'default' },
+    },
+    3: {
+        id: 3, band: 'levels 21-30', gate: 21,
+        names: { tree: 'Ironbark', shoal: 'the Blackmere Shoal', star: 'Blackfall', bloom: 'Marshcrown', cauldron: 'the Bogbrew Cauldron' },
+        resource: {
+            tree: { kind: 'alderwood', unitXp: 38, rare: 'ashwood' },
+            shoal: { kind: 'rawgrayling', unitXp: 70, rare: 'rawchar' },
+            star: { kind: 'coal', unitXp: 36, rare: 'gold' },
+            bloom: { kind: 'bloodroot', unitXp: 32, rare: 'ironwort' },
+            cauldron: { kind: 'minibountyhunterpotion', unitXp: 34, rare: 'cookingpotion' },
+        },
+        styles: { tree: 'alder', shoal: 'default', star: 'coal', bloom: 'default', cauldron: 'default' },
+    },
+    4: {
+        id: 4, band: 'levels 31-40', gate: 31,
+        names: { tree: 'Hoarbough', shoal: 'the Icewake Shoal', star: 'Frostfall', bloom: 'Frostcrown', cauldron: 'the Rimebrew Cauldron' },
+        resource: {
+            tree: { kind: 'beechwood', unitXp: 53, rare: 'oakwood' },
+            shoal: { kind: 'rawchar', unitXp: 105, rare: 'rawsalmon' },
+            star: { kind: 'silver', unitXp: 90, rare: 'gold' },
+            bloom: { kind: 'ironwort', unitXp: 45, rare: 'samphire' },
+            cauldron: { kind: 'fishingpotion', unitXp: 44, rare: 'strengthpotion' },
+        },
+        styles: { tree: 'beech', shoal: 'default', star: 'silver', bloom: 'default', cauldron: 'default' },
+    },
+};
+export function giantBand(id) {
+    return GIANT_BANDS[(id >= 1 && id <= 4 ? Math.floor(id) : 1)];
+}
+/** "Elderbough, the Great Tree". */
+export function giantName(kind, band) {
+    return `${GIANT_BANDS[band].names[kind]}, ${GIANT_KIND_INFO[kind].title}`;
+}
+/** The skill level a Giant asks. Null when `level` may work it, else the line the player reads. */
+export function giantGate(band) {
+    return GIANT_BANDS[band].gate;
+}
+/** The first band is open to everyone; the others ask the band's level. */
+export function giantCanWork(band, level) {
+    const gate = giantGate(band);
+    return gate <= 1 || Math.floor(level) >= gate;
+}
+export function giantGateLine(kind, band, level) {
+    if (giantCanWork(band, level))
+        return null;
+    return `You need ${GIANT_KIND_INFO[kind].skillName} ${giantGate(band)} to work this.`;
+}
+// ---- the clock: random, unannounced --------------------------------------------------------------------------------------
+/** A Giant lands this long after the last one ended (uniform between the two): no clock to learn. */
+export const GIANT_SPAWN_MIN_MS = 60 * MINUTE;
+export const GIANT_SPAWN_MAX_MS = 150 * MINUTE;
+/** The hard cap from landing: then it withers and only what was paid stands. */
+export const GIANT_CAP_MS = 12 * MINUTE;
+/** With five workers at the band's level it dies in about this long. */
+export const GIANT_TARGET_MS = 8 * MINUTE;
+/** After the death (or the withering) the remains stay and the view says so this long. */
+export const GIANT_SPENT_MS = 3 * MINUTE;
+/** The world-timer key the backend saves under. */
+export const GIANT_TIMER_KEY = 'giants';
+/** The one world entity id of the live Giant; a chore entity is `giant-chore-<character key>`. */
+export const GIANT_NODE_ID = 'giant-node';
+export const GIANT_CHORE_PREFIX = 'giant-chore-';
+export function giantChoreId(characterKey) {
+    return `${GIANT_CHORE_PREFIX}${characterKey}`;
+}
+export function isGiantEntityId(id) {
+    return id === GIANT_NODE_ID || id.startsWith(GIANT_CHORE_PREFIX);
+}
+/** The world entity kinds: the Giant itself (style `giantNodeStyle`) and a worker's chore (style the chore kind). */
+export const GIANT_NODE_KIND = 'skillinggiant';
+export const GIANT_CHORE_KIND = 'giantchore';
+/** The Giant entity's style, `tree:1`: what it is and its band, so the client draws the right look without the view. */
+export function giantNodeStyle(kind, band) {
+    return `${kind}:${band}`;
+}
+export function parseGiantNodeStyle(style) {
+    if (!style)
+        return null;
+    const [k, b] = style.split(':');
+    const band = Number(b);
+    if (!isGiantKind(k) || !(band === 1 || band === 2 || band === 3 || band === 4))
+        return null;
+    return { kind: k, band: band };
+}
+/** The hover and menu name of a Giant entity: "Elderbough, the Great Tree" (or the plain title for a style it cannot read). */
+export function giantEntityName(style) {
+    const p = parseGiantNodeStyle(style);
+    return p ? giantName(p.kind, p.band) : 'a Skilling Giant';
+}
+/** The hover name of a chore: "a sapling". */
+export function giantChoreEntityName(style) {
+    const info = GIANT_KINDS.map((k) => GIANT_KIND_INFO[k]).find((i) => i.chore === style);
+    return info ? info.choreName.replace(/^an? /, '').replace(/^\w/, (c) => c.toUpperCase()) : 'A chore';
+}
+/** How far the Giant has been worked, as a look: 0 whole, 1 a quarter gone, 2 half, 3 three quarters (the node is drawn a little smaller each step). */
+export function giantNodeLook(progress) {
+    return Math.max(0, Math.min(3, Math.floor(progress * 4 + 1e-9)));
+}
+/** Pick the next landing time after `endedAt`. */
+export function giantNextSpawnAt(endedAt, random = Math.random) {
+    return endedAt + GIANT_SPAWN_MIN_MS + Math.floor(random() * (GIANT_SPAWN_MAX_MS - GIANT_SPAWN_MIN_MS));
+}
+// ---- the pool: nothing per hit, health by crowd ---------------------------------------------------------------------------
+/** A worker is active with a hit inside this window (the pulse pays them; the pool sizes by them). */
+export const GIANT_ACTIVE_WINDOW_MS = 60 * SECOND;
+/** The pool is sized for at least this many workers (a lone worker reaches about 40 percent before the cap). */
+export const GIANT_MIN_ACTIVE = 3;
+export const GIANT_ACTIVE_CAP = 30;
+/** How the crowd scales the health: twice the workers, 2^0.7 times the hits (so each head's share falls, and a crowd is faster). */
+export const GIANT_CROWD_EXPONENT = 0.7;
+/** The crowd the target time is set for. */
+export const GIANT_REF_WORKERS = 5;
+/** Hits a minute a steady worker lands on this kind. */
+export function giantRefRate(kind) {
+    return MINUTE / GIANT_KIND_INFO[kind].hitMs;
+}
+/** The hits that kill a Giant of this kind with `active` workers. */
+export function giantHitsToKill(kind, active) {
+    const a = Math.min(GIANT_ACTIVE_CAP, Math.max(GIANT_MIN_ACTIVE, Math.floor(active) || 0));
+    const ref = giantRefRate(kind) * (GIANT_TARGET_MS / MINUTE) * GIANT_REF_WORKERS;
+    return ref * Math.pow(a / GIANT_REF_WORKERS, GIANT_CROWD_EXPONENT);
+}
+/** How much health one hit takes with `active` workers (0 to 1). */
+export function giantStep(kind, active) {
+    return 1 / giantHitsToKill(kind, active);
+}
+export function giantActiveCount(node, now) {
+    let n = 0;
+    for (const w of node.workers)
+        if (now - w.lastAt <= GIANT_ACTIVE_WINDOW_MS)
+            n += 1;
+    return Math.min(GIANT_ACTIVE_CAP, n);
+}
+/** A pulse fires at each of these shares of the health, and at least every GIANT_PULSE_EVERY_MS while anyone works. */
+export const GIANT_PULSE_SHARES = 10;
+export const GIANT_PULSE_EVERY_MS = 60 * SECOND;
+/**
+ * A worker's hit at `now` (the chore rule is the backend's: it does not call this while the worker's chore stands). Pure: returns the
+ * next node. The first hit also counts the worker as active for this very step.
+ */
+export function giantApplyHit(node, who, now) {
+    if (node.end)
+        return { node, counted: false, pulse: false, killed: false };
+    const workers = node.workers.map((w) => ({ ...w }));
+    let w = workers.find((x) => x.key === who.key);
+    if (!w) {
+        w = { key: who.key, hits: 0, lastAt: now, firstAt: now };
+        if (who.account)
+            w.account = who.account;
+        workers.push(w);
+    }
+    w.hits += 1;
+    w.lastAt = now;
+    const next = { ...node, workers };
+    const before = Math.floor(node.progress * GIANT_PULSE_SHARES + 1e-9);
+    next.progress = Math.min(1, next.progress + giantStep(node.kind, giantActiveCount(next, now)));
+    const after = Math.floor(next.progress * GIANT_PULSE_SHARES + 1e-9);
+    let killed = false;
+    if (next.progress >= 1) {
+        next.progress = 1;
+        next.end = { at: now, how: 'killed' };
+        killed = true;
+    }
+    // The death is its own event (the scatter), not a pulse.
+    const pulse = !killed && after > before;
+    if (pulse) {
+        next.pulses += 1;
+        next.lastPulseAt = now;
+    }
+    return { node: next, counted: true, pulse, killed };
+}
+/** Is a timed pulse due (a minute since the last, someone active, and the Giant standing)? */
+export function giantTimedPulseDue(node, now) {
+    if (node.end)
+        return false;
+    if (giantActiveCount(node, now) === 0)
+        return false;
+    return now - Math.max(node.lastPulseAt, node.landedAt) >= GIANT_PULSE_EVERY_MS;
+}
+export function giantMarkTimedPulse(node, now) {
+    return { ...node, pulses: node.pulses + 1, lastPulseAt: now };
+}
+/** The hard cap: a Giant still standing GIANT_CAP_MS after it landed withers. Idempotent. */
+export function giantExpire(node, now) {
+    if (node.end)
+        return { node, withered: false };
+    if (now - node.landedAt < GIANT_CAP_MS)
+        return { node, withered: false };
+    return { node: { ...node, end: { at: node.landedAt + GIANT_CAP_MS, how: 'withered' } }, withered: true };
+}
+// ---- chores: the click that stops a pure AFK -------------------------------------------------------------------------------
+/** A worker's first chore lands no sooner than this after their first hit; later ones this long after the last was cleared. */
+export const GIANT_CHORE_FIRST_MS = 45 * SECOND;
+export const GIANT_CHORE_MIN_MS = 60 * SECOND;
+export const GIANT_CHORE_MAX_MS = 120 * SECOND;
+/** A chore nobody clears is taken away with the Giant; a cleared one goes at once. */
+export const GIANT_CHORE_LINE = 'Your hits do nothing until it is cleared.';
+export function giantNextChoreDelay(first, random = Math.random) {
+    if (first)
+        return GIANT_CHORE_FIRST_MS + Math.floor(random() * (GIANT_CHORE_MIN_MS - GIANT_CHORE_FIRST_MS));
+    return GIANT_CHORE_MIN_MS + Math.floor(random() * (GIANT_CHORE_MAX_MS - GIANT_CHORE_MIN_MS));
+}
+/** How the chore's stand-in is drawn: an entity kind, a style and a scale (the Blender props come later: upgrades.json). */
+export function giantChoreLook(chore) {
+    if (chore === 'sapling')
+        return { kind: 'tree', style: 'birch', scale: 0.45 };
+    if (chore === 'snag')
+        return { kind: 'reeds', scale: 0.9 };
+    if (chore === 'rock')
+        return { kind: 'rock', scale: 0.7 };
+    if (chore === 'bramble')
+        return { kind: 'bush', scale: 0.7 };
+    return { kind: 'bucket', scale: 1.2 };
+}
+/** What the player reads when the chore lands and when it is cleared. */
+export function giantChoreLandLine(kind) {
+    const info = GIANT_KIND_INFO[kind];
+    return `${info.choreFix}! ${GIANT_CHORE_LINE}`;
+}
+export function giantChoreClearLine(kind) {
+    const c = GIANT_KIND_INFO[kind].chore;
+    if (c === 'sapling')
+        return 'The sapling falls. Back to the tree!';
+    if (c === 'snag')
+        return 'The line comes free. Cast again!';
+    if (c === 'rock')
+        return 'The rock breaks. Back to the star!';
+    if (c === 'bramble')
+        return 'The bramble is cut. Back to the bloom!';
+    return 'The brew settles. Keep stirring!';
+}
+/** What a hit on the Giant says while the chore stands. */
+export function giantChoreBlockLine(kind) {
+    return `Clear ${GIANT_KIND_INFO[kind].choreName} first.`;
+}
+// ---- rewards: pulses, the death, the floor ---------------------------------------------------------------------------------
+/** A pulse pays each active worker this many XP units; the death this many to a real worker (half to a light one). */
+export const GIANT_PULSE_XP_UNITS = 4;
+export const GIANT_FINAL_XP_UNITS = 40;
+/** A real worker (the full death XP and a small satchel) landed this many hits; a large satchel from this many. */
+export const GIANT_REAL_HITS = 20;
+export const GIANT_LIGHT_HITS = 5;
+export const GIANT_LARGE_SATCHEL_HITS = 60;
+export function giantPulseXp(kind, band) {
+    return GIANT_PULSE_XP_UNITS * GIANT_BANDS[band].resource[kind].unitXp;
+}
+export function giantFinalXp(kind, band, hits) {
+    const unit = GIANT_BANDS[band].resource[kind].unitXp;
+    if (hits >= GIANT_REAL_HITS)
+        return GIANT_FINAL_XP_UNITS * unit;
+    if (hits >= GIANT_LIGHT_HITS)
+        return Math.round((GIANT_FINAL_XP_UNITS * unit) / 2);
+    return 0;
+}
+/** The full death XP also asks the hits be spread over this long (spec section 6: a late rush of hits gets the light share). */
+export const GIANT_REAL_SPAN_MS = 3 * MINUTE;
+/** The death XP one worker gets: the full share for GIANT_REAL_HITS over GIANT_REAL_SPAN_MS, half for a lighter hand, nothing under GIANT_LIGHT_HITS. */
+export function giantDeathXp(kind, band, worker) {
+    if (worker.hits >= GIANT_REAL_HITS && worker.lastAt - worker.firstAt < GIANT_REAL_SPAN_MS)
+        return giantFinalXp(kind, band, GIANT_LIGHT_HITS);
+    return giantFinalXp(kind, band, worker.hits);
+}
+export function giantContribution(hits) {
+    if (hits >= GIANT_LARGE_SATCHEL_HITS)
+        return 'large';
+    if (hits >= GIANT_REAL_HITS)
+        return 'small';
+    return 'none';
+}
+export function giantEntitlements(node) {
+    const out = [];
+    for (const w of node.workers) {
+        const c = giantContribution(w.hits);
+        if (c !== 'none')
+            out.push({ key: w.key, large: c === 'large' });
+    }
+    return out;
+}
+/** A pulse crate holds this many of the resource; it lies this long; one each a pulse. */
+export const GIANT_CRATE_MIN = 5;
+export const GIANT_CRATE_MAX = 15;
+export const GIANT_CRATE_MS = 90 * SECOND;
+export const GIANT_PULSE_PICKUP_CAP = 1;
+/** The death scatter lies this long; a character takes at most this many pieces of it. */
+export const GIANT_SCATTER_MS = 120 * SECOND;
+export const GIANT_SCATTER_PICKUP_CAP = 3;
+/** Pieces land this far from the footprint edge; the work ring is this far. */
+export const GIANT_SCATTER_MIN = 2;
+export const GIANT_SCATTER_MAX = 6;
+export const GIANT_WORK_RANGE = 2;
+export function giantReach(kind) {
+    return GIANT_KIND_INFO[kind].footprint + GIANT_WORK_RANGE + (kind === 'shoal' ? 1 : 0);
+}
+/** The panel shows within this many tiles of the Giant; the pulse line is told within it too. */
+export const GIANT_PANEL_RANGE = 40;
+const clamp = (n, lo, hi) => Math.min(hi, Math.max(lo, n));
+const rollBetween = (min, max, random) => min + (Math.floor(random() * (max - min + 1)) % (max - min + 1));
+/** What the death throws for `active` workers at that moment (Windfall's fall table). A withering throws nothing. */
+export function giantScatterCounts(active) {
+    const a = Math.max(0, Math.floor(active) || 0);
+    return {
+        crates: clamp(4 + 2 * a, 8, 24),
+        smallSatchels: clamp(Math.ceil(a / 2), 2, 10),
+        largeSatchels: clamp(Math.floor(a / 5), 1, 4),
+        rare: 1 + Math.floor(a / 10),
+    };
+}
+export function giantCrateQty(random = Math.random) {
+    return rollBetween(GIANT_CRATE_MIN, GIANT_CRATE_MAX, random);
+}
+/** A satchel's coins by band: [small min, small max, large min, large max] (Windfall's table). */
+export const GIANT_SATCHEL_COINS = {
+    1: [30, 70, 80, 170],
+    2: [60, 140, 150, 350],
+    3: [100, 220, 250, 550],
+    4: [160, 320, 400, 800],
+};
+/** What opening a satchel gives: coins, the Giant's resource, and (large) its rare piece. No food, no shop goods. */
+export function giantSatchelContents(kind, band, large, random = Math.random) {
+    const [sMin, sMax, lMin, lMax] = GIANT_SATCHEL_COINS[band];
+    const r = GIANT_BANDS[band].resource[kind];
+    const items = [{ kind: 'coins', qty: large ? rollBetween(lMin, lMax, random) : rollBetween(sMin, sMax, random) }];
+    items.push({ kind: r.kind, qty: large ? rollBetween(8, 14, random) : rollBetween(5, 10, random) });
+    if (large)
+        items.push({ kind: r.rare, qty: rollBetween(1, 3, random) });
+    return items;
+}
+/** The first site list (spec section 3: four to six a band come with the balance pass; these are the anchors the data gives). */
+export const GIANT_SITES = [
+    // Band 1: Hope Town and its surroundings.
+    { id: 'g1-tree-hopewood', kind: 'tree', band: 1, where: 'in Hopewood Common', anchor: { x: 125, z: 900 }, searchRadius: 25 },
+    { id: 'g1-tree-copse', kind: 'tree', band: 1, where: 'at Hopewood Copse', anchor: { x: 500, z: 884 }, searchRadius: 30 },
+    { id: 'g1-shoal-henson', kind: 'shoal', band: 1, where: 'in Henson Pond', anchor: { x: 300, z: 835 }, searchRadius: 25 },
+    { id: 'g1-star-hollin', kind: 'star', band: 1, where: 'on the Hollin Brook shore', anchor: { x: 350, z: 938 }, searchRadius: 25 },
+    { id: 'g1-bloom-common', kind: 'bloom', band: 1, where: 'in Hopewood Common', anchor: { x: 150, z: 880 }, searchRadius: 30 },
+    { id: 'g1-cauldron-hope', kind: 'cauldron', band: 1, where: 'outside Hope Town', anchor: { x: 330, z: 905 }, searchRadius: 30 },
+    // Band 2: Calverton, the fields and the Western line's first stops.
+    { id: 'g2-tree-brindle', kind: 'tree', band: 2, where: 'in the Brindlecross pines', anchor: { x: 1850, z: 1090 }, searchRadius: 25 },
+    { id: 'g2-shoal-riversend', kind: 'shoal', band: 2, where: 'at Riversend', anchor: { x: 1851, z: 1001 }, searchRadius: 30 },
+    { id: 'g2-star-riversend', kind: 'star', band: 2, where: 'on the Riversend gravel bar', anchor: { x: 1851, z: 1001 }, searchRadius: 25 },
+    { id: 'g2-bloom-calverton', kind: 'bloom', band: 2, where: 'outside Calverton', anchor: { x: 772, z: 660 }, searchRadius: 30 },
+    { id: 'g2-cauldron-calverton', kind: 'cauldron', band: 2, where: 'outside Calverton', anchor: { x: 760, z: 670 }, searchRadius: 30 },
+    // Band 3: the Dreadwoods' edge, the Greenwood, the mine.
+    { id: 'g3-tree-rangers', kind: 'tree', band: 3, where: "by Ranger's Rest", anchor: { x: 1735, z: 1230 }, searchRadius: 25 },
+    { id: 'g3-shoal-lake', kind: 'shoal', band: 3, where: 'on the battlefield lake', anchor: { x: 600, z: 700 }, searchRadius: 40 },
+    // The mine yard is inside the PvP woods, where no Giant lands: band 3's star falls at the Emberdeep diggings instead.
+    { id: 'g3-star-emberdeep', kind: 'star', band: 3, where: 'at the Emberdeep diggings', anchor: { x: 1760, z: 862 }, searchRadius: 25 },
+    { id: 'g3-bloom-lake', kind: 'bloom', band: 3, where: 'by the battlefield lake', anchor: { x: 580, z: 722 }, searchRadius: 30 },
+    { id: 'g3-cauldron-rangers', kind: 'cauldron', band: 3, where: "by Ranger's Rest", anchor: { x: 1745, z: 1220 }, searchRadius: 25 },
+    // Band 4: the frozen north and the Highfold road.
+    { id: 'g4-tree-highfold', kind: 'tree', band: 4, where: 'on the Highfold road', anchor: { x: 2040, z: 360 }, searchRadius: 25 },
+    { id: 'g4-shoal-thaw', kind: 'shoal', band: 4, where: 'in the Thaw gorge', anchor: { x: 237, z: 150 }, searchRadius: 30 },
+    { id: 'g4-star-gorge', kind: 'star', band: 4, where: 'in the Crystal Gorge', anchor: { x: 30, z: 226 }, searchRadius: 25 },
+    { id: 'g4-bloom-highfold', kind: 'bloom', band: 4, where: 'on the Highfold road', anchor: { x: 2050, z: 370 }, searchRadius: 25 },
+    { id: 'g4-cauldron-highfold', kind: 'cauldron', band: 4, where: 'on the Highfold road', anchor: { x: 2030, z: 350 }, searchRadius: 25 },
+];
+export function giantSiteById(id) {
+    return GIANT_SITES.find((s) => s.id === id);
+}
+/**
+ * Pick the next Giant: a random band, then a random kind of that band's sites, never the site that just ran. The bands are weighted so
+ * the starter band sees the most (a newcomer meets one soon).
+ */
+export const GIANT_BAND_WEIGHTS = { 1: 4, 2: 3, 3: 2, 4: 1 };
+export function giantPickSite(lastSite, random = Math.random, sites = GIANT_SITES) {
+    const pool = sites.filter((s) => s.id !== lastSite);
+    if (pool.length === 0)
+        return null;
+    const total = pool.reduce((n, s) => n + GIANT_BAND_WEIGHTS[s.band], 0);
+    let roll = random() * total;
+    for (const s of pool) {
+        roll -= GIANT_BAND_WEIGHTS[s.band];
+        if (roll < 0)
+            return s;
+    }
+    return pool[pool.length - 1];
+}
+/** The world-chat lines (one place, so the backend and the tests read the same words). */
+export function giantLine(kind, node, where) {
+    const info = GIANT_KIND_INFO[node.kind];
+    const band = GIANT_BANDS[node.band];
+    const name = giantName(node.kind, node.band);
+    if (kind === 'lands')
+        return `World event: ${name}, ${info.lands} ${where}! Bring ${info.tool}, ${band.band}.`;
+    if (kind === 'pulse')
+        return `${band.names[node.kind]} ${info.pulse} ${where}.`;
+    if (kind === 'dies')
+        return `World event: ${name}, ${info.dies} ${where}! Crates and satchels on the ground for ${GIANT_SCATTER_MS / MINUTE} minutes.`;
+    return `World event: ${band.names[node.kind]} ${where} ${info.withers}.`;
+}
+/** One line for the "Today in Dreadwoods" panel and the login while a Giant stands (none otherwise: it is never announced ahead). */
+export function giantTodayLine(node, where) {
+    if (!node || node.end || !where)
+        return null;
+    return `Skilling Giant: ${giantName(node.kind, node.band)} is up ${where} (${GIANT_BANDS[node.band].band})`;
+}
+export function giantView(input) {
+    const { node, where, tile, now } = input;
+    const info = GIANT_KIND_INFO[node.kind];
+    const worker = input.you ? node.workers.find((w) => w.key === input.you.key) : undefined;
+    return {
+        id: node.id,
+        kind: node.kind,
+        band: node.band,
+        name: GIANT_BANDS[node.band].names[node.kind],
+        title: info.title,
+        skill: info.skillName,
+        gate: giantGate(node.band),
+        where,
+        x: tile.x,
+        z: tile.z,
+        health: Math.max(0, Math.min(1, 1 - node.progress)),
+        msToCap: node.end ? 0 : Math.max(0, node.landedAt + GIANT_CAP_MS - now),
+        pulses: node.pulses,
+        active: giantActiveCount(node, now),
+        ended: node.end ? node.end.how : null,
+        msSinceEnd: node.end ? Math.max(0, now - node.end.at) : 0,
+        you: worker || input.you?.choreStanding
+            ? { hits: worker?.hits ?? 0, satchel: giantContribution(worker?.hits ?? 0), chore: input.you?.choreStanding ? { name: info.choreName, fix: info.choreFix } : null }
+            : null,
+        canWork: input.you ? giantCanWork(node.band, input.you.level) : true,
+        tool: info.tool,
+    };
+}
+/** The paper map marks a Giant from the moment it lands until its remains are gone. */
+export function giantOnMap(view) {
+    return !!view && (view.ended === null || view.msSinceEnd < GIANT_SPENT_MS);
+}
+export const GIANT_PENDING_PER_CHARACTER = 8;
+export const GIANT_PENDING_CHARACTERS = 5000;
+export const GIANT_COLLECTED_MAX = 600;
+export function emptyGiantSave() {
+    return { v: 1, node: null, nextAt: null, lastSite: null, collected: [], pending: {} };
+}
+function num(v, lo, hi) {
+    return typeof v === 'number' && Number.isFinite(v) && v >= lo && v <= hi ? v : null;
+}
+function bandOf(v) {
+    return v === 1 || v === 2 || v === 3 || v === 4 ? v : null;
+}
+function parseWorker(raw) {
+    if (!raw || typeof raw !== 'object')
+        return null;
+    const r = raw;
+    if (typeof r.key !== 'string' || r.key.length === 0 || r.key.length > 80)
+        return null;
+    const hits = num(r.hits, 0, 1e6);
+    const lastAt = num(r.lastAt, 0, 1e15);
+    const firstAt = num(r.firstAt, 0, 1e15);
+    if (hits === null || lastAt === null || firstAt === null)
+        return null;
+    const w = { key: r.key, hits: Math.floor(hits), lastAt, firstAt };
+    if (typeof r.account === 'string' && r.account.length > 0 && r.account.length <= 80)
+        w.account = r.account;
+    return w;
+}
+export function parseGiantNode(raw) {
+    if (!raw || typeof raw !== 'object')
+        return null;
+    const r = raw;
+    const band = bandOf(r.band);
+    const progress = num(r.progress, 0, 1);
+    const pulses = num(r.pulses, 0, 1e4);
+    const lastPulseAt = num(r.lastPulseAt, 0, 1e15);
+    const landedAt = num(r.landedAt, 0, 1e15);
+    if (!isGiantKind(r.kind) || band === null || progress === null || pulses === null || lastPulseAt === null || landedAt === null)
+        return null;
+    if (typeof r.id !== 'string' || r.id.length === 0 || r.id.length > 60 || typeof r.site !== 'string' || r.site.length > 60)
+        return null;
+    const seen = new Set();
+    const workers = (Array.isArray(r.workers) ? r.workers.slice(0, 5000) : [])
+        .map(parseWorker)
+        .filter((w) => w !== null && (seen.has(w.key) ? false : (seen.add(w.key), true)));
+    let end = null;
+    const e = r.end;
+    if (e && typeof e === 'object') {
+        const at = num(e.at, 0, 1e15);
+        if (at !== null && (e.how === 'killed' || e.how === 'withered'))
+            end = { at, how: e.how };
+    }
+    return { v: 1, id: r.id, kind: r.kind, band, site: r.site, landedAt, progress, pulses: Math.floor(pulses), lastPulseAt, workers, end };
+}
+/** Defensive parse of the saved state (a corrupt save is an empty one, never a crash). */
+export function parseGiantSave(raw) {
+    if (!raw || typeof raw !== 'object')
+        return emptyGiantSave();
+    const r = raw;
+    if (r.v !== 1)
+        return emptyGiantSave();
+    const nextAt = num(r.nextAt, 0, 1e15);
+    const lastSite = typeof r.lastSite === 'string' && r.lastSite.length <= 60 ? r.lastSite : null;
+    const collected = (Array.isArray(r.collected) ? r.collected : []).filter((c) => typeof c === 'string' && c.length <= 160).slice(-GIANT_COLLECTED_MAX);
+    const pending = {};
+    if (r.pending && typeof r.pending === 'object') {
+        for (const [key, list] of Object.entries(r.pending).slice(0, GIANT_PENDING_CHARACTERS)) {
+            if (!Array.isArray(list) || key.length === 0 || key.length > 80)
+                continue;
+            const owed = list
+                .map((p) => {
+                const q = p;
+                if (!q || typeof q !== 'object')
+                    return null;
+                const band = bandOf(q.band);
+                if (typeof q.id !== 'string' || q.id.length > 60 || !isGiantKind(q.kind) || band === null)
+                    return null;
+                return { id: q.id, kind: q.kind, band, large: q.large === true };
+            })
+                .filter((p) => p !== null)
+                .slice(-GIANT_PENDING_PER_CHARACTER);
+            if (owed.length > 0)
+                pending[key] = owed;
+        }
+    }
+    return { v: 1, node: parseGiantNode(r.node), nextAt, lastSite, collected, pending };
+}
+/** The key a collected contribution satchel is saved under: one per character per Giant. */
+export function giantCollectedKey(id, characterKey) {
+    return `${id}:${characterKey}`;
+}
+//# sourceMappingURL=skillingGiants.js.map