verseluft-dnd-library 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Verseluft
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,35 @@
+# Verseluft DnD Library
+
+A small JavaScript library for DnD-style apps and websites.
+
+## What is inside
+
+- `core` for shared library setup
+- `modules` for game content such as spells, monsters, items, and classes
+- `tools` for reusable gameplay helpers such as dice rolling
+- `content` for starter data that other apps can extend
+
+## Documentation
+
+- [Human docs](./docs/human/README.md)
+- [AI docs](./docs/ai/README.md)
+- [Dice tool](./docs/human/api/tools/dice.md)
+- The published npm package includes both doc sets
+- Build the standalone wiki with `npm run wiki:build`
+
+## Example
+
+```js
+import { createDnDLibrary, rollDice } from "./src/index.js";
+
+const lib = createDnDLibrary({
+  name: "My Campaign Toolkit"
+});
+
+console.log(lib.info());
+console.log(rollDice("2d6+3"));
+```
+
+## Next steps
+
+This scaffold is ready to grow into a real package with richer rules, more content packs, and optional UI helpers.

package/docs/README.md

@@ -0,0 +1,10 @@
+# Documentation Root
+
+Choose the version that fits your needs:
+
+- [Human docs](./human/README.md)
+- [AI docs](./ai/README.md)
+
+The published npm package includes both doc sets.
+The standalone wiki is generated from the human docs only.
+Run `npm run wiki:build` to create it in `wiki-site/`.

package/docs/ai/README.md

@@ -0,0 +1,25 @@
+# AI Documentation
+
+This folder is the AI-facing version of the docs.
+
+Use it when you need:
+
+- Precise edit boundaries
+- Implementation notes
+- Safer file-by-file updates
+
+Start here:
+
+- [Overview](./overview.md)
+- [Changelog](./changelog.md)
+- [API Index](./api/index.md)
+
+Scope:
+
+- Dice tool only
+
+Rules:
+
+- Update one tool file at a time
+- Do not touch unrelated docs
+- If the API changes, update the matching human docs too

package/docs/ai/api/index.md

@@ -0,0 +1,13 @@
+# AI API Index
+
+Only the dice tool is in scope for now.
+
+## Tools
+
+- [Dice tool](./tools/dice.md)
+
+## Agent rules
+
+- If you are editing dice behavior, edit only the dice doc first
+- If the public export changes, update this index and the changelog
+- Do not expand scope to new tools unless the task explicitly asks for it

package/docs/ai/api/tools/dice.md

@@ -0,0 +1,52 @@
+# AI Dice Tool Reference
+
+This file is the AI-specific reference for the dice tool.
+
+## Exported functions
+
+- `parseDiceExpression(expression)`
+- `rollDice(expression, randomFn?)`
+- `averageRoll(expression)`
+
+## Source file
+
+- [src/tools/dice.js](/D:/Projects/Verseluft-Core/src/tools/dice.js)
+
+## Behavior summary
+
+### `parseDiceExpression(expression)`
+- Accepts strings that match `NdM` or `NdM+K` / `NdM-K`
+- If `N` is omitted, it defaults to `1`
+- Returns `{ count, sides, modifier }`
+- Throws `Error` for invalid expressions
+
+### `rollDice(expression, randomFn?)`
+- Parses the expression with `parseDiceExpression`
+- Rolls `count` times using `randomFn`, defaulting to `Math.random`
+- Returns `{ expression, rolls, modifier, total }`
+- `total` includes the modifier
+
+### `averageRoll(expression)`
+- Returns the mathematical average of the expression
+- Uses the formula `count * ((sides + 1) / 2) + modifier`
+
+## Examples
+
+```js
+import { parseDiceExpression, rollDice, averageRoll } from "verseluft-dnd-library";
+
+parseDiceExpression("2d6+3");
+rollDice("2d6+3");
+averageRoll("2d6+3");
+```
+
+## Test guidance
+
+- For deterministic tests, pass a custom `randomFn`
+- Do not compare against random outputs without controlling the source
+
+## Edit boundaries
+
+- If dice logic changes, update this file and the human dice doc together
+- Do not modify unrelated docs when editing the dice tool
+- If the export list changes, update `src/index.js` and both API index files

package/docs/ai/changelog.md

@@ -0,0 +1,13 @@
+# AI Changelog
+
+## 0.1.0
+
+- Initial scaffold
+- Dice parsing and rolling utilities added
+- Starter content and tests added
+- Standalone wiki generator added
+
+AI editing notes:
+
+- Keep changelog entries short and factual
+- When behavior changes, mention the exact file and export affected

package/docs/ai/overview.md

@@ -0,0 +1,23 @@
+# AI Overview
+
+Project: Verseluft DnD Library
+
+Purpose:
+
+- Small JavaScript toolkit for DnD-style apps and websites
+- Current scope is only the dice tool
+
+Agent guidance:
+
+- Use the matching AI tool doc for implementation details
+- Do not infer behavior from unrelated files
+- Keep edits narrow and file-specific
+
+Documentation map:
+
+- `docs/ai/overview.md`
+- `docs/ai/changelog.md`
+- `docs/ai/api/index.md`
+- `docs/ai/api/tools/dice.md`
+
+Do not add new tool docs without explicit scope changes.

package/docs/human/README.md

@@ -0,0 +1,14 @@
+# Documentation
+
+Start here:
+
+- [Overview](./overview.md)
+- [Changelog](./changelog.md)
+- [API Index](./api/index.md)
+
+Current scope:
+
+- Dice tool only
+
+To generate the standalone wiki site, run `npm run wiki:build`.
+The built HTML files will appear in `wiki-site/`.

package/docs/human/api/index.md

@@ -0,0 +1,13 @@
+# API Index
+
+This page is the central map for the library documentation.
+
+## Tools
+
+- [Dice tool](./tools/dice.md)
+
+## Notes for editors
+
+- Update only the matching tool file when changing one tool
+- Keep cross-tool changes rare and explicit
+- Add new tools as new Markdown files instead of mixing them together

package/docs/human/api/tools/dice.md

@@ -0,0 +1,95 @@
+# Dice Tool
+
+The dice tool parses and rolls dice expressions for tabletop and game-style applications.
+
+## Purpose
+
+Use this tool to:
+
+- Parse expressions like `2d6+3`
+- Roll dice with a deterministic or random source
+- Estimate the average result of a dice expression
+
+## Exports
+
+- `parseDiceExpression(expression)`
+- `rollDice(expression, randomFn?)`
+- `averageRoll(expression)`
+
+## `parseDiceExpression(expression)`
+
+Parses a dice expression and returns a structured object.
+
+### Input
+
+- `expression`: a string such as `d20`, `2d6`, or `4d8+2`
+
+### Output
+
+```js
+{
+  count: number,
+  sides: number,
+  modifier: number
+}
+```
+
+### Example
+
+```js
+import { parseDiceExpression } from "verseluft-dnd-library";
+
+const dice = parseDiceExpression("2d6+3");
+// { count: 2, sides: 6, modifier: 3 }
+```
+
+## `rollDice(expression, randomFn?)`
+
+Rolls dice and returns the individual rolls plus the total.
+
+### Input
+
+- `expression`: a dice expression string
+- `randomFn`: optional random function, defaults to `Math.random`
+
+### Output
+
+```js
+{
+  expression: string,
+  rolls: number[],
+  modifier: number,
+  total: number
+}
+```
+
+### Example
+
+```js
+import { rollDice } from "verseluft-dnd-library";
+
+const result = rollDice("2d6+3");
+// { expression: "2d6+3", rolls: [4, 2], modifier: 3, total: 9 }
+```
+
+### Testing tip
+
+Pass a custom `randomFn` when you want repeatable tests.
+
+## `averageRoll(expression)`
+
+Returns the mathematical average for the expression.
+
+### Example
+
+```js
+import { averageRoll } from "verseluft-dnd-library";
+
+averageRoll("2d6+3");
+// 10
+```
+
+## Editing rule
+
+If you change the dice tool behavior, update only this file first.
+If the public API changes, then update the central index and changelog too.

package/docs/human/changelog.md

@@ -0,0 +1,13 @@
+# Changelog
+
+## 0.1.0
+
+- Initial library scaffold
+- Added dice parsing and rolling helpers
+- Added starter content modules
+- Added package tests and a browser playground
+
+## Documentation notes
+
+- The docs are organized by topic so AI edits can stay isolated
+- Dice is the only documented tool in the first pass

package/docs/human/overview.md

@@ -0,0 +1,25 @@
+# Verseluft DnD Library
+
+Verseluft DnD Library is a small JavaScript toolkit for DnD-style apps and websites.
+
+Right now, this documentation set focuses on a single tool:
+
+- Dice tools
+
+## What this docs set is for
+
+- Human readers who want clear usage guidance
+- AI readers who need a stable, file-based reference
+- Safe editing, where each tool has its own isolated page
+
+## Documentation layout
+
+- `docs/human/overview.md` for the big picture
+- `docs/human/changelog.md` for version notes
+- `docs/human/api/index.md` for the API map
+- `docs/human/api/tools/dice.md` for the dice tool
+
+## Current scope
+
+This docs set intentionally covers only the dice tool for now.
+Other tools and modules can be added later as separate files.

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "verseluft-dnd-library",
+  "version": "0.1.0",
+  "description": "A small DnD utility library with reusable content modules and dice tools for apps and websites.",
+  "license": "MIT",
+  "keywords": [
+    "dnd",
+    "rpg",
+    "library",
+    "javascript",
+    "browser"
+  ],
+  "type": "module",
+  "main": "./src/index.js",
+  "exports": {
+    ".": "./src/index.js",
+    "./modules/*": "./src/modules/*.js",
+    "./tools/*": "./src/tools/*.js",
+    "./content/*": "./src/content/*.js"
+  },
+  "files": [
+    "src",
+    "docs",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "test": "node --test test/library.test.js",
+    "test:watch": "node --test --watch test/library.test.js",
+    "wiki:build": "node scripts/build-wiki.mjs"
+  }
+}

package/src/content/starterContent.js

@@ -0,0 +1,28 @@
+export const starterContent = {
+  monsters: [
+    {
+      id: "goblin",
+      name: "Goblin",
+      challengeRating: 0.25,
+    },
+  ],
+  spells: [
+    {
+      id: "magic-missile",
+      name: "Magic Missile",
+      level: 1,
+    },
+  ],
+  items: [
+    {
+      id: "healing-potion",
+      name: "Healing Potion",
+    },
+  ],
+  classes: [
+    {
+      id: "fighter",
+      name: "Fighter",
+    },
+  ],
+};

package/src/core/createDnDLibrary.js

@@ -0,0 +1,17 @@
+import { starterContent } from "../content/starterContent.js";
+
+export function createDnDLibrary(options = {}) {
+  const libraryName = options.name ?? "DnD Library";
+  const content = options.content ?? starterContent;
+
+  return {
+    name: libraryName,
+    content,
+    info() {
+      return {
+        name: libraryName,
+        modules: Object.keys(content),
+      };
+    },
+  };
+}

package/src/index.js

@@ -0,0 +1,7 @@
+export { createDnDLibrary } from "./core/createDnDLibrary.js";
+export { rollDice, parseDiceExpression, averageRoll } from "./tools/dice.js";
+export { getMonsterById, listMonsters } from "./modules/monsters.js";
+export { getSpellById, listSpells } from "./modules/spells.js";
+export { getItemById, listItems } from "./modules/items.js";
+export { getClassById, listClasses } from "./modules/classes.js";
+export { starterContent } from "./content/starterContent.js";

package/src/modules/classes.js

@@ -0,0 +1,20 @@
+const classes = [
+  {
+    id: "fighter",
+    name: "Fighter",
+    primaryAbility: "strength",
+  },
+  {
+    id: "wizard",
+    name: "Wizard",
+    primaryAbility: "intelligence",
+  },
+];
+
+export function listClasses() {
+  return [...classes];
+}
+
+export function getClassById(id) {
+  return classes.find((characterClass) => characterClass.id === id) ?? null;
+}

package/src/modules/items.js

@@ -0,0 +1,22 @@
+const items = [
+  {
+    id: "healing-potion",
+    name: "Healing Potion",
+    rarity: "common",
+    kind: "consumable",
+  },
+  {
+    id: "longsword",
+    name: "Longsword",
+    rarity: "common",
+    kind: "weapon",
+  },
+];
+
+export function listItems() {
+  return [...items];
+}
+
+export function getItemById(id) {
+  return items.find((item) => item.id === id) ?? null;
+}

package/src/modules/monsters.js

@@ -0,0 +1,24 @@
+const monsters = [
+  {
+    id: "goblin",
+    name: "Goblin",
+    type: "humanoid",
+    challengeRating: 0.25,
+    tags: ["small", "sneaky", "cave"],
+  },
+  {
+    id: "young-dragon",
+    name: "Young Dragon",
+    type: "dragon",
+    challengeRating: 6,
+    tags: ["flying", "boss", "fire"],
+  },
+];
+
+export function listMonsters() {
+  return [...monsters];
+}
+
+export function getMonsterById(id) {
+  return monsters.find((monster) => monster.id === id) ?? null;
+}

package/src/modules/spells.js

@@ -0,0 +1,22 @@
+const spells = [
+  {
+    id: "magic-missile",
+    name: "Magic Missile",
+    level: 1,
+    school: "evocation",
+  },
+  {
+    id: "fireball",
+    name: "Fireball",
+    level: 3,
+    school: "evocation",
+  },
+];
+
+export function listSpells() {
+  return [...spells];
+}
+
+export function getSpellById(id) {
+  return spells.find((spell) => spell.id === id) ?? null;
+}

package/src/tools/dice.js

@@ -0,0 +1,35 @@
+const DICE_PATTERN = /^(\d*)d(\d+)([+-]\d+)?$/i;
+
+export function parseDiceExpression(expression) {
+  const cleaned = String(expression).trim();
+  const match = cleaned.match(DICE_PATTERN);
+
+  if (!match) {
+    throw new Error(`Invalid dice expression: ${expression}`);
+  }
+
+  const count = match[1] ? Number(match[1]) : 1;
+  const sides = Number(match[2]);
+  const modifier = match[3] ? Number(match[3]) : 0;
+
+  return { count, sides, modifier };
+}
+
+export function rollDice(expression, randomFn = Math.random) {
+  const { count, sides, modifier } = parseDiceExpression(expression);
+  let total = modifier;
+  const rolls = [];
+
+  for (let index = 0; index < count; index += 1) {
+    const roll = Math.floor(randomFn() * sides) + 1;
+    rolls.push(roll);
+    total += roll;
+  }
+
+  return { expression, rolls, modifier, total };
+}
+
+export function averageRoll(expression) {
+  const { count, sides, modifier } = parseDiceExpression(expression);
+  return count * ((sides + 1) / 2) + modifier;
+}