miaoda-game-draft-pool-core

Use this engine-independent package for finite auto-battler shops, card drafts, rotating markets, recruit boards, and limited prize pools. Unlike a loot table, it owns finite inventory and the lifecycle available -> reserved -> committed, with release and reclaim paths.

Install

pnpm add miaoda-game-draft-pool-core

Create, buy, and release offers

import { DraftPool } from 'miaoda-game-draft-pool-core';

const pool = new DraftPool([
  { id: 'guard', tier: 'one', count: 20, value: { unitId: 'guard', cost: 1 } },
  { id: 'mage', tier: 'two', count: 12, value: { unitId: 'mage', cost: 2 } },
], { seed: 2026 });

const offer = pool.createOffer({
  id: 'player-1-shop', ownerId: 'player-1', slots: 5,
  tierWeights: [{ tier: 'one', weight: 75 }, { tier: 'two', weight: 25 }],
});

if (offer.ok) {
  const bought = pool.commitSlot(offer.offer.id, 0);
  pool.releaseOffer(offer.offer.id); // returns unbought reserved copies
  if (bought.ok) pool.reclaim([{ entryId: bought.entryId, count: 1 }]);
}

Offer creation and refresh are atomic: a shortage consumes neither stock nor RNG, and a failed refresh keeps the old offer. Selection chooses a tier by its weights, then copies proportionally within the non-empty tier. available + reserved + committed always equals the initial catalog count.

Probabilities and ownership

Use probabilities(tierWeights) for exact next-slot odds instead of duplicating selection math. ownerId is metadata, not authorization. Full offers include other owners' reservations and future RNG position, so keep snapshots and pool state on a trusted host; do not send them directly to a player who should not see hidden inventory.

Saving

snapshot contains catalog compatibility data, active offers, committed state, and RNG position. Restore with the same catalog ordering and counts. The catalog signature detects incompatible rules but is not authentication or anti-cheat protection. Persist current RNG state when a resumed shop must continue rather than restart from its seed.

Combine pool changes with wallet and roster changes inside an authoritative transaction, for example through miaoda-game-command-core. This package does not own currency, timers, inventory, or UI.

Public API

DraftPool, DraftRng, offer/slot lifecycle methods, probabilities, snapshot types, DraftEntry, TierWeight, and result/failure types are exported.