@zigrivers/scaffold 3.4.1 → 3.5.0

package/content/knowledge/game/game-domain-patterns.md

@@ -0,0 +1,297 @@
+---
+name: game-domain-patterns
+description: ECS vs DDD as mutually exclusive per-layer patterns, game state machines, and domain modeling for games
+topics: [game-dev, ecs, ddd, state-machines, domain-modeling]
+---
+
+Game software architecture differs fundamentally from business software architecture because games have two distinct layers with incompatible optimization goals: the simulation layer (real-time, data-oriented, performance-critical) and the meta-game layer (behavior-rich, event-driven, correctness-critical). Choosing the right domain modeling approach for each layer is essential. ECS and DDD are mutually exclusive paradigms — applying the wrong one to a layer creates friction that compounds throughout development.
+
+## Summary
+
+### Two Layers, Two Paradigms
+
+Games are split into two architectural layers that demand different modeling approaches:
+
+**Simulation Layer** (the "game" part):
+- Processes thousands of entities per frame at 16ms or 33ms budgets
+- Data access patterns dominate: iterate over all entities with Health, iterate over all entities with Position+Velocity
+- Behavior is uniform: every entity with the same components processes identically
+- Optimization is existential: a 1ms regression in a core system is a shipped bug
+- **Use ECS (Entity-Component-System)** — data-oriented, cache-friendly, composable
+
+**Meta-Game Layer** (the "around the game" part):
+- Manages player profiles, inventories, progression, matchmaking, economy, social features
+- Rich business rules: "a player can equip an item only if their level meets the requirement and the item is not already equipped by another character in the same party"
+- Correctness matters more than raw throughput
+- Domain language is complex and stakeholder-facing
+- **Use DDD (Domain-Driven Design)** — behavior-oriented, encapsulated, rule-rich
+
+**Do NOT mix these within a layer.** ECS in the meta-game layer creates anemic data bags with scattered business logic. DDD in the simulation layer creates cache-hostile object graphs that kill frame rates. Each paradigm is correct for its layer and wrong for the other.
+
+### Game State Machines
+
+State machines are the universal pattern in game development. They appear at every scale:
+
+- **Character states**: Idle, Walking, Running, Jumping, Falling, Attacking, Stunned, Dead
+- **Game states**: MainMenu, Loading, Playing, Paused, GameOver, Victory
+- **AI states**: Patrol, Alert, Chase, Attack, Flee, Search
+- **Animation states**: Blend trees driven by state machine transitions
+- **UI states**: Screen stacks, modal dialogs, transition animations
+
+State machines enforce that an entity can only be in one state at a time and that transitions between states are explicit and guarded.
+
+### Game-Specific Ubiquitous Language
+
+Games have domain-specific vocabulary that must be consistent across code, design docs, and team communication:
+
+- **Entity**: A thing that exists in the game world (character, projectile, pickup, trigger zone)
+- **Component**: A data bucket attached to an entity (Health, Transform, Renderable, Collider)
+- **System**: A function that processes all entities with a specific component signature
+- **Tick/Frame**: One iteration of the game loop
+- **Spawn**: Creating a new entity at runtime
+- **Despawn/Destroy**: Removing an entity from the world
+- **Pool**: A pre-allocated set of reusable entities to avoid runtime allocation
+- **Buff/Debuff**: A temporary modifier to an entity's stats
+- **Cooldown**: A timer preventing repeated use of an ability
+- **Aggro/Threat**: A value determining which target an AI prioritizes
+
+## Deep Guidance
+
+### ECS for the Simulation Layer
+
+Entity-Component-System is a data-oriented architecture where:
+- **Entities** are lightweight identifiers (typically just an integer ID)
+- **Components** are plain data structs with no behavior (Position, Velocity, Health, DamageOnContact)
+- **Systems** are functions that query for entities matching a component signature and process them
+
+The key insight is that behavior lives in systems, not in entities or components. An entity does not "know" how to move — the MovementSystem queries all entities with Position+Velocity and updates their positions.
+
+```typescript
+// ECS Example: Components are pure data, Systems are pure logic
+
+// --- Components (data only, no methods) ---
+
+interface Position {
+  x: number;
+  y: number;
+}
+
+interface Velocity {
+  dx: number;
+  dy: number;
+}
+
+interface Health {
+  current: number;
+  max: number;
+}
+
+interface DamageOnContact {
+  amount: number;
+  destroySelfAfterHit: boolean;
+}
+
+interface Collider {
+  radius: number;
+  layer: "player" | "enemy" | "projectile" | "pickup";
+}
+
+// --- Systems (logic only, no state) ---
+
+function movementSystem(
+  world: World,
+  deltaTime: number
+): void {
+  // Query all entities that have BOTH Position and Velocity
+  for (const [entity, pos, vel] of world.query<[Position, Velocity]>()) {
+    pos.x += vel.dx * deltaTime;
+    pos.y += vel.dy * deltaTime;
+  }
+}
+
+function collisionSystem(world: World): void {
+  // Query all entities with Position and Collider
+  const collidables = world.query<[Position, Collider]>();
+
+  for (const [entityA, posA, colA] of collidables) {
+    for (const [entityB, posB, colB] of collidables) {
+      if (entityA === entityB) continue;
+      // Layer-based collision filtering
+      if (!shouldCollide(colA.layer, colB.layer)) continue;
+
+      const dist = distance(posA, posB);
+      if (dist < colA.radius + colB.radius) {
+        world.emit("collision", { entityA, entityB });
+      }
+    }
+  }
+}
+
+function damageOnContactSystem(world: World): void {
+  // React to collision events
+  for (const { entityA, entityB } of world.events("collision")) {
+    const damageA = world.get<DamageOnContact>(entityA);
+    const healthB = world.get<Health>(entityB);
+
+    if (damageA && healthB) {
+      healthB.current -= damageA.amount;
+      if (damageA.destroySelfAfterHit) {
+        world.despawn(entityA);
+      }
+    }
+  }
+}
+
+// --- Entity creation (composition, not inheritance) ---
+
+function spawnPlayer(world: World, x: number, y: number): Entity {
+  return world.spawn(
+    { x, y } as Position,
+    { dx: 0, dy: 0 } as Velocity,
+    { current: 100, max: 100 } as Health,
+    { radius: 16, layer: "player" } as Collider
+  );
+}
+
+function spawnProjectile(
+  world: World,
+  x: number, y: number,
+  dx: number, dy: number
+): Entity {
+  return world.spawn(
+    { x, y } as Position,
+    { dx, dy } as Velocity,
+    { amount: 25, destroySelfAfterHit: true } as DamageOnContact,
+    { radius: 4, layer: "projectile" } as Collider
+  );
+}
+```
+
+**Why ECS works for simulation:**
+- **Cache efficiency**: Components of the same type are stored contiguously in memory; iterating over all Position components is a linear memory scan, not pointer-chasing through object graphs
+- **Composition over inheritance**: An entity's behavior emerges from its component combination; no deep inheritance hierarchies or diamond problems
+- **Parallelism**: Systems that touch non-overlapping component sets can run in parallel
+- **Flexibility**: Adding new behavior means adding a new component and system, not modifying existing classes
+
+**ECS pitfalls:**
+- Debugging is harder — an entity is just an ID; you need tooling to inspect its component set
+- Relational queries (find all enemies within range of a specific player) require spatial indexing, not just component queries
+- One-off behaviors feel awkward — if only one entity has a unique mechanic, creating a component and system for one entity feels like overkill (but do it anyway for consistency)
+
+### DDD for the Meta-Game Layer
+
+The meta-game layer manages persistent state that exists outside the real-time simulation: player accounts, inventories, progression trees, matchmaking, economies, social graphs. These domains are rich in business rules and benefit from DDD's emphasis on encapsulation and domain language.
+
+**Inventory example using DDD:**
+- An Inventory is an Aggregate Root that enforces capacity limits, stacking rules, and equip requirements
+- An Item is a Value Object — two items with the same properties are interchangeable
+- Equipping an item is a domain operation on the Inventory aggregate, not a flag flip on the item
+- Domain events (ItemEquipped, ItemDropped, InventoryFull) communicate changes to other systems
+
+**Why DDD works for meta-game:**
+- Business rules are encapsulated in domain objects, not scattered across controllers and services
+- Ubiquitous language keeps code readable by designers ("player.inventory.equip(item)" reads like the design doc)
+- Aggregates enforce transactional boundaries — an inventory operation either fully succeeds or fully rolls back
+- Domain events enable loose coupling between meta-game subsystems
+
+**Why DDD fails for simulation:**
+- Object graphs with references and encapsulation create cache-hostile memory layouts
+- Method dispatch (virtual calls through interfaces) prevents compiler optimization and branch prediction
+- Encapsulation means systems cannot batch-process similar data across entities
+- The overhead of aggregate boundaries and domain events is unacceptable at 60fps for thousands of entities
+
+### State Machine Patterns
+
+**Finite State Machine (FSM):**
+
+The simplest state machine. Each state has a set of allowed transitions. An entity is in exactly one state at a time.
+
+Use for: Character controllers, game flow, simple AI, UI screens.
+
+Limitations: State explosion when states need to combine (walking+aiming, crouching+reloading). Transitions become a combinatorial matrix.
+
+**Hierarchical State Machine (HSM):**
+
+States can contain sub-states. A "Combat" super-state might contain "MeleeAttack," "RangedAttack," and "Block" sub-states. The super-state handles common transitions (e.g., any combat sub-state can transition to "Stunned"), reducing transition duplication.
+
+Use for: Complex character controllers, sophisticated AI, multi-phase boss fights.
+
+**Pushdown Automaton (PDA):**
+
+A stack of states. "Pushing" a state pauses the current one; "popping" resumes it. The pause menu is a classic example: push Paused onto the Playing state, pop it to resume.
+
+Use for: Menu stacks, interrupt-based gameplay (cutscene interrupts exploration, then resumes), nested game states.
+
+**State machine implementation rules:**
+- States should be classes or objects, not stringly-typed enums (allows behavior attachment)
+- Every state must define: `onEnter()`, `onUpdate(dt)`, `onExit()`
+- Transitions are guarded: a transition from Idle to Attack requires `hasAmmo && !isCooldown`
+- State machines should be data-driven when possible (load states and transitions from config)
+- Log state transitions during development — most gameplay bugs are state transition bugs
+
+### Resource and Inventory Patterns
+
+**Resource types in games:**
+- **Currencies**: Discrete countable values (gold, gems, energy). Store as integers to avoid floating-point drift.
+- **Items**: Discrete objects with properties (weapons, armor, consumables). May be stackable or unique.
+- **Meters**: Continuous values that fill/drain (health, mana, stamina, fuel). Usually floats with clamping.
+- **Timers**: Resources that regenerate over real or game time (energy, daily rewards, cooldowns).
+
+**Inventory patterns:**
+- **Slot-based**: Fixed number of slots, each holds one item (or stack). UI-friendly, capacity is explicit.
+- **Weight-based**: Items have weight, inventory has a weight limit. More flexible, harder to visualize.
+- **Hybrid**: Slot-based with weight limits (e.g., Diablo: grid-based slots, each item occupies different grid sizes).
+
+**Economy sink/faucet balance:**
+- Faucets (sources of currency): quest rewards, enemy drops, crafting, trading, daily login
+- Sinks (drains of currency): item purchases, upgrades, repair costs, taxes, consumables
+- If faucets exceed sinks, inflation occurs and currency becomes worthless
+- Track currency generation and consumption rates per player-hour and tune aggressively
+
+### Player Progression Models
+
+**Experience/Level systems:**
+- XP curve formula matters: linear (constant effort per level), polynomial (increasing effort), exponential (dramatically increasing effort)
+- Common formula: `xp_for_level(n) = base * n^exponent` where exponent of 1.5-2.0 is typical
+- Level caps should match content: if the game has 20 hours of content, the level cap should be reachable in roughly 20 hours
+
+**Skill trees / Talent systems:**
+- Flat trees (many small choices) vs deep trees (few branching paths with big impact)
+- Respec cost: free respec encourages experimentation, costly respec encourages commitment
+- Trap choices (options that are never worth taking) are a design failure — every node should be viable in some build
+
+**Unlock progression:**
+- Gate unlocks behind milestones, not just time played
+- Sequence unlocks to gradually increase complexity (do not give the player every mechanic in the tutorial)
+- Prestige mechanics extend endgame by trading progress for permanent bonuses
+
+### Combat System Modeling
+
+**Damage calculation patterns:**
+- **Subtractive armor**: `damage = attack - defense` (simple, intuitive, but defense can fully negate)
+- **Multiplicative armor**: `damage = attack * (1 - defense_percent)` (defense never fully negates)
+- **Hybrid**: `damage = (attack - flat_reduction) * (1 - percent_reduction)` (most RPGs use this)
+
+**Attack resolution flow:**
+1. Attacker generates base damage (weapon + stats)
+2. Apply attacker modifiers (buffs, critical hits, elemental bonuses)
+3. Apply defender modifiers (armor, resistances, shields)
+4. Apply environmental modifiers (cover, elevation, weather)
+5. Resolve final damage (clamp to non-negative, apply to health)
+6. Trigger feedback (hit animation, damage numbers, sound effect, screen shake)
+
+### Spawning and Object Pooling
+
+**Object pooling** pre-allocates a fixed number of entities and recycles them instead of creating/destroying at runtime. This avoids garbage collection spikes and allocation overhead.
+
+**Pool sizing rules:**
+- Size the pool to the maximum concurrent count needed plus a 20% buffer
+- If the pool is exhausted, either grow it (with a warning log) or recycle the oldest active instance
+- Pre-warm pools during loading screens, not during gameplay
+- Profile actual usage to right-size pools — over-pooling wastes memory, under-pooling causes runtime allocation
+
+**Spawn patterns:**
+- **Wave spawning**: Groups of enemies spawn at intervals; common in action games and tower defense
+- **Proximity spawning**: Entities spawn when the player enters a trigger zone; keeps entity counts manageable in open worlds
+- **Procedural spawning**: Rules-based placement (spawn enemy X at least Y meters from player, at least Z meters from other enemies); used in roguelikes and open-world games
+- **Director-based spawning**: An AI "director" monitors player performance and adjusts spawn rates, types, and placement to maintain tension (Left 4 Dead's AI Director is the canonical example)

package/content/knowledge/game/game-economy-design.md

@@ -0,0 +1,355 @@
+---
+name: game-economy-design
+description: Virtual currency design, faucet/sink balancing, loot table probability, monetization models, and ethical monetization patterns
+topics: [game-dev, economy, monetization, loot-tables, balance, f2p]
+---
+
+Game economy design governs how players earn, spend, and value in-game resources and how the studio monetizes those systems. A well-designed economy creates meaningful choices — players decide what to spend resources on, creating engagement. A poorly designed economy either trivializes resources (inflation makes everything cheap) or frustrates players (everything feels unattainable). Monetization layers add a second dimension: real money must integrate with virtual economies without destroying the earned-value perception that makes the economy work.
+
+## Summary
+
+### Virtual Currency Design
+
+Most games with economies use at least two currency tiers:
+
+- **Soft currency**: Earned freely through gameplay (gold, coins, credits). Abundant faucets, many sinks. Players should never feel completely starved of soft currency.
+- **Hard currency** (premium): Purchased with real money or earned in small quantities through milestones. Fewer faucets, high-value sinks (cosmetics, time-skips, premium items). This is the monetization lever.
+
+Separating currencies prevents direct dollar-to-gameplay equivalence, which regulators and players scrutinize. Never allow hard currency to purchase competitive advantages in PvP contexts — this crosses into pay-to-win territory.
+
+### Faucet/Sink Balancing
+
+Every economy has faucets (sources of currency entering the system) and sinks (drains removing currency). When faucets exceed sinks, inflation occurs and currency becomes worthless. When sinks exceed faucets, deflation makes the game feel punishing. The goal is a steady state where players always have meaningful spending decisions.
+
+Track currency generation and consumption per player-hour. A healthy economy has a target "time to purchase" for key items: if the best sword costs 10,000 gold and players earn 500 gold/hour, the time-to-purchase is 20 hours. Adjust faucets and sinks to hit target purchase timelines.
+
+### Loot Table Probability
+
+Loot tables define drop rates for items from enemies, chests, or gacha pulls. Transparency matters: China requires probability disclosure by law, and player trust erodes quickly when drop rates feel manipulated. Use weighted random selection with published rates for any monetized loot mechanic.
+
+### Monetization Models
+
+- **Premium (buy-to-play)**: One-time purchase, all content included. DLC/expansions sold separately. No predatory pressure. Revenue is front-loaded.
+- **Free-to-play (F2P)**: Free entry, monetized through cosmetics, convenience, or content gates. Revenue is ongoing but depends on conversion rates (typically 2-5% of players spend money).
+- **Hybrid**: Premium purchase with optional cosmetic microtransactions. Increasingly common (e.g., Helldivers 2, Diablo IV).
+
+### Legal Landscape
+
+- **China**: Probability disclosure is mandatory for any randomized paid mechanic. Published rates must match actual implementation.
+- **Belgium/Netherlands**: Post-2022 FIFA loot box ruling nuanced the landscape. Belgium's Gaming Commission targeted specific implementations (FIFA Ultimate Team) rather than issuing a blanket loot box ban. The Netherlands situation shifted after court rulings; enforcement depends on whether the mechanic meets gambling criteria (prize, chance, stake). Neither country has a simple "loot boxes are banned" law — the legal test is whether the specific implementation constitutes gambling under existing frameworks.
+- **COPPA (US)**: Games directed at children under 13 face strict data collection and monetization rules. Purchases require verifiable parental consent. Aggressive monetization targeting children invites FTC scrutiny regardless of COPPA technical compliance.
+
+## Deep Guidance
+
+### Faucet/Sink Math
+
+A game economy is a system of flows. Model it as a spreadsheet before implementing it in code.
+
+```typescript
+// Economy simulation framework
+// Model faucets and sinks as rates per player-hour
+
+interface EconomyConfig {
+  currencies: CurrencyConfig[];
+  faucets: Faucet[];
+  sinks: Sink[];
+}
+
+interface CurrencyConfig {
+  id: string;
+  name: string;
+  startingBalance: number;
+  maxBalance: number;        // Soft cap — excess goes to overflow or is lost
+  decimalPlaces: 0 | 2;     // 0 for integer currencies, 2 for float
+}
+
+interface Faucet {
+  id: string;
+  currencyId: string;
+  amountPerEvent: number;
+  eventsPerHour: number;     // Average occurrences per player-hour
+  variance: number;          // 0-1, randomness factor
+  description: string;
+}
+
+interface Sink {
+  id: string;
+  currencyId: string;
+  cost: number;
+  purchasesPerHour: number;  // Average purchases per player-hour
+  required: boolean;         // Is this sink mandatory (repair) or optional (cosmetic)?
+  description: string;
+}
+
+// --- Simulation ---
+
+function simulateEconomy(
+  config: EconomyConfig,
+  hoursToSimulate: number,
+  playerCount: number
+): SimulationResult {
+  const results: SimulationResult = {
+    hourlySnapshots: [],
+    inflationRate: 0,
+    medianBalance: 0,
+    timeToPurchase: new Map(),
+  };
+
+  for (const currency of config.currencies) {
+    let totalGenerated = 0;
+    let totalSpent = 0;
+
+    for (const faucet of config.faucets.filter(f => f.currencyId === currency.id)) {
+      const hourlyGeneration = faucet.amountPerEvent * faucet.eventsPerHour;
+      totalGenerated += hourlyGeneration * hoursToSimulate;
+    }
+
+    for (const sink of config.sinks.filter(s => s.currencyId === currency.id)) {
+      const hourlySpend = sink.cost * sink.purchasesPerHour;
+      totalSpent += hourlySpend * hoursToSimulate;
+    }
+
+    const netFlow = totalGenerated - totalSpent;
+    const inflationRate = netFlow / Math.max(totalGenerated, 1);
+
+    // HEALTHY: inflation rate between -0.1 and 0.1 (10% either direction)
+    // WARNING: inflation rate between 0.1 and 0.3 or -0.1 and -0.3
+    // CRITICAL: inflation rate beyond +-0.3
+    results.inflationRate = inflationRate;
+    results.medianBalance = currency.startingBalance + netFlow / playerCount;
+
+    // Calculate time-to-purchase for each sink
+    for (const sink of config.sinks.filter(s => s.currencyId === currency.id)) {
+      const hourlyNet = (totalGenerated - totalSpent) / hoursToSimulate;
+      const hourlyEarnings = totalGenerated / hoursToSimulate;
+      const ttp = sink.cost / hourlyEarnings;
+      results.timeToPurchase.set(sink.id, ttp);
+    }
+  }
+
+  return results;
+}
+
+interface SimulationResult {
+  hourlySnapshots: number[];
+  inflationRate: number;
+  medianBalance: number;
+  timeToPurchase: Map<string, number>;
+}
+
+// --- Example: RPG economy ---
+
+const rpgEconomy: EconomyConfig = {
+  currencies: [
+    { id: "gold", name: "Gold", startingBalance: 100, maxBalance: 999999, decimalPlaces: 0 },
+  ],
+  faucets: [
+    { id: "quest-rewards", currencyId: "gold", amountPerEvent: 200, eventsPerHour: 1.5, variance: 0.2, description: "Quest completion rewards" },
+    { id: "enemy-drops", currencyId: "gold", amountPerEvent: 15, eventsPerHour: 30, variance: 0.5, description: "Gold dropped by defeated enemies" },
+    { id: "item-sales", currencyId: "gold", amountPerEvent: 50, eventsPerHour: 3, variance: 0.3, description: "Selling loot to vendors" },
+    { id: "daily-login", currencyId: "gold", amountPerEvent: 100, eventsPerHour: 0.5, variance: 0, description: "Daily login bonus (prorated per hour assuming 2hr sessions)" },
+  ],
+  sinks: [
+    { id: "equipment", currencyId: "gold", cost: 500, purchasesPerHour: 0.2, required: false, description: "Buying weapons and armor" },
+    { id: "consumables", currencyId: "gold", cost: 30, purchasesPerHour: 5, required: true, description: "Health potions, ammo, etc." },
+    { id: "repairs", currencyId: "gold", cost: 75, purchasesPerHour: 0.5, required: true, description: "Equipment repair costs" },
+    { id: "upgrades", currencyId: "gold", cost: 1000, purchasesPerHour: 0.05, required: false, description: "Upgrade slots on equipment" },
+    { id: "fast-travel", currencyId: "gold", cost: 25, purchasesPerHour: 1, required: false, description: "Fast travel between locations" },
+  ],
+};
+
+// Hourly faucet total: (200*1.5) + (15*30) + (50*3) + (100*0.5) = 300 + 450 + 150 + 50 = 950 gold/hr
+// Hourly sink total: (500*0.2) + (30*5) + (75*0.5) + (1000*0.05) + (25*1) = 100 + 150 + 37.5 + 50 + 25 = 362.5 gold/hr
+// Net flow: +587.5 gold/hr — INFLATIONARY, needs stronger sinks or weaker faucets
+```
+
+### Loot Table Design
+
+Loot tables use weighted random selection. Each item has a weight, and the probability of dropping is its weight divided by the total weight of all items in the table.
+
+```typescript
+// Loot table with weighted random selection and pity system
+
+interface LootTableEntry {
+  itemId: string;
+  weight: number;          // Relative weight (NOT percentage)
+  rarity: "common" | "uncommon" | "rare" | "epic" | "legendary";
+  maxPerDrop: number;      // Maximum times this item can appear in one drop
+}
+
+interface LootTable {
+  id: string;
+  entries: LootTableEntry[];
+  guaranteedDrops: number; // Minimum items per roll
+  bonusDropChance: number; // Probability of additional items (0-1)
+  maxDrops: number;        // Maximum total items per roll
+  pityCounter?: PityConfig;
+}
+
+interface PityConfig {
+  // After N rolls without a rare+ item, guarantee one
+  rareThreshold: number;   // Rolls without rare → guarantee rare
+  epicThreshold: number;   // Rolls without epic → guarantee epic
+  legendaryThreshold: number;
+}
+
+function rollLootTable(table: LootTable, playerPity: PityState): LootDrop[] {
+  const drops: LootDrop[] = [];
+  const totalWeight = table.entries.reduce((sum, e) => sum + e.weight, 0);
+
+  // Check pity system first
+  if (table.pityCounter && playerPity.rollsSinceLastLegendary >= table.pityCounter.legendaryThreshold) {
+    const legendaries = table.entries.filter(e => e.rarity === "legendary");
+    if (legendaries.length > 0) {
+      drops.push(selectWeightedFrom(legendaries));
+      playerPity.rollsSinceLastLegendary = 0;
+    }
+  }
+
+  // Guaranteed drops
+  for (let i = drops.length; i < table.guaranteedDrops; i++) {
+    drops.push(selectWeighted(table.entries, totalWeight));
+  }
+
+  // Bonus drops
+  while (drops.length < table.maxDrops && Math.random() < table.bonusDropChance) {
+    drops.push(selectWeighted(table.entries, totalWeight));
+  }
+
+  // Update pity counters
+  const hasRare = drops.some(d => ["rare", "epic", "legendary"].includes(d.rarity));
+  const hasLegendary = drops.some(d => d.rarity === "legendary");
+  playerPity.rollsSinceLastRare = hasRare ? 0 : playerPity.rollsSinceLastRare + 1;
+  playerPity.rollsSinceLastLegendary = hasLegendary ? 0 : playerPity.rollsSinceLastLegendary + 1;
+
+  return drops;
+}
+
+function selectWeighted(entries: LootTableEntry[], totalWeight: number): LootDrop {
+  let roll = Math.random() * totalWeight;
+  for (const entry of entries) {
+    roll -= entry.weight;
+    if (roll <= 0) {
+      return { itemId: entry.itemId, rarity: entry.rarity };
+    }
+  }
+  // Fallback (should never reach due to floating point)
+  const last = entries[entries.length - 1];
+  return { itemId: last.itemId, rarity: last.rarity };
+}
+
+function selectWeightedFrom(subset: LootTableEntry[]): LootDrop {
+  const total = subset.reduce((s, e) => s + e.weight, 0);
+  return selectWeighted(subset, total);
+}
+
+interface PityState {
+  rollsSinceLastRare: number;
+  rollsSinceLastLegendary: number;
+}
+
+interface LootDrop {
+  itemId: string;
+  rarity: string;
+}
+
+// Published probability disclosure (required in China, good practice everywhere)
+// Given a table with weights: common=700, uncommon=200, rare=70, epic=25, legendary=5
+// Total weight: 1000
+// Probabilities: common=70%, uncommon=20%, rare=7%, epic=2.5%, legendary=0.5%
+// With pity at 200 rolls: effective legendary rate is higher than 0.5%
+```
+
+### Battle Pass Structure
+
+Battle passes are a retention mechanic: players purchase a pass and unlock rewards by playing over a defined season. The design must balance accessibility (casual players can complete it) with aspiration (dedicated players feel rewarded).
+
+**Key design parameters:**
+- **Season length**: 8-12 weeks is standard. Shorter seasons feel rushed; longer seasons lose urgency.
+- **Total XP required**: Calculate backwards from target playtime. If the goal is 1 hour/day for 80% of the season, total XP = (daily XP rate) * (season days * 0.8).
+- **Free vs premium tiers**: Free track gets meaningful rewards (not just scraps). Premium track gets exclusive cosmetics. Never gate gameplay-affecting items behind premium.
+- **Catch-up mechanics**: Players who start late or miss days need a path to completion. Weekly challenges that award large XP chunks, bonus XP weekends, or purchasable tier skips (with limits).
+
+### Monetization Models in Depth
+
+**Premium (buy-to-play):**
+
+Revenue is front-loaded at launch. Post-launch revenue comes from DLC and expansions. No daily engagement pressure on the economy. The economy can be generous because there is no monetization tension. This is the safest model for player trust but the hardest to sustain financially for live-service games.
+
+**Free-to-play (F2P):**
+
+Revenue depends on a small percentage of paying players. The economy must create desire without creating frustration. Common F2P revenue sources:
+- Cosmetics (skins, emotes, effects) — safest; no gameplay impact
+- Convenience (XP boosts, fast-travel, inventory expansion) — moderate; time-vs-money tradeoff
+- Energy systems (limited plays per day, replenished with premium currency) — aggressive; feels exploitative
+- Gacha/loot boxes (randomized rewards) — most profitable, most controversial, most regulated
+
+**Conversion funnel:**
+- 100% of players install for free
+- ~30% reach meaningful engagement (play more than 1 hour)
+- ~5% make any purchase ever
+- ~1% become recurring spenders
+- ~0.1% are "whales" (high spenders)
+
+Designing for whales is ethically fraught. The industry is moving toward broader, lower-cost monetization that converts more of the 5% rather than extracting more from the 0.1%.
+
+### Predatory Pattern Avoidance
+
+These patterns damage player trust and invite regulatory action:
+
+- **Artificial scarcity timers**: "Buy now or it's gone forever!" creates FOMO-driven purchasing. If used, ensure items genuinely return in future rotations.
+- **Obfuscated pricing**: Converting real money to gems to coins to items makes it hard for players to understand what they are spending. Keep the money-to-value chain as short as possible.
+- **Pay-to-win**: Any monetization that grants competitive advantage in PvP destroys game integrity and player trust. Even perceived pay-to-win (stat boosts, faster progression in competitive contexts) is toxic.
+- **Undisclosed odds manipulation**: Adjusting loot table probabilities based on player spending patterns (giving better drops to new spenders to "hook" them) is deceptive and potentially illegal.
+- **Dark patterns in purchase UI**: Making the "buy" button prominent and the "earn through gameplay" option hidden, using confusing currency bundles (1100 gems when items cost 1000, forcing leftover currency), or auto-selecting the most expensive option.
+
+### Ethical Monetization Checklist
+
+```yaml
+ethical_monetization_checklist:
+  transparency:
+    - All purchasable items have clear real-money cost visible
+    - Loot box / gacha probabilities are published and accurate
+    - Currency conversion rates are simple and visible
+    - No hidden fees, auto-renewals without clear disclosure
+
+  fairness:
+    - No competitive advantage from spending money (PvP contexts)
+    - Free players can access all gameplay content (F2P model)
+    - Battle pass is completable with reasonable playtime
+    - No artificial throttling to pressure purchases
+
+  player_respect:
+    - Purchase confirmations prevent accidental spending
+    - Refund policy is clear and accessible
+    - No targeting of spending prompts based on loss/frustration
+    - Children and minors have spending protections
+    - No manipulative urgency ("limited time!" when it returns regularly)
+
+  legal_compliance:
+    - China: probability disclosure for all randomized paid mechanics
+    - Belgium/Netherlands: legal review of loot box implementation
+    - COPPA: parental consent for under-13 purchases
+    - Platform TOS: compliance with each platform's monetization rules
+    - GDPR: spending data handled per data protection regulations
+
+  economy_health:
+    - Inflation/deflation tracked with automated monitoring
+    - Economy simulation run before every balance change
+    - New faucets/sinks analyzed for impact before deployment
+    - Player wealth distribution monitored (Gini coefficient)
+    - Exploit detection for currency duplication or manipulation
+```
+
+### Economy Monitoring in Production
+
+Once live, an economy requires ongoing monitoring. Key metrics:
+
+- **Currency velocity**: How fast currency moves through the system (earned and spent per player-hour)
+- **Median and mean balance**: Median is more informative than mean (whales skew the mean)
+- **Gini coefficient**: Measures wealth inequality among players (0 = perfect equality, 1 = one player has everything). A healthy game economy typically targets 0.3-0.5.
+- **Time-to-purchase drift**: If the time to buy a key item increases over time, the economy is deflating. If it decreases, it is inflating.
+- **Sink utilization**: What percentage of players use each sink? Underused sinks need to be made more attractive or replaced.
+- **Exploit detection**: Monitor for outlier currency gains (players earning 10x the average may have found a dupe exploit or farming bot)
+
+Run economy simulations before every balance patch. A change that looks small ("increase quest rewards by 20%") can compound dramatically when millions of players execute it daily.