Dice Roller — Complete Documentation

Free online dice roller by Uplup. Roll up to 1,000 dice at once with realistic 3D animations. Supports d4 through d20, advanced statistics, and CSV/TXT export.

Overview
Getting Started
Rolling Dice
Customization
Results & Statistics
Animation & Rendering
Live / Full-Screen Mode
Saving Configurations
Probability Education
Platform Statistics
API Reference
FAQ

1. Overview

The Uplup Dice Roller is a free, ad-free virtual dice tool with:

d4 through d20 — 4, 6, 8, 10, 12, 14, 16, 18, and 20-sided dice
Up to 1,000 dice per roll
Realistic 3D animation with multi-stage bounce physics
10 color themes — pastel and vibrant options
4 dice sizes — small, medium, large, extra-large
Advanced statistics — distribution charts, expected vs actual, most/least common
CSV and TXT export — download complete roll history
Save configurations — logged-in users can save and load setups
Full-screen mode — presentation-ready live mode
Probability education — interactive lessons on uniform distribution, law of large numbers, and more

URL: uplup.com/dice-roller

2. Getting Started

Visit uplup.com/dice-roller
Click the dice or press Space to roll
Results appear in the table with sum and timestamp
Adjust dice count, type, size, and theme via the Customize button

No account required. Settings persist in browser cookies for 365 days.

3. Rolling Dice

3.1 Basic Roll

Click the dice display area or the Roll button to roll. The dice animate with realistic 3D physics and land on random values.

Roll flow:

Click to trigger roll
Dice spin with random rotation (4-10 spins per axis)
Easing: cubic ease-out for natural deceleration
Bounce animation (5 phases: 25px → 15px → 8px → 3px → 1px)
Wobble effect with dampening
Final value displayed
Result added to history table

Roll duration: 1.5 to 3 seconds per die (randomized per die for staggered finishes).

3.2 Dice Types (d4–d20)

Dice	Sides	Use Case
d4	4	Damage rolls (D&D daggers)
d6	6	Standard dice, board games
d8	8	Damage rolls (D&D longswords)
d10	10	Percentile rolls
d12	12	Damage rolls (D&D greataxes)
d14	14	Specialty games
d16	16	Specialty games
d18	18	Specialty games
d20	20	Attack rolls, saving throws (D&D)

Each die type has unique dot/pip layouts for every face value, defined in dotPositions.ts. Dots are positioned on a 9×9 grid and rendered as colored circles.

Set the dice type using the Number of Sides slider in the Customize modal (step: 2, range: 4–20).

3.3 Multiple Dice (1–1,000)

Roll multiple dice simultaneously:

UI limit: 1–100 dice (input + range slider in Customize modal)
Backend support: Up to 1,000 dice
All dice animate independently with randomized durations
Results show individual values plus sum total
Each die completes at a different time for a natural staggered effect

3.4 Keyboard Shortcuts

Shortcut	Action
Space	Roll dice
Ctrl + U	Undo last roll
Ctrl + Shift + C	Clear all results (with confirmation)
Esc	Exit full-screen mode

4. Customization

Open the Customize modal via the button in the navigation bar.

4.1 Number of Dice

Text input: type a number (1–100)
Range slider: drag to select
Both inputs sync in real-time

4.2 Number of Sides

Range slider only (step: 2)
Options: 4, 6, 8, 10, 12, 14, 16, 18, 20
Current value displayed below the slider

4.3 Dice Size

Size	Pixel Dimension
Small	30px
Medium	60px
Large	120px (default)
Extra Large	240px

Button group selector — active button highlighted in coral (#E8604C).

4.4 Dice Themes

10 pastel color themes:

Theme	Name	Dice Color	Dot Color
1	Pastel Pink	#FFD1DC	#5A3E36
2	Lavender	#E0BBE4	#4A3F55
3	Mint	#B5EAD7	#3A6D5C
4	Peach	#FFDAC1	#5C3A21
5	Pastel Blue	#C7CEEA	#3E3C6B
6	Lemon	#F7E8A4	#665A2E
7	Rose	#FF9AA2	#671E26
8	Seafoam	#D4F1F4	#3A5A5B
9	Light Yellow	#FFF1B6	#645E1B
10	Light Green	#E2F0CB	#4C5C2E

Themes are selectable as a 3-column grid with color preview circles. Also accessible via the quick theme picker in the navigation bar.

4.5 Title Display

When a configuration is saved, toggle Show Title to display the configuration name above the dice area.

5. Results & Statistics

5.1 Results Table

Column	Description
Roll #	Sequential roll number (newest first)
Results	Individual die values (comma-separated)
Sum	Total of all dice in the roll
Time	Timestamp (HH:MM:SS format)
Actions	Delete button (trash icon)

The table is reverse-chronological (most recent roll at top). Each row can be individually deleted.

5.2 Roll Summary

Always-visible statistics:

Stat	Description	Formula
Total Rolls	Number of roll actions	Count of results
Dice Rolled	Total individual dice	Sum of all dice per roll
Expected Average	Theoretical mean	(sides + 1) / 2
Actual Average	Observed mean	Sum of all values / count

5.3 Distribution Analysis

Horizontal bar chart showing the frequency of each face value:

Per-number count and percentage
Most Common number with count and %
Least Common number with count and %
Expected per face percentage (1/sides × 100)
Deviation from Expected — how far actual differs from theoretical

Bar color: coral (#E8604C)

5.4 Export (CSV & TXT)

CSV Export (dice-roll-results-YYYY-MM-DD.csv):

Roll #,Results,Sum,Timestamp
1,"3, 5, 2",10,"3/25/2026, 2:45:30 PM"
2,"6, 1, 4",11,"3/25/2026, 2:45:35 PM"

Summary
Total Rolls,2
Total Dice Rolled,6
Expected Average,3.5
Actual Average,3.5

Distribution
Number,Count,Percentage
1,1,16.7%
2,1,16.7%
...

TXT Export (dice-roll-results-YYYY-MM-DD.txt):

DICE ROLL RESULTS
═══════════════════════════════════════
Roll #1: 3, 5, 2 (Sum: 10) - 2:45:30 PM
Roll #2: 6, 1, 4 (Sum: 11) - 2:45:35 PM
═══════════════════════════════════════
SUMMARY
Total Rolls: 2
Total Dice Rolled: 6
...

6. Animation & Rendering

3D Physics

Each die is a div element with CSS 3D transforms:

Spin Phase (1.5–3s):

Random rotation: 4-10 full spins per axis (X, Y, Z)
Random direction per axis (clockwise or counter-clockwise)
Oscillating X/Y offsets for movement
Vertical arc (sine wave trajectory)
Scale variation: 1 ± 0.1
Box shadow during roll: 0 8px 16px rgba(0,0,0,0.3)

Bounce Phase (0.6–1s):

5 decreasing bounces: 25px → 15px → 8px → 3px → 1px
Quadratic settling rotation (dampening wobble)
8 Hz sine wobble that decays with time
Scale effect during each bounce

Performance:

requestAnimationFrame for smooth 60fps
will-change: transform optimization during animation
transform-style: preserve-3d for 3D rendering
Hydration-safe (mounted flag prevents SSR mismatch)

7. Live / Full-Screen Mode

Enter presentation mode via the Full Screen button.

Features:

Dice centered on screen with dark background
All UI hidden (navigation, sidebar, results)
Roll counter displayed top-left
Title displayed top-center (if configured)
Intercom widget hidden via CSS
Escape key to exit

Ideal for: tabletop game nights, classroom probability demonstrations, live streams.

8. Saving Configurations

Cookie Persistence (All Users)

All settings automatically saved to browser cookies (365-day expiry):

Number of dice, dice type, dice size, theme
Title, show title toggle
Complete roll history

Server Persistence (Logged-In Users)

Create a free account to save configurations to the cloud:

Auto-save after each roll
Manual save via the Save button
Load configurations via URL parameter: ?config_id=abc123
Delete configurations (soft delete)

Save payload: includes all settings plus the full results array.

9. Probability Education

Six interactive educational cards covering:

Topic	Key Concept
Uniform Distribution	Each face has equal 1/n probability. For a d6: 16.67% per face.
Law of Large Numbers	As rolls increase, actual percentages converge to expected values. Try 10 → 100 → 1,000 rolls.
Independent Events	Each roll is independent — no “memory.” The Gambler’s Fallacy explained.
Sum Probabilities	With 2+ dice, sums follow a bell curve. For 2d6, 7 is most common (6 combinations).
Expected Value	Formula: (1 + 2 + … + n) / n. For a d6: 3.5. For 3d6: 10.5.
Polyhedral Dice	D&D context: d4 (daggers), d8 (longswords), d12 (greataxes), d20 (attack rolls).

Use case banner:

Gamers & Game Designers
Students & Teachers
Researchers (Monte Carlo simulations)
Data Analysis

10. Platform Statistics

The landing page displays global usage stats (cached every 5 minutes):

Stat	Description
Total Rolls (24h)	Roll actions in the past 24 hours
Total Rolls (30d)	Roll actions in the past 30 days
Total Dice Rolled (24h)	Individual dice rolled in 24 hours
Total Dice Rolled (30d)	Individual dice rolled in 30 days

Tab selector switches between 24-hour and 30-day views.

11. API Reference

Endpoints

Method	Route	Auth	Description
`POST`	`/api/v2/dice/roll`	None	Roll dice (cryptographic random)
`POST`	`/api/v2/dice/configurations`	Required	Save/update configuration
`GET`	`/api/v2/dice/configurations/{id}`	Required	Load configuration
`POST`	`/api/v2/dice/configurations/delete`	Required	Delete configuration
`POST`	`/api/v2/dice/track`	None	Anonymous analytics tracking
`GET`	`/api/v2/dice/stats`	None	Cached platform statistics

Roll Dice (`POST /api/v2/dice/roll`)

// Request
{ "num_dice": 3, "num_sides": 6 }

// Response
{
  "success": true,
  "data": {
    "rolls": [3, 5, 2],
    "total": 10,
    "num_dice": 3,
    "num_sides": 6,
    "timestamp": "2026-03-25T14:30:00.000Z"
  }
}

Uses System.Security.Cryptography.RandomNumberGenerator.GetInt32() for fair results.

12. FAQ

Q: Is the dice roller free?
A: Yes. 100% free, no ads, no signups, no limits.

Q: Are the rolls truly random?
A: Yes. The backend uses System.Security.Cryptography.RandomNumberGenerator for cryptographically secure random numbers. The frontend also uses JavaScript’s random number generator for the animation.

Q: How many dice can I roll at once?
A: Up to 100 in the UI, up to 1,000 via the API.

Q: What dice types are supported?
A: d4, d6, d8, d10, d12, d14, d16, d18, and d20 (4 through 20 sides, even numbers).

Q: Can I export my results?
A: Yes. Export as CSV (for spreadsheets) or TXT (human-readable) with full roll history, summary statistics, and distribution data.

Q: Can I save my setup?
A: Yes. Create a free account to save configurations to the cloud. Without an account, settings persist in browser cookies for 365 days.

Q: Does it work on mobile?
A: Yes. Fully responsive with touch-friendly controls.

Q: Can I use this for D&D?
A: Absolutely. Supports all standard polyhedral dice (d4, d6, d8, d10, d12, d20) used in Dungeons & Dragons and other tabletop RPGs.

This document covers every feature, option, and capability of the Uplup Dice Roller as of March 25, 2026.