@provable-games/dm-engine 0.1.0

package/dist/rules/gameSimulation.js

@@ -0,0 +1,845 @@
+/**
+ * Client-only game simulation logic.
+ * Pure functions porting Cairo contract formulas for use in useGameCore.
+ */
+import { BEAST_NAMES, BEAST_SPECIAL_NAME_LEVEL_UNLOCK } from "../constants/beast.js";
+import { MAX_ADVENTURER_HEALTH, MAX_ADVENTURER_XP, MAX_GOLD, MIN_DAMAGE_FROM_BEASTS, MIN_DAMAGE_FROM_OBSTACLES, } from "../constants/game.js";
+import { ItemId, SUFFIX_UNLOCK_GREATNESS } from "../constants/loot.js";
+import { getBeastName, getBeastTier, getBeastType } from "./beast.js";
+import { calculateAttackDamage, calculateBeastDamage, calculateLevel, elementalAdjustedDamage, } from "./game.js";
+import { getMaxHealth } from "./health.js";
+import { ItemUtils, Tier } from "./loot.js";
+import { generateStartingStatsFromSeed } from "./processFutures.js";
+// ─── Item progression constants (mirrors contracts/src/constants/adventurer.cairo) ───
+const ITEM_MAX_GREATNESS = 20;
+const MAX_GREATNESS_STAT_BONUS = 1;
+const PREFIX_UNLOCK_GREATNESS = 19;
+const VITALITY_INSTANT_HEALTH_BONUS = 15;
+const MAX_ITEM_XP = 400;
+const EQUIPMENT_SLOTS = [
+    "weapon",
+    "chest",
+    "head",
+    "waist",
+    "foot",
+    "hand",
+    "neck",
+    "ring",
+];
+// ─── Random helpers ──────────────────────────────────────────────
+export const randomU8 = () => Math.floor(Math.random() * 256);
+export const randomU16 = () => Math.floor(Math.random() * 65536);
+export const randomU32 = () => Math.floor(Math.random() * 0x100000000);
+// ─── Tier item lists (from Cairo get_t*_items) ──────────────────
+export const T5_ITEMS = [
+    ItemId.Book,
+    ItemId.Wand,
+    ItemId.Hood,
+    ItemId.Sash,
+    ItemId.Shirt,
+    ItemId.Shoes,
+    ItemId.Gloves,
+    ItemId.Club,
+    ItemId.Helm,
+    ItemId.RingMail,
+    ItemId.HeavyBoots,
+    ItemId.HeavyBelt,
+    ItemId.HeavyGloves,
+    ItemId.ShortSword,
+    ItemId.LeatherBelt,
+    ItemId.LeatherBoots,
+    ItemId.LeatherArmor,
+    ItemId.LeatherGloves,
+    ItemId.Cap,
+];
+export const T4_ITEMS = [
+    ItemId.LongSword,
+    ItemId.HardLeatherBelt,
+    ItemId.HardLeatherBoots,
+    ItemId.HardLeatherArmor,
+    ItemId.LeatherCap,
+    ItemId.HardLeatherGloves,
+    ItemId.Mace,
+    ItemId.ChainMail,
+    ItemId.FullHelm,
+    ItemId.ChainBoots,
+    ItemId.ChainGloves,
+    ItemId.MeshBelt,
+    ItemId.Robe,
+    ItemId.LinenHood,
+    ItemId.LinenSash,
+    ItemId.LinenShoes,
+    ItemId.LinenGloves,
+];
+export const T3_ITEMS = [
+    ItemId.Tome,
+    ItemId.BoneWand,
+    ItemId.LinenRobe,
+    ItemId.SilkHood,
+    ItemId.WoolSash,
+    ItemId.WoolShoes,
+    ItemId.WoolGloves,
+    ItemId.Scimitar,
+    ItemId.StuddedLeatherArmor,
+    ItemId.StuddedLeatherBoots,
+    ItemId.StuddedLeatherBelt,
+    ItemId.StuddedLeatherGloves,
+    ItemId.WarCap,
+    ItemId.Maul,
+    ItemId.Greaves,
+    ItemId.Gauntlets,
+    ItemId.PlateMail,
+    ItemId.GreatHelm,
+    ItemId.PlatedBelt,
+];
+export const T2_ITEMS = [
+    ItemId.GraveWand,
+    ItemId.Chronicle,
+    ItemId.SilkRobe,
+    ItemId.DivineHood,
+    ItemId.SilkSash,
+    ItemId.SilkSlippers,
+    ItemId.SilkGloves,
+    ItemId.Falchion,
+    ItemId.DragonsCrown,
+    ItemId.DragonskinBelt,
+    ItemId.DragonskinBoots,
+    ItemId.DragonskinArmor,
+    ItemId.DragonskinGloves,
+    ItemId.Quarterstaff,
+    ItemId.OrnateChestplate,
+    ItemId.WarBelt,
+    ItemId.OrnateHelm,
+    ItemId.OrnateGreaves,
+    ItemId.OrnateGauntlets,
+];
+export const T1_ITEMS = [
+    ItemId.GhostWand,
+    ItemId.Grimoire,
+    ItemId.DivineRobe,
+    ItemId.Crown,
+    ItemId.BrightsilkSash,
+    ItemId.DivineSlippers,
+    ItemId.DivineGloves,
+    ItemId.Katana,
+    ItemId.DemonHusk,
+    ItemId.DemonCrown,
+    ItemId.DemonhideBelt,
+    ItemId.DemonsHands,
+    ItemId.DemonhideBoots,
+    ItemId.Warhammer,
+    ItemId.HolyChestplate,
+    ItemId.AncientHelm,
+    ItemId.HolyGreaves,
+    ItemId.HolyGauntlets,
+    ItemId.OrnateBelt,
+];
+// ─── Combat helpers ──────────────────────────────────────────────
+export const getTierMultiplier = (tier) => {
+    return Math.max(1, 6 - tier); // T1=5, T2=4, T3=3, T4=2, T5=1
+};
+export const applyDamageReduction = (damage, reductionPercent) => {
+    if (damage <= 0 || reductionPercent <= 0)
+        return Math.max(0, damage);
+    const clamped = Math.min(100, Math.max(0, reductionPercent));
+    return Math.max(0, Math.floor((damage * (100 - clamped)) / 100));
+};
+/**
+ * Ability-based threat avoidance (used for ambush with wisdom, dodge with intelligence).
+ * Returns true if the threat is avoided.
+ */
+export const abilityBasedAvoidThreat = (level, stat) => {
+    if (stat >= level)
+        return true;
+    const rnd = randomU8();
+    const scaledChance = Math.floor((level * rnd) / 255);
+    return stat > scaledChance;
+};
+export const abilityBasedAvoidThreatWithRoll = (level, stat, avoidRnd) => {
+    if (stat >= level)
+        return { avoided: true, rnd: 0 };
+    const rnd = avoidRnd ?? randomU8();
+    const scaledChance = Math.floor((level * rnd) / 255);
+    return { avoided: stat > scaledChance, rnd };
+};
+// ─── Encounter level/health generation ───────────────────────────
+const getDifficultyOffset = (adventurerLevel) => {
+    if (adventurerLevel >= 50)
+        return 80;
+    if (adventurerLevel >= 40)
+        return 40;
+    if (adventurerLevel >= 30)
+        return 20;
+    if (adventurerLevel >= 20)
+        return 10;
+    return 0;
+};
+const getHealthOffset = (adventurerLevel) => {
+    if (adventurerLevel >= 50)
+        return 500;
+    if (adventurerLevel >= 40)
+        return 400;
+    if (adventurerLevel >= 30)
+        return 200;
+    if (adventurerLevel >= 20)
+        return 100;
+    return 10;
+};
+export const getEncounterLevel = (adventurerLevel, levelRnd) => {
+    const base = 1 + ((levelRnd ?? randomU16()) % Math.max(1, adventurerLevel * 3));
+    return base + getDifficultyOffset(adventurerLevel);
+};
+export const getEncounterHealth = (adventurerLevel, healthRnd) => {
+    const base = 1 + ((healthRnd ?? randomU16()) % Math.max(1, adventurerLevel * 20));
+    return Math.min(MAX_ADVENTURER_HEALTH, base + getHealthOffset(adventurerLevel));
+};
+// ─── Attack location ─────────────────────────────────────────────
+const ATTACK_SLOTS = ["chest", "head", "waist", "foot", "hand"];
+// Every roll below takes an OPTIONAL pre-drawn value. Omitted, they behave exactly as before
+// (Math.random), which is what VRF dungeons want -- their optimistic render is corrected by the
+// chain events that follow. Supplied, they make the simulation a deterministic function of a seed,
+// which is what block-hash commit/reveal requires: there, nothing arrives later to correct a wrong
+// guess, and acting on one permanently bricks the run.
+export const getAttackLocation = (rnd) => {
+    return ATTACK_SLOTS[(rnd ?? randomU8()) % 5];
+};
+const SLOT_DISPLAY_NAMES = {
+    chest: "Chest",
+    head: "Head",
+    waist: "Waist",
+    foot: "Foot",
+    hand: "Hand",
+};
+export const getSlotDisplayName = (slot) => {
+    return SLOT_DISPLAY_NAMES[slot] || "None";
+};
+// ─── Obstacle type from ID ───────────────────────────────────────
+const getObstacleType = (id) => {
+    if (id >= 1 && id < 26)
+        return "Magic";
+    if (id < 51)
+        return "Blade";
+    return "Bludgeon";
+};
+const getObstacleTier = (id) => {
+    const offset = (id - 1) % 25;
+    if (offset < 5)
+        return 1;
+    if (offset < 10)
+        return 2;
+    if (offset < 15)
+        return 3;
+    if (offset < 20)
+        return 4;
+    return 5;
+};
+// ─── Armor type helper ───────────────────────────────────────────
+const getArmorType = (itemId) => {
+    if (itemId === 0)
+        return "None";
+    const type = ItemUtils.getItemType(itemId);
+    // Map item types to armor types for elemental calculation
+    if (type === "Cloth" || type === "Hide" || type === "Metal")
+        return type;
+    return "None";
+};
+export const generateBeast = (adventurerLevel) => {
+    const id = 1 + (randomU32() % 75);
+    const level = getEncounterLevel(adventurerLevel);
+    const health = getEncounterHealth(adventurerLevel);
+    const tier = getBeastTier(id);
+    const hasSpecials = level >= BEAST_SPECIAL_NAME_LEVEL_UNLOCK;
+    const special2 = hasSpecials ? 1 + (randomU8() % 69) : 0;
+    const special3 = hasSpecials ? 1 + (randomU8() % 18) : 0;
+    return { id, level, health, tier, special2, special3 };
+};
+export const beastToBeastEvent = (beast) => ({
+    id: beast.id,
+    baseName: BEAST_NAMES[beast.id],
+    name: getBeastName(beast.id, beast.level, beast.special2, beast.special3),
+    health: beast.health,
+    level: beast.level,
+    type: getBeastType(beast.id),
+    tier: beast.tier,
+    specialPrefix: beast.level >= BEAST_SPECIAL_NAME_LEVEL_UNLOCK ? String(beast.special2) : null,
+    specialSuffix: beast.level >= BEAST_SPECIAL_NAME_LEVEL_UNLOCK ? String(beast.special3) : null,
+    isCollectable: false,
+    traitSeed: BigInt(0),
+});
+export const generateObstacle = (adventurerLevel, rolls) => {
+    const id = 1 + ((rolls?.idRnd ?? randomU32()) % 75);
+    const level = getEncounterLevel(adventurerLevel, rolls?.levelRnd);
+    const tier = getObstacleTier(id);
+    const type = getObstacleType(id);
+    return { id, level, tier, type };
+};
+// ─── Obstacle damage ─────────────────────────────────────────────
+export const calculateObstacleDamage = (obstacle, armor, adventurerLevel, baseDamageReduction, rolls) => {
+    const slot = getAttackLocation(rolls?.attackLocationRnd);
+    const attackPower = obstacle.level * getTierMultiplier(obstacle.tier);
+    const armorType = getArmorType(armor.id);
+    const armorLevel = armor.id ? calculateLevel(armor.xp) : 0;
+    const armorTier = armor.id ? ItemUtils.getItemTier(armor.id) : Tier.T5;
+    const armorPower = armor.id ? armorLevel * getTierMultiplier(armorTier) : 0;
+    let adjustedAttack = elementalAdjustedDamage(attackPower, obstacle.type, armorType);
+    // Critical hit check
+    const critChance = Math.min(adventurerLevel, 100);
+    const isCrit = isCriticalHit(critChance, rolls?.criticalHitRnd);
+    if (isCrit) {
+        adjustedAttack *= 2;
+    }
+    let damage = Math.max(MIN_DAMAGE_FROM_OBSTACLES, adjustedAttack - armorPower);
+    if (baseDamageReduction > 0) {
+        damage = Math.max(MIN_DAMAGE_FROM_OBSTACLES, applyDamageReduction(damage, baseDamageReduction));
+    }
+    return { damage, location: getSlotDisplayName(slot), critical_hit: isCrit };
+};
+// ─── XP reward calculation ───────────────────────────────────────
+export const getBaseXpReward = (tier, entityLevel, adventurerLevel) => {
+    const levelDecay = Math.min(adventurerLevel * 2, 95);
+    const tierMult = getTierMultiplier(tier);
+    const reward = Math.floor((tierMult * entityLevel) / 2);
+    const decayed = Math.floor((reward * (100 - levelDecay)) / 100);
+    return Math.max(4, decayed); // MINIMUM_XP_REWARD = 4
+};
+export const getDiscovery = (adventurerLevel, rolls) => {
+    const typeRnd = rolls?.typeRnd ?? randomU8();
+    const scaledType = Math.floor((typeRnd * 100 + 127) / 255);
+    const amountRnd1 = rolls?.amountRnd1 ?? randomU8();
+    const amountRnd2 = rolls?.amountRnd2 ?? randomU8();
+    if (scaledType < 45) {
+        return { type: "Gold", amount: (amountRnd1 % Math.max(1, adventurerLevel)) + 1 };
+    }
+    if (scaledType < 90) {
+        return { type: "Health", amount: ((amountRnd1 % Math.max(1, adventurerLevel)) + 1) * 2 };
+    }
+    // Loot
+    const tierRnd = Math.floor((amountRnd1 * 100 + 127) / 255);
+    let items;
+    if (tierRnd < 50)
+        items = T5_ITEMS;
+    else if (tierRnd < 80)
+        items = T4_ITEMS;
+    else if (tierRnd < 92)
+        items = T3_ITEMS;
+    else if (tierRnd < 98)
+        items = T2_ITEMS;
+    else
+        items = T1_ITEMS;
+    const itemId = items[amountRnd2 % items.length];
+    return { type: "Loot", amount: itemId, itemId };
+};
+// ─── Adventurer state helpers ────────────────────────────────────
+export const increaseHealth = (adventurer, amount) => {
+    adventurer.health = Math.min(getMaxHealth(adventurer.stats.vitality), adventurer.health + amount);
+};
+export const decreaseHealth = (adventurer, amount) => {
+    adventurer.health = Math.max(0, adventurer.health - amount);
+};
+export const increaseGold = (adventurer, amount) => {
+    adventurer.gold = Math.min(MAX_GOLD, adventurer.gold + amount);
+};
+export const increaseXp = (adventurer, amount) => {
+    const previousLevel = calculateLevel(adventurer.xp);
+    adventurer.xp = Math.min(MAX_ADVENTURER_XP, adventurer.xp + amount);
+    const newLevel = calculateLevel(adventurer.xp);
+    if (newLevel > previousLevel) {
+        adventurer.stat_upgrades_available += newLevel - previousLevel;
+    }
+};
+export const canExplore = (adventurer) => {
+    return (adventurer.health > 0 &&
+        adventurer.beast_health === 0 &&
+        adventurer.stat_upgrades_available === 0);
+};
+// ─── Loot discovery helpers ──────────────────────────────────────
+/**
+ * Get the armor Item at a given attack slot.
+ */
+export const getArmorAtSlot = (adventurer, slot) => {
+    return adventurer.equipment[slot] || { id: 0, xp: 0 };
+};
+/**
+ * Mirrors `_process_discovery` in the exploration contract: a discovered item
+ * is replaced with gold (T1=20, T2=16, T3=12, T4=8, T5=4) when the adventurer
+ * already owns it (equipped or in bag) or has nowhere to put it (bag full and
+ * equipment slot occupied). Returns null when the item would be kept.
+ */
+export const getLootDiscoveryGoldConversion = (adventurer, bag, itemId) => {
+    const equipment = adventurer.equipment;
+    const equipped = [
+        equipment.weapon,
+        equipment.chest,
+        equipment.head,
+        equipment.waist,
+        equipment.foot,
+        equipment.hand,
+        equipment.neck,
+        equipment.ring,
+    ].some((item) => item.id === itemId);
+    const inBag = bag.some((item) => item.id === itemId);
+    const slot = ItemUtils.getItemSlot(itemId);
+    const slotKey = slot.toLowerCase();
+    const slotFree = equipment[slotKey]?.id === 0;
+    const bagFull = bag.length >= 15;
+    let reason;
+    if (equipped || inBag) {
+        reason = "owned";
+    }
+    else if (bagFull && !slotFree) {
+        reason = "inventory_full";
+    }
+    else {
+        return null;
+    }
+    const tier = ItemUtils.getItemTier(itemId);
+    switch (tier) {
+        case 1:
+            return { gold: 20, reason };
+        case 2:
+            return { gold: 16, reason };
+        case 3:
+            return { gold: 12, reason };
+        case 4:
+            return { gold: 8, reason };
+        default:
+            return { gold: 4, reason };
+    }
+};
+/**
+ * Try to add a discovered loot item to equipment or bag.
+ * Returns the gold conversion if the item couldn't be added (already owned or
+ * inventory full), or null if the item was equipped/bagged.
+ */
+export const processLootDiscovery = (adventurer, bag, itemId) => {
+    const conversion = getLootDiscoveryGoldConversion(adventurer, bag, itemId);
+    if (conversion) {
+        return conversion;
+    }
+    const equipment = adventurer.equipment;
+    const slotKey = ItemUtils.getItemSlot(itemId).toLowerCase();
+    const slotFree = equipment[slotKey]?.id === 0;
+    const newItem = { id: itemId, xp: 0 };
+    if (slotFree) {
+        // Equip directly
+        equipment[slotKey].id = newItem.id;
+        equipment[slotKey].xp = newItem.xp;
+    }
+    else {
+        // Add to bag
+        bag.push(newItem);
+    }
+    return null;
+};
+// ─── Combat: Adventurer attack ───────────────────────────────────
+/**
+ * Item greatness (level) from XP, capped at 20.
+ */
+export const getItemGreatness = (item) => {
+    if (item.xp === 0)
+        return 1;
+    return Math.min(20, Math.floor(Math.sqrt(item.xp)));
+};
+/**
+ * Luck-based critical hit check (used for adventurer attacks).
+ */
+/** `ImplCombat::is_critical_hit(chance, rnd)`: `chance * 256 > 100 * rnd`. */
+export const isCriticalHit = (luck, criticalHitRnd) => {
+    const rnd = criticalHitRnd ?? randomU8();
+    return luck * 256 > 100 * rnd;
+};
+/**
+ * Precompute adventurer attack damage (normal and critical) against current beast.
+ * Delegates to calculateAttackDamage from game.ts which includes weapon specials,
+ * ring name-match bonus, and ring critical hit bonus.
+ */
+export const calculateAdventurerAttackDamage = (adventurer, beast) => {
+    const { baseDamage, criticalDamage } = calculateAttackDamage(adventurer.equipment.weapon, adventurer, beast);
+    return { normal: baseDamage, crit: criticalDamage };
+};
+export const calculateBeastCounterAttack = (beast, adventurer, baseDamageReduction, isAmbush = false, rolls) => {
+    const slot = getAttackLocation(rolls?.attackLocationRnd);
+    const armor = getArmorAtSlot(adventurer, slot);
+    const beastDmg = calculateBeastDamage(beast, adventurer, armor);
+    // Level-based crit check for beasts
+    const adventurerLevel = calculateLevel(adventurer.xp);
+    const critChance = Math.min(adventurerLevel, 100);
+    const isCrit = isCriticalHit(critChance, rolls?.criticalHitRnd);
+    let damage = isCrit ? beastDmg.criticalDamage : beastDmg.baseDamage;
+    // Apply damage reduction for ambushes only
+    if (isAmbush && baseDamageReduction > 0) {
+        damage = Math.max(MIN_DAMAGE_FROM_BEASTS, applyDamageReduction(damage, baseDamageReduction));
+    }
+    return { damage, location: getSlotDisplayName(slot), critical_hit: isCrit, slot };
+};
+/**
+ * Generate starting stats when adventurer levels from 1 to 2.
+ * 12 random point allocations across 6 stats.
+ */
+// ─── Inventory: equip / drop ─────────────────────────────────────
+/** Get suffix name for an item if its greatness unlocks specials. */
+const getItemSuffix = (item, salt) => {
+    if (item.id === 0)
+        return null;
+    const greatness = getItemGreatness(item);
+    if (greatness < SUFFIX_UNLOCK_GREATNESS)
+        return null;
+    const specials = ItemUtils.getSpecials(item.id, greatness, salt);
+    return specials.special1;
+};
+/** Apply suffix boost to stats (matches contract apply_suffix_boost). */
+const applySuffixBoost = (stats, suffix) => {
+    if (suffix === "of Power") {
+        stats.strength += 3;
+    }
+    else if (suffix === "of Titans") {
+        stats.strength += 2;
+    }
+    else if (suffix === "of Skill") {
+        stats.dexterity += 3;
+    }
+    else if (suffix === "of Perfection") {
+        stats.strength += 1;
+        stats.dexterity += 1;
+    }
+    else if (suffix === "of Brilliance") {
+        stats.intelligence += 3;
+    }
+    else if (suffix === "of Enlightenment") {
+        stats.wisdom += 3;
+    }
+    else if (suffix === "of Protection") {
+        stats.dexterity += 1;
+    }
+    else if (suffix === "of Anger") {
+        stats.strength += 2;
+        stats.dexterity += 1;
+    }
+    else if (suffix === "of Rage") {
+        stats.strength += 1;
+        stats.wisdom += 1;
+    }
+    else if (suffix === "of Fury") {
+        stats.intelligence += 1;
+    }
+    else if (suffix === "of Vitriol") {
+        stats.intelligence += 2;
+        stats.wisdom += 1;
+    }
+    else if (suffix === "of the Fox") {
+        stats.dexterity += 2;
+    }
+    else if (suffix === "of Detection") {
+        stats.wisdom += 2;
+        stats.dexterity += 1;
+    }
+    else if (suffix === "of Reflection") {
+        stats.intelligence += 1;
+        stats.wisdom += 2;
+    }
+};
+/** Remove suffix boost from stats (matches contract remove_suffix_boost). */
+const removeSuffixBoost = (stats, suffix) => {
+    if (suffix === "of Power") {
+        stats.strength -= 3;
+    }
+    else if (suffix === "of Titans") {
+        stats.strength -= 2;
+    }
+    else if (suffix === "of Skill") {
+        stats.dexterity -= 3;
+    }
+    else if (suffix === "of Perfection") {
+        stats.strength -= 1;
+        stats.dexterity -= 1;
+    }
+    else if (suffix === "of Brilliance") {
+        stats.intelligence -= 3;
+    }
+    else if (suffix === "of Enlightenment") {
+        stats.wisdom -= 3;
+    }
+    else if (suffix === "of Protection") {
+        stats.dexterity -= 1;
+    }
+    else if (suffix === "of Anger") {
+        stats.strength -= 2;
+        stats.dexterity -= 1;
+    }
+    else if (suffix === "of Rage") {
+        stats.strength -= 1;
+        stats.wisdom -= 1;
+    }
+    else if (suffix === "of Fury") {
+        stats.intelligence -= 1;
+    }
+    else if (suffix === "of Vitriol") {
+        stats.intelligence -= 2;
+        stats.wisdom -= 1;
+    }
+    else if (suffix === "of the Fox") {
+        stats.dexterity -= 2;
+    }
+    else if (suffix === "of Detection") {
+        stats.wisdom -= 2;
+        stats.dexterity -= 1;
+    }
+    else if (suffix === "of Reflection") {
+        stats.intelligence -= 1;
+        stats.wisdom -= 2;
+    }
+};
+/** Remove bag boost from stats (matches contract remove_bag_boost). */
+/** Mirror of `apply_bag_boost`; `removeBagBoost` below is its inverse. */
+const applyBagBoost = (stats, suffix) => {
+    if (suffix === "of Giant") {
+        stats.vitality += 3;
+    }
+    else if (suffix === "of Titans") {
+        stats.charisma += 1;
+    }
+    else if (suffix === "of Perfection") {
+        stats.vitality += 1;
+    }
+    else if (suffix === "of Protection") {
+        stats.vitality += 2;
+    }
+    else if (suffix === "of Rage") {
+        stats.charisma += 1;
+    }
+    else if (suffix === "of Fury") {
+        stats.vitality += 1;
+        stats.charisma += 1;
+    }
+    else if (suffix === "of the Fox") {
+        stats.charisma += 1;
+    }
+    else if (suffix === "of the Twins") {
+        stats.charisma += 3;
+    }
+};
+/** `ImplAdventurer::get_vitality_item_boost` -- vitality granted by an item suffix. */
+const vitalityItemBoost = (suffix) => {
+    if (suffix === "of Giant")
+        return 3;
+    if (suffix === "of Perfection")
+        return 1;
+    if (suffix === "of Protection")
+        return 2;
+    if (suffix === "of Fury")
+        return 1;
+    return 0;
+};
+/** `ImplAdventurer::unlocked_specials(previous_level, new_level)`. */
+const unlockedSpecials = (previousLevel, newLevel) => {
+    if (previousLevel < SUFFIX_UNLOCK_GREATNESS && newLevel >= PREFIX_UNLOCK_GREATNESS) {
+        return { suffixUnlocked: true, prefixesUnlocked: true };
+    }
+    if (previousLevel < SUFFIX_UNLOCK_GREATNESS && newLevel >= SUFFIX_UNLOCK_GREATNESS) {
+        return { suffixUnlocked: true, prefixesUnlocked: false };
+    }
+    if (previousLevel < PREFIX_UNLOCK_GREATNESS && newLevel >= PREFIX_UNLOCK_GREATNESS) {
+        return { suffixUnlocked: false, prefixesUnlocked: true };
+    }
+    return { suffixUnlocked: false, prefixesUnlocked: false };
+};
+/**
+ * `ImplItem::grant_xp_to_equipped_items` -- item XP plus everything a level-up drags along.
+ *
+ * The naive "just add xp, capped at 400" loop this replaces silently skipped three things that all
+ * live in the packed adventurer, and so all show up as settlement mismatches:
+ *   - `item_specials_salt`, written the FIRST time any item unlocks specials and never again,
+ *   - a bonus stat upgrade point when an item reaches max greatness,
+ *   - the suffix/bag stat boosts (and one-time vitality health) applied at the unlock itself.
+ *
+ * `itemSpecialsRnd` is the roll the salt is seeded from -- `item_specials_seed` on a beast kill,
+ * the explore `rnd3` on an obstacle. Pass `undefined` to keep the old xp-only behaviour.
+ */
+export const grantXpToEquippedItems = (adventurer, xpAmount, adventurerId, itemSpecialsRnd) => {
+    for (const slotKey of EQUIPMENT_SLOTS) {
+        const item = adventurer.equipment[slotKey];
+        if (item.id === 0)
+            continue;
+        const previousLevel = getItemGreatness(item);
+        item.xp = Math.min(MAX_ITEM_XP, item.xp + xpAmount);
+        const newLevel = getItemGreatness(item);
+        if (newLevel <= previousLevel || itemSpecialsRnd === undefined)
+            continue;
+        if (newLevel === ITEM_MAX_GREATNESS) {
+            adventurer.stat_upgrades_available += MAX_GREATNESS_STAT_BONUS;
+        }
+        const { suffixUnlocked, prefixesUnlocked } = unlockedSpecials(previousLevel, newLevel);
+        if (!suffixUnlocked && !prefixesUnlocked)
+            continue;
+        // The salt is per-adventurer and write-once. If it is already set, the specials were fixed
+        // long ago and this level-up only reveals more of them -- nothing new is rolled.
+        const existingSeed = ItemUtils.getItemSpecialsSeed(adventurer.item_specials_salt, adventurerId);
+        if (existingSeed !== 0) {
+            if (suffixUnlocked) {
+                const specials = ItemUtils.getSpecials(item.id, newLevel, existingSeed);
+                applyUnlockedSuffix(adventurer, specials.special1);
+            }
+            continue;
+        }
+        const masked = itemSpecialsRnd & 0x3fff;
+        adventurer.item_specials_salt = masked === 0 ? 1 : masked;
+        if (suffixUnlocked) {
+            const newSeed = ItemUtils.getItemSpecialsSeed(adventurer.item_specials_salt, adventurerId);
+            const specials = ItemUtils.getSpecials(item.id, newLevel, newSeed);
+            applyUnlockedSuffix(adventurer, specials.special1);
+        }
+    }
+};
+const applyUnlockedSuffix = (adventurer, suffix) => {
+    if (!suffix)
+        return;
+    applySuffixBoost(adventurer.stats, suffix);
+    applyBagBoost(adventurer.stats, suffix);
+    const vitality = vitalityItemBoost(suffix);
+    if (vitality !== 0) {
+        increaseHealth(adventurer, vitality * VITALITY_INSTANT_HEALTH_BONUS);
+    }
+};
+const removeBagBoost = (stats, suffix) => {
+    if (suffix === "of Giant") {
+        stats.vitality -= 3;
+    }
+    else if (suffix === "of Titans") {
+        stats.charisma -= 1;
+    }
+    else if (suffix === "of Perfection") {
+        stats.vitality -= 1;
+    }
+    else if (suffix === "of Protection") {
+        stats.vitality -= 2;
+    }
+    else if (suffix === "of Rage") {
+        stats.charisma -= 1;
+    }
+    else if (suffix === "of Fury") {
+        stats.vitality -= 1;
+        stats.charisma -= 1;
+    }
+    else if (suffix === "of the Fox") {
+        stats.charisma -= 1;
+    }
+    else if (suffix === "of the Twins") {
+        stats.charisma -= 3;
+    }
+};
+/**
+ * Equip a single item from bag into the correct equipment slot.
+ * If the slot is occupied, the displaced item moves to the bag.
+ */
+export const equipItem = (adventurer, bag, itemId) => {
+    const salt = adventurer.item_specials_salt;
+    // Find and remove item from bag (preserve XP)
+    const bagIndex = bag.findIndex((i) => i.id === itemId);
+    let item;
+    if (bagIndex >= 0) {
+        item = bag.splice(bagIndex, 1)[0];
+    }
+    else {
+        item = { id: itemId, xp: 0 };
+    }
+    // Determine target slot
+    const slotName = ItemUtils.getItemSlot(itemId);
+    const slotKey = slotName.toLowerCase();
+    const current = adventurer.equipment[slotKey];
+    // Displace current item to bag if it exists
+    if (current && current.id !== 0) {
+        // Remove suffix boost for displaced item (contract: remove_suffix_boost)
+        const displacedSuffix = getItemSuffix(current, salt);
+        if (displacedSuffix) {
+            removeSuffixBoost(adventurer.stats, displacedSuffix);
+        }
+        bag.push({ ...current });
+    }
+    // Equip new item
+    adventurer.equipment[slotKey].id = item.id;
+    adventurer.equipment[slotKey].xp = item.xp;
+    // Apply suffix boost for newly equipped item (contract: apply_suffix_boost)
+    const newSuffix = getItemSuffix(item, salt);
+    if (newSuffix) {
+        applySuffixBoost(adventurer.stats, newSuffix);
+    }
+};
+/**
+ * Drop a single item from equipment or bag.
+ */
+export const dropItem = (adventurer, bag, itemId) => {
+    const salt = adventurer.item_specials_salt;
+    // Check equipment first
+    for (const slotKey of [
+        "weapon",
+        "chest",
+        "head",
+        "waist",
+        "foot",
+        "hand",
+        "neck",
+        "ring",
+    ]) {
+        const item = adventurer.equipment[slotKey];
+        if (item.id === itemId) {
+            // Remove suffix boost for equipped item (contract: remove_suffix_boost)
+            const suffix = getItemSuffix(item, salt);
+            if (suffix) {
+                removeSuffixBoost(adventurer.stats, suffix);
+            }
+            item.id = 0;
+            item.xp = 0;
+            // Clamp health to max (stat boosts may have changed)
+            const maxHp = getMaxHealth(adventurer.stats.vitality);
+            if (adventurer.health > maxHp)
+                adventurer.health = maxHp;
+            return;
+        }
+    }
+    // Check bag
+    const bagIndex = bag.findIndex((i) => i.id === itemId);
+    if (bagIndex >= 0) {
+        const bagItem = bag[bagIndex];
+        // Remove bag boost for bag item (contract: remove_bag_boost)
+        const suffix = getItemSuffix(bagItem, salt);
+        if (suffix) {
+            removeBagBoost(adventurer.stats, suffix);
+        }
+        bag.splice(bagIndex, 1);
+    }
+    // Clamp health
+    const maxHp = getMaxHealth(adventurer.stats.vitality);
+    if (adventurer.health > maxHp)
+        adventurer.health = maxHp;
+};
+// ─── Combat: Starting stats ─────────────────────────────────────
+export const generateStartingStats = (levelSeed) => {
+    // Seeded, this is `ImplStats::generate_starting_stats`: the same twelve points, dealt by
+    // repeated `divmod 6` over the level seed instead of by twelve independent random draws.
+    if (levelSeed !== undefined) {
+        return generateStartingStatsFromSeed(levelSeed);
+    }
+    const stats = {
+        strength: 0,
+        dexterity: 0,
+        vitality: 0,
+        intelligence: 0,
+        wisdom: 0,
+        charisma: 0,
+        luck: 0,
+    };
+    const statKeys = [
+        "strength",
+        "dexterity",
+        "vitality",
+        "intelligence",
+        "wisdom",
+        "charisma",
+    ];
+    for (let i = 0; i < 12; i++) {
+        const idx = Math.floor(Math.random() * 6);
+        stats[statKeys[idx]]++;
+    }
+    return stats;
+};
+//# sourceMappingURL=gameSimulation.js.map