DiceTales

DiceTales Setup Guide

Get DiceTales running in less than 5 minutes! This streamlined guide covers everything from local play to development setup.

🚀 Quick Start

Option 1: Play Online (Easiest)

Simply open index.html in your browser and start playing immediately - no setup required!

Option 2: Download and Play Locally

  1. Download the repository 
    git clone https://github.com/AsleshSura/DiceTales.git
cd DiceTales
  2. Open in browser
    • Double-click index.html, or
    • Open index.html in any modern web browser
  3. Start playing!
    • Click “New Game” to begin your adventure
    • The AI will generate your story in real-time using HuggingFace models

📋 Requirements

Minimum Requirements

🔧 Development Setup

For Local Development

  1. Clone the repository 
    git clone https://github.com/AsleshSura/DiceTales.git
cd DiceTales
  2. Serve files locally (recommended for development) 
    # Using Python 3
python -m http.server 8000
   
# Using Python 2
python -m SimpleHTTPServer 8000
   
# Using Node.js
npx serve .
   
# Using PHP
php -S localhost:8000
  3. Open in browser Navigate to http://localhost:8000

Why Use a Local Server?

🎮 First Time Setup

1. Character Creation

When you first start DiceTales:

  1. Choose your character stats - Distribute points among:
    • Strength: Physical power and melee combat
    • Dexterity: Agility, stealth, and ranged combat
    • Constitution: Health, stamina, and endurance
    • Intelligence: Knowledge, reasoning, and magic
    • Wisdom: Perception, insight, and willpower
    • Charisma: Social skills and leadership

  2. Set your character name - This will appear in your adventure

  3. Choose difficulty (optional):
    • Beginner: More forgiving dice rolls
    • Standard: Balanced gameplay
    • Expert: Challenging experience

2. Understanding the Interface

┌─────────────────────────────────────────┐
│             Story Area                  │
│  (HuggingFace AI narrative appears here)│
├─────────────────────────────────────────┤
│             Choice Buttons              │
│  [Option 1] [Option 2] [Option 3] [...]  │
├─────────────────────┬───────────────────┤
│    Character Stats  │    Dice Area      │
│  STR: 14  INT: 12   │   Roll D20     │
│  DEX: 16  WIS: 10   │   [Turn Result]   │
│  CON: 13  CHA: 11   │   "Turn Active"   │
│  HP: 15/15 XP: 0    │                   │
└─────────────────────┴───────────────────┘

3. Turn-Based Game Controls

Action Method Notes
Make Choice Click any choice button Progresses story
Roll Dice Click dice when available One roll per turn only
View Stats Always visible in bottom-left Updates automatically
Save Game Automatic (LocalStorage) Saves after each action
Load Game Refresh page and click “Continue” Restores last state
New Game Click “New Game” button Starts fresh adventure

4. Turn System (New in v2.0)

🌐 Deployment Options

GitHub Pages (Free)

  1. Fork the repository on GitHub
  2. Go to Settings → Pages
  3. Select “Deploy from a branch” → “main”
  4. Your game will be available at https://yourusername.github.io/DiceTales/

Netlify (Free)

  1. Create account at netlify.com
  2. Drag the DiceTales folder to the deploy area
  3. Your game gets a unique URL instantly

Vercel (Free)

  1. Install Vercel CLI: npm i -g vercel
  2. In the DiceTales directory: vercel
  3. Follow the prompts for instant deployment

Self-Hosted

Upload all files to any web server that serves static files:

🔧 Configuration Options

HuggingFace AI Settings

Edit advanced/js/ai.js to customize AI behavior:

// Model configuration (models tried in order)
const AI_CONFIG = {
    HF_MODELS: [
        'microsoft/GODEL-v1_1-large-seq2seq',
        'microsoft/DialoGPT-large',
        'facebook/blenderbot-400M-distill',
        'microsoft/DialoGPT-medium'
    ]
};

// Response settings
const MAX_NEW_TOKENS = 150;
const TEMPERATURE = 0.8;
const TOP_P = 0.9;

Note: DiceTales uses advanced HuggingFace models with intelligent fallback responses for reliability.

Audio Settings

Edit advanced/js/audio.js to customize sound effects:

🐛 Troubleshooting

Common Issues

“AI Error: Unable to generate story” message

“Cannot roll dice” (dice appears disabled)

“Game won’t load”

“Choices not appearing”

“Game state not saving”

HuggingFace-Specific Issues

“Model loading failed” errors

Slow AI responses

Getting Help

  1. Check the console (F12) for error messages
  2. Try a different browser to isolate issues
  3. Clear cache and cookies for the site
  4. Disable extensions that might interfere
  5. Report bugs on the GitHub repository

⚡ Performance Tips

For Best Experience

For Developers

Turn-Based Strategy Tips

Need more help? Check out the Game Guide for gameplay tips or Technical Overview for development details.