# eduGame

**Repository Path**: crazy-wen/eduGame

## Basic Information

- **Project Name**: eduGame
- **Description**: 科普游戏
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-24
- **Last Updated**: 2026-05-27

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 🐚 深蓝宝藏：海洋探险队

> 一款面向儿童的 2D 海洋科普探险小游戏，在探索珊瑚湾的过程中学习海洋知识、收集宝藏碎片。

## 🎮 在线体验

```bash
npm start
# 浏览器打开 http://localhost:4173
```

## 📸 游戏概览

- **类型**：2D Canvas 科普问答探险游戏
- **受众**：6–12 岁儿童
- **主题**：海洋生态保护（珊瑚、海星、塑料污染）
- **目标**：探索珊瑚湾，与 NPC 对话，答对知识问答，集齐 3 个宝藏碎片

## ✨ 核心功能

| 功能 | 说明 |
|------|------|
| 🗺️ 珊瑚湾地图 | 960×640 Canvas 渲染，含海滩、珊瑚区、宝藏洞穴等区域 |
| 🎭 NPC 对话 | 机械海鸥、海龟博士等角色，气泡式对话跟随锚点定位 |
| 📝 知识问答 | 3 个主线题池 + 3 个隐藏任务题池，每池含 easy/normal/hard 三档难度 |
| 🏆 计分系统 | 基础分 + 连对加成 + 隐藏任务奖励，答错扣连击但不惩罚分数 |
| 🎖️ 结算评价 | 三档评价（传奇/守护者/勇敢），含本地 PK 排行榜（localStorage） |
| 🔊 音频系统 | Web Audio API 程序化背景音乐 + Web Speech API 中文语音旁白 |
| 🎨 双渲染模式 | 优先加载 PNG 精灵图，加载失败时回退到 Canvas 程序化绘制 |
| 🖱️ 多输入支持 | WASD/方向键移动 + 鼠标点击自动寻路 + 键盘快捷答题 |

## 🏗️ 技术栈

- **前端**：原生 HTML + CSS + JavaScript（ES Modules）
- **渲染**：Canvas 2D API
- **音频**：Web Audio API（程序化合成） + Web Speech API（TTS 旁白）
- **服务器**：Node.js 原生 HTTP 静态文件服务（零依赖）
- **测试**：Node.js 内置 `node:test` 测试框架
- **许可证**：MIT

## 📁 项目结构

```
eduGame/
├── index.html                  # 游戏入口页面（含全部 HTML 结构）
├── styles.css                  # 全局样式（HUD、对话框、问答面板、结算屏）
├── server.mjs                  # 零依赖静态文件服务器（端口 4173）
├── package.json                # 项目配置（npm start / npm test）
│
├── src/                        # 源码模块
│   ├── main.js                 # 主入口：游戏循环、事件绑定、场景切换
│   ├── data.js                 # 游戏数据：地图、任务步骤、对话、题库、NPC
│   ├── gameState.js            # 状态管理：不可变状态更新、答题判定
│   ├── renderer.js             # Canvas 渲染：地图绘制、角色精灵、交互高亮
│   ├── input.js                # 输入处理：键盘绑定、移动向量、答题快捷键
│   ├── audio.js                # 音频引擎：程序化 BGM、TTS 语音、风格切换
│   ├── progression.js          # 进度系统：计分、评价、排行榜、随机题池
│   ├── dialogueLayout.js       # 对话布局：气泡定位算法
│   ├── assets.js               # 资源加载：PNG 精灵图异步加载
│   └── uiCopy.js               # UI 文案：开始/结算界面文本
│
├── assets/images/              # 游戏图片资源（PNG 精灵图）
│   ├── coral-bay-map.png       # 珊瑚湾背景地图
│   ├── player.png              # 玩家角色
│   ├── mechanical-seagull.png  # 机械海鸥 NPC
│   ├── dr-turtle.png           # 海龟博士 NPC
│   ├── strange-shell.png       # 奇怪贝壳
│   └── treasure-chest.png      # 宝藏箱
│
├── tests/                      # 单元测试
│   ├── gameState.test.mjs      # 状态管理测试
│   ├── progression.test.mjs    # 进度系统测试
│   ├── audio.test.mjs          # 音频引擎测试
│   ├── input.test.mjs          # 输入处理测试
│   ├── assets.test.mjs         # 资源加载测试
│   ├── dialogueLayout.test.mjs # 对话布局测试
│   └── uiCopy.test.mjs         # UI 文案测试
│
├── docs/superpowers/           # AI 协作开发文档
│   ├── plans/                  # 开发计划
│   └── specs/                  # 技术规格
│
└── deep_blue_treasure_prototype_v_0_2.md  # 原型设计文档（v0.2）
```

## 🎯 游戏流程

```
开始界面（输入探险名）
    ↓
珊瑚湾 · 出生点 → 机械海鸥对话（了解宝藏线索）
    ↓
海滩区 → 奇怪贝壳（珊瑚知识问答 → 碎片 1/3）
    ↓
珊瑚区 → 海龟博士对话 + 海星问答（碎片 2/3）
    ↓
宝藏点 → 小宝箱对话 + 塑料污染问答（碎片 3/3）
    ↓
结算界面（评价 + 徽章 + 排行榜）
```

> 每局随机出现 1 个隐藏任务（清道蟹/海图鳐/迷路小鱼），完成后获得额外分数。

## 🚀 快速开始

### 环境要求

- Node.js 18+

### 运行

```bash
# 克隆项目
git clone <repo-url>

# 启动开发服务器
npm start

# 浏览器访问
open http://localhost:4173
```

### 测试

```bash
npm test
```

## 📐 架构设计

### 状态管理

采用**不可变状态更新**模式：每次状态变更都通过 `cloneState()` 创建新副本，保证状态可预测、易于测试。

### 渲染流水线

```
requestAnimationFrame(loop)
  → update(deltaSeconds)    # 物理更新：移动、自动寻路
  → draw()                  # 画面渲染 + DOM HUD 同步
    → renderGame(ctx, ...)  # Canvas 分层绘制：地图 → 道具 → 交互区 → 玩家
```

### 题池随机

每个问答节点关联一个题池（3 道不同难度），每次游戏随机抽取，增加重玩性。

## 📄 许可证

[MIT License](./LICENSE) © 2026 问天