aether-dice 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 AetherDice contributors
+
+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,174 @@
+# AetherDice
+
+A standalone, framework-agnostic **3D dice roller** for the browser. Renders
+`d4 · d6 · d8 · d10 · d12 · d20 · d100` as a physics-driven, transparent canvas overlay
+— and **settles each die on a value you supply**, so the visual always matches whatever
+your app's logic already decided.
+
+Built to be dropped into any web app (including no-build, vanilla-ESM ones) as a single
+prebuilt module + assets.
+
+> AetherDice is a **presentation layer**. It does not roll randomly or do dice math —
+> your app owns the RNG and modifiers; AetherDice shows the given face values with a
+> believable tumble.
+
+## Features
+
+- All standard polyhedral dice + `d100` (as tens/units d10s, with percentile mode).
+- **Deterministic results** — pass the exact value each die must land on.
+- Physics-based tumble (Three.js + cannon-es) with a guaranteed final face.
+- Mixed throws in one roll (e.g. `1d20 + 2d6`).
+- Themeable with **real HDR edge bloom** — `aether` (glowing cyan default), `aether-neon`,
+  `aether-molten`, `classic`, or your own.
+- Respects `prefers-reduced-motion`; instant/skip mode; WebGL-absent fallback signal.
+- Ships as one ESM bundle + assets; no framework dependency.
+
+## Install
+
+```bash
+npm install aether-dice
+```
+
+Or load directly (no build step) via CDN:
+
+```js
+import { AetherDice } from 'https://cdn.jsdelivr.net/npm/aether-dice/dist/aether-dice.esm.js';
+```
+
+## Quick start
+
+```js
+import { AetherDice } from 'aether-dice';
+
+const dice = new AetherDice({
+  container: document.getElementById('dice-overlay'), // a positioned element
+  assetPath: '/assets/aether-dice/',                  // where textures/wasm live
+  theme: 'aether',
+});
+
+await dice.init();
+
+// The outcome is decided by YOUR app; AetherDice just renders it:
+const result = await dice.roll(
+  [{ sides: 20 }, { sides: 6 }, { sides: 6 }],
+  { results: [17, 4, 2] },
+);
+// → { dice: [{sides:20,value:17}, {sides:6,value:4}, {sides:6,value:2}], total: 23 }
+```
+
+## API
+
+### `new AetherDice(options)`
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `container` | `HTMLElement` | — | Element the canvas overlay mounts into (required). |
+| `assetPath` | `string` | — | Base URL for textures/wasm assets. |
+| `theme` | `string \| object` | `'aether'` | Built-in theme name or a theme object. |
+| `scale` | `number` | `6` | Die size. |
+| `gravity` | `number` | `40` | Physics gravity. |
+| `throwForce` | `number` | `8` | Initial impulse strength. |
+| `reducedMotion` | `boolean` | auto | `true` skips the tumble and shows the result instantly. Defaults to the user's `prefers-reduced-motion`. |
+| `maxDice` | `number` | `20` | Safety cap on dice per roll. |
+
+### Methods
+
+- `await dice.init()` — load the engine + assets; resolves when ready.
+- `await dice.roll(dice, opts)` — render a roll. `dice` is a notation string
+  (`'2d8'`) or an array (`[{ sides: 20 }, …]`). `opts.results` is the array of values
+  each die must land on (**always pass this from a game**). `opts.instant` skips the
+  tumble for this call. Resolves to `{ dice: [{ sides, value }], total }`.
+- `dice.clear()` — remove dice from the scene.
+- `dice.destroy()` — dispose all GPU resources (call on unmount).
+- `dice.on(event, handler)` / `dice.off(event, handler)`.
+
+### Events
+
+| Event | Payload | When |
+|---|---|---|
+| `rollStart` | `{ dice }` | A roll begins. |
+| `rollComplete` | `{ dice, total, text }` | Dice settle. `text` is the readable result (use it for logs / screen readers). |
+| `webglUnavailable` | `{}` | WebGL can't initialize — fall back to a 2D presentation. |
+
+## Determinism (the important part)
+
+If you omit `results`, AetherDice may roll randomly and return the landed values — handy
+for demos. **In a real game, always pass `results`** so the rendered dice match your
+authoritative roll. Internally the tumble runs with a random throw, then a corrective
+rotation guarantees the requested face ends up. The result is *also* delivered as text
+via `rollComplete`, so the visual is never the only source of truth.
+
+## Theming
+
+Pass a built-in theme name or a theme object. A theme object is merged over the `aether`
+default, so you only specify what you want to change:
+
+```js
+new AetherDice({ theme: 'aether-neon' });          // built-in name
+
+new AetherDice({ theme: {                          // custom (merged over aether)
+  dieColor:      '#10131a',   // body color
+  edgeGlow:      '#39d0ff',   // edge color (base hue of the glow)
+  numberColor:   '#eaf6ff',   // numeral color
+  numberFont:    '600 220px "Trebuchet MS", system-ui, sans-serif',
+  metalness:     0.2,
+  roughness:     0.35,
+  opacity:       0.92,         // <1 → translucent body
+  ambient:       '#22303a',    // ambient light color
+  keyLight:      '#ffffff',    // key (directional) light color
+  bloom:         true,         // enable the edge bloom post-process
+  edgeIntensity: 2.2,          // HDR edge multiplier (>1 → brighter, punchier glow)
+  bloomStrength: 1.5,          // overall bloom amount
+  bloomRadius:   0.6,          // bloom spread
+  bloomThreshold:0,            // luminance cutoff (0 = bloom all edge light)
+}});
+```
+
+### Built-in themes
+
+| Preview | Name | Look |
+|---|---|---|
+| <img src="https://raw.githubusercontent.com/BeastPhoenix/aether-dice/v0.1.0/docs/images/theme-aether.png" width="150" alt="aether theme"> | `aether` (default) | Dark dice, glowing cyan edges, light numerals. |
+| <img src="https://raw.githubusercontent.com/BeastPhoenix/aether-dice/v0.1.0/docs/images/theme-aether-neon.png" width="150" alt="aether-neon theme"> | `aether-neon` | Deep violet body, searing magenta-purple edge glow. |
+| <img src="https://raw.githubusercontent.com/BeastPhoenix/aether-dice/v0.1.0/docs/images/theme-aether-molten.png" width="150" alt="aether-molten theme"> | `aether-molten` | Dark ember body, hot orange edge glow, warm numerals. |
+| <img src="https://raw.githubusercontent.com/BeastPhoenix/aether-dice/v0.1.0/docs/images/theme-classic.png" width="150" alt="classic theme"> | `classic` | Ivory/black, no glow. |
+
+### Edge bloom (the glow is real)
+
+The edge glow is a true **bloom** post-process, not a flat outline. It uses *selective*
+bloom — only the die edges glow, never the body or numerals — and the edge color is pushed
+into **HDR** (`edgeIntensity` > 1) so the brightest part of each edge blows out to a
+white-hot core with a saturated colored halo, like neon. Two knobs shape it:
+
+- `edgeIntensity` — how over-bright the edge *source* is (character of the glow).
+- `bloomStrength` / `bloomRadius` — how much the glow *spreads* (amount and softness).
+
+Set `bloom: false` (as `classic` does) to skip the post-processing pipeline entirely — the
+edges then render as a plain line, or are omitted if `edgeGlow` is transparent.
+
+## Supported dice
+
+`d4, d6, d8, d10, d12, d20, d100`. The `d4` is read by its apex/bottom convention; `d100`
+renders as a tens die (`00–90`) + a units die (`0–9`) and can combine to a percentile.
+
+## Development
+
+```bash
+npm install
+npm run dev      # demo page with live reload
+npm test         # unit tests (value resolution, d4/d100, corrective orientation)
+npm run build    # emits dist/aether-dice.esm.js + assets/
+```
+
+The `/demo` page rolls every die type, mixed throws, and lets you force a predetermined
+result to verify determinism.
+
+## Distribution
+
+Published to npm and consumable via jsDelivr. The public API above is the semver
+stability contract. Ship `dist/aether-dice.esm.js` + `assets/`; consumers point
+`assetPath` at the hosted assets.
+
+## License
+
+MIT.

package/SPEC.md

@@ -0,0 +1,160 @@
+# AetherDice — Technical Specification
+
+A standalone, framework-agnostic **3D dice roller** for the browser, built to be
+developed in its own GitHub repo and consumed by Chronicles of Aethermoor (and any
+other web app) as a prebuilt ES module.
+
+> **Suggested identity:** repo `aether-dice`, npm package `aether-dice`, default
+> theme `aether` (glowing edges to match Aethermoor's sci-fi/fantasy look).
+
+---
+
+## 1. Purpose & non-goals
+
+**Purpose:** render a physics-driven 3D dice roll as a transparent overlay, and
+**settle each die on a caller-supplied value** (the consuming app owns the RNG and
+math; the library only *shows* results).
+
+**Non-goals:**
+- No dice-notation math (no `+3` modifiers, no advantage logic). The app computes the
+  result; the library renders the given face values. This keeps the library a pure
+  presentation layer.
+- No game logic, no UI chrome beyond the canvas.
+- No framework coupling (no React/Vue dependency).
+
+---
+
+## 2. The critical requirement: deterministic results
+
+This is the feature that justifies building it and the part most DIY dice fail.
+
+- The caller passes the exact value(s) each die must end on: `roll(dice, { results })`.
+- The library runs a physics tumble for *feel*, then **guarantees** the final upward
+  face matches the requested value.
+
+**Recommended technique:** run the physics simulation with a randomized throw; when a
+die comes to rest, read its landed top face; if it differs from the target, apply a
+short corrective quaternion tween that rotates the die so the **target face's normal
+points to world-up** (about the resting vertical axis to keep it natural). This yields
+believable tumbling with a guaranteed outcome.
+
+Each die geometry ships with a **face → value map** and per-face outward normals. Note
+the **d4 special case**: a tetrahedron is read from the bottom/apex convention, not a
+top face — handle its value resolution separately.
+
+WebGL unavailable, or `reducedMotion`/`instant` requested → **skip the tumble** and
+present the result immediately (or emit an event so the app can fall back to 2D).
+
+---
+
+## 3. Supported dice
+
+`d4, d6, d8, d10, d12, d20`, plus `d100` (rendered as two d10s: a tens die `00–90` and
+a units die `0–9`, with a percentile-combine mode). Mixed rolls in one throw are
+supported (e.g. `1d20 + 2d6`).
+
+---
+
+## 4. Tech stack (recommended)
+
+| Concern | Choice | Notes |
+|---|---|---|
+| Renderer | **Three.js** (ESM) | Well-documented, tree-shakeable. Babylon.js is a valid alternative. |
+| Physics | **cannon-es** | Lightweight, ESM, maintained. (rapier-wasm if more accuracy is wanted.) |
+| Build | **Vite** (library mode) or Rollup | Emits a single `dist/aether-dice.esm.js` + assets. |
+| Geometry | Procedural polyhedra + UV-mapped number textures | Generate at build or runtime; cache. |
+
+The library owns its bundler — that is the whole point of the separate repo. The game
+never sees Three.js as a dependency; it loads one built ESM file.
+
+---
+
+## 5. Public API (framework-agnostic, promise-based)
+
+```js
+import { AetherDice } from 'aether-dice';
+
+const dice = new AetherDice({
+  container:    document.getElementById('dice-overlay'), // a positioned element
+  assetPath:    'https://cdn.example/aether-dice/assets/',
+  theme:        'aether',     // built-in theme name or a theme object
+  scale:        6,            // die size
+  gravity:      40,
+  throwForce:   8,
+  reducedMotion:false,        // true → no tumble, show result instantly
+  maxDice:      20,           // safety cap
+});
+
+await dice.init();            // loads engine + assets; resolves when ready
+
+// Render a roll whose outcome is already decided by the caller:
+const result = await dice.roll(
+  [{ sides: 20 }, { sides: 6 }, { sides: 6 }],
+  { results: [17, 4, 2] }     // each die settles on these faces, in order
+);
+// result === { dice: [{sides:20,value:17}, {sides:6,value:4}, {sides:6,value:2}], total: 23 }
+
+dice.roll('2d8', { results: [5, 8] });   // dice-notation string form also accepted
+dice.clear();                            // remove dice from the scene
+dice.on('rollStart' | 'rollComplete' | 'webglUnavailable', handler);
+dice.destroy();                          // dispose geometries, materials, renderer
+```
+
+Behavioral contract:
+- If `results` is omitted, the library may roll randomly (useful for demos) and return
+  the landed values — but the **consuming game must always pass `results`**.
+- `instant: true` per-call, or global `reducedMotion`, skips animation.
+- All GPU resources are disposed on `destroy()`; one renderer instance per `AetherDice`.
+
+---
+
+## 6. Theming
+
+A theme defines: die material/color, edge glow, number (pip) color/font, environment
+lighting, and optional custom textures (via `assetPath`). Ship at least:
+- `aether` (default) — dark dice, glowing cyan edges, light numerals.
+- `classic` — ivory/black for a traditional look.
+
+Custom themes are plain objects passed to the constructor.
+
+---
+
+## 7. Accessibility & performance
+
+- Honor `prefers-reduced-motion` automatically (overridable).
+- Emit the textual result via `rollComplete` so the app can log it / announce it to
+  screen readers — **the visual is never the only channel for the result**.
+- Pause/idle the render loop when no dice are active; cap dice count (`maxDice`).
+- Lazy-initializable: `init()` is async so the consuming app can defer the heavy load
+  until 3D dice are actually enabled.
+
+---
+
+## 8. Distribution & versioning
+
+- Publish to **npm** as `aether-dice` and/or attach a built bundle to GitHub releases
+  consumable via **jsDelivr** (e.g. `https://cdn.jsdelivr.net/npm/aether-dice/dist/aether-dice.esm.js`).
+- Ship `dist/aether-dice.esm.js` (single file) + an `assets/` folder (textures, any
+  wasm). Document the `assetPath` the consumer must point at.
+- Semantic versioning. The **public API in §5 is the stability contract**.
+
+---
+
+## 9. Deliverables (definition of done)
+
+- The library + Vite/Rollup library-mode build emitting the ESM bundle + assets.
+- A **standalone demo page** (`/demo`) rolling every die type and mixed throws, with a
+  field to force a predetermined result (proves §2).
+- Unit tests for the value-resolution math (face→value, d4 convention, d100 combine)
+  and the corrective-orientation logic.
+- Docs: `README.md` (install + the §5 API), and a `CLAUDE.md`/`AGENTS.md` for the repo.
+- MIT license.
+
+## 10. Acceptance criteria
+
+1. Every die type renders and **always settles on the requested value** across 100+
+   randomized throws (automated check on the resolution logic).
+2. `reducedMotion`/`instant` and WebGL-absent paths present the result with no tumble.
+3. Consumable from a no-build host via a single ESM import + `assetPath` (proven by the
+   game's integration — see `INTEGRATION.md`).
+4. `destroy()` leaks no GPU resources (verify in a mount/unmount loop).