⚡ tsDice Quick Reference

Fast lookup for developers and power users

🎯 At a Glance

┌──────────────────────────────────────────────────────┐
│  tsDice: tsParticles Random Configuration Generator  │
│  • 16 JavaScript modules (13 core + constants)       │
│  • 17 keyboard shortcuts                             │
│  • 111 Vitest specs with 76% coverage                │
│  • Infinite undo history                             │
│  • Production build: 46 KB (gzipped)                 │
└──────────────────────────────────────────────────────┘

🔤 Keyboard Shortcuts

Shuffle Commands

Toggles

Navigation

Utilities

Easter Egg

📁 File Structure

tsdice/
├── index.html                  # Main app + inline styles
├── package.json                # Dependencies & scripts
├── README.md / ANALYSIS.md     # High-level + deep-dive docs
├── ARCHITECTURE.md             # Technical deep dive
├── USER_GUIDE.md / QUICK_REFERENCE.md
├── CHANGELOG.md / CONTRIBUTING.md / CODE_OF_CONDUCT.md / SECURITY.md
├── vite.config.js / vitest.config.js
├── styles/                     # variables.css + components.css
├── tests/                      # Vitest specs + setup + README
├── coverage/                   # HTML reports from `npm run test:coverage`
└── js/
    ├── main.js                 # Orchestrator (830 lines)
    ├── state.js                # State container
  ├── errorHandler.js         # Typed, centralized error handling
  ├── stateManager.js         # Dispatch-based state management
  ├── constants/              # Modular constants (UI, colors, particles)
    │   ├── ui.js              # UI constants
    │   ├── particles.js       # Particle config
    │   └── colors.js          # Color palettes
    ├── constants.js            # Barrel export
    ├── utils.js                # Helpers
    ├── configGenerator.js      # Randomization
    ├── particlesService.js     # tsParticles facade
    ├── uiManager.js            # DOM manipulation
    ├── commandManager.js       # Undo/redo
    ├── modalManager.js         # Modal lifecycle
    ├── tooltipManager.js       # Tooltip behavior
    └── keyboardShortcuts.js    # Keyboard events

🎨 Module Cheat Sheet

Import Map

// Core dependencies
import { tsParticles } from 'cdn.jsdelivr.net/@tsparticles/engine@3.9.1/+esm';
import { loadAll } from 'cdn.jsdelivr.net/@tsparticles/all@3.9.1/+esm';

// Internal modules
import { AppState } from './state.js';
import { UIManager } from './uiManager.js';
import { ModalManager } from './modalManager.js';
import { ConfigGenerator } from './configGenerator.js';
import { CommandManager } from './commandManager.js';
import { copyToClipboard, getRandomItem, debounce } from './utils.js';
import {
  darkColorPalette,
  lightColorPalette,
  BUTTON_IDS,
} from './constants.js';
import {
  buildConfig,
  loadParticles,
  reapplyToggleStates,
} from './particlesService.js';
import { initTooltipManager } from './tooltipManager.js';
import { initKeyboardShortcuts } from './keyboardShortcuts.js';

API Quick Reference

State Management

// Read state
AppState.ui.isDarkMode;
AppState.particleState.chaosLevel;
AppState.particleState.currentConfig;

// Modify state (always through commands!)
CommandManager.execute(command);

Config Generation

ConfigGenerator.generateAppearance();
ConfigGenerator.generateMovement();
ConfigGenerator.generateInteraction();
ConfigGenerator.generateSpecialFX();

Particles Service

buildConfig({ all: true }); // Full randomization
buildConfig({ appearance: true }); // Appearance only
await loadParticles(config);
reapplyToggleStates(config);

UI Management

UIManager.syncUI(); // Sync all UI to state
UIManager.showToast(message);
UIManager.announce(message); // Screen reader
UIManager.openModal(modal, opener);
UIManager.closeModal(modal);

Command Pattern

const command = {
  async execute() {
    /* do thing */
  },
  async undo() {
    /* undo thing */
  },
};
CommandManager.execute(command);
CommandManager.undo();
CommandManager.redo();

🎲 Chaos Level Guide

Formula: particleCount = 20 + (chaosLevel * 20)

🎯 Common Workflows

Rapid Exploration

Alt+A → Alt+A → Alt+A → Space → Alt+Z

Fine Tuning

Alt+A → Alt+V → Alt+V → Alt+P → Alt+S

Undo Recovery

Alt+A (oops!) → Alt+Z → Alt+Z → Alt+Y

Create & Share

1. Shuffle until happy
2. Alt+S (share)
3. Paste URL anywhere

🔧 Configuration Structure

Minimal Config

{
  background: { color: { value: "#111" } },
  fpsLimit: 120,
  detectRetina: true,
  particles: {
    number: { value: 120 },
    color: { value: "#ff007b" },
    shape: { type: "circle" },
    opacity: { value: { min: 0.3, max: 1 } },
    size: { value: { min: 1, max: 7.5 } },
    move: {
      enable: true,
      speed: 5,
      direction: "none",
      outModes: { default: "out" }
    }
  },
  interactivity: {
    events: {
      onHover: { enable: true, mode: "repulse" },
      onClick: { enable: true, mode: "push" }
    },
    modes: {
      repulse: { distance: 100 },
      push: { quantity: 5 }
    }
  }
}

With All Features

{
  // ... base config
  particles: {
    // ... appearance
    stroke: { width: 2, color: { value: "random" } },
    move: {
      // ... movement
      trail: { enable: true, length: 10 },
      attract: { enable: true, rotate: { x: 1000, y: 1000 } },
      gravity: { enable: true, acceleration: 20 }
    },
    collisions: { enable: true, mode: "bounce" },
    wobble: { enable: true, distance: 5, speed: 5 },
    rotate: { animation: { enable: true, speed: 20 } },
    links: { enable: true, distance: 150 },
    twinkle: { particles: { enable: true } }
  }
}

🎨 Color Palettes

Dark Mode

[
  '#ff007b',
  '#33ff57',
  '#3357ff',
  '#ffc300',
  '#ffffff',
  '#ad55ff',
  '#00f5d4',
  '#f15bb5',
];

Light Mode

[
  '#f72585',
  '#7209b7',
  '#3a0ca3',
  '#4361ee',
  '#4cc9f0',
  '#f94144',
  '#f3722c',
  '#f9c74f',
];

🔀 Particle Shapes

[
  'circle',
  'square',
  'triangle',
  'star',
  'polygon',
  'line',
  'heart',
  'rounded-rectangle',
  'character',
];

📐 Directions

[
  'none',
  'top',
  'top-right',
  'right',
  'bottom-right',
  'bottom',
  'bottom-left',
  'left',
  'top-left',
];

🖱️ Interaction Modes

Hover

['repulse', 'grab', 'bubble', 'slow', 'connect', 'parallax', 'attract'];

Click

['push', 'bubble', 'remove', 'trail', 'absorb'];

🐛 Debugging

Check State

console.log(AppState);
console.log(AppState.particleState.currentConfig);

Check History

console.log(CommandManager.undoStack.length);
console.log(CommandManager.redoStack.length);

Force Sync UI

UIManager.syncUI();

Manually Load Config

await loadParticles(yourConfig);

Clear History

CommandManager.undoStack = [];
CommandManager.redoStack = [];

📊 Performance Tips

1. Keep Chaos ≤ 7 on mobile
2. Disable links for better FPS
3. Pause when not watching (Space)
4. Use Light theme if laggy
5. Disable collisions if laggy

🔗 Useful Links

• Live Demo: zophiezlan.github.io/tsdice
• GitHub: github.com/zophiezlan/tsdice
• Desktop Version: desktop branch
• tsParticles Docs: particles.js.org

💡 Quick Recipes

Zen Mode

Chaos: 2 | Theme: Light | Gravity: Off | Walls: Off
Shuffle until: Circles + Pastel colors + Slow movement

Matrix Rain

Chaos: 6 | Theme: Dark | Gravity: On | Walls: On
Shuffle until: Green lines + Downward direction

Confetti

Chaos: 10 | Theme: Any | Gravity: On | Walls: On
Shuffle until: Multi-color + Diverse shapes

Starfield

Chaos: 4 | Theme: Dark | Gravity: Off | Walls: Off
Shuffle until: Stars + Links enabled + Slow speed

📝 Common Patterns

Command Factory Pattern

const createShuffleCommand = (options) => ({
  async execute() {
    /* generate & load */
  },
  async undo() {
    /* restore old */
  },
});

Toggle Factory Pattern

const createToggleCommand = (stateKey, applyFn) => ({
  async execute() {
    AppState.ui[stateKey] = !AppState.ui[stateKey];
    await applyFn();
  },
  async undo() {
    await this.execute();
  },
});

Debounce Pattern

const debouncedFn = debounce((arg) => {
  // Expensive operation
}, 500);

🎓 Learning Path

1. Beginner: Use GUI, explore shuffles
2. Intermediate: Learn keyboard shortcuts
3. Advanced: Create custom recipes
4. Expert: Modify source code, add features

⚠️ Gotchas

1. History: Infinite undo/redo (memory permitting)
2. URL length: Configs too large may fail to share
3. Browser support: Requires ES6 modules
4. Chaos 10: May be laggy on old devices
5. Share URLs: Short URLs expire after ~1 year

For full details, see:

• 📖 User Guide — How to use tsDice
• 🏗️ Architecture — How it works
• 📊 Analysis — Complete technical overview
• 📄 README — Project overview

Now go create something beautiful! ✨