# 凡人修仙传 · 阅读助手

为《凡人修仙传》读者打造的**完全离线**的沉浸式阅读辅助工具。纯 HTML / CSS / JavaScript 构建，无任何框架、无服务器、无外部依赖，一个文件夹即可运行。

> 当你看到后面忘了前面——人物是谁、这条线讲到哪、这个宗门什么来头——让这个助手帮你实时回忆。

## ✨ 功能

| 页面 | 内容 |
|------|------|
| **首页** | 原创掌天瓶 CSS 光影、墨色群山、流云、灵气粒子与法阵轨道动画；BGM 无缝播放器 |
| **人物 · 众生命牌谱** | 数百位角色数据，搜索、分类筛选、键盘操作、沉浸式卷轴弹窗 |
| **剧情 · 修仙命轨** | 中央灵脉、境界轨道、关键事件卡片轴，帮助理清时间线 |
| **世界观 · 登仙阶** | 交错阶梯展示修炼境界、法则卡片与境界灵光 |
| **地图 · 暗色山河图卷** | 三界切换、区域悬浮提示与键盘聚焦 |

- 完全离线：双击 `index.html` 即可运行，不依赖服务器、在线字体或外部图片
- 移动端适配，支持键盘操作
- 人物卡片、地图区域、世界观标签等交互音效

## 🎵 BGM 无缝切换

播放器采用 **"应用外壳 + 内容页"** 架构：`index.html` 作为持续存在的应用外壳承载唯一播放器，五个内容页在内部框架中切换，因此**切换页面不会打断音乐**，浏览器前进／后退也不中断，曲目、进度、音量状态全部保留。

详见 [docs/BGM_无缝切换说明.md](docs/BGM_无缝切换说明.md)。

## 🚀 运行

```bash
# 无需安装任何依赖，直接打开
open index.html
# Windows 直接双击 index.html 即可
```

> ⚠️ 必须从 `index.html` 进入。直接打开子页面会自动跳回应用外壳。

## 🗂️ 目录结构

```
.
├── index.html          # 应用外壳 + 唯一 BGM 播放器
├── home.html           # 首页视觉内容
├── characters.html     # 人物页
├── plot.html           # 剧情页
├── world.html          # 世界观页
├── map.html            # 地图页
├── data/               # 人物、地理、世界观 JSON 数据
├── assets/
│   ├── audio/README.md    # 音乐放置说明（见下）
│   └── portraits/README.md # 人物图片放置说明（见下）
└── docs/               # 开发文档
```

## 🎨 资源说明

本仓库**不包含音乐文件与人物图片**，原因见下方版权声明。

- **音乐**：播放器支持自定义 BGM，将**你有合法使用权**的四首 MP3 按 `assets/audio/README.md` 中的命名放入 `assets/audio/` 即可。
- **人物图片**：将图片按 `assets/portraits/README.md` 的映射表放入 `assets/portraits/` 即可自动匹配。未放置图片的角色自动退回纯 CSS / SVG 原创意象肖像，不会出现破损图标。

## 🧰 技术栈

- 原生 HTML5 + CSS3 + JavaScript（零框架、零构建）
- 数据驱动：JSON 数据库驱动人物 / 地理 / 世界观
- CSS 动画、内嵌 SVG、自定义暗色仙侠主题
- 开发协作：Claude Code 等 AI 工具辅助

## ⚖️ 版权声明

- **原著版权**：《凡人修仙传》由忘语所著，版权归原作者及版权方所有。本项目中的剧情总结、世界观设定、人物 / 地理数据等均为**粉丝出于学习与个人使用目的整理**，仅供参考，**请勿用于任何商业用途**。
- **素材版权**：本仓库刻意不包含音乐与角色图片，请使用**你有合法使用权**的资源。涉及第三方素材的版权归各自权利人所有。
- **代码许可**：本项目代码以 MIT 许可开源，见 [LICENSE](LICENSE.md)。

## 📬 反馈

本项目是个人兴趣项目。若你发现数据错误或有功能建议，欢迎提 Issue。
