@swrpg-online/dice 1.1.0 → 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) {
@@ -16,25 +15,6 @@ function parseDiceNotation(input) {
         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);
@@ -99,30 +79,38 @@ function parseDiceNotation(input) {
     }
     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)`);
-    if (result.summary.lightSide > 0)
-        parts.push(`${result.summary.lightSide} Light Side(s)`);
-    if (result.summary.darkSide > 0)
-        parts.push(`${result.summary.darkSide} Dark Side(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
@@ -130,12 +118,13 @@ const main = () => {
         - 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) {
@@ -483,7 +484,7 @@ const forceDieResult = (roll) => {
             };
     }
 };
-const sumResults = (results) => {
+const sumResults = (results, options) => {
     const sums = results.reduce((acc, curr) => ({
         successes: acc.successes + curr.successes,
         failures: acc.failures + curr.failures,
@@ -503,7 +504,6 @@ const sumResults = (results) => {
         lightSide: 0,
         darkSide: 0,
     });
-    // Calculate net successes/failures
     let netSuccesses = 0;
     let netFailures = 0;
     if (sums.successes === sums.failures) {
@@ -516,7 +516,7 @@ const sumResults = (results) => {
     else {
         netFailures = sums.failures - sums.successes;
     }
-    return {
+    const result = {
         successes: netSuccesses,
         failures: netFailures,
         advantages: sums.advantages,
@@ -526,10 +526,10 @@ const sumResults = (results) => {
         lightSide: sums.lightSide,
         darkSide: sums.darkSide,
     };
+    return result;
 };
-const roll = (pool) => {
+const roll = (pool, options) => {
     var _a, _b, _c, _d, _e, _f, _g;
-    // Initialize all dice counts to 0 if undefined
     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;
@@ -611,9 +611,23 @@ const roll = (pool) => {
             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

@@ -16,6 +16,7 @@ export type DiceResult = {
     despair: number;
     lightSide: number;
     darkSide: number;
+    hints?: string[];
 };
 export type DieType = "boost" | "ability" | "proficiency" | "setback" | "difficulty" | "challenge" | "force";
 export type DetailedDieResult = {
@@ -27,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.1.0",
+  "version": "1.2.0",
   "description": "A TypeScript library for simulating Star Wars RPG narrative dice rolls.",
   "main": "dist/index.js",
   "bin": {