# RollOne

**Repository Path**: mrchip233/RollOne

## Basic Information

- **Project Name**: RollOne
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-10-08
- **Last Updated**: 2026-10-08

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# RollOne · 弹弓骰子

一个移动端优先的响应式单页应用。骰子是用 CSS 3D 搭的**真六面立方体**：
按住它向后拉、松手弹出，骰子朝反方向飞出去翻滚，最后带阻尼回落到舞台中心，**朝上的那面就是结果**。

- 六个面 = 5 种颜色 + 1 个「?」问号面，每个结果概率严格为 `1 / 6`
- 拉动力度参与随机种子，但混入每次新取的系统熵，因此**力度再偏心也不会破坏等概率**
- 颜色由 `src/config/colors.ts` 数据驱动，增删颜色只改这一处
- 纯前端、无后端、无 PWA，除 React 外**零运行时依赖**

需求演变与开发指令记录在 [`prompt.md`](./prompt.md)。

## 演示
![演示](resources/screenshot.png)

- [resources/screenshot.png](resources/screenshot.png) —— 界面截图，499×944
- [resources/demo.mp4](resources/demo.mp4) —— 演示视频，16 秒 / 496×1080 / 30fps

> GitHub 的 Markdown 会过滤 `<video>` 标签，所以在 GitHub 上请直接点开 `resources/demo.mp4`；
> VS Code、GitLab、Gitea 的 Markdown 预览里可以直接播放。
> ⚠️ 视频是 **HEVC（H.265）** 编码，Chrome / Firefox 播不了，只有 Safari 能直接播——见「已知问题」。

## 常用命令

```bash
pnpm install
pnpm dev      # 启动开发服务器（已带 --host，手机可同局域网访问）
pnpm test     # 运行 Vitest 单测
pnpm build    # tsc -b + vite build
pnpm lint     # oxlint
```

单跑某个测试文件：

```bash
pnpm exec vitest run src/lib/cube.test.ts
```

## 项目结构

```
src/
  config/colors.ts        结果集配置：唯一需要改动的地方（颜色 / 问号）
  lib/
    random.ts             拒绝采样 randBelow —— 等概率的根基
    roll.ts               buildFaces / choice / rollFace / faceIndexToLandingEuler 的调用方
    seededRandom.ts       mix32 混合种子 + mulberry32 确定性 PRNG
    slingshot.ts          拖拽位移 → 力度 / 发射方向 / 滚动轴（纯几何）
    cube.ts               立方体槽位、面摆放、落地姿态、transform 拼装（纯几何）
    tumble.ts             力度 → 时长 / 圈数 / 距离 + 缓动常量
    animationPreference.ts 动画开关的持久化与默认值
  components/
    Dice3D.tsx            CSS 3D 立方体（纯展示，姿态由外部传入的 transform 决定）
    AnimationToggle.tsx   ARIA switch
  App.tsx                 状态机：拖拽 → 发射 → 翻滚 → 回落 → 定格
```

设计上刻意让 `lib/` 里全是**纯函数**：几何、抽样、种子、时序都不依赖 DOM，
因此可以脱离浏览器直接单测。`App.tsx` 只负责把这些纯函数接成状态机和定时器。

## 测试

11 个文件、122 个用例，覆盖四类：

| 类别 | 例子 |
| --- | --- |
| 概率正确性 | 拒绝采样穷举验证无偏、种子化抽取的等概率与确定性 |
| 几何正确性 | 六个槽位落地后法向等于桌面法线、面内文字正立、面摆放与法向量表一致 |
| 动画约束 | 峰值角速度上限、两段缓动在衔接处速度都为 0、上调落定时长不变 |
| 组件行为 | 拖拽跟手（含俯视倾角补偿）、力度不足不触发、关闭动画立即出结果 |

几何与动画那两类是**回归安全网**：它们守着的都是"错了也几乎看不出来"的东西
（朝上的面和播报结果不一致、转速过高看久了头晕），改参数后务必全跑一遍。

## 操作

- **拖拽发射**：按住骰子（或其周围的舞台）往任意方向拖，松手后骰子朝反方向弹出。
  拖动距离决定力度：更远就飞得更高、转得更久。
- **拉动距离小于 12px** 视为没拉动，松手原地回弹、不改变结果。
- **后备按钮**：键盘 / 屏幕阅读器 / 不便拖拽时使用，以默认力度发射。
- 结果通过 `aria-live` 播报；骰子本体标记为 `aria-hidden`，不与交互元素抢焦点。

## 立方体朝向：目标和直觉不一样

场景整体带一个 `rotateX(45deg)` 的俯视倾角，所以**场景的 +Z 才是桌面法线**，也就是骰子顶面的朝向。
而 CSS 里名叫 `top` 的那个面，法向其实是 `-Y`（屏幕上方）——在俯视场景里它对应的是
「背离观察者、平躺在桌面上」的那一面，**不是**骰子顶面。

落地姿态表因此按 `+Z` 推导，见 `src/lib/cube.ts`：

| 槽位 | 法向 → 桌面法线 | rx | ry | rz |
| --- | --- | --- | --- | --- |
| front | +Z → +Z | 0 | 0 | 0 |
| back | −Z → +Z | 0 | 180 | 0 |
| right | +X → +Z | 0 | −90 | 0 |
| left | −X → +Z | 0 | 90 | 0 |
| top | −Y → +Z | −90 | 0 | 0 |
| bottom | +Y → +Z | 90 | 0 | 0 |

两件事由单测机器校验，不靠肉眼：

1. 六个槽位落地后，该面法向必须等于桌面法线，且**有且仅有它自己朝上**；
   同时该面上的文字方向必须相对镜头正立，否则问号会倒过来。
2. `index.css` 里六个面的 CSS 摆法和 `cube.ts` 里的法向量表是两份独立真相。
   测试会从 CSS 反解出旋转、用同一套矩阵算出法向再与表对照，任何一边被单独改动都会失败。

## 随机抽取为什么是公平的

抽取走 `randBelow()`（`src/lib/random.ts`），采用**拒绝采样**，等价于 Python `random.choice` 内部的 `_randbelow`：

```ts
const bound = Math.floor(space / limit) * limit  // 不超过字空间的最大 limit 倍数
for (;;) {
  const value = source()
  if (value < bound) return value % limit        // 落在可整除区才接受
  // 否则落在 [bound, space) 这个“尾巴”上 → 整段丢弃重抽
}
```

直接用 `随机数 % limit` 会**引入偏差**：当 `limit` 不能整除 `2**32` 时（例如 6），
靠前的余数会多分到一些随机字。拒绝采样保证每个结果对应**数量完全相同**的字，
概率精确等于 `1 / limit`。

## 种子怎么来的

```ts
quantized = clamp(round(力度 × 0xFFFFFFFF), 0, 0xFFFFFFFF)
seed      = mix32(quantized ^ entropy)      // entropy = 每次投掷新取的 crypto 随机数
```

`mulberry32(seed)` 产出的函数符合 `Uint32Source`，直接插进 `randBelow` 的既有接口，
种子化抽取和无偏抽取复用同一条路径。

**为什么不是「力度就是随机源」**：拉动力度是人的输入，没人能均匀地拉。
如果结果是 `f(力度)` 的纯函数，那么一是同样力度必出同样结果、可以被练出来，
二是人总倾向于拉到相近区间，会出现某一面反复出现——等概率就不成立了。
异或一个均匀的熵之后 `quantized ^ entropy` 仍然均匀，所以各面严格等概率；
而力度改变低位输入，同一熵下不同力度给出不同结果，力度是**真实参与**决定而不是摆设。

单测同时锁住两个方向：同一熵下不同力度要能给出多个不同结果；
同一力度下不同熵要能覆盖全部 6 个结果。

## 投掷动画

两段式，都用 CSS `transition` 插值 + `setTimeout` 推进状态
（不用 `Element.animate`，jsdom 未实现它；也不依赖 `transitionend`）：

1. **起飞**：位移到飞行落点、抬升 `translateZ`、加 `360° × n` 整圈自旋
2. **回落**：位移归零、姿态角**不再变化**、落地定格

翻滚**只在起飞段发生**。回落段是纯平移——曾经让回落段也补一圈，结果是
「先转几圈停下、又转几圈回中间」两次转圈的观感，用户直接反馈过，所以撤掉了。
两段的缓动也做了衔接：起飞段 ease-out 结尾速度归零，回落段就用起步斜率为 0 的
`EASE_RETURN`，避免"停一下又突然动起来"的断裂感。

`src/lib/tumble.ts` 定义力度 → 时长 / 圈数 / 距离的映射。

### 翻滚往哪个方向滚

翻滚**不是**绕固定轴转，而是**跟着投掷方向滚**——这是纯滚动的物理：角速度方向 = 桌面法线 × 发射方向。

```ts
// 发射方向 = 拖拽的反方向，所以轴 = (pull.y, -pull.x, 0) 归一化
export function rollAxis(pull: Vector): { ax: number; ay: number }
```

| 拖拽方向 | 发射方向 | 滚动轴 |
| --- | --- | --- |
| 往下拉 | 屏幕上方 | `rotate3d(1, 0, 0, …)` |
| 往上拉 | 屏幕下方 | `rotate3d(-1, 0, 0, …)` |
| 往左拉 | 右侧 | `rotate3d(0, 1, 0, …)` |
| 往右拉 | 左侧 | `rotate3d(0, -1, 0, …)` |

落地姿态（六个槽位各自的角度）单独用 `rotateY rotateX rotateZ` 表达，写在 `rotate3d` **之后**。
变换函数列表顺序必须两端完全一致，CSS 才能逐分量插值出多圈旋转；这也是为什么
`cube.ts` 的 `cubeTransform()` 要把函数列表拼成固定顺序。

滚动角度累计在 `RollSpin.deg` 里，静止时恒为 360 的整数倍——此时 `rotate3d` 等效于没有旋转，
所以换轴、清零都不会有视觉跳变。

### 调速

所有时长参数集中在 `src/lib/tumble.ts`，一共四个常量：

```ts
export const TIME_SCALE = 2    // 起飞段的时间缩放
export const FLY_SHARE = 0.6   // 起飞段占 totalMs 的比例（只在 TIME_SCALE = 1 时是最终占比）
const totalMs = 620 + 260 * 力度
```

两段时长：

```ts
flyMs    = round(totalMs × FLY_SHARE × TIME_SCALE)   // 起飞段 = 旋转窗口，吃缩放
settleMs = round(totalMs × (1 − FLY_SHARE))          // 回落段，不吃缩放
spins    = 2                                          // 固定 2 圈
```

`TIME_SCALE` **只作用于起飞段**：回落段要的是一次利落的"直接回到中央"，放大它会显得拖沓。
代价是 `TIME_SCALE` 不再是"全局"缩放，改它会同时改变两段的**比例**——只有 `TIME_SCALE = 1`
时两段才严格按 `FLY_SHARE` 划分。

**改 `TIME_SCALE` 会同比抬高翻滚角速度**，动它之后必须确认「翻滚速度不会引起眩晕」
那组单测仍然通过——它们是调参时的安全网。

### 翻滚速度与眩晕约束

翻滚的角速度 = 该段圈数 ÷ 该段时长，而**峰值**还要再乘上该段缓动的起步斜率
（`cubic-bezier(x1,y1,…)` 的起步斜率约等于 `y1/x1`）。峰值才是看久了头晕的元凶。

所以有这几条约束，都有单测守着：

- 只转 2 圈
- 翻滚**全部在起飞段**完成，回落段姿态角原地不动
- 起飞段明显长于回落段——翻滚需要时间，这是压住角速度的主要手段
- `EASE_FLY = cubic-bezier(0.35, 0.5, 0.6, 1)`：起步斜率约 1.5，而不是原来那版 (0.18, 0.72) 的 4.0

**约束最紧的是最小力度那档**，因为圈数固定为 2 而起飞段随力度变长：
力度越小 → 起飞段越短 → 转速越高。当前参数下各力度的峰值约为：

| 力度 | 0 | 0.5 | 1 |
| --- | --- | --- | --- |
| 峰值 圈/秒 | 4.03 | 3.33 | 2.84 |

方向是反的（弱力度转得最快）。想让弱力度也别转那么快，有两条路：
给 `flyMs` 加下限，或者让 `spins` 随力度递减。

效果（默认力度，从最初版本到现在的完整演进）：

| 版本 | 总时长 | 圈数 | 峰值 圈/秒 |
| --- | --- | --- | --- |
| 最初 | 1466ms | 4 | **10.44** |
| 1/4 速度 + 减圈 | 5864ms | 3 | 2.94 |
| 1/2 速度 + 摊开翻滚 | 2932ms | 3 | 3.92 |
| 1/2 速度 + 翻滚只在起飞段 | 2932ms | 3 | 2.56 |
| 当前（TIME_SCALE=2 + 2 圈 + 短回落） | 1263ms | 2 | 3.17 |

单测断言：圈数在 2～3、起步斜率 < 2、峰值 < 4.5 圈/秒；另外还断言了两段缓动在衔接处的
速度都为 0，以及在组件层抓起飞段结束时的姿态角、比对回落段结束后是否完全一致。

### 投掷动画开关

页面底部有一个「投掷动画」开关（ARIA `role="switch"`）。
关闭时松手直接跳到落地姿态，无过渡、无两段动画。

- **默认值**：跟随系统 `prefers-reduced-motion`——系统要求减少动态效果时默认关闭，否则开启。
- **显式选择优先**：用户手动切换过后记住该选择并覆盖系统偏好。前端不保留
  `@media (prefers-reduced-motion)` 规则，否则它会把用户显式打开的动画又屏蔽掉。
- **持久化**：写入 `localStorage` 的 `rollone:animation-enabled`；
  存储不可用（Safari 隐私模式等）时静默降级，本次会话内开关依然有效。

逻辑在 `src/lib/animationPreference.ts`，纯函数、可单独测试。

## 新增 / 修改颜色

在 `src/config/colors.ts` 的 `COLORS` 数组里增删条目即可。
注意立方体固定 6 个面，`COLORS` 超过 5 项后多出的颜色不会出现在骰子上。

```ts
{ id: 'teal', label: '青色', color: '#2f7d78' }
```

- `id` 必须唯一，且不能使用保留值 `'question'`
- `label` 是结果播报里显示的中文名（`aria-live` 会念出来，也是色盲用户唯一的区分手段）
- `color` 必须是 `#RGB` / `#RRGGBB` 等合法十六进制颜色

默认调色板见 `src/config/colors.ts` 里的 `COLORS`。这里刻意不复制具体的十六进制值——
调色板会被反复微调，写死在文档里必然过期。

## 浏览器与设备要求

- 需要 `transform-style: preserve-3d` 与 `perspective`：现代 Chrome / Safari / Firefox / Edge 都支持，桌面与移动端一致。
- 触控用 Pointer Events + `touch-action: none`，拖拽时不会带动页面滚动。
- `setPointerCapture` 是渐进增强（代码里写作 `?.()` 可选调用）——jsdom 未实现它，硬调用会让组件测试直接抛错。
- 无 `crypto.getRandomValues` 的运行时回退到 `Math.random`。

## 已知问题

**弱力度反而转得更快。** 圈数固定 2 圈，而起飞段时长随力度增长，于是力度越小转速越高
（当前系数下最小力度约 4.03 圈/秒，满力度约 2.84）。两条修法：给 `flyMs` 加下限，
或让 `spins` 随力度递减。

**`TIME_SCALE` 不是"全局"缩放。** 它只作用于起飞段，回落段不吃缩放，所以改它会改变
两段的**比例**；只有 `TIME_SCALE = 1` 时两段才严格按 `FLY_SHARE` 划分。若这是有意的，
保持现状即可；若想恢复全局语义，需要给 `settleMs` 补上乘数。

**演示视频是 HEVC（H.265）编码。** Chrome / Firefox 不支持这个编码，只有 Safari 能播，
而 GitHub 又会过滤 `<video>` 标签——两者叠加的结果是：多数人点开 `resources/demo.mp4`
只能下载、不能直接看。两条修法：

```bash
# 转成浏览器通吃的 H.264（体积会涨一些，可加 -crf 28 压一压）
ffmpeg -i resources/demo.mp4 -c:v libx264 -pix_fmt yuv420p -movflags +faststart resources/demo-h264.mp4
```

或者截取前几秒做成 GIF——GIF 到处都能内联播放，但 16 秒的视频转 GIF 会有好几 MB，
建议只截一段关键动作。

## 技术栈

TypeScript · React 19 · Vite 8 · Tailwind CSS 4（`@tailwindcss/vite`，CSS-first）·
Vitest 5 + Testing Library · pnpm（淘宝镜像，见 `.npmrc`）

3D 用纯 CSS（`perspective` + `transform-style: preserve-3d`），没有 three.js 之类的依赖。

## 许可证

[MIT](./LICENSE) © 2026 zouyu