@jjlmoya/utils-tabletop 1.3.0

package/src/tool/dice-roller-simulator/i18n/zh.ts

@@ -0,0 +1,305 @@
+import { bibliography } from '../bibliography';
+import type { ToolLocaleContent } from '../../../types';
+
+export const content: ToolLocaleContent = {
+  slug: 'dice-roller-simulator',
+  title: '在线骰子模拟器与概率计算器',
+  description: '在线投掷虚拟多面体骰子（D4, D6, D8, D10, D12, D20, D100），添加修正值，并查看桌游与跑团的实时骰子统计数据和出现概率分析。',
+  ui: {
+    title: '在线骰子模拟器与概率计算器',
+    rollButton: '投掷骰子',
+    clearButton: '清除历史记录',
+    historyTitle: '投掷历史',
+    noHistory: '暂无投掷记录。请添加骰子并点击“投掷骰子”开始。',
+    totalRolls: '总投掷次数',
+    averageRoll: '平均投掷结果',
+    lastRoll: '最近投掷总和',
+    modifierLabel: '修正值 (+/-)',
+    probabilityTitle: '概率分布分析',
+    selectDice: '选择要投掷的骰子',
+  },
+  seo: [
+    { type: 'title', text: '掌握桌游胜率：多面体骰子的概率如何塑造您的游戏进程', level: 2 },
+    { type: 'paragraph', html: '多面体骰子是桌面角色扮演游戏（TRPG跑团）和现代棋盘游戏的核心。无论您是在《地下城与守卫》中追求高难度的豁免判定，还是在为资源产出进行投掷，所有结果都受到数学概率的支配。了解不同骰子类型的组合如何影响您的胜率，对于游戏过程中的战术决策至关重要。' },
+    {
+      type: 'stats',
+      items: [
+        { value: '5.0%', label: '自然20概率' },
+        { value: '10.5', label: '3d6投掷平均值' },
+        { value: '9.75%', label: '优势判定下自然20' },
+      ],
+      columns: 3,
+    },
+    { type: 'title', text: '多个骰子的数学逻辑：为什么3d6比单个D20更稳健', level: 2 },
+    { type: 'paragraph', html: '投掷单个D20骰子时，1到20之间的每个结果都有相同的5%概率出现，从而形成平坦的概率分布。然而，当投掷像3d6这样的多个骰子时，结果会聚集在平均值10.5附近。这种钟形曲线（正规分布）意味着，投出中等结果的可能性远大于极端值，这为游戏带来了一致性，减少了单颗骰子判定时的不稳定性和运气成分。' },
+    { type: 'title', text: 'D20概率详解：大成功、大失败与修正值的作用', level: 2 },
+    { type: 'paragraph', html: '仅加2的微小修正值就能大幅改变成功的概率，将困难的任务变成可以达成的挑战。在许多游戏规则中，自然20代表自动大成功（5%概率），而自然1则是大失败。通过将这些概率结果可视化，可以帮助玩家理性看待随机性，并根据统计数据支持来规划您的战术行动。' },
+    {
+      type: 'title',
+      text: '标准多面体骰子早见参考表',
+      level: 3,
+    },
+    {
+      type: 'table',
+      headers: ['骰子类型', '最小投掷值', '最大投掷值', '平均结果', 'TRPG跑团中的主要作用'],
+      rows: [
+        ['D4', '1', '4', '2.5', '魔法飞弹、匕首伤害、微小陷阱与障碍'],
+        ['D6', '1', '6', '3.5', '火球术、标准长剑、属性判定'],
+        ['D8', '1', '8', '4.5', '长剑伤害、治疗法术、中型武器判定'],
+        ['D10', '1', '10', '5.5', '长戟伤害、戏法伤害、百分位数（十位数）'],
+        ['D12', '1', '12', '6.5', '巨斧伤害、野蛮人生命值判定'],
+        ['D20', '1', '20', '10.5', '豁免判定、攻击判定、技能判定'],
+        ['D100', '1', '100', '50.5', '百分类判定表、狂野魔法暴走判定'],
+      ],
+    },
+    {
+      type: 'tip',
+      title: '如何在脑海中快速计算骰子平均值',
+      html: '要计算任何单颗骰子的平均值，只需将最小值（1）和最大值相加，然后除以2。例如，一颗D6的平均值是 (1 + 6) / 2 = 3.5。如果是多个骰子，只需将单颗骰子的平均值乘以骰子数量即可（例如，3d6的平均值是 3 * 3.5 = 10.5）。如果带有固定的修正值，直接加上该值即可（例如，3d6 + 4 的平均值是 14.5）。',
+    },
+    {
+      type: 'title',
+      text: '平坦几率判定系统与曲线分布判定系统的对比',
+      level: 3,
+    },
+    {
+      type: 'proscons',
+      title: 'D20系统与3d6钟形曲线系统对比',
+      items: [
+        {
+          pro: 'D20判定系统计算非常迅速，大成功和大失败的概率固定为相eqn的5%。',
+          con: 'D20的判定结果起伏极大，使得角色本身的技能熟练度往往不及骰子本身的运气。',
+        },
+        {
+          pro: '3d6钟形曲线系统倾向于投出中间值，确保高技能角色极少在简单的任务中失败。',
+          con: '3d6系统判定时需要相加三颗骰子的出目，且投出完美18的概率极低（仅0.46%）。',
+        },
+      ],
+    },
+    {
+      type: 'title',
+      text: '了解概率判定机制',
+      level: 3,
+    },
+    {
+      type: 'comparative',
+      items: [
+        {
+          title: 'D20判定系统（线形分布）',
+          description: '动作判定使用单颗20面骰子，每个结果的几率均等为5%。高波动性带来了紧张刺激的体验，但缺乏稳定性。',
+          icon: 'mdi:dice-d20',
+          highlight: false,
+          points: [
+            '每个结果出目概率固定为5%',
+            '出目分散，随机波动极大',
+            '修正值以线性的方式提升成功率',
+          ],
+        },
+        {
+          title: '3d6判定系统（钟形曲线）',
+          description: '相加三颗6面骰子，创建以10.5为中心的标准正态分布。结果高度一致稳定。',
+          icon: 'mdi:chart-bell-curve',
+          highlight: true,
+          points: [
+            '投出中间结果的概率非常高',
+            '投出极端结果的情况极其罕见',
+            '修正值对成功率的影响呈非线性',
+          ],
+        },
+        {
+          title: '百分比判定系统（投掷出目小于目标值）',
+          description: '使用两颗10面骰子组合生成1到100之间的数字。出目小于等于角色的属性值即为成功，成功概率极其直观。',
+          icon: 'mdi:percent-box-outline',
+          highlight: false,
+          points: [
+            '成功概率直接与百分比挂钩',
+            '直观易懂，一目了然',
+            '角色属性和技能成长在数学上非常清晰',
+          ],
+        },
+      ],
+      columns: 3,
+    },
+    {
+      type: 'diagnostic',
+      variant: 'info',
+      title: '赌徒谬误：骰子本身没有记忆',
+      icon: 'mdi:information-outline',
+      badge: 'PROBABILITY TIP',
+      html: 'TRPG跑团和桌游中常见的误区是认为之前的投掷结果会影响接下来的出目。如果在D20判定中连续投出了三次“1”，玩家往往会觉得下一次应该“出大数”了。然而实际上，每一次投掷都是独立事件。下一次投出20的概率依然是精确的5%。理性认识这一点能帮助玩家做出更客观的战术决策。',
+    },
+    {
+      type: 'title',
+      text: '多面体骰子与桌游概率专业术语表',
+      level: 3,
+    },
+    {
+      type: 'glossary',
+      items: [
+        {
+          term: '优势与劣势判定',
+          definition: '玩家投掷两颗D20骰子，优势下取较大值，劣势下取较小值。优势判定将出目的期望值从10.5提升至13.8。',
+        },
+        {
+          term: '钟形曲线（正态分布）',
+          definition: '出目聚集在中间平均值附近的概率分布。投掷并相加多颗骰子（如3d6或2d10）时产生。',
+        },
+        {
+          term: '大成功',
+          definition: '骰子投出最大值（如D20的20）时的自动成功判定，通常会带来额外伤害或特殊收益效果。',
+        },
+        {
+          term: '大失败',
+          definition: '骰子投出最小值1时的自动失败判定，往往会伴随滑稽或灾难性的后果。',
+        },
+        {
+          term: '期望值',
+          definition: '投掷骰子长期以来的平均出目。单颗D6的期望值是3.5；单颗D20是10.5。',
+        },
+        {
+          term: '百分比骰子',
+          definition: '同时投掷两颗D10骰子（一颗代表十位数，一颗代表个位数）以获取1到100之间的数值判定。',
+        },
+      ],
+    },
+  ],
+  faq: [
+    {
+      question: '概率模拟器是如何运作的？',
+      answer: '它利用排列组合数学方法计算出选定骰子和修正值组合的精确概率分布，从而让您能直观查看骰出高于或低于目标数值的几率。',
+    },
+    {
+      question: '支持哪些类型的骰子？',
+      answer: '支持TRPG跑团和各类桌游中常用的所有标准多面体骰子，包括D4, D6, D8, D10, D12, D20以及D100。',
+    },
+    {
+      question: '修正值是什么？如何起作用？',
+      answer: '修正值是代表角色技能熟练度、外部增益或减益效果的固定数值（如+1、-2等）。它会直接加到或减去您的骰子投掷出目总和。',
+    },
+    {
+      question: '带有优势或劣势判定投掷是什么意思？',
+      answer: '优势投掷指同时投掷两颗D20骰子并保留较大的那颗出目；劣势投掷指保留较小的那颗出目。这是跑团游戏中的经典判定机制。',
+    },
+    {
+      question: '大成功与大失败分别指什么？',
+      answer: '大成功通常指骰子投出了其出目上限（如D20的20），表示绝对的成功或双倍的伤害判定。大失败指骰子投出了出目下限1，表示绝对的失败且往往伴随不利影响。',
+    },
+    {
+      question: '模拟器是如何计算投掷概率的？',
+      answer: '模拟器在数学上穷举计算了选定骰子池和修正值所有出目的排列组合，进而展示每种可能出目总和的精确占比百分比。',
+    },
+    {
+      question: '为什么投掷3d6比投掷单颗D20更为稳定？',
+      answer: '投掷单颗D20时，每个出目出现的概率都是均等的5%。而投掷3d6时，三个出目相加会使得结果形成钟形曲线，概率集中在平均值10.5附近，使极端的高低数值极其罕见。',
+    },
+  ],
+  bibliography,
+  howTo: [
+    {
+      name: '添加骰子',
+      text: '点击骰子图标，将它们加入到您当前准备投掷的骰子池中。',
+    },
+    {
+      name: '添加修正值',
+      text: '输入正数或负数修正值，以便应用到最后的总和计算中。',
+    },
+    {
+      name: '投掷并查看统计',
+      text: '点击“投掷骰子”按钮以触发投掷动画、投掷历史记录和实时的概率分布图。',
+    },
+  ],
+  schemas: [
+    {
+      '@context': 'https://schema.org',
+      '@type': 'SoftwareApplication',
+      'name': '在线骰子模拟器与概率计算器',
+      'operatingSystem': 'All',
+      'applicationCategory': 'UtilitiesApplication',
+      'browserRequirements': 'Requires HTML5. Requires JavaScript.'
+    },
+    {
+      '@context': 'https://schema.org',
+      '@type': 'FAQPage',
+      'mainEntity': [
+        {
+          '@type': 'Question',
+          'name': '概率模拟器是如何运作的？',
+          'acceptedAnswer': {
+            '@type': 'Answer',
+            'text': '它利用排列组合数学方法计算出选定骰子和修正值组合的精确概率分布，从而让您能直观查看骰出高于或低于目标数值的几率。'
+          }
+        },
+        {
+          '@type': 'Question',
+          'name': '支持哪些类型的骰子？',
+          'acceptedAnswer': {
+            '@type': 'Answer',
+            'text': '支持TRPG跑团和各类桌游中常用的所有标准多面体骰子，包括D4, D6, D8, D10, D12, D20以及D100。'
+          }
+        },
+        {
+          '@type': 'Question',
+          'name': '修正值是什么？如何起作用？',
+          'acceptedAnswer': {
+            '@type': 'Answer',
+            'text': '修正值是代表角色技能熟练度、外部增益或减益效果的固定数值（如+1、-2等）。它会直接加到或减去您的骰子投掷出目总和。'
+          }
+        },
+        {
+          '@type': 'Question',
+          'name': '带有优势或劣势判定投掷是什么意思？',
+          'acceptedAnswer': {
+            '@type': 'Answer',
+            'text': '优势投掷指同时投掷两颗D20骰子并保留较大的那颗出目；劣势投掷指保留较小的那颗出目。这是跑团游戏中的经典判定机制。'
+          }
+        },
+        {
+          '@type': 'Question',
+          'name': '大成功与大失败分别指什么？',
+          'acceptedAnswer': {
+            '@type': 'Answer',
+            'text': '大成功通常指骰子投出了其出目上限（如D20的20），表示绝对的成功或双倍的伤害判定。大失败指骰子投出了出目下限1，表示绝对的失败且往往伴随不利影响。'
+          }
+        },
+        {
+          '@type': 'Question',
+          'name': '模拟器是如何计算投掷概率的？',
+          'acceptedAnswer': {
+            '@type': 'Answer',
+            'text': '模拟器在数学上穷举计算了选定骰子池和修正值所有出目的排列组合，进而展示每种可能出目总和的精确占比百分比	。'
+          }
+        },
+        {
+          '@type': 'Question',
+          'name': '为什么投掷3d6比投掷单颗D20更为稳定？',
+          'acceptedAnswer': {
+            '@type': 'Answer',
+            'text': '投掷单颗D20时，每个出目出现的概率都是均等的5%。而投掷3d6时，三个出目相加会使得结果形成钟形曲线，概率集中在平均值10.5附近，使极端的高低数值极其罕见。'
+          }
+        }
+      ]
+    },
+    {
+      '@context': 'https://schema.org',
+      '@type': 'HowTo',
+      'name': 'How to Use the Dice Roller Simulator',
+      'step': [
+        {
+          '@type': 'HowToStep',
+          'name': '添加骰子',
+          'text': '点击骰子图标，将它们加入到您当前准备投掷的骰子池中。'
+        },
+        {
+          '@type': 'HowToStep',
+          'name': '添加修正值',
+          'text': '输入正数或负数修正值，以便应用到最后的总和计算中。'
+        },
+        {
+          '@type': 'HowToStep',
+          'name': '投掷并查看统计',
+          'text': '点击“投掷骰子”按钮以触发投掷动画、投掷历史记录和实时的概率分布图。'
+        }
+      ]
+    }
+  ],
+};

package/src/tool/dice-roller-simulator/index.ts

@@ -0,0 +1,9 @@
+import type { ToolDefinition } from '../../types';
+import { diceRollerSimulator } from './entry';
+export * from './entry';
+export const DICE_ROLLER_SIMULATOR_TOOL: ToolDefinition = {
+  entry: diceRollerSimulator,
+  Component: () => import('./component.astro'),
+  SEOComponent: () => import('./seo.astro'),
+  BibliographyComponent: () => import('./bibliography.astro'),
+};

package/src/tool/dice-roller-simulator/modules/chart.ts

@@ -0,0 +1,32 @@
+export function drawDistributionChart(container: HTMLElement | null, totals: number[]) {
+  if (!container) {
+    return;
+  }
+  container.innerHTML = '';
+
+  if (totals.length === 0) {
+    container.innerHTML = '<div class="chart-empty-state">No rolls recorded yet</div>';
+    return;
+  }
+
+  const counts = new Map<number, number>();
+  for (const val of totals) {
+    counts.set(val, (counts.get(val) || 0) + 1);
+  }
+
+  const uniqueTotals = Array.from(counts.keys()).sort((a, b) => a - b);
+  const maxCount = Math.max(...Array.from(counts.values()));
+
+  for (const total of uniqueTotals) {
+    const count = counts.get(total) || 0;
+    const heightPercent = (count / maxCount) * 100;
+
+    const barCol = document.createElement('div');
+    barCol.className = 'chart-bar-column';
+    barCol.innerHTML = `
+      <div class="chart-bar-fill" style="height: ${heightPercent}%" data-count="${count}"></div>
+      <span class="chart-bar-label">${total}</span>
+    `;
+    container.appendChild(barCol);
+  }
+}

package/src/tool/dice-roller-simulator/modules/history.ts

@@ -0,0 +1,87 @@
+export interface RollLog {
+  id: string;
+  timestamp: string;
+  dice: string[];
+  modifier: number;
+  total: number;
+}
+
+const STORAGE_KEY = 'jjlmoya_tabletop_roll_history';
+
+export function getHistory(): RollLog[] {
+  const data = localStorage.getItem(STORAGE_KEY);
+  return data ? JSON.parse(data) : [];
+}
+
+export function saveHistory(history: RollLog[]) {
+  localStorage.setItem(STORAGE_KEY, JSON.stringify(history));
+}
+
+function createHistoryCard(log: RollLog): HTMLDivElement {
+  const item = document.createElement('div');
+  item.className = 'history-card-item';
+  const diceTagsHtml = log.dice.map(d => {
+    const parts = d.split(':');
+    return `<span class="breakdown-die-tag" data-die-type="${parts[0]}">${parts[1]}</span>`;
+  }).join(' ');
+
+  item.innerHTML = `
+    <div class="history-card-header">
+      <span>${new Date(log.timestamp).toLocaleTimeString()}</span>
+      <span>Mod: ${log.modifier >= 0 ? '+' : ''}${log.modifier}</span>
+    </div>
+    <div class="history-card-body">
+      <div class="history-dice-tags">${diceTagsHtml}</div>
+      <span class="history-grand-total">${log.total}</span>
+    </div>
+  `;
+  return item;
+}
+
+interface HistoryUIRefs {
+  list: HTMLElement | null;
+  emptyMsg: HTMLElement | null;
+  totalVal: HTMLElement | null;
+  averageVal: HTMLElement | null;
+  lastVal: HTMLElement | null;
+  badge: HTMLElement | null;
+}
+
+function setText(el: HTMLElement | null, text: string) {
+  if (el) {
+    el.textContent = text;
+  }
+}
+
+export function renderHistory(refs: HistoryUIRefs, onDrawChart: (totals: number[]) => void) {
+  const history = getHistory();
+  if (!refs.list || !refs.emptyMsg) return;
+
+  if (history.length === 0) {
+    refs.emptyMsg.style.display = 'block';
+    refs.list.innerHTML = '';
+    setText(refs.totalVal, '0');
+    setText(refs.averageVal, '--');
+    setText(refs.lastVal, '--');
+    setText(refs.badge, '0');
+    onDrawChart([]);
+    return;
+  }
+
+  refs.emptyMsg.style.display = 'none';
+  refs.list.innerHTML = '';
+
+  const totals = history.map(h => h.total);
+  const sum = totals.reduce((a, b) => a + b, 0);
+
+  for (let i = history.length - 1; i >= 0; i--) {
+    refs.list.appendChild(createHistoryCard(history[i]));
+  }
+
+  setText(refs.totalVal, history.length.toString());
+  setText(refs.badge, history.length.toString());
+  setText(refs.averageVal, (sum / history.length).toFixed(1));
+  setText(refs.lastVal, history[history.length - 1].total.toString());
+
+  onDrawChart(totals);
+}

package/src/tool/dice-roller-simulator/modules/particles.ts

@@ -0,0 +1,22 @@
+export function spawnParticle(container: HTMLElement, text: string, x?: number, y?: number) {
+  const el = document.createElement('span');
+  el.className = 'floating-magic-particle';
+  el.textContent = text;
+  if (x !== undefined && y !== undefined) {
+    el.style.left = `${x}px`;
+    el.style.top = `${y}px`;
+  } else {
+    el.style.left = '50%';
+    el.style.top = '20%';
+  }
+  container.appendChild(el);
+  setTimeout(() => el.remove(), 600);
+}
+
+export function spawnRollPop(container: HTMLElement, total: number) {
+  const el = document.createElement('div');
+  el.className = 'floating-roll-pop';
+  el.textContent = `${total >= 0 ? '+' : ''}${total}`;
+  container.appendChild(el);
+  setTimeout(() => el.remove(), 1000);
+}

package/src/tool/dice-roller-simulator/seo.astro

@@ -0,0 +1,16 @@
+---
+import { SEORenderer } from '@jjlmoya/utils-shared';
+import { diceRollerSimulator } from './index';
+import type { KnownLocale } from '../../types';
+
+interface Props {
+  locale?: KnownLocale;
+}
+
+const { locale = 'en' } = Astro.props;
+const loader = diceRollerSimulator.i18n[locale] || diceRollerSimulator.i18n.en;
+const content = await loader?.();
+if (!content) return null;
+---
+
+{content.seo?.length > 0 && <SEORenderer content={{ locale, sections: content.seo }} />}

package/src/tools.ts

@@ -0,0 +1,9 @@
+export { ALL_ENTRIES } from './entries';
+import type { ToolDefinition } from './types';
+import { DICE_ROLLER_SIMULATOR_TOOL } from './tool/dice-roller-simulator';
+import { BOARD_GAME_TIMER_TOOL } from './tool/board-game-timer';
+
+export const ALL_TOOLS: ToolDefinition[] = [
+  DICE_ROLLER_SIMULATOR_TOOL,
+  BOARD_GAME_TIMER_TOOL,
+];

package/src/types.ts

@@ -0,0 +1,70 @@
+import type { SEOSection } from '@jjlmoya/utils-shared';
+import type { WithContext, Thing } from 'schema-dts';
+
+export type { SEOSection };
+
+export type KnownLocale =
+  | 'ar' | 'da' | 'de' | 'en' | 'es' | 'fi'
+  | 'fr' | 'id' | 'it' | 'ja' | 'ko' | 'nb' | 'nl'
+  | 'pl' | 'pt' | 'ru' | 'sv' | 'tr' | 'zh';
+
+export interface FAQItem {
+  question: string;
+  answer: string;
+}
+
+export interface BibliographyEntry {
+  name: string;
+  url: string;
+}
+
+export interface HowToStep {
+  name: string;
+  text: string;
+}
+
+export interface ToolLocaleContent<TUI extends Record<string, string> = Record<string, string>> {
+  slug: string;
+  title: string;
+  description: string;
+  ui: TUI;
+  seo: SEOSection[];
+  faq: FAQItem[];
+  bibliography: BibliographyEntry[];
+  howTo: HowToStep[];
+  schemas: WithContext<Thing>[];
+}
+
+export interface CategoryLocaleContent {
+  slug: string;
+  title: string;
+  description: string;
+  seo: SEOSection[];
+}
+
+export type LocaleLoader<T> = () => Promise<T>;
+
+export type LocaleMap<T> = Partial<Record<KnownLocale, LocaleLoader<T>>>;
+
+export interface TabletopToolEntry<TUI extends Record<string, string> = Record<string, string>> {
+  id: string;
+  icons: {
+    bg: string;
+    fg: string;
+  };
+  i18n: LocaleMap<ToolLocaleContent<TUI>>;
+}
+
+export interface TabletopCategoryEntry {
+  icon: string;
+  tools: TabletopToolEntry[];
+  i18n: LocaleMap<CategoryLocaleContent>;
+}
+
+export interface ToolDefinition {
+  entry: TabletopToolEntry;
+  Component: unknown;
+  SEOComponent: unknown;
+  BibliographyComponent: unknown;
+}
+