Pixel Art Quiz Game (React + Vite + Google Sheets)

这是一款复古像素风（Pixel Art）的网页闯关问答游戏。游戏前端使用 React + Vite 构建，后端数据（题目与成绩）通过 Google Apps Script 与 Google Sheets 进行交互。

🎯 功能特色

• 像素风格 (Pixel Art)：怀旧 CRT 屏幕效果、像素字体与 UI。
• 动态关主：每一关通过 DiceBear API 随机生成像素风 Boss。
• Google Sheets 整合：
  • 自动读取云端题库。
  • 游戏结束后自动将成绩（分数、通关状态）回传至 Google Sheets。

---

🚀 快速开始 (安装指南)

1. 环境准备

确保您的电脑已安装 Node.js (建议版本 v16+)。

2. 下载与安装

# 进入项目目录
cd f:/Github/pixel-game

# 安装依赖
npm install

3. 本地开发

npm run dev

启动后访问终端显示的本地链接（通常是 http://localhost:5173）。

---

🛠️ Google Sheets 与 Apps Script 配置指南

此游戏依赖 Google Sheets 作为数据库。请按照以下步骤完成配置：

1. 建立 Google Sheets

新建一个 Google Sheet，设定以下两个工作表（Sheet）：

工作表 1：题目

在第一行建立以下栏位（顺序必须一致）：

A	B	C	D	E	F	G
ID	Question	OptionA	OptionB	OptionC	OptionD	Answer
1	问题内容...	选项A	选项B	选项C	选项D	C

(请参考下方的 测试题库 复制资料)

工作表 2：回答

在第一行建立以下栏位（顺序必须一致）：

A	B	C	D	E	F	G
ID	Runs	Total Score	Max Score	First Clear	Pass Count	Last Played
(留空)	(留空)	(留空)	(留空)	(留空)	(留空)	(留空)

---

2. 部署 Google Apps Script

1. 在 Google Sheet 中，点击上方菜单的 扩展程序 (Extensions) > Apps Script。
2. 将本项目中 backend/code.gs 的完整代码复制并覆盖到编辑器中。
3. 点击 保存 (Save) 💾。
4. 点击右上角的 部署 (Deploy) > 新建部署 (New deployment)。
5. 配置部署设置：
   • 类型: Web 应用 (Web app)
   • 执行身份 (Execute as): 我 (Me) (这一点很重要!)
   • 谁可以访问 (Who has access): 任何人 (Anyone) (为了让前端能无需登入即可读取数据)
6. 点击 部署，复制生成的 Web App URL。

---

3. 设定环境变量

1. 在项目根目录找到或建立 .env 文件。
2. 填入您刚刚获得的 Web App URL：

VITE_GOOGLE_APP_SCRIPT_URL=https://script.google.com/macros/s/您的应用ID/exec
VITE_PASS_THRESHOLD=3  # 设置需要答对几题才算通过
VITE_QUESTION_COUNT=5  # 设置每次游玩的题目数量

---

📚 生成式AI基础知识测试题库 (10题)

您可以直接复制下表内容到您的 题目 工作表中（从第 2 行开始贴上，不要覆盖标题行）。

ID	Question	OptionA	OptionB	OptionC	OptionD	Answer
1	什么是生成式 AI (Generative AI) 的主要特点？	只能分析现有数据	可以创造新的内容（文本、图像等）	专门用于物理机器人控制	仅用于数学计算	B
2	下列哪一个是著名的生成式语言模型？	Excel	Photoshop	GPT-4	Windows	C
3	"Prompt Engineering" 指的是什么？	编写计算机硬件驱动	设计 AI 模型的物理外观	编写提示词以引导 AI 生成结果	修复打印机错误	C
4	Transformer 架构最初是为解决什么问题而提出的？	图像识别	机器翻译 (NLP)	自动驾驶	股票预测	B
5	下列哪项不是常见的生成式 AI 应用？	文本摘要	图像生成 (如 Midjourney)	传统的关键词搜索	代码编写助手	C
6	训练大型语言模型 (LLM) 通常需要什么？	大量的数据与算力	一台普通的计算器	不需要任何数据	手动输入规则	A
7	AI 生成的内容可能出现的“胡说八道”现象被称为什么？	幻觉 (Hallucination)	崩溃 (Crash)	蓝屏 (BSOD)	睡眠 (Sleep)	A
8	下列哪个工具主要用于根据文本生成图像？	ChatGPT	Stable Diffusion	GitHub Copilot	BERT	B
9	为什么使用生成式 AI 时需要注意数据隐私？	AI 会偷走你的电脑	模型可能会记忆并泄漏敏感训练数据	AI 不喜欢私密数据	屏幕会变黑	B
10	RAG (检索增强生成) 技术的主要目的是什么？	减少模型参数	增加模型训练时间	结合外部知识库以提高回答准确性	让 AI 画图更漂亮	C

---

🎮 验证与测试

1. 启动项目 npm run dev。
2. 输入任意 ID（例如 TEST01）。
3. 确认是否能成功载入题目。
4. 完成答题后，检查 回答 工作表是否新增了记录。

---

🚀 GitHub Pages 自动部署指南

本项目已内置 GitHub Actions 工作流，支持提交代码后自动部署到 GitHub Pages。

1. 准备 Github 仓库

1. 在 GitHub 上新建一个仓库（Repository）。
2. 将本地代码推送到该仓库：

   git init
   git add .
   git commit -m "Initial commit"
   git branch -M main
   git remote add origin https://github.com/您的用户名/仓库名.git
   git push -u origin main

2. 配置 Secrets (环境变量)

由于部署在公开网络，不建议将敏感信息直接写在代码中（虽然 Vite 实际上会将它们打包到前端代码里，但在构建流程中使用 Secrets 更规范）。

1. 进入 GitHub 仓库页面。
2. 点击 Settings > Secrets and variables > Actions。
3. 点击 New repository secret，添加以下三个变量（参考您的 .env 或 .env.example）：
   • VITE_GOOGLE_APP_SCRIPT_URL: (您的 Web App URL)
   • VITE_PASS_THRESHOLD: (例如 3)
   • VITE_QUESTION_COUNT: (例如 5)

3. 给 Actions 写权限

1. 在 Settings > Actions > General。
2. 滚动到底部 Workflow permissions。
3. 勾选 Read and write permissions。
4. 点击 Save。

4. 触发部署

• 只要您将代码 push 到 main 分支，GitHub Action 就会自动开始构建。
• 构建完成后，会自动建立一个 gh-pages 分支。

5. 开启 GitHub Pages

1. 构建成功后，进入 Settings > Pages。
2. 在 Build and deployment 下的 Source 选择 Deploy from a branch。
3. Branch 选择 gh-pages，文件夹选 /(root)。
4. 点击 Save。
5. 稍等片刻，GitHub 会显示您的在线游戏链接！

6. 常见问题 (Troubleshooting)

• 部署后页面空白 (404 Error)：

  • 这通常是因为资源路径问题。本项目已预设 vite.config.js 中的 base: './' 来解决此问题。
  • 确保您使用的是 HashRouter (App.jsx 已配置)。

• 右上角显示 "DEMO MODE (OFFLINE)"：

  • 这表示游戏没有关联到 Google Apps Script。
  • 请检查 GitHub 仓库的 Settings > Secrets and variables > Actions，确保已添加 VITE_GOOGLE_APP_SCRIPT_URL。
  • 添加 Secret 后，您需要重新运行刚才的 Action 才能生效（或提交个空 commit）。

---

📂 项目结构