PokerBetting

The money and the turns of a poker hand — chips, pot, antes, and the betting-round state machine, with NPCs stepping through injected strategy callbacks.

What it does

PokerBettingSystem runs a hand. On poker.dealRequest it seats every player with a fresh stack, pulls the ante from each into the pot, opens a betting round, and steps the leading NPCs until the first human is up. NPC seats decide through a strategy callback you supply; a human seat pauses the round and waits for input.

A human's choice arrives one of two ways: poker.actionSubmitted (a HUD button, { type }) or poker.turnAction (a raw action for the active seat, { playerId?, action }). Either way the director runs the action's chip math — check / call / bet / raise / all-in / fold — marks the seat folded when needed, awards the whole pot the instant only one seat remains, and steps the trailing NPCs.

After any chip movement it broadcasts poker.chips (every stack plus the pot). It also emits poker.currentTurn whenever the live seat changes, poker.actionRequired with the menu offered to a waiting human, poker.actionTaken once per seat that acts, and poker.handOver when a hand ends on the last fold.

The chip math (applyAction, awardPot) and the turn machine (stepBettingRound, submitHumanAction) are exported helpers you can call directly; the System is the EventBus wiring around them.

Use it in a scene

bjs download scene PokerBetting

{
  "Table": {
    "components": {
      "PokerBetting": {
        "playerIds": ["player", "npc0", "npc1"],
        "humanPlayerIds": ["player"],
        "startingStack": 500,
        "ante": 5,
        "minBet": 10
      }
    }
  }
}

Start a hand by emitting poker.dealRequest. Assign NPC strategies before the deal with world.getSystem(PokerBettingSystem)?.setStrategies(map) or by handling poker.strategies in your own glue.

Props

Events

The emitted poker.actionTaken is a different name from the poker.turnAction input on purpose — sharing one name would make the System re-hear its own emissions on the bus.

Strategies

An NPC seat acts through an NpcStrategy callback: (playerId, availableActions, context?) => ActionType. The component owns the ActionType union, the standardActions menu, and the NpcStrategy type, but never imports a concrete AI — pass strategies in. With no strategies assigned, every NPC plays randomStrategy (uniform pick from the offered actions). A strategy may write a StrategyReasoning onto the optional context for a HUD to read back.

Dependencies

None. The director carries no rendering and no sibling components; it runs entirely over the EventBus. The example scene adds a camera, a light, and a felt box only so the hand has something to sit on.

Notes

• One hand per scene: events route into the first entity carrying a PokerBetting component.
• A bet, raise, or all-in is capped at the seat's stack, so a short stack goes all-in rather than into the negative; antes are capped the same way.
• submitHumanAction (called for both poker.actionSubmitted and poker.turnAction) records the human's action and steps the NPCs behind them in one call. The System applies each recorded action's chips exactly once via an appliedCount cursor, so the auto-stepped NPCs are never double-charged.
• A poker.turnAction with a playerId that isn't the active seat is dropped; omit playerId to target whoever is up.
• The cores (createChipState, createBettingRound, …) are exported, deterministic, and dependency-free — drive a whole hand in a test without a World.