Skill: dletter2/rhythm-master (version 1.0.0)

--- name: rhythm-master description: This skill enables playing a rhythm game called "节奏大师" (Rhythm Master) similar to QQ Dance/DDR. Players press arrow keys and spacebar in time with falling notes to score points. The game features multiple difficulty levels, combo system, judgment ratings (PERFECT/GREAT/GOOD/BAD/MISS), local leaderboard, and can be extended with online leaderboards. Use this skill when the user wants to play a rhythm game, test their reflexes, or have fun with a keyboard-based music game. --- # 节奏大师 - Rhythm Master ## 简介 《节奏大师》是一款键盘节奏游戏，玩家需要在正确的时机按下对应的按键（↑↓←→空格），跟随音乐节奏击打落下的音符。游戏拥有完善的判定系统、连击机制、多难度等级和排行榜功能。 ## 何时使用此 Skill - 用户说"我想玩节奏游戏"、"来玩音游"、"测试手速" - 用户想要类似 QQ炫舞、osu!、太鼓达人 的游戏体验 - 用户想玩需要反应速度的键盘游戏 - 聚会时需要竞技性小游戏 - 用户明确表示想玩音乐节奏游戏 ## 游戏特色 ### 🎮 核心玩法 - **5键操作**：← ↓ SPACE ↑ → - **实时判定**：PERFECT / GREAT / GOOD / BAD / MISS - **连击系统**：连击越高，得分倍数越高 - **生命系统**：MISS会扣除生命，生命归零游戏结束 ### 📊 难度等级 | 难度 | 速度 | 音符密度 | 适合人群 | |------|------|----------|----------| | 简单 (EASY) | 慢 | 稀疏 | 初学者 | | 普通 (NORMAL) | 中等 | 中等 | 普通玩家 | | 困难 (HARD) | 快 | 密集 | 熟练玩家 | | 专家 (EXPERT) | 极快 | 极密 | 高手 | ### 🏆 排行榜系统 - **本地排行榜**：自动保存前100名，使用浏览器 LocalStorage - **联网排行榜**：可扩展至 Firebase/自建服务器（需额外配置） - **详细统计**：保存 PERFECT/GREAT/GOOD/BAD/MISS 数量和最大连击 ## 游戏数据与资源 ### 游戏机制文档 - `references/game_mechanics.md` - 完整游戏机制说明 - 判定系统（50ms-200ms 时间窗口） - 得分计算公式 - 连击加成表 - 评级系统（SSS/A/B/C/D） - 游戏模式（经典/无尽/挑战/对战/练习） ### 排行榜系统文档 - `references/leaderboard_system.md` - 排行榜实现方案 - 本地存储实现（已内置） - Firebase 联网方案 - 自建后端方案（Node.js + MongoDB） - 防作弊机制 - 部署指南 ### 游戏实现 - `assets/rhythm-game.html` - 完整的网页版游戏 - 单文件 HTML，开箱即用 - 响应式设计，支持移动端 - 完整的游戏逻辑和UI - 本地排行榜功能 ## 如何使用 ### 启动游戏 **方式一：直接打开 HTML 文件** 1. 打开 `assets/rhythm-game.html` 2. 使用浏览器打开（推荐 Chrome/Edge/Firefox） 3. 选择难度，点击"开始游戏" **方式二：部署到网页服务器** ```bash # 使用 Python 快速启动本地服务器 cd assets python -m http.server 8080 # 访问 http://localhost:8080/rhythm-game.html ``` **方式三：部署到公网** - GitHub Pages - Netlify - Vercel - Cloudflare Pages ### 游戏操作 ``` 按键布局： 左手区 空格 右手区 ┌───┬───┐ ┌───┬───┐ │ ← │ ↓ │ [SPACE] │ ↑ │ → │ └───┴───┘ └───┴───┘ 小指 无名指 双手拇指 食指 中指 ``` **操作技巧：** 1. **保持节奏感**：跟着内心默数节拍 2. **预判音符**：眼睛看判定线，余光看音符 3. **手位固定**：保持手位不要移动 4. **宁可GOOD不断连**：保持连击比准确率更重要 5. **放松心态**：紧张会影响反应速度 ### 游戏规则 1. **音符下落**：音符从上方落下，到达判定线时按键 2. **判定等级**： - 🌟 PERFECT (±50ms) - 100分 - ✨ GREAT (±100ms) - 80分 - 👍 GOOD (±150ms) - 50分 - 😕 BAD (±200ms) - 20分，连击中断 - ❌ MISS (>200ms) - 0分，扣1生命 3. **连击加成**： - 1-10连击：1.0x - 11-30连击：1.1x - 31-50连击：1.2x - 51-100连击：1.5x - 101-200连击：2.0x - 200+连击：2.5x 4. **评级系统**（根据准确率）： - SSS (100%) - 节奏之神 - SS (95-99%) - 节奏大师 - S (90-94%) - 节奏高手 - A (80-89%) - 节奏达人 - B (70-79%) - 节奏学徒 - C (60-69%) - 节奏新手 - D (<60%) - 节奏小白 ## 游戏流程 ### 1. 主菜单 ``` 🎵 节奏大师 [选择难度：简单/普通/困难/专家] [▶ 开始游戏] [🏆 排行榜] [❓ 游戏说明] ``` ### 2. 游戏界面 ``` 得分: 12,500 | 连击: 45 | 生命: ♥♥♥♥♥ | 时间: 45s [COMBO 显示区域] ← ↓ SPACE ↑ → ○ ○ ○ ○ ○ ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ [判定线] 【音符从这里落下】 ``` ### 3. 游戏结束 ``` 🎉 游戏结束 最终得分: 98,500 评级: S 统计： PERFECT: 120 | GREAT: 35 | GOOD: 5 BAD: 0 | MISS: 0 | 最大连击: 156 [输入名字保存分数] [💾 保存分数] [🏆 查看排行榜] [🔙 返回主菜单] ``` ## 扩展联网排行榜 ### 快速方案：Firebase（推荐） **步骤：** 1. 访问 https://firebase.google.com 创建项目 2. 获取配置信息 3. 在 `rhythm-game.html` 中添加 Firebase SDK 4. 修改保存分数和获取排行榜的函数 **代码示例：** ```javascript // 保存到云端 async function saveScoreOnline(scoreData) { const db = firebase.database(); await db.ref('leaderboard').push(scoreData); } // 获取排行榜 async function getOnlineLeaderboard() { const snapshot = await db.ref('leaderboard') .orderByChild('score') .limitToLast(20) .once('value'); return snapshot.val(); } ``` 详细配置请参考 `references/leaderboard_system.md` ## 游戏特色功能 ### 视觉效果 - 🌈 霓虹科技风格 UI - ✨ 判定结果动态特效 - 🔥 连击数越高背景越华丽 - 💥 MISS时屏幕震动反馈 - 🎨 不同按键不同颜色区分 ### 音效反馈 - 每个按键有不同的音高 - 判定结果有不同音效 - 连击 milestone 有特殊音效 ### 响应式设计 - 支持桌面端和移动端 - 自适应不同屏幕尺寸 - 触摸操作支持（移动端） ## 技术规格 ### 性能要求 - 目标帧率：60fps - 输入延迟：<16ms - 支持浏览器：Chrome 80+, Firefox 75+, Edge 80+, Safari 13+ ### 代码结构 ``` rhythm-game.html ├── HTML 结构 │ ├── 菜单界面 │ ├── 游戏界面 │ ├── 结算界面 │ └── 排行榜界面 ├── CSS 样式 │ ├── 霓虹灯主题 │ ├── 动画效果 │ └── 响应式布局 └── JavaScript 逻辑 ├── 游戏状态管理 ├── 音符生成系统 ├── 判定系统 ├── 得分计算 └── 排行榜存储 ``` ## 注意事项 ### 键盘兼容性 - 确保键盘支持多键同时按下（防鬼键） - 部分笔记本键盘可能有限制 - 推荐使用外接机械键盘获得最佳体验 ### 浏览器设置 - 确保浏览器允许自动播放（如需添加背景音乐） - 建议全屏模式游玩（按 F11） - 关闭省电模式以保持 60fps ### 游戏体验优化 1. **首次游玩**：建议从"简单"难度开始 2. **提高准确率**：专注听节奏而非看音符 3. **保持连击**：宁可准确率稍低也不要断连 4. **休息间隔**：每玩3-5局休息眼睛和手指 ## 示例对话 ### 启动游戏 ``` 用户：我想玩节奏游戏 AI：好的！为你启动《节奏大师》🎵 这是一款键盘节奏游戏，使用 ← ↓ SPACE ↑ → 五个按键。 音符会从上方落下，到达判定线时按下对应按键！ 游戏已准备好，选择难度开始吧： - 🟢 简单 - 适合初学者 - 🔵 普通 - 标准难度 - 🟡 困难 - 需要较好反应 - 🔴 专家 - 极限挑战 你想选择哪个难度？ ``` ### 游戏进行中提示 ``` AI：游戏开始！跟着节奏点击按键... 💡 小技巧： 1. 眼睛看判定线，余光看音符 2. 保持放松，紧张会影响反应 3. 宁可GOOD不断连，连击加成很重要！ 当前状态： ❤️ 生命：5/5 | ⭐ 连击：0 | 🎯 得分：0 准备好了吗？3... 2... 1... GO! 🎮 ``` ### 游戏结束后 ``` AI：🎉 游戏结束！ 📊 你的成绩： ━━━━━━━━━━━━━━━━━━━━━━ 得分：98,500 评级：S (节奏高手) 最大连击：156 详细统计： 🌟 PERFECT：120 ✨ GREAT：35 👍 GOOD：5 😕 BAD：0 ❌ MISS：0 ━━━━━━━━━━━━━━━━━━━━━━ 太棒了！几乎没有失误！想再挑战一次更高难度吗？ ``` ## 文件清单 ``` rhythm-master/ ├── SKILL.md # 本文件 - 核心文档 ├── references/ │ ├── game_mechanics.md # 游戏机制详细说明 │ └── leaderboard_system.md # 排行榜系统方案 └── assets/ └── rhythm-game.html # 完整游戏文件 ``` ## 许可 本 Skill 为开源项目，可自由使用、修改和分发。 --- 🎵 **准备好挑战你的反应极限了吗？打开 rhythm-game.html 开始游戏吧！**

path: FIREBASE_SETUP.md
content: # 🔥 Firebase 联网排行榜配置教程

本教程将指导你如何配置 Firebase，让《节奏大师》拥有真正的全球排行榜功能。

---

## 📋 概述

**当前状态**：
- ✅ `rhythm-game.html` - 本地版（仅本地存储）
- ✅ `rhythm-game-online.html` - 联网版（需要 Firebase 配置）

**配置后效果**：
- 🌍 全球玩家分数实时同步
- 🏆 真正的全球排行榜
- 💾 数据永久保存，不会丢失
- ⚡ 实时更新，无需刷新页面

---

## 🚀 配置步骤（5分钟搞定）

### 步骤 1：创建 Firebase 项目

1. 访问 [Firebase 官网](https://firebase.google.com/)
2. 点击 **"Get Started"** 或 **"开始使用"**
3. 登录你的 Google 账号
4. 点击 **"创建项目"**
5. 输入项目名称（如：`rhythm-master-game`）
6. 勾选同意条款，点击 **"继续"**
7. 询问是否启用 Google Analytics → 选择 **"不启用"**（简化流程）
8. 点击 **"创建项目"**，等待创建完成

### 步骤 2：创建 Realtime Database

1. 项目创建完成后，点击 **"继续"**
2. 在左侧菜单找到 **"构建"** → **"Realtime Database"**
3. 点击 **"创建数据库"**
4. 选择数据库位置（建议选择 `asia-southeast1` 新加坡，离你最近）
5. 安全规则选择 **"以锁定模式开始"**（稍后会修改）
6. 点击 **"启用"**

### 步骤 3：修改安全规则

1. 数据库创建后，点击 **"规则"** 标签
2. 修改规则为以下内容（允许读写）：

```json
{
  "rules": {
    ".read": true,
    ".write": true,
    "leaderboard": {
      ".read": true,
      ".write": true
    }
  }
}
```

3. 点击 **"发布"**

⚠️ **注意**：这个规则允许任何人读写，仅用于演示。生产环境应该添加验证。

### 步骤 4：获取配置信息

1. 点击左侧 **"项目概览"** 旁边的 **"⚙️"**（齿轮图标）
2. 选择 **"项目设置"**
3. 在 **"常规"** 标签页，下拉到 **"你的应用"** 部分
4. 点击 **"</>"**（添加 Web 应用）
5. 输入应用昵称（如：`rhythm-web`）
6. 点击 **"注册应用"**
7. 你会看到一段配置代码，类似这样：

```javascript
const firebaseConfig = {
  [REDACTED_SECRET]",
  authDomain: "rhythm-master-game.firebaseapp.com",
  databaseURL: "https://rhythm-master-game-default-rtdb.firebaseio.com",
  projectId: "rhythm-master-game",
  storageBucket: "rhythm-master-game.appspot.com",
  messagingSenderId: "123456789012",
  appId: "1:123456789012:web:abc123def456"
};
```

### 步骤 5：配置游戏文件

1. 打开 `rhythm-game-online.html`
2. 找到第 92-100 行的 `firebaseConfig` 配置
3. 将你在步骤 4 获取的配置信息粘贴进去：

```javascript
// 原来的配置（需要替换）
const firebaseConfig = {
    [REDACTED_SECRET]",
    authDomain: "your-project.firebaseapp.com",
    databaseURL: "https://your-project-default-rtdb.firebaseio.com",
    projectId: "your-project",
    storageBucket: "your-project.appspot.com",
    messagingSenderId: "YOUR_SENDER_ID",
    appId: "YOUR_APP_ID"
};

// 替换为你自己的配置，例如：
const firebaseConfig = {
    [REDACTED_SECRET]",
    authDomain: "rhythm-master-game.firebaseapp.com",
    databaseURL: "https://rhythm-master-game-default-rtdb.firebaseio.com",
    projectId: "rhythm-master-game",
    storageBucket: "rhythm-master-game.appspot.com",
    messagingSenderId: "123456789012",
    appId: "1:123456789012:web:abc123def456"
};
```

4. 保存文件

### 步骤 6：测试

1. 在浏览器中打开配置好的 `rhythm-game-online.html`
2. 如果看到 **"🌐 已连接到全球服务器"**，说明配置成功！
3. 玩一局游戏，保存分数
4. 查看排行榜，应该能看到你的分数

---

## 🌐 部署到公网

配置好 Firebase 后，将游戏部署到公网，让所有人都能访问：

### 方案 1：GitHub Pages（免费，推荐）

1. 在 GitHub 创建新仓库（如 `rhythm-master`）
2. 上传 `rhythm-game-online.html` 并重命名为 `index.html`
3. 进入仓库 **Settings** → **Pages**
4. Source 选择 **Deploy from a branch**，Branch 选择 **main**
5. 等待几分钟后，访问 `https://你的用户名.github.io/rhythm-master/`

### 方案 2：Netlify（免费）

1. 访问 [Netlify](https://www.netlify.com/)
2. 注册账号（可用 GitHub 账号登录）
3. 点击 **"Add new site"** → **"Deploy manually"**
4. 将 `rhythm-game-online.html` 拖放到上传区域
5. 等待部署完成，获得免费域名

### 方案 3：Vercel（免费）

1. 访问 [Vercel](https://vercel.com/)
2. 注册账号（可用 GitHub 账号登录）
3. 点击 **"Add New..."** → **"Project"**
4. 导入 GitHub 仓库或上传文件
5. 自动部署，获得免费域名

---

## 📊 数据管理

### 查看数据库数据

1. 进入 Firebase 控制台
2. 点击 **"Realtime Database"**
3. 可以看到所有玩家提交的数据

### 数据结构

```json
{
  "leaderboard": {
    "-Nabc123": {
      "playerName": "玩家名",
      "score": 98500,
      "maxCombo": 156,
      "perfect": 120,
      "great": 35,
      "good": 5,
      "bad": 0,
      "miss": 0,
      "difficulty": "hard",
      "timestamp": 1678623456789,
      "date": "2026-03-12T10:30:00.000Z"
    },
    "-Ndef456": { ... }
  }
}
```

### 清理数据

如果想重置排行榜：
1. 进入 Realtime Database
2. 点击 `leaderboard` 节点
3. 点击右侧的 **"X"** 删除
4. 确认删除

---

## 🔒 安全建议

### 生产环境规则（进阶）

如果你要正式发布，建议使用更严格的规则：

```json
{
  "rules": {
    ".read": true,
    "leaderboard": {
      ".write": true,
      ".indexOn": ["score", "timestamp"],
      "$scoreId": {
        ".validate": "newData.hasChildren(['playerName', 'score', 'maxCombo', 'difficulty', 'timestamp'])"
      }
    }
  }
}
```

### 防作弊建议

1. **频率限制**：限制同一IP提交频率
2. **分数验证**：服务端验证分数合理性
3. **人机验证**：添加 reCAPTCHA

这些需要配合 Cloud Functions 实现，详见 [Firebase 文档](https://firebase.google.com/docs/functions)。

---

## ❓ 常见问题

### Q1: 连接失败，显示 "未连接到服务器"

**可能原因**：
- Firebase 配置信息错误
- 网络问题
- 安全规则未设置

**解决方案**：
1. 检查 `apiKey`、`databaseURL` 是否正确
2. 确保数据库规则已设置为允许读写
3. 打开浏览器开发者工具(F12)查看 Console 错误信息

### Q2: 可以提交分数，但排行榜不显示

**可能原因**：
- 数据格式错误
- 查询条件问题

**解决方案**：
1. 在 Firebase 控制台检查数据是否存在
2. 检查数据字段是否完整

### Q3: 排行榜加载很慢

**解决方案**：
1. 限制查询数量（已设置为50条）
2. 添加数据库索引（在安全规则中添加 `.indexOn`）
3. 使用分页加载

### Q4: 免费额度够吗？

Firebase 免费额度（Spark 计划）：
- 数据库：1GB 存储，10GB/月 下载
- 并发：100 个同时连接
- 足够支持数千名玩家

---

## 📱 测试清单

配置完成后，检查以下功能：

- [ ] 页面显示 "🌐 已连接到全球服务器"
- [ ] 可以正常游戏
- [ ] 游戏结束后可以保存分数
- [ ] 排行榜显示刚刚保存的分数
- [ ] 不同浏览器/设备可以看到相同的数据

---

## 🎉 完成！

配置完成后，你就拥有了一个真正联网的《节奏大师》游戏！

- 🌍 全球玩家可以一起竞技
- 🏆 实时更新的排行榜
- 💾 永久保存的游戏记录
- 📱 随时随地访问

快分享给朋友们一起玩吧！🎮

---

## 📞 需要帮助？

- Firebase 官方文档：https://firebase.google.com/docs
- Firebase 中文文档：https://firebase.google.cn/docs
- 社区支持：https://github.com/firebase/firebase-js-sdk/discussions


path: README.md
content: # 🎵 节奏大师 - Rhythm Master

一款类似 QQ炫舞 的键盘节奏游戏 Skill！

## 🎮 游戏简介

《节奏大师》是一款基于网页的键盘节奏游戏，玩家需要在正确的时机按下方向键（↑↓←→）和空格键，跟随音乐节奏击打落下的音符。

### 核心特色

- 🎯 **5键操作**：← ↓ SPACE ↑ → 简单易上手
- 🌟 **精准判定**：PERFECT/GREAT/GOOD/BAD/MISS 五级判定
- 🔥 **连击系统**：连击越高，得分倍数越高（最高 2.5x）
- 📊 **多难度等级**：简单/普通/困难/专家 四个难度
- 🏆 **排行榜系统**：本地存储 + 可扩展联网排行榜
- 🎨 **霓虹科技风**：炫酷的视觉特效和动画
- 📱 **响应式设计**：支持桌面端和移动端

## 🚀 快速开始

### 方法一：直接打开（最简单）
```
1. 双击打开 assets/rhythm-game.html
2. 在浏览器中开始游戏
```

### 方法二：本地服务器
```bash
cd assets
python -m http.server 8080
# 访问 http://localhost:8080/rhythm-game.html
```

### 方法三：部署到公网
将 `rhythm-game.html` 部署到：
- [GitHub Pages](https://pages.github.com/)
- [Netlify](https://www.netlify.com/)
- [Vercel](https://vercel.com/)
- [Cloudflare Pages](https://pages.cloudflare.com/)

## 🎯 操作说明

### 按键布局
```
左手区          空格          右手区
┌───┬───┐                    ┌───┬───┐
│ ← │ ↓ │       [SPACE]      │ ↑ │ → │
└───┴───┘                    └───┴───┘
小指  无名指      双手拇指       食指  中指
```

### 游戏流程
1. 选择难度等级
2. 3秒倒计时准备
3. 音符从上方落下
4. 音符到达判定线时按下对应按键
5. 根据准确度获得不同判定和分数
6. 保持连击获得更高分数
7. 生命归零或时间结束游戏结束

## 📊 判定系统

| 判定 | 时间窗口 | 得分 | 效果 |
|------|----------|------|------|
| 🌟 PERFECT | ±50ms | 100分 | 完美命中 |
| ✨ GREAT | ±100ms | 80分 | 很好 |
| 👍 GOOD | ±150ms | 50分 | 不错 |
| 😕 BAD | ±200ms | 20分 | 较差，断连击 |
| ❌ MISS | >200ms | 0分 | 错过，扣生命 |

## 🏆 评级系统

根据准确率评定等级：

| 评级 | 准确率 | 称号 |
|------|--------|------|
| SSS | 100% | 🏅 节奏之神 |
| SS | 95-99% | 🥈 节奏大师 |
| S | 90-94% | 🥉 节奏高手 |
| A | 80-89% | ⭐ 节奏达人 |
| B | 70-79% | 📈 节奏学徒 |
| C | 60-69% | 📖 节奏新手 |
| D | <60% | 🌱 节奏小白 |

## 📁 文件结构

```
rhythm-master/
├── SKILL.md                     # Skill 核心文档
├── README.md                    # 本文件
├── references/
│   ├── game_mechanics.md       # 游戏机制详细说明
│   └── leaderboard_system.md   # 排行榜系统方案
└── assets/
    └── rhythm-game.html        # 完整游戏（单文件）
```

## 🎨 游戏截图

### 主菜单
```
🎵 节奏大师
RHYTHM MASTER - 用键盘感受节奏的律动

选择难度：
[简单] [普通] [困难] [专家]

[▶ 开始游戏]
[🏆 排行榜]
[❓ 游戏说明]
```

### 游戏界面
```
得分: 12,500  |  连击: 45  |  生命: ♥♥♥♥♥  |  时间: 45s

        🔥 45 COMBO! 🔥

    ←       ↓      SPACE      ↑       →
    ○       ○        ○        ○       ○

    ═══════════════════════════════
              [判定线]
```

### 结算界面
```
🎉 游戏结束

最终得分: 98,500
评级: S

统计：
PERFECT: 120  |  GREAT: 35  |  GOOD: 5
BAD: 0        |  MISS: 0    |  最大连击: 156

[保存分数] [查看排行榜] [返回主菜单]
```

## 🌐 联网排行榜

### 已实现的本地排行榜
- ✅ 自动保存前100名
- ✅ 浏览器 LocalStorage 存储
- ✅ 包含玩家名、分数、连击、难度、日期

### 扩展为联网排行榜

#### 方案一：Firebase（推荐，免费）
```javascript
// 在 rhythm-game.html 中添加 Firebase 配置
const firebaseConfig = {
  // 你的 Firebase 配置
};
firebase.initializeApp(firebaseConfig);

// 保存分数
firebase.database().ref('leaderboard').push(scoreData);

// 获取排行榜
firebase.database().ref('leaderboard')
  .orderByChild('score')
  .limitToLast(20)
  .once('value', callback);
```

#### 方案二：自建后端
- Node.js + Express + MongoDB
- 详细代码见 `references/leaderboard_system.md`

## 💡 操作技巧

### 新手建议
1. **从简单难度开始** - 熟悉节奏和按键
2. **保持手位固定** - 不要移动手的位置
3. **眼睛看判定线** - 余光看音符
4. **宁可GOOD不断连** - 连击加成非常重要

### 进阶技巧
1. **预判音符** - 提前看后面的音符序列
2. **听节奏** - 跟着背景音乐节拍按键
3. **肌肉记忆** - 熟练后形成条件反射
4. **放松心态** - 紧张会影响反应速度

## 🔧 技术规格

### 浏览器支持
- ✅ Chrome 80+
- ✅ Firefox 75+
- ✅ Edge 80+
- ✅ Safari 13+

### 性能
- 🎯 目标帧率：60fps
- ⚡ 输入延迟：<16ms
- 📱 支持移动端触摸操作

### 代码架构
```
rhythm-game.html
├── HTML (结构)
│   ├── 菜单界面
│   ├── 游戏界面
│   ├── 结算界面
│   └── 排行榜界面
├── CSS (样式)
│   ├── 霓虹灯主题
│   ├── 动画效果
│   └── 响应式布局
└── JavaScript (逻辑)
    ├── 游戏状态管理
    ├── 音符生成系统
    ├── 判定系统
    ├── 得分计算
    └── 排行榜存储
```

## 🎮 游戏模式

### 当前实现
- **经典模式** - 60秒限时挑战

### 可扩展模式
- **无尽模式** - 无限进行直到生命耗尽
- **挑战模式** - 特定高难度谱面
- **对战模式** - 双人同屏对战
- **练习模式** - 可调节速度的慢速练习

扩展方案详见 `references/game_mechanics.md`

## 📝 更新日志

### v1.0.0
- ✅ 基础游戏玩法
- ✅ 5键操作系统
- ✅ 5级判定系统
- ✅ 4种难度等级
- ✅ 连击和得分系统
- ✅ 本地排行榜
- ✅ 响应式设计
- ✅ 霓虹科技风UI

## 🤝 贡献

欢迎提交 Issue 和 PR！

### 可扩展功能
- [ ] 添加背景音乐
- [ ] 自定义谱面编辑器
- [ ] 多人实时对战
- [ ] 成就系统
- [ ] 皮肤系统
- [ ] 更多音符类型（长按、连打）

## 📄 许可

MIT License - 可自由使用、修改和分发

---

🎵 **准备好挑战你的反应极限了吗？开始游戏吧！**

**操作提示**：按 F11 进入全屏模式获得最佳体验！


path: references/game_mechanics.md
content: # 节奏大师 - 游戏机制说明

## 游戏概述

《节奏大师》是一款键盘节奏游戏，玩家需要在正确的时机按下对应的按键（↑↓←→空格），根据准确度和连击数获得分数。

## 核心玩法

### 按键系统

#### 基础按键
- **↑** (上箭头) - 对应方向 "UP"
- **↓** (下箭头) - 对应方向 "DOWN"
- **←** (左箭头) - 对应方向 "LEFT"
- **→** (右箭头) - 对应方向 "RIGHT"
- **Space** (空格键) - 对应 "HIT"

#### 按键显示方式
```
╔══════════════════════════════════════╗
║  ←    ↑    SPACE    ↓    →          ║
║  ○    ○     ○      ○    ○           ║
║                                      ║
║         ██████████████████          ║  ← 判定线
║                                      ║
╚══════════════════════════════════════╝
```

### 游戏流程

#### 1. 开始界面
- 显示游戏标题和 Logo
- 选择游戏模式
- 查看排行榜
- 设置选项

#### 2. 游戏准备
- 3秒倒计时
- 显示即将开始的提示
- 玩家准备手位（建议：左手 ←↓，右手 →↑，拇指空格）

#### 3. 游戏进行
- 音符从上方落下
- 经过判定线时按下对应按键
- 实时显示判定结果和分数
- 显示连击数

#### 4. 游戏结束
- 显示最终得分
- 显示统计信息（Perfect/Great/Good/Miss 数量）
- 显示最大连击数
- 输入玩家名字保存分数
- 查看排行榜排名

---

## 判定系统

### 判定等级

| 判定 | 时间窗口 | 得分倍率 | 效果 |
|------|----------|----------|------|
| **PERFECT** | ±50ms | 100% | 完美命中，连击+1 |
| **GREAT** | ±100ms | 80% | 很好，连击+1 |
| **GOOD** | ±150ms | 50% | 一般，连击+1 |
| **BAD** | ±200ms | 20% | 较差，连击中断 |
| **MISS** | >200ms 或未按 | 0% | 错过，连击中断 |

### 判定显示
- **PERFECT**: 彩虹色闪烁 + "PERFECT!" 文字
- **GREAT**: 金色闪烁 + "GREAT!" 文字
- **GOOD**: 绿色闪烁 + "GOOD" 文字
- **BAD**: 灰色闪烁 + "BAD" 文字
- **MISS**: 红色闪烁 + "MISS" 文字 + 屏幕轻微震动

---

## 得分系统

### 基础得分公式
```
单音符得分 = 基础分(100) × 判定倍率 × 连击加成 × 难度系数
```

### 连击加成
| 连击数 | 加成倍率 |
|--------|----------|
| 1-10 | 1.0x |
| 11-30 | 1.1x |
| 31-50 | 1.2x |
| 51-100 | 1.5x |
| 101-200 | 2.0x |
| 200+ | 2.5x |

### 难度系数
| 难度 | 下落速度 | 音符密度 | 系数 |
|------|----------|----------|------|
| 简单 (EASY) | 慢 | 稀疏 | 1.0x |
| 普通 (NORMAL) | 中等 | 中等 | 1.2x |
| 困难 (HARD) | 快 | 密集 | 1.5x |
| 专家 (EXPERT) | 极快 | 极密 | 2.0x |
| 大师 (MASTER) | 极速 | 疯狂 | 3.0x |

### 评级系统
根据最终得分百分比评定等级：

| 评级 | 得分百分比 | 称号 |
|------|------------|------|
| **SSS** | 100% | 节奏之神 |
| **SS** | 95-99% | 节奏大师 |
| **S** | 90-94% | 节奏高手 |
| **A** | 80-89% | 节奏达人 |
| **B** | 70-79% | 节奏学徒 |
| **C** | 60-69% | 节奏新手 |
| **D** | <60% | 节奏小白 |

---

## 游戏模式

### 1. 经典模式 (Classic)
- 标准节奏游戏玩法
- 随机生成音符序列
- 固定时长（60秒/120秒/完整歌曲）
- 适合练习和熟悉操作

### 2. 无尽模式 (Endless)
- 无限进行直到 MISS 数达到上限（3次）
- 速度会逐渐加快
- 挑战最高连击和分数
- 适合高手挑战极限

### 3. 挑战模式 (Challenge)
- 特定的高难度谱面
- 预设的音符序列
- 完成特定目标（如：全连击、不准有MISS等）
- 解锁成就和奖励

### 4. 对战模式 (VS Mode)
- 两名玩家同屏对战
- 相同音符序列
- 分数高者获胜
- 支持本地双人（键盘左右分区）

### 5. 练习模式 (Practice)
- 可调节速度（0.5x - 2.0x）
- 可暂停和回放
- 显示判定线提示
- 适合新手学习

---

## 音符类型

### 基础音符
- **单音符 (Single)**: 普通按键，按一次即可

### 高级音符
- **长音符 (Long)**: 按住不放直到音符结束
- **连音符 (Chain)**: 快速连续按下同一按键多次
- **组合音符 (Combo)**: 同时按下多个按键（如：↑+→）

### 特殊音符
- **奖励音符 (Bonus)**: 金色音符，击中获得额外分数
- **生命音符 (Heal)**: 绿色音符，恢复失误次数
- **危险音符 (Danger)**: 红色音符，错过会扣除大量分数

---

## 生命值系统

### 经典模式
- 初始生命：5颗心
- BAD：-0.5心
- MISS：-1心
- 生命归零：游戏结束

### 无尽模式
- 初始生命：3次失误机会
- 任何非 PERFECT/GREAT：消耗 1 次机会
- 机会归零：游戏结束

---

## 排行榜系统

### 本地排行榜
- 存储在浏览器 LocalStorage
- 保存前 100 名分数
- 包含：排名、玩家名、分数、连击、难度、日期

### 联网排行榜
- 使用后端 API 存储
- 全球排名
- 好友排名
- 每周/每月重置

### 分数提交
```json
{
  "playerName": "Player123",
  "score": 98500,
  "maxCombo": 156,
  "perfect": 120,
  "great": 35,
  "good": 5,
  "bad": 0,
  "miss": 0,
  "difficulty": "HARD",
  "gameMode": "classic",
  "timestamp": "2026-03-12T10:30:00Z"
}
```

---

## 视觉效果

### 判定线
- 发光效果
- 判定成功时闪烁对应颜色
- 判定失败时红色警告

### 音符样式
- 不同按键用不同颜色区分
- 音符带有光晕效果
- 接近判定线时放大提醒

### 背景效果
- 动态背景随节奏变化
- 连击数高时背景更加华丽
- 判定结果有粒子特效

### UI 界面
- 现代科技感设计
- 霓虹灯风格配色
- 流畅的动画过渡

---

## 音效系统

### 按键音效
- 每个按键有不同的音高
- 形成简单的音乐旋律
- 判定结果有不同的音效反馈

### 背景音乐
- 多首不同风格的 BGM
- 根据节奏自动播放
- 可调整音量或静音

### 音效反馈
- PERFECT: 清脆的高音
- GREAT: 中音
- GOOD: 低音
- BAD/MISS: 闷响或警告音

---

## 操作技巧

### 手位建议
```
左手区          空格          右手区
┌───┬───┐                    ┌───┬───┐
│ ← │ ↓ │       [SPACE]      │ ↑ │ → │
└───┴───┘                    └───┴───┘
小指  无名指      双手拇指       食指  中指
```

### 进阶技巧
1. **预判**: 提前看后面的音符序列
2. **节奏感**: 跟着背景音乐的节拍按键
3. **肌肉记忆**: 熟练后形成条件反射
4. **连击保持**: 宁可牺牲准确度也要保持连击
5. **放松**: 紧张会影响反应速度

---

## 难度曲线

### 简单 (EASY)
- BPM: 80-100
- 单音符为主
- 间隔较长 (>1秒)
- 适合初学者

### 普通 (NORMAL)
- BPM: 100-130
- 偶尔出现双音符
- 间隔中等 (0.5-1秒)
- 适合有一定基础的玩家

### 困难 (HARD)
- BPM: 130-160
- 常见双音符和短连击
- 间隔较短 (0.3-0.5秒)
- 需要较好反应速度

### 专家 (EXPERT)
- BPM: 160-200
- 频繁出现组合音符
- 间隔很短 (0.2-0.3秒)
- 需要精准操作

### 大师 (MASTER)
- BPM: 200+
- 复杂的音符组合
- 超高密度
- 极限挑战

---

## 技术规格

### 输入延迟
- 目标延迟: <16ms (60fps)
- 支持键盘防鬼键 (Anti-ghosting)

### 帧率
- 目标帧率: 60fps
- 音符动画流畅
- 判定精准

### 兼容性
- 支持主流浏览器
- 支持键盘输入
- 响应式设计（支持不同分辨率）


path: references/leaderboard_system.md
content: # 排行榜系统说明

## 系统概述

《节奏大师》支持两种排行榜模式：
1. **本地排行榜** - 使用浏览器 LocalStorage 存储
2. **联网排行榜** - 使用后端服务器存储（需要额外配置）

---

## 本地排行榜

### 已实现功能

网页版游戏已内置本地排行榜功能：
- 自动保存前 100 名高分记录
- 数据存储在浏览器 LocalStorage
- 包含玩家名、分数、连击、难度、日期

### 数据结构
```javascript
{
  playerName: "玩家名",
  score: 98500,
  maxCombo: 156,
  perfect: 120,
  great: 35,
  good: 5,
  bad: 0,
  miss: 0,
  difficulty: "hard",
  date: "2026/3/12"
}
```

### 特点
- ✅ 无需服务器，开箱即用
- ✅ 数据私密，仅保存在本地
- ✅ 响应速度快
- ❌ 无法跨设备同步
- ❌ 浏览器清理数据会丢失

---

## 联网排行榜

### 方案一：使用免费云服务

#### 推荐平台
1. **Firebase** (Google)
   - 免费额度：100个并发连接，1GB存储
   - 实时数据库，支持实时排行榜
   
2. **Supabase**
   - 免费额度：500MB数据库
   - PostgreSQL数据库，易于使用

3. **JSONbin.io**
   - 免费额度：10,000条记录
   - 简单REST API

#### Firebase 实现示例

**1. 初始化 Firebase**
```javascript
// 在 HTML 中添加 Firebase SDK
<script src="https://www.gstatic.com/firebasejs/9.0.0/firebase-app.js"></script>
<script src="https://www.gstatic.com/firebasejs/9.0.0/firebase-database.js"></script>

<script>
// Firebase 配置（需要替换为自己的配置）
const firebaseConfig = {
  [REDACTED_SECRET]",
  authDomain: "your-project.firebaseapp.com",
  databaseURL: "https://your-project-default-rtdb.firebaseio.com",
  projectId: "your-project",
  storageBucket: "your-project.appspot.com",
  messagingSenderId: "123456789",
  appId: "1:123456789:web:abcdef"
};

// 初始化
const app = firebase.initializeApp(firebaseConfig);
const database = firebase.database();
</script>
```

**2. 保存分数到云端**
```javascript
async function saveScoreOnline(scoreData) {
  try {
    const newScoreRef = database.ref('leaderboard').push();
    await newScoreRef.set({
      ...scoreData,
      timestamp: firebase.database.ServerValue.TIMESTAMP
    });
    console.log('分数已保存到云端');
  } catch (error) {
    console.error('保存失败:', error);
  }
}
```

**3. 获取排行榜**
```javascript
async function getOnlineLeaderboard(limit = 20) {
  try {
    const snapshot = await database.ref('leaderboard')
      .orderByChild('score')
      .limitToLast(limit)
      .once('value');
    
    const scores = [];
    snapshot.forEach(child => {
      scores.unshift(child.val()); // 降序排列
    });
    
    return scores;
  } catch (error) {
    console.error('获取排行榜失败:', error);
    return [];
  }
}
```

### 方案二：自建后端服务器

#### 技术栈推荐
- **Node.js + Express** - 轻量级后端
- **MongoDB** - 数据库存储
- **Redis** - 排行榜缓存

#### API 设计

**POST /api/scores - 提交分数**
```json
// Request
{
  "playerName": "Player123",
  "score": 98500,
  "maxCombo": 156,
  "difficulty": "hard",
  "stats": {
    "perfect": 120,
    "great": 35,
    "good": 5,
    "bad": 0,
    "miss": 0
  }
}

// Response
{
  "success": true,
  "rank": 15,
  "message": "分数已保存，排名第15位"
}
```

**GET /api/leaderboard - 获取排行榜**
```
GET /api/leaderboard?difficulty=hard&limit=20

// Response
{
  "success": true,
  "data": [
    {
      "rank": 1,
      "playerName": "RhythmKing",
      "score": 150000,
      "maxCombo": 300,
      "difficulty": "hard",
      "date": "2026-03-12"
    },
    // ...
  ]
}
```

**GET /api/rank/:playerId - 查询玩家排名**
```
GET /api/rank/Player123

// Response
{
  "success": true,
  "rank": 15,
  "total": 1250,
  "topPercent": 1.2
}
```

#### Node.js 后端示例

**server.js**
```javascript
const express = require('express');
const mongoose = require('mongoose');
const cors = require('cors');

const app = express();
app.use(cors());
app.use(express.json());

// 连接 MongoDB
mongoose.connect('mongodb://localhost/rhythm_game');

// 分数模型
const ScoreSchema = new mongoose.Schema({
  playerName: String,
  score: Number,
  maxCombo: Number,
  difficulty: String,
  stats: Object,
  date: { type: Date, default: Date.now }
});

const Score = mongoose.model('Score', ScoreSchema);

// 提交分数
app.post('/api/scores', async (req, res) => {
  try {
    const score = new Score(req.body);
    await score.save();
    
    // 计算排名
    const rank = await Score.countDocuments({
      score: { $gt: req.body.score }
    }) + 1;
    
    res.json({ success: true, rank });
  } catch (error) {
    res.status(500).json({ success: false, error: error.message });
  }
});

// 获取排行榜
app.get('/api/leaderboard', async (req, res) => {
  try {
    const { difficulty, limit = 20 } = req.query;
    const query = difficulty ? { difficulty } : {};
    
    const scores = await Score.find(query)
      .sort({ score: -1 })
      .limit(parseInt(limit));
    
    res.json({ success: true, data: scores });
  } catch (error) {
    res.status(500).json({ success: false, error: error.message });
  }
});

app.listen(3000, () => {
  console.log('服务器运行在 http://localhost:3000');
});
```

---

## 防作弊机制

### 客户端验证
1. **输入验证**
   - 检查按键频率是否合理（人类极限约 10次/秒）
   - 检查判定时间是否合理

2. **分数验证**
   ```javascript
   function validateScore(scoreData) {
     const { perfect, great, good, bad, miss, score, maxCombo } = scoreData;
     
     // 总音符数
     const totalNotes = perfect + great + good + bad + miss;
     
     // 计算理论最高分
     const maxPossibleScore = totalNotes * 100 * 2.5; // 假设全PERFECT+最高连击加成
     
     // 验证分数是否合理
     if (score > maxPossibleScore) return false;
     
     // 验证连击是否合理
     if (maxCombo > totalNotes) return false;
     
     return true;
   }
   ```

### 服务端验证
1. **请求频率限制** - 防止批量提交
2. **IP 限制** - 同一IP短时间内多次提交需验证
3. **分数合理性检查** - 服务端重新计算验证

---

## 排行榜功能增强

### 1. 分类排行榜
- 按难度分类（简单/普通/困难/专家排行榜）
- 按模式分类（经典/无尽/挑战模式排行榜）
- 按时间分类（今日/本周/本月/总榜）

### 2. 社交功能
- 好友排行榜
- 附近玩家排行榜
- 国家/地区排行榜

### 3. 成就系统
```javascript
const achievements = {
  firstPlay: { name: "初次体验", desc: "完成第一局游戏" },
  combo10: { name: "渐入佳境", desc: "达成10连击" },
  combo50: { name: "手速达人", desc: "达成50连击" },
  combo100: { name: "节奏大师", desc: "达成100连击" },
  combo200: { name: "神之手", desc: "达成200连击" },
  fullCombo: { name: "完美演出", desc: "无MISS完成游戏" },
  allPerfect: { name: "全P大神", desc: "全PERFECT完成游戏" },
  score100k: { name: "十万分俱乐部", desc: "单次得分超过10万" },
  score500k: { name: "五十万传奇", desc: "单次得分超过50万" }
};
```

---

## 部署建议

### 静态网页部署
将 `rhythm-game.html` 部署到以下免费平台：

1. **GitHub Pages**
   - 免费、稳定、自定义域名
   
2. **Netlify**
   - 免费额度充足
   - 支持自定义域名和 HTTPS

3. **Vercel**
   - 专为前端优化
   - 全球 CDN 加速

4. **Cloudflare Pages**
   - 无限带宽
   - 全球边缘网络

### 完整部署步骤

```bash
# 1. 创建项目目录
mkdir rhythm-master-game
cd rhythm-master-game

# 2. 复制游戏文件
cp assets/rhythm-game.html index.html

# 3. 初始化 Git
git init
git add .
git commit -m "Initial commit"

# 4. 创建 GitHub 仓库并推送
git remote add origin https://github.com/yourusername/rhythm-master.git
git push -u origin main

# 5. 启用 GitHub Pages
# 在仓库设置中启用 Pages，选择 main 分支

# 6. 访问 https://yourusername.github.io/rhythm-master
```

---

## 扩展功能建议

### 1. 添加音乐
使用 Web Audio API 播放背景音乐：
```javascript
const audioContext = new (window.AudioContext || window.webkitAudioContext)();
// 加载和播放音频文件
```

### 2. 自定义谱面
允许玩家创建和分享自定义音符序列：
```javascript
const customChart = {
  bpm: 120,
  notes: [
    { time: 0, lane: 'left' },
    { time: 0.5, lane: 'right' },
    // ...
  ]
};
```

### 3. 多人对战
使用 WebSocket 实现实时对战：
```javascript
const ws = new WebSocket('wss://your-server.com/game');
ws.onmessage = (event) => {
  const data = JSON.parse(event.data);
  // 更新对手分数
};
```

---

## 总结

当前实现已包含完整的本地排行榜功能。如需联网排行榜，建议：

1. **快速方案**：使用 Firebase，30分钟可完成集成
2. **完整方案**：自建 Node.js 后端，需要服务器资源
3. **折中方案**：使用 JSONbin.io 等简单云服务

根据实际需求选择合适的方案即可！


Security scan verdicts — ClawScan: suspicious | static analysis: suspicious | VirusTotal: clean | SkillSpector: suspicious (CRITICAL)