@swrpg-online/dice 1.0.5 → 1.2.0

package/README.md

@@ -7,25 +7,71 @@
 
 A TypeScript library that creates dice rolls using the [narrative dice system](https://star-wars-rpg-ffg.fandom.com/wiki/Narrative_Dice) for the Star Wars Role-Playing Game by [Fantasy Flight Games](https://www.fantasyflightgames.com/en/starwarsrpg/) and [Edge Studio](https://www.edge-studio.net/categories-games/starwarsrpg/).
 
+## Features
+
+- Complete narrative dice system implementation
+- Detailed roll breakdown for each die
+- Action hints to suggest possible uses for advantages, triumphs, etc.
+- Roll results include:
+  - Successes / Failures
+  - Advantages / Threats
+  - Triumphs / Despairs
+  - Light / Dark Side Points (Force dice)
+- Comprehensive Test Coverage
+- The safety of TypeScript
+- CLI Support
+
 ## Installation
 
+### As a CLI Tool
+
+To use the dice roller from the command line:
+
+```bash
+npm i -g @swrpg-online/dice
+```
+
+### As a project dependency
+
 ```bash
 npm i @swrpg-online/dice
 ```
 
-or optionally to use as a CLI command you can install globally with `npm i -g @swrpg-online/dice`
+## CLI Usage
 
-## Features
+```
+swrpg-dice <dice-notation> [options]
+```
 
-- Complete narrative dice system implementation
-- Detailed roll breakdown for each die
-- Comprehensive test coverage
-- TypeScript type safety
-- roll from a CLI
+Example:
 
-## Usage
+```
+swrpg-dice 2y 1g 1p 1b 1sb --hints
+```
+
+Output:
 
-via code:
+```
+1 Success(es), 4 Advantage(s), 1 Threat(s)
+
+Possible actions:
+ • 1 Advantage or 1 Triumph - Recover one strain (may be applied more than once).
+ • 1 Advantage or 1 Triumph - Add a boost die to the next allied active character's check.
+ • 1 Advantage or 1 Triumph - Notice a single important point in the ongoing conflict, such as the location of a blast door's control panel or
+ ...
+```
+
+Dice Options:
+
+- y/pro = Yellow / Proficiency
+- g/a = Green / Ability
+- b/boo = Blue / Boost
+- r/c = Red / Challenge
+- p/diff = Purple / Difficulty
+- blk/k/sb/s = Black / Setback
+- w/f = White / Force
+
+## Programmatic Usage
 
 ```typescript
 import { roll, DicePool } from '@swrpg-online/dice';
@@ -39,9 +85,8 @@ const pool: DicePool = {
 
 const result = roll(pool);
 
-// Access detailed results
-console.log(result.results);  // Array of individual die results
-console.log(result.summary);  // Summary of total successes, advantages, etc.
+console.log(result.results);
+console.log(result.summary);
 
 => {
   "results": [
@@ -57,18 +102,6 @@ console.log(result.summary);  // Summary of total successes, advantages, etc.
         "despair": 0
       }
     },
-    {
-      "type": "ability",
-      "roll": 3,
-      "result": {
-        "successes": 1,
-        "failures": 0,
-        "advantages": 0,
-        "threats": 0,
-        "triumphs": 0,
-        "despair": 0
-      }
-    },
     {
       "type": "proficiency",
       "roll": 10,
@@ -81,30 +114,7 @@ console.log(result.summary);  // Summary of total successes, advantages, etc.
         "despair": 0
       }
     },
-    {
-      "type": "difficulty",
-      "roll": 2,
-      "result": {
-        "successes": 0,
-        "failures": 1,
-        "advantages": 0,
-        "threats": 0,
-        "triumphs": 0,
-        "despair": 0
-      }
-    },
-    {
-      "type": "challenge",
-      "roll": 11,
-      "result": {
-        "successes": 0,
-        "failures": 0,
-        "advantages": 0,
-        "threats": 2,
-        "triumphs": 0,
-        "despair": 0
-      }
-    }
+    ...
   ],
   "summary": {
     "successes": 0,
@@ -117,21 +127,9 @@ console.log(result.summary);  // Summary of total successes, advantages, etc.
 }
 ```
 
-Each roll result includes:
-
-- Detailed breakdown of each die roll
-- Die type identification
-- Individual results per die
-- Overall summary of the roll
-
-# Roadmap or Under Review
+# License
 
-- implement the Force die
-- implement ability to add success, failure, and so on to dice pools
-- ship combat?
-- crits?
-- polyhedral dice for convenience?
-- anything else?
+This project is licensed under the MIT License.
 
 # Contribution
 

package/dist/cli.d.ts

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { DicePool } from "./types";
+import { DicePool, RollResult } from "./types";
 export declare function parseDiceNotation(input: string): DicePool;
-export declare function formatResult(result: any): string;
+export declare const formatResult: (result: RollResult) => string;
 export declare const main: () => void;

package/dist/cli.js

@@ -1,9 +1,8 @@
 #!/usr/bin/env node
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.main = void 0;
+exports.main = exports.formatResult = void 0;
 exports.parseDiceNotation = parseDiceNotation;
-exports.formatResult = formatResult;
 const dice_1 = require("./dice");
 // import * as path from 'path';
 function parseDiceNotation(input) {
@@ -14,67 +13,49 @@ function parseDiceNotation(input) {
         setBackDice: 0,
         difficultyDice: 0,
         challengeDice: 0,
+        forceDice: 0,
     };
-    // function getImagePath(type: string): string {
-    //     const basePath = path.join(__dirname, 'images');
-    //     switch (type) {
-    //       case 'successes':
-    //         return path.join(basePath, 'success.svg'); // Adjust path and extension as needed
-    //       case 'failures':
-    //         return path.join(basePath, 'failure.svg');
-    //       case 'advantages':
-    //         return path.join(basePath, 'advantage.svg');
-    //       case 'threats':
-    //         return path.join(basePath, 'threat.svg');
-    //       case 'triumphs':
-    //         return path.join(basePath, 'triumph.svg');
-    //       case 'despair':
-    //         return path.join(basePath, 'despair.svg');
-    //       default:
-    //         return '';
-    //     }
-    //   }
     const parts = input.toLowerCase().trim().split(" ");
     for (const part of parts) {
         const count = parseInt(part);
-        const color = part.slice(String(count).length);
+        const color = part.slice(String(count).length).toLowerCase();
         switch (color) {
-            // y/pro = Yellow/Proficiency
+            // y/pro = Yellow / Proficiency
             case "y":
                 pool.proficiencyDice = count;
                 break;
             case "pro":
                 pool.proficiencyDice = count;
                 break;
-            // g/a = Green/Ability
+            // g/a = Green / Ability
             case "g":
                 pool.abilityDice = count;
                 break;
             case "a":
                 pool.abilityDice = count;
                 break;
-            // b/boo = Blue/Boost
+            // b/boo = Blue / Boost
             case "b":
                 pool.boostDice = count;
                 break;
             case "boo":
                 pool.boostDice = count;
                 break;
-            // r/c = Red/ Challenge
+            // r/c = Red / Challenge
             case "r":
                 pool.challengeDice = count;
                 break;
             case "c":
                 pool.challengeDice = count;
                 break;
-            // p/diff = Purple/ Difficulty
+            // p/diff = Purple / Difficulty
             case "p":
                 pool.difficultyDice = count;
                 break;
             case "diff":
                 pool.difficultyDice = count;
                 break;
-            // blk/k/sb/s = Black/Setback
+            // blk/k/sb/s = Black / Setback
             case "blk":
                 pool.setBackDice = count;
                 break;
@@ -87,44 +68,63 @@ function parseDiceNotation(input) {
             case "s":
                 pool.setBackDice = count;
                 break;
-            // w/f = White/Force
-            // TODO
+            // w/f = White / Force
+            case "w":
+                pool.forceDice = count;
+                break;
+            case "f":
+                pool.forceDice = count;
+                break;
         }
     }
     return pool;
 }
-function formatResult(result) {
-    const parts = [];
+const formatResult = (result) => {
+    const effects = [];
     if (result.summary.successes > 0)
-        parts.push(`${result.summary.successes} Success(es)`);
+        effects.push(`${result.summary.successes} Success(es)`);
     if (result.summary.failures > 0)
-        parts.push(`${result.summary.failures} Failure(s)`);
+        effects.push(`${result.summary.failures} Failure(s)`);
     if (result.summary.advantages > 0)
-        parts.push(`${result.summary.advantages} Advantage(s)`);
+        effects.push(`${result.summary.advantages} Advantage(s)`);
     if (result.summary.threats > 0)
-        parts.push(`${result.summary.threats} Threat(s)`);
+        effects.push(`${result.summary.threats} Threat(s)`);
     if (result.summary.triumphs > 0)
-        parts.push(`${result.summary.triumphs} Triumph(s)`);
+        effects.push(`${result.summary.triumphs} Triumph(s)`);
     if (result.summary.despair > 0)
-        parts.push(`${result.summary.despair} Despair(s)`);
-    return parts.join(", ") || "No effects";
-}
+        effects.push(`${result.summary.despair} Despair(s)`);
+    const resultText = effects.length > 0 ? effects.join(", ") : "No effects";
+    if (result.summary.hints && result.summary.hints.length > 0) {
+        return `${resultText}\n\nPossible actions:\n${result.summary.hints.map((hint) => " • " + hint).join("\n")}`;
+    }
+    return resultText;
+};
+exports.formatResult = formatResult;
 const main = () => {
-    const input = process.argv.slice(2).join(" ");
-    if (!input) {
-        console.log(`Usage: > swrpg-dice 2y 1g 2p 1r
+    const args = process.argv.slice(2);
+    const hintsIndex = args.indexOf("--hints");
+    const showHints = hintsIndex !== -1;
+    const diceNotation = hintsIndex !== -1
+        ? args.filter((_, index) => index !== hintsIndex).join(" ")
+        : args.join(" ");
+    if (!diceNotation.trim()) {
+        console.log(`Usage: swrpg-dice <dice-notation> <dice-options>
+      Example: swrpg-dice 2y 1g 1p 1b 1sb --hints
+      Dice Options:
         - y/pro = Yellow / Proficiency
         - g/a = Green / Ability
         - b/boo = Blue / Boost
         - r/c = Red / Challenge
         - p/diff = Purple / Difficulty
         - blk/k/sb/s = Black / Setback
-    `);
+        - w/f = White/Force
+      Options:
+        --hints  Show possible actions based on roll results`);
         process.exit(1);
     }
-    const pool = parseDiceNotation(input);
-    const result = (0, dice_1.roll)(pool);
-    console.log(formatResult(result));
+    const pool = parseDiceNotation(diceNotation);
+    const result = (0, dice_1.roll)(pool, { hints: showHints });
+    console.log((0, exports.formatResult)(result));
 };
 exports.main = main;
 if (require.main === module) {

package/dist/dice.d.ts

@@ -1,2 +1,2 @@
-import { DicePool, RollResult } from "./types";
-export declare const roll: (pool: DicePool) => RollResult;
+import { DicePool, RollResult, RollOptions } from "./types";
+export declare const roll: (pool: DicePool, options?: RollOptions) => RollResult;

package/dist/dice.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.roll = void 0;
+const hints_1 = require("./hints");
 const rollDie = (sides) => Math.floor(Math.random() * sides) + 1;
 const boostDieResult = (roll) => {
     switch (roll) {
@@ -12,6 +13,8 @@ const boostDieResult = (roll) => {
                 threats: 0,
                 triumphs: 0,
                 despair: 0,
+                lightSide: 0,
+                darkSide: 0,
             };
         case 4:
             return {
@@ -21,6 +24,8 @@ const boostDieResult = (roll) => {
                 threats: 0,
                 triumphs: 0,
                 despair: 0,
+                lightSide: 0,
+                darkSide: 0,
             };
         case 5:
             return {
@@ -30,6 +35,8 @@ const boostDieResult = (roll) => {
                 threats: 0,
                 triumphs: 0,
                 despair: 0,
+                lightSide: 0,
+                darkSide: 0,
             };
         case 6:
             return {
@@ -39,6 +46,8 @@ const boostDieResult = (roll) => {
                 threats: 0,
                 triumphs: 0,
                 despair: 0,
+                lightSide: 0,
+                darkSide: 0,
             };
         default:
             return {
@@ -48,6 +57,8 @@ const boostDieResult = (roll) => {
                 threats: 0,
                 triumphs: 0,
                 despair: 0,
+                lightSide: 0,
+                darkSide: 0,
             };
     }
 };
@@ -62,6 +73,8 @@ const setBackDieResult = (roll) => {
                 threats: 0,
                 triumphs: 0,
                 despair: 0,
+                lightSide: 0,
+                darkSide: 0,
             };
         case 5:
         case 6:
@@ -72,6 +85,8 @@ const setBackDieResult = (roll) => {
                 threats: 1,
                 triumphs: 0,
                 despair: 0,
+                lightSide: 0,
+                darkSide: 0,
             };
         default:
             return {
@@ -81,6 +96,8 @@ const setBackDieResult = (roll) => {
                 threats: 0,
                 triumphs: 0,
                 despair: 0,
+                lightSide: 0,
+                darkSide: 0,
             };
     }
 };
@@ -95,6 +112,8 @@ const abilityDieResult = (roll) => {
                 threats: 0,
                 triumphs: 0,
                 despair: 0,
+                lightSide: 0,
+                darkSide: 0,
             };
         case 4:
             return {
@@ -104,6 +123,8 @@ const abilityDieResult = (roll) => {
                 threats: 0,
                 triumphs: 0,
                 despair: 0,
+                lightSide: 0,
+                darkSide: 0,
             };
         case 5:
         case 6:
@@ -114,6 +135,8 @@ const abilityDieResult = (roll) => {
                 threats: 0,
                 triumphs: 0,
                 despair: 0,
+                lightSide: 0,
+                darkSide: 0,
             };
         case 7:
             return {
@@ -123,6 +146,8 @@ const abilityDieResult = (roll) => {
                 threats: 0,
                 triumphs: 0,
                 despair: 0,
+                lightSide: 0,
+                darkSide: 0,
             };
         case 8:
             return {
@@ -132,6 +157,8 @@ const abilityDieResult = (roll) => {
                 threats: 0,
                 triumphs: 0,
                 despair: 0,
+                lightSide: 0,
+                darkSide: 0,
             };
         default:
             return {
@@ -141,6 +168,8 @@ const abilityDieResult = (roll) => {
                 threats: 0,
                 triumphs: 0,
                 despair: 0,
+                lightSide: 0,
+                darkSide: 0,
             };
     }
 };
@@ -154,6 +183,8 @@ const difficultyDieResult = (roll) => {
                 threats: 0,
                 triumphs: 0,
                 despair: 0,
+                lightSide: 0,
+                darkSide: 0,
             };
         case 3:
             return {
@@ -163,6 +194,8 @@ const difficultyDieResult = (roll) => {
                 threats: 0,
                 triumphs: 0,
                 despair: 0,
+                lightSide: 0,
+                darkSide: 0,
             };
         case 4:
         case 5:
@@ -174,6 +207,8 @@ const difficultyDieResult = (roll) => {
                 threats: 1,
                 triumphs: 0,
                 despair: 0,
+                lightSide: 0,
+                darkSide: 0,
             };
         case 7:
             return {
@@ -183,6 +218,8 @@ const difficultyDieResult = (roll) => {
                 threats: 2,
                 triumphs: 0,
                 despair: 0,
+                lightSide: 0,
+                darkSide: 0,
             };
         case 8:
             return {
@@ -192,6 +229,8 @@ const difficultyDieResult = (roll) => {
                 threats: 1,
                 triumphs: 0,
                 despair: 0,
+                lightSide: 0,
+                darkSide: 0,
             };
         default:
             return {
@@ -201,6 +240,8 @@ const difficultyDieResult = (roll) => {
                 threats: 0,
                 triumphs: 0,
                 despair: 0,
+                lightSide: 0,
+                darkSide: 0,
             };
     }
 };
@@ -215,6 +256,8 @@ const proficiencyDieResult = (roll) => {
                 threats: 0,
                 triumphs: 0,
                 despair: 0,
+                lightSide: 0,
+                darkSide: 0,
             };
         case 4:
         case 5:
@@ -225,6 +268,8 @@ const proficiencyDieResult = (roll) => {
                 threats: 0,
                 triumphs: 0,
                 despair: 0,
+                lightSide: 0,
+                darkSide: 0,
             };
         case 6:
             return {
@@ -234,6 +279,8 @@ const proficiencyDieResult = (roll) => {
                 threats: 0,
                 triumphs: 0,
                 despair: 0,
+                lightSide: 0,
+                darkSide: 0,
             };
         case 7:
         case 8:
@@ -245,6 +292,8 @@ const proficiencyDieResult = (roll) => {
                 threats: 0,
                 triumphs: 0,
                 despair: 0,
+                lightSide: 0,
+                darkSide: 0,
             };
         case 10:
         case 11:
@@ -255,6 +304,8 @@ const proficiencyDieResult = (roll) => {
                 threats: 0,
                 triumphs: 0,
                 despair: 0,
+                lightSide: 0,
+                darkSide: 0,
             };
         case 12:
             return {
@@ -264,6 +315,8 @@ const proficiencyDieResult = (roll) => {
                 threats: 0,
                 triumphs: 1,
                 despair: 0,
+                lightSide: 0,
+                darkSide: 0,
             };
         default:
             return {
@@ -273,6 +326,8 @@ const proficiencyDieResult = (roll) => {
                 threats: 0,
                 triumphs: 0,
                 despair: 0,
+                lightSide: 0,
+                darkSide: 0,
             };
     }
 };
@@ -287,6 +342,8 @@ const challengeDieResult = (roll) => {
                 threats: 0,
                 triumphs: 0,
                 despair: 0,
+                lightSide: 0,
+                darkSide: 0,
             };
         case 4:
         case 5:
@@ -297,6 +354,8 @@ const challengeDieResult = (roll) => {
                 threats: 0,
                 triumphs: 0,
                 despair: 0,
+                lightSide: 0,
+                darkSide: 0,
             };
         case 6:
         case 7:
@@ -307,6 +366,8 @@ const challengeDieResult = (roll) => {
                 threats: 1,
                 triumphs: 0,
                 despair: 0,
+                lightSide: 0,
+                darkSide: 0,
             };
         case 8:
         case 9:
@@ -317,6 +378,8 @@ const challengeDieResult = (roll) => {
                 threats: 1,
                 triumphs: 0,
                 despair: 0,
+                lightSide: 0,
+                darkSide: 0,
             };
         case 10:
         case 11:
@@ -327,6 +390,8 @@ const challengeDieResult = (roll) => {
                 threats: 2,
                 triumphs: 0,
                 despair: 0,
+                lightSide: 0,
+                darkSide: 0,
             };
         case 12:
             return {
@@ -336,6 +401,8 @@ const challengeDieResult = (roll) => {
                 threats: 0,
                 triumphs: 0,
                 despair: 1,
+                lightSide: 0,
+                darkSide: 0,
             };
         default:
             return {
@@ -345,10 +412,79 @@ const challengeDieResult = (roll) => {
                 threats: 0,
                 triumphs: 0,
                 despair: 0,
+                lightSide: 0,
+                darkSide: 0,
             };
     }
 };
-const sumResults = (results) => {
+const forceDieResult = (roll) => {
+    switch (roll) {
+        case 1:
+        case 2:
+        case 3:
+        case 4:
+        case 5:
+            return {
+                successes: 0,
+                failures: 0,
+                advantages: 0,
+                threats: 0,
+                triumphs: 0,
+                despair: 0,
+                lightSide: 1,
+                darkSide: 0,
+            };
+        case 6:
+        case 7:
+            return {
+                successes: 0,
+                failures: 0,
+                advantages: 0,
+                threats: 0,
+                triumphs: 0,
+                despair: 0,
+                lightSide: 2,
+                darkSide: 0,
+            };
+        case 8:
+        case 9:
+        case 10:
+        case 11:
+            return {
+                successes: 0,
+                failures: 0,
+                advantages: 0,
+                threats: 0,
+                triumphs: 0,
+                despair: 0,
+                lightSide: 0,
+                darkSide: 1,
+            };
+        case 12:
+            return {
+                successes: 0,
+                failures: 0,
+                advantages: 0,
+                threats: 0,
+                triumphs: 0,
+                despair: 0,
+                lightSide: 0,
+                darkSide: 2,
+            };
+        default:
+            return {
+                successes: 0,
+                failures: 0,
+                advantages: 0,
+                threats: 0,
+                triumphs: 0,
+                despair: 0,
+                lightSide: 0,
+                darkSide: 0,
+            };
+    }
+};
+const sumResults = (results, options) => {
     const sums = results.reduce((acc, curr) => ({
         successes: acc.successes + curr.successes,
         failures: acc.failures + curr.failures,
@@ -356,6 +492,8 @@ const sumResults = (results) => {
         threats: acc.threats + curr.threats,
         triumphs: acc.triumphs + curr.triumphs,
         despair: acc.despair + curr.despair,
+        lightSide: acc.lightSide + (curr.lightSide || 0),
+        darkSide: acc.darkSide + (curr.darkSide || 0),
     }), {
         successes: 0,
         failures: 0,
@@ -363,8 +501,9 @@ const sumResults = (results) => {
         threats: 0,
         triumphs: 0,
         despair: 0,
+        lightSide: 0,
+        darkSide: 0,
     });
-    // Calculate net successes/failures
     let netSuccesses = 0;
     let netFailures = 0;
     if (sums.successes === sums.failures) {
@@ -377,24 +516,27 @@ const sumResults = (results) => {
     else {
         netFailures = sums.failures - sums.successes;
     }
-    return {
+    const result = {
         successes: netSuccesses,
         failures: netFailures,
         advantages: sums.advantages,
         threats: sums.threats,
         triumphs: sums.triumphs,
         despair: sums.despair,
+        lightSide: sums.lightSide,
+        darkSide: sums.darkSide,
     };
+    return result;
 };
-const roll = (pool) => {
-    var _a, _b, _c, _d, _e, _f;
-    // Initialize all dice counts to 0 if undefined
+const roll = (pool, options) => {
+    var _a, _b, _c, _d, _e, _f, _g;
     const boostCount = (_a = pool.boostDice) !== null && _a !== void 0 ? _a : 0;
     const abilityCount = (_b = pool.abilityDice) !== null && _b !== void 0 ? _b : 0;
     const proficiencyCount = (_c = pool.proficiencyDice) !== null && _c !== void 0 ? _c : 0;
     const setBackCount = (_d = pool.setBackDice) !== null && _d !== void 0 ? _d : 0;
     const difficultyCount = (_e = pool.difficultyDice) !== null && _e !== void 0 ? _e : 0;
     const challengeCount = (_f = pool.challengeDice) !== null && _f !== void 0 ? _f : 0;
+    const forceCount = (_g = pool.forceDice) !== null && _g !== void 0 ? _g : 0;
     // Ensure all dice counts are non-negative
     const sanitizedPool = {
         boostDice: Math.max(0, boostCount),
@@ -403,6 +545,7 @@ const roll = (pool) => {
         setBackDice: Math.max(0, setBackCount),
         difficultyDice: Math.max(0, difficultyCount),
         challengeDice: Math.max(0, challengeCount),
+        forceDice: Math.max(0, forceCount),
     };
     const detailedResults = [];
     // Roll boost dice
@@ -459,9 +602,32 @@ const roll = (pool) => {
             result: challengeDieResult(roll),
         });
     }
+    // Roll force dice
+    for (let i = 0; i < sanitizedPool.forceDice; i++) {
+        const roll = rollDie(12);
+        detailedResults.push({
+            type: "force",
+            roll,
+            result: forceDieResult(roll),
+        });
+    }
+    const summary = sumResults(detailedResults.map((r) => r.result));
+    if (options === null || options === void 0 ? void 0 : options.hints) {
+        const applicableHints = hints_1.hints.filter((hint) => {
+            const { cost } = hint;
+            return Object.entries(cost).some(([symbol, required]) => {
+                const summaryKey = (symbol.toLowerCase() + "s");
+                const value = summary[summaryKey];
+                if (typeof value !== "number")
+                    return false;
+                return required <= value;
+            });
+        });
+        summary.hints = applicableHints.map((hint) => `${(0, hints_1.hintCostDisplayText)(hint)} - ${hint.description}`);
+    }
     return {
         results: detailedResults,
-        summary: sumResults(detailedResults.map((r) => r.result)),
+        summary: summary,
     };
 };
 exports.roll = roll;

package/dist/hints.d.ts

@@ -0,0 +1,11 @@
+import { type Symbol } from "./types";
+export type CostType = {
+    [key in Symbol]?: number;
+};
+type Hint = {
+    description: string;
+    cost: CostType;
+};
+export declare const hints: Hint[];
+export declare function hintCostDisplayText(hint: Hint): string;
+export {};

package/dist/hints.js

@@ -0,0 +1,246 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.hints = void 0;
+exports.hintCostDisplayText = hintCostDisplayText;
+const types_1 = require("./types");
+// 1 advantage or 1 triumph
+const recoverOneStrain = "Recover one strain (may be applied more than once).";
+const addBoostDieToActiveAlly = "Add a boost die to the next allied active character's check.";
+const noticeImportantPoint = "Notice a single important point in the ongoing conflict, such as the location of a blast door's control panel or a weak point on an attack speeder.";
+const inflictCriticalInjury = "Inflict a Critical Injury with a successful attack that deals damage past soak (Advantage cost may vary).";
+const activateWeaponQuality = "Activate a weapon quality (Advantage cost may vary).";
+// 2 advantage or 1 triumph
+const performManeuver = "Perform an immediate free maneuver that does not exceed the two maneuver per turn limit.";
+const addSetbackDie = "Add a setback die to the targeted character's next check.";
+const addBoostDieToAnyAlly = "Add a boost die to any allied character's next check, including that of the active character.";
+// 3 advantage or 1 triumph
+const negateEnemy = "Negate the targeted enemy's defensive bonuses (such as the defense gained from cover, equipment, or performing the Guarded Stance maneuver) util the end of the current round.";
+const ignoreEnvironment = "Ignore penalizing environmental effects such as inclement weather, zero gravity, or similar circumstances until the end of the active character's next turn.";
+const disableOpponent = "When dealing damage to a target, have the attack disable the opponent or one piece of gear rather than dealing wounds or strain. This could include hobbling them temporarily with a shot to the leg, or disabling their comlink. This should be agreed upon by the player and the GM, and the effects are up to the GM (although Table 6-10: Critical Injury Result is a god resource to consult for possible effects). The effects should be temporary and not too excessive.";
+const gainDefense = "Gain + 1 melee or ranged defense until the end of the active character's next turn.";
+const dropWeapon = "Force the target to drop a melee or ranged weapon they are wielding.";
+// 1 triumph
+const upgradeDifficultyTargetedCharacter = "Upgrade the difficulty of the targeted character's next check.";
+const doSomethingVital = "Do something vital, such as shooting the controls to the nearby blast doors to seal them shut.";
+const upgradeAnyAllyCheck = "Upgrade any allied character's next check, including that of the current active character.";
+// 2 triumph
+const destroyEquipment = "When dealing damage to a target, have the attack destroy a piece of equipment the target is using, such as blowing up his blaster or destroying a personal shield generator.";
+// 1 threat or 1 despair
+const sufferStrain = "The active character suffers 1 strain.";
+const loseManeuverBenefit = "The active character loses the benefits of a prior maneuver (such as from taking cover or assuming a Guarded Stance) until they perform the maneuver again.";
+// 2 threat or 1 despair
+const freeManeuver = "An opponent may immediately perform one free maneuver in response to the active character's check.";
+const addBoostDieToTargetedCharacter = "Add a boost die to the targeted character's next check.";
+const sufferSetback = "The active character or an allied character suffers a setback die on their next action.";
+// 3 threat or 1 despair
+const fallProne = "The active character falls prone.";
+const gainSignificantAdvantage = "The active character grants the enemy a significant advantage in the ongoing encounter, such as accidentally blasting the controls to a bridge the active character was planning to use for their escape.";
+// 1 despair
+const outOfAmmo = "The character's ranged weapon imediately runs out of ammunition and may not be used for the remainder of the encounter.";
+const upgradeDifficultyAlliedCharacter = "Upgrade the difficulty of an allied character's next check, including that of the current active character.";
+const damagedItem = "The tool or melee weapon the character is using becomes damaged.";
+exports.hints = [
+    // 1 advantage or 1 triumph
+    {
+        description: recoverOneStrain,
+        cost: {
+            [types_1.SYMBOLS.ADVANTAGE]: 1,
+            [types_1.SYMBOLS.TRIUMPH]: 1,
+        },
+    },
+    {
+        description: addBoostDieToActiveAlly,
+        cost: {
+            [types_1.SYMBOLS.ADVANTAGE]: 1,
+            [types_1.SYMBOLS.TRIUMPH]: 1,
+        },
+    },
+    {
+        description: noticeImportantPoint,
+        cost: {
+            [types_1.SYMBOLS.ADVANTAGE]: 1,
+            [types_1.SYMBOLS.TRIUMPH]: 1,
+        },
+    },
+    {
+        description: inflictCriticalInjury,
+        cost: {
+            [types_1.SYMBOLS.ADVANTAGE]: 1,
+            [types_1.SYMBOLS.TRIUMPH]: 1,
+        },
+    },
+    {
+        description: activateWeaponQuality,
+        cost: {
+            [types_1.SYMBOLS.ADVANTAGE]: 1,
+            [types_1.SYMBOLS.TRIUMPH]: 1,
+        },
+    },
+    // 2 advantage or 1 triumph
+    {
+        description: performManeuver,
+        cost: {
+            [types_1.SYMBOLS.ADVANTAGE]: 2,
+            [types_1.SYMBOLS.TRIUMPH]: 1,
+        },
+    },
+    {
+        description: addSetbackDie,
+        cost: {
+            [types_1.SYMBOLS.ADVANTAGE]: 2,
+            [types_1.SYMBOLS.TRIUMPH]: 1,
+        },
+    },
+    {
+        description: addBoostDieToAnyAlly,
+        cost: {
+            [types_1.SYMBOLS.ADVANTAGE]: 2,
+            [types_1.SYMBOLS.TRIUMPH]: 1,
+        },
+    },
+    // 3 advantage or 1 triumph
+    {
+        description: negateEnemy,
+        cost: {
+            [types_1.SYMBOLS.ADVANTAGE]: 3,
+            [types_1.SYMBOLS.TRIUMPH]: 1,
+        },
+    },
+    {
+        description: ignoreEnvironment,
+        cost: {
+            [types_1.SYMBOLS.ADVANTAGE]: 3,
+            [types_1.SYMBOLS.TRIUMPH]: 1,
+        },
+    },
+    {
+        description: disableOpponent,
+        cost: {
+            [types_1.SYMBOLS.ADVANTAGE]: 3,
+            [types_1.SYMBOLS.TRIUMPH]: 1,
+        },
+    },
+    {
+        description: gainDefense,
+        cost: {
+            [types_1.SYMBOLS.ADVANTAGE]: 3,
+            [types_1.SYMBOLS.TRIUMPH]: 1,
+        },
+    },
+    {
+        description: dropWeapon,
+        cost: {
+            [types_1.SYMBOLS.ADVANTAGE]: 3,
+            [types_1.SYMBOLS.TRIUMPH]: 1,
+        },
+    },
+    // 1 triumph
+    {
+        description: upgradeDifficultyTargetedCharacter,
+        cost: {
+            [types_1.SYMBOLS.TRIUMPH]: 1,
+        },
+    },
+    {
+        description: doSomethingVital,
+        cost: {
+            [types_1.SYMBOLS.TRIUMPH]: 1,
+        },
+    },
+    {
+        description: upgradeAnyAllyCheck,
+        cost: {
+            [types_1.SYMBOLS.TRIUMPH]: 1,
+        },
+    },
+    // 2 triumph
+    {
+        description: destroyEquipment,
+        cost: {
+            [types_1.SYMBOLS.TRIUMPH]: 2,
+        },
+    },
+    // 1 threat or 1 despair
+    {
+        description: sufferStrain,
+        cost: {
+            [types_1.SYMBOLS.THREAT]: 1,
+            [types_1.SYMBOLS.DESPAIR]: 1,
+        },
+    },
+    {
+        description: loseManeuverBenefit,
+        cost: {
+            [types_1.SYMBOLS.THREAT]: 1,
+            [types_1.SYMBOLS.DESPAIR]: 1,
+        },
+    },
+    // 2 threat or 1 despair
+    {
+        description: freeManeuver,
+        cost: {
+            [types_1.SYMBOLS.THREAT]: 2,
+            [types_1.SYMBOLS.DESPAIR]: 1,
+        },
+    },
+    {
+        description: addBoostDieToTargetedCharacter,
+        cost: {
+            [types_1.SYMBOLS.THREAT]: 1,
+            [types_1.SYMBOLS.DESPAIR]: 1,
+        },
+    },
+    {
+        description: sufferSetback,
+        cost: {
+            [types_1.SYMBOLS.THREAT]: 2,
+            [types_1.SYMBOLS.DESPAIR]: 1,
+        },
+    },
+    // 3 threat or 1 despair
+    {
+        description: fallProne,
+        cost: {
+            [types_1.SYMBOLS.THREAT]: 3,
+            [types_1.SYMBOLS.DESPAIR]: 1,
+        },
+    },
+    {
+        description: gainSignificantAdvantage,
+        cost: {
+            [types_1.SYMBOLS.THREAT]: 3,
+            [types_1.SYMBOLS.DESPAIR]: 1,
+        },
+    },
+    // 1 despair
+    {
+        description: outOfAmmo,
+        cost: {
+            [types_1.SYMBOLS.DESPAIR]: 1,
+        },
+    },
+    {
+        description: upgradeDifficultyAlliedCharacter,
+        cost: {
+            [types_1.SYMBOLS.DESPAIR]: 1,
+        },
+    },
+    {
+        description: damagedItem,
+        cost: {
+            [types_1.SYMBOLS.DESPAIR]: 1,
+        },
+    },
+];
+function hintCostDisplayText(hint) {
+    if (!hint.cost || Object.keys(hint.cost).length === 0) {
+        return "No cost";
+    }
+    const parts = Object.entries(hint.cost)
+        .filter(([_, count]) => count && count > 0)
+        .map(([symbol, count]) => {
+        const symbolName = symbol.charAt(0) + symbol.toLowerCase().slice(1);
+        return `${count} ${symbolName}${count > 1 ? "(s)" : ""}`;
+    });
+    return parts.length > 0 ? parts.join(" or ") : "No cost";
+}

package/dist/types.d.ts

@@ -5,6 +5,7 @@ export type DicePool = {
     setBackDice?: number;
     difficultyDice?: number;
     challengeDice?: number;
+    forceDice?: number;
 };
 export type DiceResult = {
     successes: number;
@@ -13,8 +14,11 @@ export type DiceResult = {
     threats: number;
     triumphs: number;
     despair: number;
+    lightSide: number;
+    darkSide: number;
+    hints?: string[];
 };
-export type DieType = "boost" | "ability" | "proficiency" | "setback" | "difficulty" | "challenge";
+export type DieType = "boost" | "ability" | "proficiency" | "setback" | "difficulty" | "challenge" | "force";
 export type DetailedDieResult = {
     type: DieType;
     roll: number;
@@ -24,3 +28,17 @@ export type RollResult = {
     results: DetailedDieResult[];
     summary: DiceResult;
 };
+export declare const SYMBOLS: {
+    readonly SUCCESS: "SUCCESS";
+    readonly FAILURE: "FAILURE";
+    readonly ADVANTAGE: "ADVANTAGE";
+    readonly THREAT: "THREAT";
+    readonly TRIUMPH: "TRIUMPH";
+    readonly DESPAIR: "DESPAIR";
+    readonly LIGHT: "LIGHT";
+    readonly DARK: "DARK";
+};
+export type Symbol = keyof typeof SYMBOLS;
+export type RollOptions = {
+    hints?: boolean;
+};

package/dist/types.js

@@ -1,2 +1,13 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.SYMBOLS = void 0;
+exports.SYMBOLS = {
+    SUCCESS: "SUCCESS",
+    FAILURE: "FAILURE",
+    ADVANTAGE: "ADVANTAGE",
+    THREAT: "THREAT",
+    TRIUMPH: "TRIUMPH",
+    DESPAIR: "DESPAIR",
+    LIGHT: "LIGHT",
+    DARK: "DARK",
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@swrpg-online/dice",
-  "version": "1.0.5",
+  "version": "1.2.0",
   "description": "A TypeScript library for simulating Star Wars RPG narrative dice rolls.",
   "main": "dist/index.js",
   "bin": {