历史长河 — 互动历史教育游戏
一段话简介：这是一个面向中文教育场景的「以历史人物为主线，以可玩交互为载体」的浏览器游戏。玩家先在主页选择一位历史人物（已有杜甫与但丁双故事线，鲁米线筹备中），随后在该文明的一张古地图 + 时间轴上自由探索他一生的关键事件——主角小人沿手绘感的墨线路径在地图上真实行走，走过的路留成实墨、未至之地覆着纸色薄雾，地图本身就是进度条。每个事件都不是被动观看，而是一段可玩的小关卡：探索式 NPC 对话、史料选择题、补诗拼字、数字华容道、画面「找茬」式触发诗句、Pac-Man 风格的出城避守卫，以及多段地图行走小游戏。整套引擎由 React + Vite + 纯 JSON 场景数据驱动，所有阶段、立绘、对话、触发点、棋盘地图都可以在内置的 ?editor=true 可视化编辑器里调位置/大小/旋转/3D 透视/分支（支持按故事线切换、从 13 种交互模板一键插入、保存自动备份），配合 /api/save-event 本地 dev 中间件直接落盘到对应线的 event.json。杜甫人物线已全部完成（10 事件 / 61 个互动场景 / 10 种交互类型 / 全事件配 quiz + 成就与人物回顾系统），但丁线 9 事件数据就绪，详见下方制作总结。
通过游戏方式学习中国历史人物的生平故事。选择不同角色，沿着时间轴探索他们走过的地点，体验视觉小说式对话，阅读历史叙事与经典诗篇，并通过问答挑战检验所学。
杜甫人物线 · 制作总结
总共设计并制作了 10 个事件，跨越 736—770 年：
736 落第壮游 → 744 遇李白 → 747 制举 → 751 献赋 → 755 安史 → 757 左拾遗 → 759 弃官 → 760 草堂 → 765 夔州 → 770 舟中
61 个互动场景（phase），10 种交互类型：explore×22、transition×18、forced_choice×6、map_travel×5、poem_compose×3（望岳/春望/登高）、comic_reveal×3（石壕村/岳阳楼/江上旧梦连环画）、exam×1（野无遗贤 8 题）、sliding_puzzle×1（三大礼赋华容道）、click_points×1（春望找茬）、escape_game×1（长安出城 Pac-Man）。全部 10 个事件均配 3 题 quiz。
美术资产：46 张时期背景、36 个 NPC 立绘、15 张杜甫分期立绘（青年/中年/官服/漂泊/晚年自动随年代切换）、23 件道具、7 张地图——地图通过专业地图软件检索历史坐标制作，真实还原杜甫一生足迹。
可直接复用到后续人物的系统：时间轴 + 大地图导航、成就 + 人物回顾、BGM 框架（按时期自动切歌）、可视化场景编辑器（全部 phase 类型可编辑）、积分 + 账号 + 排行榜（LeanCloud 云端 / 本地双模式）。
下一步（Ray）
环境要求
- Node.js >= 18（推荐 20+）
- npm（随 Node.js 一起安装）
- Git
快速开始
# 1. 克隆仓库
git clone https://github.com/Ivyyyy24381/Chinese_history_game.git
cd Chinese_history_game
# 2. 安装依赖
npm install
# 3. 启动开发服务器
npm run dev
浏览器打开 http://localhost:5173 即可开始游戏。
打开 http://localhost:5173/?editor=true 进入场景编辑器。
构建生产版本：
npm run build
构建产物在 dist/ 目录下，可以直接部署到任意静态托管服务（GitHub Pages、Vercel、Netlify 等）。
项目结构
Chinese_history_game/
├── index.html / package.json / vite.config.js # vite.config 含编辑器 dev 保存中间件
│
├── public/assets/ # 静态资源（Vite 直接 serve）
│ ├── home/ # 主页素材 hp_{title,background,portrait,name}_<line>
│ ├── shared/{items,bgm}/ # 跨线共用
│ └── <line>/ # 每条故事线一套（dufu / dante / …）
│ ├── hero/ · npcs/ · props/ · maps/ · bgm/
│ └── events/<事件ID>/{backgrounds,npcs}/
│
├── src/
│ ├── main.jsx # React 入口
│ ├── App.jsx # 顶层：选人 / 游戏 / 编辑器路由
│ │
│ ├── styles/
│ │ ├── game.css
│ │ └── theme.js # 全局视觉 token（纸色/文字色阶/金线/字距/halo()/scrim()）
│ │
│ ├── components/
│ │ ├── CharacterSelect.jsx # 主页选人（全站视觉风格基准）
│ │ ├── GameMap.jsx # 古地图：旅人墨线路径 / 同时代符号 / 雾 / mapTheme
│ │ ├── Timeline.jsx # 底部时间轴细带（hover/focus 展开）
│ │ ├── ScenePlayer.jsx # 互动场景引擎（13 种交互类型）
│ │ ├── SceneEditor.jsx # 可视化场景编辑器
│ │ ├── TimelineEditor.jsx # 时间线编辑器（?editor=true 入口）
│ │ ├── EventPanel.jsx # 历史叙事 + 诗词面板
│ │ ├── QuizPanel.jsx # 问答系统
│ │ └── ScoreBar.jsx # 左上人物信息条（主页名牌排版）
│ │
│ ├── data/
│ │ ├── characters.js # 人物花名册（单一事实来源；含地图 mapTheme）
│ │ ├── phaseTemplates.js # 编辑器「插入交互模板」的 13 种模板
│ │ ├── dufuPoses.js · dantePoses.js
│ │ └── <line>/
│ │ ├── timeline.json # 时间轴总览 + 角色信息 + 地图坐标
│ │ └── events/<事件ID>/
│ │ ├── event.json # 场景定义（phases、NPC、对话）
│ │ └── quiz.json # 答题题目（可选）
│ │
│ └── utils/ # asset.js · usePrefersReducedMotion.js
│
└── .editor-backups/ # 编辑器写盘前自动备份（gitignore）
（更细的「东西放哪、为什么」见 docs/FOLDER_STRUCTURE.md，
全流程见 docs/PIPELINE.md。）
场景编辑器
浏览器打开 http://localhost:5173/?editor=true 进入编辑器：先落在时间线编辑器
（拖 pin 调地图坐标、拖 tick 调年份、改事件元数据），从事件下钻进场景编辑器。
基本操作
- 顶部先选故事线（dufu / dante / …），再选场景文件，通过阶段标签切换不同阶段。
顶栏始终显示当前编辑的完整落盘路径（如
src/data/dante/events/1295_arte/event.json）。
- 点击 + 新增阶段 创建空白阶段；或点 🧩 插入交互模板——13 种交互类型每种一张卡
（示意图 + 一句话说明 + 取材事件），点卡即插入一个填好占位内容、可直接运行的新阶段。
- 点击 💾 保存到文件 将修改写回该故事线的 JSON（仅 dev 模式可用）。写盘前原文件自动
备份到
.editor-backups/<line>/<事件ID>/（保留最近 20 份），保存成功回显完整路径 + 字节数；
有未保存改动时关页面 / 返回 / 切线会弹确认。
左侧面板 — 资源 & 触发器
人物资源：点击立绘添加到场景中，拖拽调整位置。第一个选项 「Aa 文字标签」 可添加无立绘的纯文字交互点（适合榜单、墙壁题文等物品）。
交互触发器：
- ➡️ 继续按键 — 场景中显示的可点击按钮
- 🚪 场景入口 — 区域触发点
选中触发器后可在右侧编辑触发动作（进入下一阶段、跳转指定阶段、跳转其他场景、触发对话）和触发条件（始终可用、所有NPC交谈后等）。
场景信息：设置当前阶段的 ID、标题、叙述文字、玩家指示。
中间画布
拖拽人物和触发器调整位置，点击选中后在右侧编辑详情。
右侧面板 — 详情编辑
阶段流程：查看所有阶段的流程图，设置当前阶段的下一步跳转。
根据阶段类型显示不同的编辑内容：
- explore（探索）：NPC 对话编辑、缩放/翻转、是否为线索
- exam（考试）：考官立绘/名称、选择题和填空题（含干扰项）编辑
- transition（过场）：过场文字、公告/榜单、杜甫反应
- forced_choice（选择）：问题、选项、正确/错误反馈、结论叙述
- poem_compose（诗歌创作）：情境描述、正确诗句、候选词句
场景 JSON 结构
每个事件一个 event.json，包含多个阶段（phases），阶段间通过 nextPhase 字段串联：
{
"id": "747_exam",
"title": "制举「野无遗贤」",
"year": "747",
"type": "interactive",
"phases": [
{
"id": "explore_outside",
"type": "explore",
"background": "/assets/dufu/events/747_exam/backgrounds/changan_street_2.png",
"title": "长安街头",
"narrative": "...",
"instruction": "点击周围的人物与他们交谈",
"npcs": [...],
"requiredTalks": 3,
"nextPhase": "exam_intro",
"triggers": [...]
},
{
"id": "exam",
"type": "exam",
"examiner": { "portrait": "...", "name": "李林甫" },
"questions": [...]
}
]
}
添加新内容
添加新场景素材：该线共用立绘放 public/assets/<line>/npcs/，事件专属素材放
public/assets/<line>/events/<事件ID>/{backgrounds,npcs}/。编辑器会自动发现新文件。
用编辑器创建/修改场景：打开 ?editor=true，选故事线和场景文件，从模板插入阶段或新建，
拖放人物、编辑对话、设置触发器，保存即可（自动落到正确的线并备份）。
手动编辑 JSON：修改 src/data/<line>/events/<事件ID>/event.json，NPC 对话格式：
{
"id": "merchant",
"name": "小商贩",
"portrait": "/assets/dufu/npcs/merchant.png",
"position": { "x": 30, "y": 60 },
"dialogues": [
{ "speaker": "merchant", "speakerName": "小商贩", "text": "客官，来碗胡辣汤？" }
]
}
无立绘的文字交互点将 portrait 设为空字符串即可。
添加新角色的完整故事线：照 docs/CHARACTER_TEMPLATE.md 走——
在 src/data/characters.js 花名册加一项（含地图 mapTheme），建 src/data/<line>/
和 public/assets/<line>/，引擎与地图页零代码复用。
技术栈
- React 18 — UI 组件化
- Vite — 开发服务器与构建
- JSON 数据驱动 — 内容与代码分离，方便扩展
- 场景编辑器 — 可视化编辑 NPC 位置、对话、触发器、考试题目
