dice-core 2026-02-16
Initialize dice-core library with 3D physics simulation, React Three Fiber components, and secure throw system
114 files · 16,001+ · 6,971-

Core simulation engine

instantiate architectural
7 files changed
  • pre-simulate.ts Deterministic physics pre-simulation using Rapier with seeded RNG for reproducible dice rolls
  • playback.ts Frame-by-frame playback system that replays pre-simulated physics results
  • spawn-configs.ts Dice spawn position, rotation, and velocity configuration
  • pre-simulate-async.ts Async wrapper for pre-simulation with cancellation support
  • pre-simulate-worker.ts Web worker for offloading pre-simulation to a background thread
  • quat-math.ts Quaternion math utilities for orientation calculations
  • seeded-rng.ts Seeded random number generator for deterministic simulation
  • Built a deterministic physics pre-simulation engine using Rapier that produces reproducible dice rolls via seeded RNG, with async and web worker execution options instantiate architectural
    3 files
    • pre-simulate.ts
    • pre-simulate-async.ts
    • seeded-rng.ts

React Three Fiber components

instantiate architectural
8 files changed
  • DiceArena.tsx Main arena component managing dice rolls, Rapier initialization, camera, and orchestration
  • DiceScene.tsx Scene component handling simulation execution, settlement detection, and result reporting
  • DiceRoller.tsx Roller component triggering dice throws with notation parsing
  • Die.tsx Individual die component for live physics interaction
  • PlaybackDie.tsx Die component for frame-by-frame playback of pre-simulated results
  • Chamber.tsx Invisible physics boundaries containing dice within the arena
  • DiceLighting.tsx Configurable lighting setup for the dice scene
  • ErrorBoundary.tsx React error boundary with WebGL context loss recovery
  • Created a full React Three Fiber component hierarchy: DiceArena orchestrates DiceScene which manages Die/PlaybackDie instances within a Chamber with configurable DiceLighting instantiate architectural
    3 files
    • DiceArena.tsx
    • DiceScene.tsx
    • DiceRoller.tsx

Dice geometry and face reading

instantiate behavioral
6 files changed
  • geometry-data.ts Geometry definitions for all standard dice types (D4/D6/D8/D10/D12/D20/D100)
  • face-reader.ts Face value determination from die orientation using normal vector alignment
  • notation-parser.ts Dice notation parser supporting standard formats like 2d6+3, 1d20, etc.
  • custom-geometry.ts Custom geometry support for non-standard dice
  • textures.ts Texture generation for dice face numbering
  • modifiers.ts Dice roll modifier application (bonuses, penalties, advantage)
  • Implemented geometry data, face reading via normal alignment, notation parsing, and texture generation for all standard polyhedral dice types instantiate behavioral
    3 files
    • geometry-data.ts
    • face-reader.ts
    • notation-parser.ts

Configuration and types

instantiate behavioral
4 files changed
  • defaults.ts Default configuration values for physics, rendering, and arena settings
  • dice-configs.ts Per-die-type configuration (size, mass, restitution)
  • config.ts TypeScript interfaces for all configuration options
  • dice.ts Dice type definitions and enums
  • Defined comprehensive configuration defaults and TypeScript types for physics, rendering, arena, and per-die-type settings instantiate behavioral
    2 files
    • defaults.ts
    • config.ts

Visual system

instantiate behavioral
4 files changed
  • die-meshes.ts Three.js mesh creation for dice with materials and textures
  • chamber-meshes.ts Arena boundary mesh generation
  • face-data.ts Face positioning and UV data for all dice types
  • die-visuals.tsx Visual component for rendering dice with glow and effects
  • Built a vanilla Three.js visual layer with mesh factories, chamber boundaries, face data, and a die-visuals component with glow effects instantiate behavioral
    3 files
    • die-meshes.ts
    • chamber-meshes.ts
    • die-visuals.tsx

Bug fixes across 8 iterations

harden behavioral
1 file changed
  • rapier-init.ts Rapier WASM initialization with retry logic
  • Fixed number plane offset and depth clipping on D10/D12 dice, WebGL context loss crashes, D10 secure throw face value remapping, multi-dice spawn logic, pre-simulation arena containment, and die settling detection harden behavioral
    4 files
    • DiceArena.tsx
    • DiceScene.tsx
    • Die.tsx
    • PlaybackDie.tsx

Testing and CI

qualify behavioral
4 files changed
  • ci.yml CI workflow for linting, testing, and building
  • dice-roll.spec.ts E2E dice roll tests with Playwright
  • physics-parity.spec.ts Physics parity tests between simulation and playback
  • public-api.test.ts Public API surface tests
  • Added CI workflow, Playwright E2E tests for dice rolling and physics parity, and comprehensive unit tests for the public API, face reader, notation parser, and simulation engine qualify behavioral
    3 files
    • ci.yml
    • dice-roll.spec.ts
    • public-api.test.ts

Build and tooling

baseline internal
5 files changed
  • vite.config.ts Vite build configuration for library output
  • eslint.config.js ESLint configuration
  • .prettierrc Prettier formatting rules
  • pre-commit Pre-commit hook for linting
  • index.html Vanilla HTML example demonstrating dice-core usage
  • Configured Vite for library builds, added ESLint/Prettier/Husky tooling, and created a vanilla HTML example baseline internal
    3 files
    • vite.config.ts
    • eslint.config.js
    • index.html
changelog → 2026-02-27 dice-core →