A type-safe implementation of Powered by the Apocalypse dice rolling mechanics that supports:

• 🎲 Standard 2d6 + stat rolls
• 🎯 Automatic outcome determination (strong hit, weak hit, miss)
• ⚡ Advantage/disadvantage mechanics
• 🔒 Full TypeScript support
• 🪶 Tree-shakeable implementation

Works with any PbtA game including Dungeon World, Monster of the Week, Apocalypse World, Masks, and more.

Installation

npm install @randsum/pbta
# or
yarn add @randsum/pbta
# or
bun add @randsum/pbta

Usage

import { rollPbtA } from "@randsum/pbta"

// Basic roll
const result = rollPbtA({ stat: 2 })
// result.result: 'strong_hit' | 'weak_hit' | 'miss'

// With bonuses
const result = rollPbtA({
  stat: 1,
  forward: 1, // One-time bonus
  ongoing: 0 // Persistent bonus
})

// With advantage (roll 3d6, keep 2 highest)
const result = rollPbtA({
  stat: 2,
  advantage: true
})

// With disadvantage (roll 3d6, keep 2 lowest)
const result = rollPbtA({
  stat: 2,
  disadvantage: true
})

API Reference

rollPbtA

Makes a PbtA roll following standard mechanics.

function rollPbtA(arg: PbtARollArgument): GameRollResult<PbtAOutcome, PbtARollDetails, RollRecord>

Parameters:

• stat: Stat modifier (typically -3 to +4)
• forward?: One-time bonus
• ongoing?: Persistent bonus
• advantage?: Roll with advantage (3d6, keep 2 highest)
• disadvantage?: Roll with disadvantage (3d6, keep 2 lowest)

Returns:

• result: 'strong_hit' | 'weak_hit' | 'miss'
• total: Final roll total
• details: Additional roll information
• rolls: Full roll records with modifier history

Outcomes

• Strong Hit (10+): Complete success, you do what you set out to do
• Weak Hit (7-9): Partial success, you do it but with a cost or complication
• Miss (6-): Failure, things go wrong

Related Packages

• @randsum/roller: Core dice rolling implementation