decideAction guide

Rule-based action from serialized table state, Monte Carlo equity (or strength fallback when sim count is 0), pot odds, and call EV.

State shape

See NativePokerState. You may pass PKST Uint8Array from encodePokerState or packPokerState instead of a live object—see Packed poker state.

Field	Required	Notes
players[]	yes	Each player needs holeCards: CardInput (string[] or packed Uint8Array)
communityCards	yes	Board cards (CardInput)
phase	yes	preflop, flop, turn, river, showdown, handcomplete (case variants accepted)
actedThisStreet	yes	One boolean per player
pot, currentBet, blinds, seats	optional	Table geometry

Hero seat: pass heroSeat explicitly, or the engine uses the acting player's seat, or seat 0.

Config

See NativeBotConfig and optional NativeOpponentModel.

normalizeBotConfig fills missing fields and clamps values before you call policy exports.

When monteCarloSimulations is 0, strategy falls back to encoded hand strength instead of simulated equity.

Example

const poker = require('poker-calculations');

const state = {
  players: [
    {
      name: 'Hero',
      holeCards: ['Ah', 'Kh'],
      stack: 200,
      committedThisStreet: 0,
      seat: 0,
    },
    {
      name: 'Villain',
      holeCards: ['Qc', 'Qd'],
      stack: 180,
      committedThisStreet: 10,
      seat: 1,
    },
  ],
  communityCards: ['Qh', 'Jh', '2c'],
  phase: 'flop',
  pot: 30,
  currentBet: 10,
  smallBlind: 1,
  bigBlind: 2,
  buttonSeat: 0,
  actingIndex: 0,
  actedThisStreet: [false, true],
};

const config = {
  monteCarloSimulations: 2000,
  monteCarloVillains: 1,
  rngSeed: 42,
};

const decision = poker.decideAction(state, config, null, 0);
console.log(decision.action, decision.raiseBy);

Non-blocking and cancellation

decideActionAsync runs the same logic on the libuv thread pool. When monteCarloSimulations > 0, pass AsyncOptions to abort in-flight Monte Carlo:

const ac = new AbortController();
const pending = poker.decideActionAsync(state, config, null, 0, { signal: ac.signal });
// ac.abort(); // Promise rejects with AbortError
const decision = await pending;

Diagnostics and EV breakdown

Export	Use when
decideActionWithDiagnostics	You need the chosen action plus legal actions, EV breakdown, and a reason string in one call. Returns DecisionDiagnosticResult.
actionEvBreakdown	You want fold/check/call/raise EV and equity without committing to a single action. Returns ActionEvBreakdownResult.
explainDecisionFactors	You need ranked human-readable factors behind a policy choice. Returns DecisionFactor rows.

Validation and legal actions

Export	Use when
validatePokerState	Pre-flight a snapshot before simulation or policy runs. Returns PokerStateValidationResult.
legalActionSummary	You need raise bounds and which actions are legal. Returns LegalActionSummaryResult.
candidateActionSet	Build a discrete action menu with raise sizes. Returns CandidateAction rows.
actionMaskFromState	Encode legality as a compact bitmask for ML or fast filters.

Batch policy and features

Export	Use when
runBotPolicyBatch	Evaluate many table snapshots in one native crossing.
stateToFeatureVector	Feed a fixed-length numeric vector into custom models or clustering.

PKST binary snapshots

encodePokerState and decodePokerState round-trip NativePokerState through PKST bytes. Pure-JS helpers also ship on poker-calculations/encode.

API reference

Full Import / When / How for every export in the Strategy category.