andyhuo520/tang-changan
GitHub: andyhuo520/tang-changan
基于 Three.js 的纯前端 3D 交互项目，以唐代长安城为背景复刻了一座可漫游、可对话、可游戏的互动微缩沙盘。
Stars: 102 | Forks: 23
# 大唐长安 · Tang Chang'an Diorama (V11)
复刻 Expeditione™ 风格的互动微缩沙盘，主题 **大唐百年史**。120×160 单位级地图、**三大殿纵轴**（含元 → 宣政 → 紫宸）、跨河桥梁、七层大雁塔、曲江画舫、朱雀城门、东西二市、稻麦水利、胡旋舞乐——配以 **昼夜流转 · 四季流转 · 宵禁夜禁 · 唐诗节点 · 寺钟鸡鸣 · 天气切换（雨/沙/雾 + 闪电雷声 + 风向斜飘）· NPC 市井段子 · 历史事件轴 · 4 款 mini-game · 移动端适配 · 🎮 RPG 模式 · 👀 第一人称 FPS 模式 · 🖼 5 座 360° 殿宇展厅**，一幅可漫游、可对话、可吟诗、可游戏、可扮演、可入殿看展、可穿越百年的盛唐画卷。
## 开发教程与 Agora Skills 安装
- 科普教程 Markdown：[`docs/05_从设计到完成_开发过程科普教程.md`](docs/05_从设计到完成_开发过程科普教程.md)
- 精排 HTML 版：[`docs/05_从设计到完成_开发过程科普教程.html`](docs/05_从设计到完成_开发过程科普教程.html)
教程中的「7.0 开发前置：安装 Agora Skills / Agora CLI」包含：
- 安装 `agora` CLI；
- `agora login` 登录；
- `agora project doctor --feature convoai` 检查 ConvoAI；
- `agora project env write .env.local --overwrite` 写入语音后端环境变量；
- 常见 `CAN_NOT_GET_GATEWAY_SERVER` / `401 Invalid token` 排查。
## V11 · 经济基建 · 4 币种 · 5 类物品 · 5 处店铺
游戏 (Mode 2) 与展示 (Mode 1) 至此**真正分家** —— Mode 2 多出一套有源有汇的经济：
### 4 种货币（同步显示在屏右上"钱包"胸牌）
| 币种 | 图标 | 主用途 |
|------|------|--------|
| **铜钱** copper | 🪙 | 食货 / 小件文房 / 小礼物 |
| **绢帛** silk | 🧵 | 衣冠 / 中价文房 / 雅物 |
| **金锭** gold | 🏵 | 真迹 / 凭证 / 城门通牒 |
| **风雅** fame | ✦ | 累计（雅物 / 诗仙赞 → 解锁高阶 NPC） |
### 4 职业 · 不同开局资源
| 职业 | 开局钱包 | 开局物品 |
|------|---------|---------|
| 文士 scholar | 30 文 + 2 绢 + ✦5 | 湖州狼毫 + 一刀宣纸 |
| 商贾 merchant | 80 文 + 4 绢 + ✦1 | — |
| 仕女 lady | 50 文 + 3 绢 + 1 金 + ✦3 | 一枚玉佩 |
| 武人 soldier | 40 文 + ✦2 | 胡饼 ×2 |
### 5 类物品（共 27 件，分类聚合显示）
| 类 | 例 | 效果 |
|----|----|------|
| 🥯 **食货** food | 胡饼 / 葡萄酒 / 酥山 / 剑南春 | **吃** → 回体力 + 临时风度 charm |
| 🖌 **文房** literati | 狼毫 / 松烟墨 / 宣纸 / 端砚 / 唐诗集 / 全唐诗 | 累加 **poetryBonus**，达 15 解锁"灵思一次" |
| 👘 **衣冠** attire | 青衫 / 乌纱帽 / 玉佩 / 织锦帕 / 香囊 | **着** → 装备槽（头/身/饰）+ 常驻 charm |
| 🪞 **雅物** collectible | 西凉铜镜 / 东海明珠 / 吴道子真迹 / 蜀锦 / 滕王阁序拓本 | 入袋即 ✦风雅 累计 |
| 🪪 **凭证** pass | 诗仙赞腰牌 / 通关文牒 / 进士印 | 解锁区域 / 高阶 NPC |
### 5 处店铺（实地店招 · 走近 `F` 开店）
| 店 | 位置 | 主售 |
|----|------|------|
| 🏮 **朱雀酒肆** | (-5, -1) | 食货 7 件（胡饼/葡萄酒/酥山/剑南春…） |
| 🏮 **东市米粮铺** | (5, 16) | 食货 4 件（粳米/胡饼/栗子/清茗） |
| 🏮 **东市文房斋** | (-5, 17) | 文房 7 件（笔墨纸砚 + 唐诗集 + 全唐诗） |
| 🏮 **东市绫罗肆** | (0, 19) | 衣冠 6 件（青衫/乌纱/玉佩/竹簪…） |
| 🏮 **西市胡商货栈** | (-22, -3) | 雅物 + 凭证（铜镜/明珠/真迹/蜀锦/拓本/城坊图/文牒） |
店招实地建模：立柱 + 灯笼 + 牌匾（CanvasTexture 中文 STKaiti）+ 灯笼缓慢晃动。买/卖 modal 顶部显示钱包 4 币种，按类聚合商品，价格用 🪙🧵🏵 图标，买不起的灰显禁用。
### 体力 + 风度系统
- **体力 stamina** 0-100，初始 100；每秒自动 +1 恢复（mini-game / 跑步消耗待加）
- 屏右上**绿色 4px 条**实时显示
- 食物给定量回复，酒/茶/酥山额外给**临时 charm 风度**（60-180 秒 buff）
### 文房灵感 → 接入诗会
持有文房物品自动累计 poetryBonus（笔 +10、墨/纸 +5、砚 +20、唐诗集 +25、全唐诗 +35）。
- bonus ≥ **15** → 诗会内可灵思**一次**（答错时获一次重答机会，且会标红错项）
- bonus ≥ **35** → 玩家直接成为"长安第一才子"（彩蛋）
### Loot 重构
旧的 REWARDS_GOOD/SMALL/CONSOL/PERFECT → 统一迁到 `LOOT_TABLES` (win/draw/lose/perfect)，全部用 itemId 引用。币奖单独用 `COIN_10` / `COIN_3` / `SILK_1` token 处理。所有路径（猜拳/猜谜/对诗）共享一致 grantReward。
## V10 · 诗酒小宴 · 飞花令 · 对对联 · 诗仙赞
街头三玩之外再开一种 **盛唐文人雅集** —— 走到 NPC 旁 `E` 开对话，到末尾会出现紫粉色按钮 **🍷 对诗**（文士 / 仕女 / 老人 / 僧人 100%，兵卒 / 农夫 30%）。点开后随机抽 3 轮，混合两种唐风玩法：
| 玩法 | 形式 |
|------|------|
| **飞花令** | 给关键字 (花/月/风/春/江/酒/山/雪)，4 句中选**含此字**的诗 |
| **对对联** | 给上联，4 句中选下联（干扰项均为**其他名联的下联**，迷惑性强） |
**3 巡定胜负 · 奖品分级**：
| 战绩 | 级别 | 奖品池 |
|------|------|--------|
| 3/3 | **诗仙赞 ✦** | 🍶 一壶剑南春 / 📚 《全唐诗》/ 🖌 湖州狼毫 / 🟫 端州歙砚 / 🎨 吴道子真迹 / 🪪 诗仙赞墨色腰牌 |
| 2/3 | 才情不俗 | 小赏（三文钱 / 胡饼 / 打油诗…） |
| 1/3 | 勉强一巡 | 安慰（路人一笑 / 鬼脸） |
| 0/3 | 颗粒无收 | 文士调侃：「公子何不饮酒，少谈诗？」 |
题库规模：
- 飞花令：**8 个关键字 × 每字 ~6 含字句 + ~6 不含字句**，组合数 >180
- 对联：18 副名联（王勃 / 李白 / 王维 / 柳宗元 / 杜甫 / 白居易 / 王翰 / 王之涣 / 张九龄…）
对诗 UI 与街头小游戏统一 `.sg-card` 风格，但配色改为 **暗夜紫 + 桃花粉**，提示气泡用 **STKaiti 楷体 + 紫色左竖条**，呼应"花间一壶酒"的雅意。
## V9 · 街头玩耍 · 猜拳猜谜 + 随机赏赐 + 行囊系统
游戏模式中靠近任意路人，按 `E` 打开对话；在对话**最后一行**会出现两枚按钮：
| 按钮 | 玩法 |
|------|------|
| **🪨 猜拳** | 经典石剪布。你出招后，NPC 转手轮抽签 600ms 落定 → 胜 / 平 / 负 |
| **🎴 猜谜** | 唐风题库（民俗谜语 + 长安史实），四选一，对错均有奖 |
**胜负判定 → 不同奖品池**：
- **胜** → 十文开元通宝 / 西凉铜镜 / 滕王阁序拓本 / 龙井香囊 / 葡萄酒 / 东海明珠 / 织锦帕 / 酥山
- **平** → 三文铜钱 / 胡饼 / 打油诗 / 炒栗子 / 竹簪
- **负** → 路人一笑 / "再来" / 鬼脸（安慰，无价值但有趣）
NPC 角色对游戏的态度：
| 角色 | 愿意陪玩 |
|------|---------|
| 文士 / 商贾 / 仕女 / 童子 / 农夫 / 胡商 / 货郎 / 街边路人 | 100% |
| 兵卒 / 官员 / 僧侣 | 30%（性子严，但偶尔也兴致来时） |
**行囊系统 (Inventory)**：
- 屏幕右上 Inventory **胸牌**: `🪙 X 文 · 🎁 Y 件 · [最近 3 件 icon]`
- 点击胸牌弹出**总览面板**：分行显示所有藏品（含数量×N）
- 中央**赏赐 Toast** 飘字：`王翁 赏你 🪞 一面西凉铜镜`
12 题谜库：
## V8 · 入殿看展 · 第一人称 + 壁画展厅
新增三件大事：
1. **天气升级**：雨天 5-20 秒概率触发 **闪电屏闪 + 低频雷鸣**；雨/沙/雾各有风向 → 雨条斜飘、沙粒阵风吹拂、雾色阴沉
2. **第一人称 (FPS) 模式**：游戏中按 `V` 切换第三/第一人称；点击锁鼠标真实视角看世界；按 `Esc` 释放
3. **大殿 360° 展厅**：走到 5 个殿门口（含元殿 / 宣政殿 / 紫宸殿 / 大雁塔 / 曲江亭）→ 按 `F` 入展 → FPS 在展厅内自由游走，看向壁画时屏幕底部显示标题 + 注释；按 `F` 或 `Esc` 礼出展厅
### 5 座展厅清单
| ID | 标题 | 壁画 |
| --- | --- | --- |
| `hanyuan` | 含元殿 · 万邦来朝 | 万邦来朝图 / 元日大朝 / 受降图 / 凤翔丹墀 |
| `xuanzheng` | 宣政殿 · 常朝政务 | 常朝图 / 紫绯朝服 / 中书省草制 / 御史台 |
| `zichen` | 紫宸殿 · 内朝寝兴 | 入阁仪 / 夜对 / 后宫 |
| `pagoda` | 大雁塔 · 玄奘西天 | 玄奘取经图 / 译经场 / 雁塔题名 / 佛祖说法 |
| `qujiang` | 曲江亭 · 文人雅集 | 丽人行 / 曲江流饮 / 杏园探花 |
每幅壁画现在是程序化占位（暖金色调底 + 题字 + 注解）。**想换真实素材**：把图片放进 `murals/`，命名 `{galleryId}_{index}.jpg`，详见 `murals/README.md`。
## V7 · 长安行客 · RPG 模式
点击顶栏 **🎮 游戏模式** 按钮，从 4 个角色预设（**士子 / 商贾 / 仕女 / 游侠**）中挑选你的长安身份，输入名字，进入第三人称漫游：
| 操作 | 键位 |
| --- | --- |
| 移动 | `W` `A` `S` `D` 或方向键 |
| 疾走 | 长按 `Shift` |
| 与最近 NPC 交互 | `E` / 空格 / 回车 |
| 退出游戏 | `Esc` |
- **主线任务**：《初到长安》5 步剧情链：朱雀门 → 西市张掌柜 → 大雁塔题名 → 大明宫含元殿 → 名垂长安
- **场景自动联动**：与 217 个 NPC 都可对话；不同坊里的人物会按身份（守门将/商贾/学子/儒生/百姓/官员/胡商/僧侣）说出不同的市井段子
- **任务驱动**：在朱雀门附近的兵卒、西市的商贾、大雁塔下的学子会触发任务专属台词与剧情推进
- **HUD**：左上任务条 / 下方按键提示 / 顶部 toast 通知 / 底部对话框
- **镜头**：相机从俯瞰沙盘平滑过渡到主角第三人称跟随，主角头顶有金色光环 + 箭头标识
## 一句话技术栈
**纯前端**（HTML + Three.js + 原生 JS），**无构建步骤**，浏览器直接打开即可。
## 如何运行
cd /Users/andyhu/Downloads/Company/han-diorama
python3 -m http.server 8088
# 访问 http://localhost:8088/
## 场景全景 (V6·三殿盛唐版)
┌─────────────────────────────────────┐
│ 🏛 紫宸殿 (内殿/皇帝寝兴) │ z=-89
│ 私密单层 · 飞檐高耸 · 4 近臣 + 琴师 │
└────────────────┬────────────────────┘
│←連廊
┌────────────────┴────────────────────┐
│ 🏛 宣政殿 (常朝/政务) │ z=-76
│ 重檐两层 · 8 朝臣紫绯 · 4 带刀侍卫 │
└────────────────┬────────────────────┘
│←連廊
┌────────────────┴────────────────────┐
│ 🏛 含元殿 (大朝/万邦来朝) │ z=-60
│ 三层金顶 · 龙凤丹墀 · 翔鸾栖凤双阙 │
│ 12 御林军 + 8 朝臣 + 苍松石狮 │
└────────────────┬────────────────────┘
┌────────────────┴────────────────────┐
│ 🏯 朱雀门 (皇城南正门) │
└────────────────┬────────────────────┘
┌────────────────┴────────────────────┐
│ ⚔️ 边塞战场 / 突厥穹庐 / 烽燧 │
└────────────────┬────────────────────┘
┌────────┐ ┌────────────┴────────────┐ ┌─────────────────┐
│ 🐫 驼商│ │ │ │ │
│ + 🏛西市│←┤ 朱雀大街 · 22 行人坊灯 28 ├→│ 🌾 田畴 筒车曲辕犁│
│ 胡旋舞 │ │ 官吏马队 · 宵禁可见 │ │ 弯腰插秧农夫 │
└────────┘ └────────────┬─────────────┘ └─────────────────┘
┌────────────┴─────────────┐
│ 🌊 灞河 + 渭水 + 拱桥 │
└────────────┬─────────────┘
┌────────────────┴────────────────────┐
│ 🌅 曲江池 (西南) 🏯 大雁塔 (东南) │
│ 画舫 · 亭台 · 柳岸 · 慈恩寺 · 石狮香炉 │
└─────────────────────────────────────┘
## 内容清单 (V6 三殿百年版)
### 🏛️ 唐代地标
- **大明宫三大殿**（V6）— 含元殿 + 宣政殿 + 紫宸殿 三层纵轴，双侧長廊相连
- **含元殿** — 三层金顶高台、龙凤丹墀龙尾道、翔鸾·栖凤双阙、12 御林军 + 8 朝臣
- **宣政殿**（新）— 重檐两层、9 柱前廊、8 紫绯朝臣 + 4 甲士
- **紫宸殿**（新）— 单层精巧高翘飞檐、4 近臣 + 仕女琴师、后花园松柏假山
- **大雁塔**（慈恩寺塔）— 7 层方塔、攒尖砖石、四面拱窗、金顶刹
- **朱雀门城楼** — 三门道、九五至尊八十一钉、重檐两层、龙凤双旗
- **曲江池** — 22×18 大水面、中央水亭、2 艘画舫、垂柳成行
- **东市/西市** — 双市制、围墙·市门牌坊·8 摊位·胡姬舞台
- **灞河 / 渭水** — 贯穿南北 + 东西的双河系统、跨河石拱桥
- **筒车 / 曲辕犁** — 唐代标志性农具
- **朱雀大街坊灯** — 28 盏路灯，夜间发光
### 👥 人物角色 (217 NPC)
- 文士 / 农夫 / 商人 / 西域胡商 / 仕女 / 进贤冠学者 / 童子 / 兵卒 / 突厥
- **胡姬胡旋舞**（4 人围圈旋转，袖飞带飘）
- 弯腰插秧农夫（4 人，pose=bend / squat / kneel）
- 朱雀大街 22 名行人（**宵禁时隐去**）+ 3 队官吏马队
- 含元殿御林军 12 + 紫绯朝臣 8 + 宣政殿朝臣 8 + 紫宸殿近臣 4
- 朱雀门下 6 名出入旅人 + 城上 4 名甲士 + 门外 3 骑迎送
- 慈恩寺塔前 8 名香客/僧侣 + 曲江池 8 名游赏人
### 🎬 实时动画 (18 种)
1. 阴阳昼夜循环（日出·日落·星空）
2. 人物原地浮动
3. 旗帜飘动 + 战旗
4. 龙骨水车 + 筒车旋转
5. 烽燧夜间脉冲发光（**天宝乱期间日夜常燃**）
6. 步兵 / 骑兵路径行进
7. 鸟群盘旋
8. 桃花飘落（春季）
9. 帅帐战鼓拍动
10. 战场扬尘消散
11. 画舫水面摆动
12. 胡姬胡旋舞
13. 香炉烟柱
14. 落叶飘零（秋季）
15. 雪花飘落（冬季）
16. 萤火虫游弋（夏夜）
17. **雨滴垂落**（新，天气=雨）
18. **风沙横扫**（新，天气=沙）
### 🌙 里坊夜禁
- 22:00 - 5:00 自动进入宵禁
- 街上 22 名行人**隐去**（不见人烟）
- 朱雀大街两侧 28 盏**坊灯**点亮发光
- 顶部弹出"宵禁中 · CURFEW · 街禁闭坊"徽章
### 🌸 四季流转
| 季 | 草色 | 树色 | 粒子 |
| --- | --- | --- | --- |
| 春 仲春·二月 | 翠绿 0x7BA84C | 嫩柳 | 桃花瓣 |
| 夏 盛夏·六月 | 深绿 0x4F7E2C | 苍翠 | 萤火虫（夜） |
| 秋 秋深·九月 | 黄棕 0x9A8C3A | 金红枫叶 | 落叶 |
| 冬 严冬·腊月 | 雪白 0xC8CED2 | 枯枝 | 雪花 |
### 🌧️ 天气系统 (新)
| 天气 | 雾色 | 视距 | 粒子 |
| --- | --- | --- | --- |
| 晴 | 暗夜色 | 200-450 | — |
| 雨 | 蓝灰 0x556070 | 80-320 | 380 滴垂直雨丝 |
| 沙 | 沙黄 0x8a6840 | 30-180 | 240 颗沙粒横扫 |
| 雾 | 苍白 0xb8c0c8 | 30-220 | — |
切换在左下角"晴雨沙雾"按钮（季节按钮上方）。
### 📜 历史事件轴 (新)
| 时代 | 年代 | 主君 | 视觉特征 |
| --- | --- | --- | --- |
| **贞观之治** | 627-649 | 唐太宗 | 兵力 1.6×，市场 0.8×，洁净 |
| **开元盛世** | 713-741 | 唐玄宗 | 市场 1.4×，胡商繁忙，金黄 tint |
| **安史之乱** | 755-763 | 玄宗→肃宗 | 兵力 2.0×，市场 0.3×，烽火常燃 |
| **天宝之后** | 763-907 | 代宗以后 | 市场 0.6×，藩镇割据，苍白 tint |
顶部时间轴按钮（⏱）打开年代切换，**自动调整 NPC 分布 + 环境光 + 烽火状态**，并弹出 8 秒历史信息横幅。
### 🗨️ 点击 NPC (新)
- 217 个 NPC 全部可点击（屏幕半径 32 像素匹配）
- 8 类身份各 4-6 句市井段子：
- 里坊百姓 / 市井商贾 / 深闺仕女 / 士林文士 / 军中兵卒 / 孩童 / 西域胡商 / 北蕃突厥
- 点击弹出气泡（角色标签 + 段子），4.2 秒自动淡出
例：
军中·兵卒 "边塞月明夜，闻笛能让壮士落泪。"
市井·商贾 "西州瓜，安息香，要不要看看？三十文一斤。"
深闺·仕女 "今春流行高髻簪花，鬓边再贴个红色花钿。"
### 🔊 音效 (Web Audio synth)
- 寺钟（早朝 6:00 / 午时 12:00 / 暮鼓 18:00）— 三泛音合成
- 关坊鼓（22:00）— 低音 + 噪声击打
- 鸡鸣（5:00）— 锯齿波频扫
- 切换场景轻铃 + 持续环境底音
- 顶部喇叭按钮可一键静音
- 弓射 mini-game 中击中靶心马蹄音
### 📜 唐诗节点
顶部"诗"按钮开启诗心模式，9 个场景各配一首唐诗：
- 朱雀大街 ·《长安古意》卢照邻
- 大明宫 ·《和贾舍人早朝大明宫之作》王维
- 大雁塔 ·《与高适薛据登慈恩寺浮图》岑参
- 曲江池 ·《丽人行》杜甫
- 东市 ·《长安道》储光羲
- 田畴 ·《观刈麦》白居易
- 朱雀门 ·《和贾至舍人早朝大明宫》杜甫
- 边塞 ·《从军行》王昌龄
- 驼商 ·《凉州词》王翰
诗签为羊皮纸色衬线竖排，浮于右上。
### 📱 移动端适配
- ≤ 900px 自动切换：侧栏改为汉堡抽屉
- 顶部·底部 HUD 缩小重排，场景按钮横排
- OrbitControls 内置双指捏合缩放
- 切换场景自动收起侧栏
### 🎮 小游戏 (4 款全部完成 V6)
顶部 ⊕ 按钮打开 mini-games modal：
- **蹴鞠** — 点击鞠球持续高踢，连踢数记录
- **雁塔题名**（新）— 石壁描红，长安鼠标拖出"進士及第"四字（含碑文水印）
- **曲江流饮**（新）— 羽觞顺曲水漂流，停下时点击赋诗（8 回，倒计圈 1.5s）
- **弓射**（新）— 准星 + 拉弓蓄力 + 风向偏差，5 箭计中靶环数
每款都带退出按钮，互不干扰。
### 🌐 镜头导览系统
- 9 个预定视点：朱雀大街 / 大明宫 / 大雁塔 / 曲江池 / 东市 / 田畴 / 朱雀门 / 边塞 / 驼商
- 三大殿专属视点（URL）：
- `#view=palaceAxis` — 三殿纵轴俯视
- `#view=xuanzheng` — 宣政殿前广场
- `#view=zichen` — 紫宸殿内庭
- 顶部魔术棒按钮启动自动巡游，每段约 7 秒
- URL 深链：
- `#h=18` 设置初始时刻
- `#view=palace` 直跳大明宫
- `#tour=1` 启动时自动巡游
### 🗨️ 交互系统
- **18 个**可点击热点（新增宣政殿、紫宸殿）
- 每个场景独立的多人对话剧本（老者×子游 角色扮演）
- 时间滑块：0-24 小时手动控制 / 切换自动模式
### 🎮 RPG 游戏模式 (V7)
- 顶部 🎮 按钮：弹出 4 角色选择卡（士子 / 商贾 / 仕女 / 游侠）
- WASD 第三人称漫游，相机平滑跟随
- 主角头顶金色光环 + 箭头标识
- 走近 NPC → `E` 提示 → 弹出对话框（含背景、连续 3-5 行剧本）
- 5 步主线任务《初到长安》
- 触发雁塔 mini-game 联动（题名后任务推进）
- 8 类身份化 NPC 段子（兵卒/官员/商贾/学子/儒生/百姓/胡商/僧侣）
- 任务面板 + Toast 通知 + 控制提示常驻
- `Esc` 退出回到上帝视角
### 👀 FPS 第一人称 (V8)
- 游戏中按 `V` 切换第三/第一人称
- 点击画布锁定鼠标（PointerLockControls）→ 鼠标看 / WASD 走 / Shift 疾走
- 头部位置 (y=1.6) + 走路微晃
- `Esc` 释放鼠标，再按 `V` 切回 TPS
### 🖼 360° 殿宇展厅 (V8)
- 5 座展厅：含元殿 / 宣政殿 / 紫宸殿 / 大雁塔 / 曲江亭
- 走到殿门 8 单位内 → 屏幕显示 `F 入 XX 看壁画`
- 进入展厅 = FPS + 球形房间 + 4-8 面墙挂壁画 + 中央木匾牌
- 看向壁画 (≥ 0.85 朝向 dot) → 底部弹出 **标题 + 注释卡**
- 程序化壁画：暖色底 + 描金边 + 题字 + 注解，每幅独立色调
- **支持真实素材**：丢图到 `murals/`，自动替换占位
- `F` / `Esc` 礼出展厅
### ⛈ 天气增强 (V8)
- 雨天每 6-20 秒概率闪电：**屏幕白闪 220ms** + 0.8-3s 后 **低频雷鸣**（Web Audio 合成）
- 雨：风向 `(-0.6, 0.3)` → 雨条整体 -7° 斜倾
- 沙：风向 `(1.4, 0.15)` 强度 3.0 → 阵风调制（gust = 1+0.5sin）
- 雾：风弱，几乎静止
- 晴：微风从东吹
## UI / 控制
| 操作 | 效果 |
| ---- | ---- |
| 拖动 / 鼠标右键 | 旋转视角 |
| 滚轮 / 双指捏合 | 缩放（受限） |
| 鼠标左键 / 触摸 | 点击物体看历史介绍 / 点击 NPC 看段子 |
| 右侧 1-9 编号按钮 | 切换 9 大场景 |
| 顶部 ☀ 图标 | 切换自动昼夜 |
| 顶部 ✦ 魔术棒图标 | 启动自动巡游 |
| 顶部 ◁ 喇叭图标 | 音效开关 |
| 顶部 ☷ 诗图标 | 切换诗心模式 |
| 顶部 ⊕ 圈图标 | 打开小游戏 |
| 顶部 ⏱ 时间轴图标 | 打开历史事件轴 |
| 顶部 🎮 角色图标 | 进入 RPG 游戏模式 |
| 左下春夏秋冬 | 切换季节 |
| 左下晴雨沙雾 | 切换天气 |
| 底部时间滑块 | 手动调节小时 |
| **游戏模式** WASD / 方向键 | 控制主角行走 |
| **游戏模式** Shift | 长按疾走 |
| **游戏模式** E / Space / Enter | 与最近 NPC 对话 |
| **游戏模式** V | 切换 第三人称 / 第一人称 |
| **游戏模式** F | 入殿看壁画 / 退展厅 |
| **游戏模式** Esc | 释放鼠标 / 退展厅 / 退游戏 |
| **FPS 模式** 点击画布 | 锁定鼠标进入真实视角 |
| **FPS 模式** 鼠标 | 转头看世界 |
| **展厅模式** 鼠标 + WASD | 在 360° 房间内自由游走，看向壁画看注释 |
| `#h=X` URL 参数 | 设定初始小时（0-23.99） |
| `#view=KEY` | 直跳视点 |
| `#tour=1` | 启动时自动巡游 |
## 文件结构
han-diorama/
├── index.html ← UI 框架 + CSS + 顶栏底栏 + 场景栏 + 时间滑块 + modal/overlay + 游戏模式 HUD
├── scene.js ← Three.js 主程序（~6600 行）
└── README.md
## 渲染特性
- **正交相机**（OrthographicCamera）+ frustum=64，sandbox 俯视感（游戏模式相机 zoom=1.4 + 平滑 lerp 跟随主角）
- 阴影范围 ±100（覆盖 120×160 单位地图）
- 雾默认 200-450 单位（天气切换会变窄）
- 后期：OutlinePass（拾取高亮）+ UnrealBloom（灯笼 / 烽火 / 金顶辉光）
- 性能：~1200+ 网格、217 NPC、移动端 30+ FPS
- 游戏模式：WASD 输入捕获 + 60Hz 主角位姿更新 + 屏幕空间最近 NPC 查询
## Phase 11 路线（继续可做）
- [ ] **Mode 1 区分**：把现有漫游变成"5 主题策展导览"（自动相机巡线 + 字幕 + 解说音）
- [ ] **价格浮动**：早市 / 午市 / 晚市差价，跨市套利
- [ ] **NPC 雇佣 / 短工**：上午帮工 → 下午结算 → 给铜钱
- [ ] **科举系统**：以一次性诗会大测验解锁"进士印"凭证
- [ ] **接入名家 NPC**：李白 / 杜甫 / 王维，各开诗仙赞解锁支线
- [ ] **安史之乱触发 cutscene**：财产损失判定 + 选阵营
- [ ] **着装影响 NPC 称呼**：着青衫 → 文士叫你"君"；着乌纱 → 商贾叫你"大人"
## Phase 10 路线（继续可做）
- [ ] **酒令系统**：曲水流觞中真的实现行酒令 (击鼓传花 / 五色筹 / 雅令俗令分级)
- [ ] **诗词填空**：给一句缺 1-2 字的名句，玩家从 4 字中补出（更高级别）
- [ ] **诗仙赞累积**：累计获得 3 张诗仙赞墨色腰牌 → 解锁李白 NPC 邀你登黄鹤楼
- [ ] **更大诗库**：扩到 50 副对联 + 16 个飞花令关键字（添风/雨/夜/星/泪/愁/梦/酒等）
- [ ] **NPC 出题难度**：根据 NPC 角色生成不同难度（文士出冷门，童子出热门）
## Phase 9 路线（继续可做）
- [ ] **更多街头游戏**：投壶 / 双陆 / 蹴鞠 / 围棋开局猜白先黑先
- [ ] **赏品装备化**：腰牌 / 锦帕 → 解锁特殊对话或区域
- [ ] **NPC 个性表情**：胜场加倍兴奋、败场摆鬼脸的连续表情动画
- [ ] **连胜奖品爆发**：连续 3 胜后概率掉落"东海明珠"等顶级藏品
## Phase 8 路线（继续可做）
1. **真实壁画素材** — 用户提供图片后接入 5 座展厅
2. **多支线任务** — 加"长安八景巡礼""坊间公案"等支线
3. **战斗系统** — 边塞场景接入弓射 mini-game 作为简易战斗
4. **多人物联动剧情** — 主角间互动
5. **物品栏 / 装备** — 拾取笔墨纸砚、腰牌、钱袋
6. **更多殿宇展厅** — 麟德殿 / 太极殿 / 兴庆宫
7. **天气过渡动画** — 切天气时雾参数渐变
8. **历史事件 cutscene** — 安史之乱触发后烽火台炸开
9. **VR / WebXR** — 头显沉浸式漫游
10. **多人联机** — WebSocket 同步漫游
11. **碰撞检测** — 让主角不能穿墙穿建筑
12. **环境音** — 不同坊里的环境声（市集喧哗 / 寺院钟鸣 / 边塞马蹄）
## GitHub 部署
静态站点可托管在 **GitHub Pages**（含 CI 自动发布）。步骤见 [docs/GITHUB_DEPLOY.md](docs/GITHUB_DEPLOY.md)。
gh auth login
chmod +x scripts/push-to-github.sh
./scripts/push-to-github.sh tang-changan # 仓库名可自定
线上示例 URL：`https://<你的用户名>.github.io/tang-changan/index.html?world=new`
## 致谢
- Three.js / OrbitControls / postprocessing / EffectComposer
- 营造法式 / 唐两京城坊考 / 大唐六典 / 资治通鉴 — 历史参考
- 《全唐诗》 — 诗歌素材
## 开发教程与 Agora Skills 安装
- 科普教程 Markdown：[`docs/05_从设计到完成_开发过程科普教程.md`](docs/05_从设计到完成_开发过程科普教程.md)
- 精排 HTML 版：[`docs/05_从设计到完成_开发过程科普教程.html`](docs/05_从设计到完成_开发过程科普教程.html)
教程中的「7.0 开发前置：安装 Agora Skills / Agora CLI」包含：
- 安装 `agora` CLI；
- `agora login` 登录；
- `agora project doctor --feature convoai` 检查 ConvoAI；
- `agora project env write .env.local --overwrite` 写入语音后端环境变量；
- 常见 `CAN_NOT_GET_GATEWAY_SERVER` / `401 Invalid token` 排查。
## V11 · 经济基建 · 4 币种 · 5 类物品 · 5 处店铺
游戏 (Mode 2) 与展示 (Mode 1) 至此**真正分家** —— Mode 2 多出一套有源有汇的经济：
### 4 种货币（同步显示在屏右上"钱包"胸牌）
| 币种 | 图标 | 主用途 |
|------|------|--------|
| **铜钱** copper | 🪙 | 食货 / 小件文房 / 小礼物 |
| **绢帛** silk | 🧵 | 衣冠 / 中价文房 / 雅物 |
| **金锭** gold | 🏵 | 真迹 / 凭证 / 城门通牒 |
| **风雅** fame | ✦ | 累计（雅物 / 诗仙赞 → 解锁高阶 NPC） |
### 4 职业 · 不同开局资源
| 职业 | 开局钱包 | 开局物品 |
|------|---------|---------|
| 文士 scholar | 30 文 + 2 绢 + ✦5 | 湖州狼毫 + 一刀宣纸 |
| 商贾 merchant | 80 文 + 4 绢 + ✦1 | — |
| 仕女 lady | 50 文 + 3 绢 + 1 金 + ✦3 | 一枚玉佩 |
| 武人 soldier | 40 文 + ✦2 | 胡饼 ×2 |
### 5 类物品（共 27 件，分类聚合显示）
| 类 | 例 | 效果 |
|----|----|------|
| 🥯 **食货** food | 胡饼 / 葡萄酒 / 酥山 / 剑南春 | **吃** → 回体力 + 临时风度 charm |
| 🖌 **文房** literati | 狼毫 / 松烟墨 / 宣纸 / 端砚 / 唐诗集 / 全唐诗 | 累加 **poetryBonus**，达 15 解锁"灵思一次" |
| 👘 **衣冠** attire | 青衫 / 乌纱帽 / 玉佩 / 织锦帕 / 香囊 | **着** → 装备槽（头/身/饰）+ 常驻 charm |
| 🪞 **雅物** collectible | 西凉铜镜 / 东海明珠 / 吴道子真迹 / 蜀锦 / 滕王阁序拓本 | 入袋即 ✦风雅 累计 |
| 🪪 **凭证** pass | 诗仙赞腰牌 / 通关文牒 / 进士印 | 解锁区域 / 高阶 NPC |
### 5 处店铺（实地店招 · 走近 `F` 开店）
| 店 | 位置 | 主售 |
|----|------|------|
| 🏮 **朱雀酒肆** | (-5, -1) | 食货 7 件（胡饼/葡萄酒/酥山/剑南春…） |
| 🏮 **东市米粮铺** | (5, 16) | 食货 4 件（粳米/胡饼/栗子/清茗） |
| 🏮 **东市文房斋** | (-5, 17) | 文房 7 件（笔墨纸砚 + 唐诗集 + 全唐诗） |
| 🏮 **东市绫罗肆** | (0, 19) | 衣冠 6 件（青衫/乌纱/玉佩/竹簪…） |
| 🏮 **西市胡商货栈** | (-22, -3) | 雅物 + 凭证（铜镜/明珠/真迹/蜀锦/拓本/城坊图/文牒） |
店招实地建模：立柱 + 灯笼 + 牌匾（CanvasTexture 中文 STKaiti）+ 灯笼缓慢晃动。买/卖 modal 顶部显示钱包 4 币种，按类聚合商品，价格用 🪙🧵🏵 图标，买不起的灰显禁用。
### 体力 + 风度系统
- **体力 stamina** 0-100，初始 100；每秒自动 +1 恢复（mini-game / 跑步消耗待加）
- 屏右上**绿色 4px 条**实时显示
- 食物给定量回复，酒/茶/酥山额外给**临时 charm 风度**（60-180 秒 buff）
### 文房灵感 → 接入诗会
持有文房物品自动累计 poetryBonus（笔 +10、墨/纸 +5、砚 +20、唐诗集 +25、全唐诗 +35）。
- bonus ≥ **15** → 诗会内可灵思**一次**（答错时获一次重答机会，且会标红错项）
- bonus ≥ **35** → 玩家直接成为"长安第一才子"（彩蛋）
### Loot 重构
旧的 REWARDS_GOOD/SMALL/CONSOL/PERFECT → 统一迁到 `LOOT_TABLES` (win/draw/lose/perfect)，全部用 itemId 引用。币奖单独用 `COIN_10` / `COIN_3` / `SILK_1` token 处理。所有路径（猜拳/猜谜/对诗）共享一致 grantReward。
## V10 · 诗酒小宴 · 飞花令 · 对对联 · 诗仙赞
街头三玩之外再开一种 **盛唐文人雅集** —— 走到 NPC 旁 `E` 开对话，到末尾会出现紫粉色按钮 **🍷 对诗**（文士 / 仕女 / 老人 / 僧人 100%，兵卒 / 农夫 30%）。点开后随机抽 3 轮，混合两种唐风玩法：
| 玩法 | 形式 |
|------|------|
| **飞花令** | 给关键字 (花/月/风/春/江/酒/山/雪)，4 句中选**含此字**的诗 |
| **对对联** | 给上联，4 句中选下联（干扰项均为**其他名联的下联**，迷惑性强） |
**3 巡定胜负 · 奖品分级**：
| 战绩 | 级别 | 奖品池 |
|------|------|--------|
| 3/3 | **诗仙赞 ✦** | 🍶 一壶剑南春 / 📚 《全唐诗》/ 🖌 湖州狼毫 / 🟫 端州歙砚 / 🎨 吴道子真迹 / 🪪 诗仙赞墨色腰牌 |
| 2/3 | 才情不俗 | 小赏（三文钱 / 胡饼 / 打油诗…） |
| 1/3 | 勉强一巡 | 安慰（路人一笑 / 鬼脸） |
| 0/3 | 颗粒无收 | 文士调侃：「公子何不饮酒，少谈诗？」 |
题库规模：
- 飞花令：**8 个关键字 × 每字 ~6 含字句 + ~6 不含字句**，组合数 >180
- 对联：18 副名联（王勃 / 李白 / 王维 / 柳宗元 / 杜甫 / 白居易 / 王翰 / 王之涣 / 张九龄…）
对诗 UI 与街头小游戏统一 `.sg-card` 风格，但配色改为 **暗夜紫 + 桃花粉**，提示气泡用 **STKaiti 楷体 + 紫色左竖条**，呼应"花间一壶酒"的雅意。
## V9 · 街头玩耍 · 猜拳猜谜 + 随机赏赐 + 行囊系统
游戏模式中靠近任意路人，按 `E` 打开对话；在对话**最后一行**会出现两枚按钮：
| 按钮 | 玩法 |
|------|------|
| **🪨 猜拳** | 经典石剪布。你出招后，NPC 转手轮抽签 600ms 落定 → 胜 / 平 / 负 |
| **🎴 猜谜** | 唐风题库（民俗谜语 + 长安史实），四选一，对错均有奖 |
**胜负判定 → 不同奖品池**：
- **胜** → 十文开元通宝 / 西凉铜镜 / 滕王阁序拓本 / 龙井香囊 / 葡萄酒 / 东海明珠 / 织锦帕 / 酥山
- **平** → 三文铜钱 / 胡饼 / 打油诗 / 炒栗子 / 竹簪
- **负** → 路人一笑 / "再来" / 鬼脸（安慰，无价值但有趣）
NPC 角色对游戏的态度：
| 角色 | 愿意陪玩 |
|------|---------|
| 文士 / 商贾 / 仕女 / 童子 / 农夫 / 胡商 / 货郎 / 街边路人 | 100% |
| 兵卒 / 官员 / 僧侣 | 30%（性子严，但偶尔也兴致来时） |
**行囊系统 (Inventory)**：
- 屏幕右上 Inventory **胸牌**: `🪙 X 文 · 🎁 Y 件 · [最近 3 件 icon]`
- 点击胸牌弹出**总览面板**：分行显示所有藏品（含数量×N）
- 中央**赏赐 Toast** 飘字：`王翁 赏你 🪞 一面西凉铜镜`
12 题谜库：
## V8 · 入殿看展 · 第一人称 + 壁画展厅
新增三件大事：
1. **天气升级**：雨天 5-20 秒概率触发 **闪电屏闪 + 低频雷鸣**；雨/沙/雾各有风向 → 雨条斜飘、沙粒阵风吹拂、雾色阴沉
2. **第一人称 (FPS) 模式**：游戏中按 `V` 切换第三/第一人称；点击锁鼠标真实视角看世界；按 `Esc` 释放
3. **大殿 360° 展厅**：走到 5 个殿门口（含元殿 / 宣政殿 / 紫宸殿 / 大雁塔 / 曲江亭）→ 按 `F` 入展 → FPS 在展厅内自由游走，看向壁画时屏幕底部显示标题 + 注释；按 `F` 或 `Esc` 礼出展厅
### 5 座展厅清单
| ID | 标题 | 壁画 |
| --- | --- | --- |
| `hanyuan` | 含元殿 · 万邦来朝 | 万邦来朝图 / 元日大朝 / 受降图 / 凤翔丹墀 |
| `xuanzheng` | 宣政殿 · 常朝政务 | 常朝图 / 紫绯朝服 / 中书省草制 / 御史台 |
| `zichen` | 紫宸殿 · 内朝寝兴 | 入阁仪 / 夜对 / 后宫 |
| `pagoda` | 大雁塔 · 玄奘西天 | 玄奘取经图 / 译经场 / 雁塔题名 / 佛祖说法 |
| `qujiang` | 曲江亭 · 文人雅集 | 丽人行 / 曲江流饮 / 杏园探花 |
每幅壁画现在是程序化占位（暖金色调底 + 题字 + 注解）。**想换真实素材**：把图片放进 `murals/`，命名 `{galleryId}_{index}.jpg`，详见 `murals/README.md`。
## V7 · 长安行客 · RPG 模式
点击顶栏 **🎮 游戏模式** 按钮，从 4 个角色预设（**士子 / 商贾 / 仕女 / 游侠**）中挑选你的长安身份，输入名字，进入第三人称漫游：
| 操作 | 键位 |
| --- | --- |
| 移动 | `W` `A` `S` `D` 或方向键 |
| 疾走 | 长按 `Shift` |
| 与最近 NPC 交互 | `E` / 空格 / 回车 |
| 退出游戏 | `Esc` |
- **主线任务**：《初到长安》5 步剧情链：朱雀门 → 西市张掌柜 → 大雁塔题名 → 大明宫含元殿 → 名垂长安
- **场景自动联动**：与 217 个 NPC 都可对话；不同坊里的人物会按身份（守门将/商贾/学子/儒生/百姓/官员/胡商/僧侣）说出不同的市井段子
- **任务驱动**：在朱雀门附近的兵卒、西市的商贾、大雁塔下的学子会触发任务专属台词与剧情推进
- **HUD**：左上任务条 / 下方按键提示 / 顶部 toast 通知 / 底部对话框
- **镜头**：相机从俯瞰沙盘平滑过渡到主角第三人称跟随，主角头顶有金色光环 + 箭头标识
## 一句话技术栈
**纯前端**（HTML + Three.js + 原生 JS），**无构建步骤**，浏览器直接打开即可。
## 如何运行
cd /Users/andyhu/Downloads/Company/han-diorama
python3 -m http.server 8088
# 访问 http://localhost:8088/
## 场景全景 (V6·三殿盛唐版)
┌─────────────────────────────────────┐
│ 🏛 紫宸殿 (内殿/皇帝寝兴) │ z=-89
│ 私密单层 · 飞檐高耸 · 4 近臣 + 琴师 │
└────────────────┬────────────────────┘
│←連廊
┌────────────────┴────────────────────┐
│ 🏛 宣政殿 (常朝/政务) │ z=-76
│ 重檐两层 · 8 朝臣紫绯 · 4 带刀侍卫 │
└────────────────┬────────────────────┘
│←連廊
┌────────────────┴────────────────────┐
│ 🏛 含元殿 (大朝/万邦来朝) │ z=-60
│ 三层金顶 · 龙凤丹墀 · 翔鸾栖凤双阙 │
│ 12 御林军 + 8 朝臣 + 苍松石狮 │
└────────────────┬────────────────────┘
┌────────────────┴────────────────────┐
│ 🏯 朱雀门 (皇城南正门) │
└────────────────┬────────────────────┘
┌────────────────┴────────────────────┐
│ ⚔️ 边塞战场 / 突厥穹庐 / 烽燧 │
└────────────────┬────────────────────┘
┌────────┐ ┌────────────┴────────────┐ ┌─────────────────┐
│ 🐫 驼商│ │ │ │ │
│ + 🏛西市│←┤ 朱雀大街 · 22 行人坊灯 28 ├→│ 🌾 田畴 筒车曲辕犁│
│ 胡旋舞 │ │ 官吏马队 · 宵禁可见 │ │ 弯腰插秧农夫 │
└────────┘ └────────────┬─────────────┘ └─────────────────┘
┌────────────┴─────────────┐
│ 🌊 灞河 + 渭水 + 拱桥 │
└────────────┬─────────────┘
┌────────────────┴────────────────────┐
│ 🌅 曲江池 (西南) 🏯 大雁塔 (东南) │
│ 画舫 · 亭台 · 柳岸 · 慈恩寺 · 石狮香炉 │
└─────────────────────────────────────┘
## 内容清单 (V6 三殿百年版)
### 🏛️ 唐代地标
- **大明宫三大殿**（V6）— 含元殿 + 宣政殿 + 紫宸殿 三层纵轴，双侧長廊相连
- **含元殿** — 三层金顶高台、龙凤丹墀龙尾道、翔鸾·栖凤双阙、12 御林军 + 8 朝臣
- **宣政殿**（新）— 重檐两层、9 柱前廊、8 紫绯朝臣 + 4 甲士
- **紫宸殿**（新）— 单层精巧高翘飞檐、4 近臣 + 仕女琴师、后花园松柏假山
- **大雁塔**（慈恩寺塔）— 7 层方塔、攒尖砖石、四面拱窗、金顶刹
- **朱雀门城楼** — 三门道、九五至尊八十一钉、重檐两层、龙凤双旗
- **曲江池** — 22×18 大水面、中央水亭、2 艘画舫、垂柳成行
- **东市/西市** — 双市制、围墙·市门牌坊·8 摊位·胡姬舞台
- **灞河 / 渭水** — 贯穿南北 + 东西的双河系统、跨河石拱桥
- **筒车 / 曲辕犁** — 唐代标志性农具
- **朱雀大街坊灯** — 28 盏路灯，夜间发光
### 👥 人物角色 (217 NPC)
- 文士 / 农夫 / 商人 / 西域胡商 / 仕女 / 进贤冠学者 / 童子 / 兵卒 / 突厥
- **胡姬胡旋舞**（4 人围圈旋转，袖飞带飘）
- 弯腰插秧农夫（4 人，pose=bend / squat / kneel）
- 朱雀大街 22 名行人（**宵禁时隐去**）+ 3 队官吏马队
- 含元殿御林军 12 + 紫绯朝臣 8 + 宣政殿朝臣 8 + 紫宸殿近臣 4
- 朱雀门下 6 名出入旅人 + 城上 4 名甲士 + 门外 3 骑迎送
- 慈恩寺塔前 8 名香客/僧侣 + 曲江池 8 名游赏人
### 🎬 实时动画 (18 种)
1. 阴阳昼夜循环（日出·日落·星空）
2. 人物原地浮动
3. 旗帜飘动 + 战旗
4. 龙骨水车 + 筒车旋转
5. 烽燧夜间脉冲发光（**天宝乱期间日夜常燃**）
6. 步兵 / 骑兵路径行进
7. 鸟群盘旋
8. 桃花飘落（春季）
9. 帅帐战鼓拍动
10. 战场扬尘消散
11. 画舫水面摆动
12. 胡姬胡旋舞
13. 香炉烟柱
14. 落叶飘零（秋季）
15. 雪花飘落（冬季）
16. 萤火虫游弋（夏夜）
17. **雨滴垂落**（新，天气=雨）
18. **风沙横扫**（新，天气=沙）
### 🌙 里坊夜禁
- 22:00 - 5:00 自动进入宵禁
- 街上 22 名行人**隐去**（不见人烟）
- 朱雀大街两侧 28 盏**坊灯**点亮发光
- 顶部弹出"宵禁中 · CURFEW · 街禁闭坊"徽章
### 🌸 四季流转
| 季 | 草色 | 树色 | 粒子 |
| --- | --- | --- | --- |
| 春 仲春·二月 | 翠绿 0x7BA84C | 嫩柳 | 桃花瓣 |
| 夏 盛夏·六月 | 深绿 0x4F7E2C | 苍翠 | 萤火虫（夜） |
| 秋 秋深·九月 | 黄棕 0x9A8C3A | 金红枫叶 | 落叶 |
| 冬 严冬·腊月 | 雪白 0xC8CED2 | 枯枝 | 雪花 |
### 🌧️ 天气系统 (新)
| 天气 | 雾色 | 视距 | 粒子 |
| --- | --- | --- | --- |
| 晴 | 暗夜色 | 200-450 | — |
| 雨 | 蓝灰 0x556070 | 80-320 | 380 滴垂直雨丝 |
| 沙 | 沙黄 0x8a6840 | 30-180 | 240 颗沙粒横扫 |
| 雾 | 苍白 0xb8c0c8 | 30-220 | — |
切换在左下角"晴雨沙雾"按钮（季节按钮上方）。
### 📜 历史事件轴 (新)
| 时代 | 年代 | 主君 | 视觉特征 |
| --- | --- | --- | --- |
| **贞观之治** | 627-649 | 唐太宗 | 兵力 1.6×，市场 0.8×，洁净 |
| **开元盛世** | 713-741 | 唐玄宗 | 市场 1.4×，胡商繁忙，金黄 tint |
| **安史之乱** | 755-763 | 玄宗→肃宗 | 兵力 2.0×，市场 0.3×，烽火常燃 |
| **天宝之后** | 763-907 | 代宗以后 | 市场 0.6×，藩镇割据，苍白 tint |
顶部时间轴按钮（⏱）打开年代切换，**自动调整 NPC 分布 + 环境光 + 烽火状态**，并弹出 8 秒历史信息横幅。
### 🗨️ 点击 NPC (新)
- 217 个 NPC 全部可点击（屏幕半径 32 像素匹配）
- 8 类身份各 4-6 句市井段子：
- 里坊百姓 / 市井商贾 / 深闺仕女 / 士林文士 / 军中兵卒 / 孩童 / 西域胡商 / 北蕃突厥
- 点击弹出气泡（角色标签 + 段子），4.2 秒自动淡出
例：
军中·兵卒 "边塞月明夜，闻笛能让壮士落泪。"
市井·商贾 "西州瓜，安息香，要不要看看？三十文一斤。"
深闺·仕女 "今春流行高髻簪花，鬓边再贴个红色花钿。"
### 🔊 音效 (Web Audio synth)
- 寺钟（早朝 6:00 / 午时 12:00 / 暮鼓 18:00）— 三泛音合成
- 关坊鼓（22:00）— 低音 + 噪声击打
- 鸡鸣（5:00）— 锯齿波频扫
- 切换场景轻铃 + 持续环境底音
- 顶部喇叭按钮可一键静音
- 弓射 mini-game 中击中靶心马蹄音
### 📜 唐诗节点
顶部"诗"按钮开启诗心模式，9 个场景各配一首唐诗：
- 朱雀大街 ·《长安古意》卢照邻
- 大明宫 ·《和贾舍人早朝大明宫之作》王维
- 大雁塔 ·《与高适薛据登慈恩寺浮图》岑参
- 曲江池 ·《丽人行》杜甫
- 东市 ·《长安道》储光羲
- 田畴 ·《观刈麦》白居易
- 朱雀门 ·《和贾至舍人早朝大明宫》杜甫
- 边塞 ·《从军行》王昌龄
- 驼商 ·《凉州词》王翰
诗签为羊皮纸色衬线竖排，浮于右上。
### 📱 移动端适配
- ≤ 900px 自动切换：侧栏改为汉堡抽屉
- 顶部·底部 HUD 缩小重排，场景按钮横排
- OrbitControls 内置双指捏合缩放
- 切换场景自动收起侧栏
### 🎮 小游戏 (4 款全部完成 V6)
顶部 ⊕ 按钮打开 mini-games modal：
- **蹴鞠** — 点击鞠球持续高踢，连踢数记录
- **雁塔题名**（新）— 石壁描红，长安鼠标拖出"進士及第"四字（含碑文水印）
- **曲江流饮**（新）— 羽觞顺曲水漂流，停下时点击赋诗（8 回，倒计圈 1.5s）
- **弓射**（新）— 准星 + 拉弓蓄力 + 风向偏差，5 箭计中靶环数
每款都带退出按钮，互不干扰。
### 🌐 镜头导览系统
- 9 个预定视点：朱雀大街 / 大明宫 / 大雁塔 / 曲江池 / 东市 / 田畴 / 朱雀门 / 边塞 / 驼商
- 三大殿专属视点（URL）：
- `#view=palaceAxis` — 三殿纵轴俯视
- `#view=xuanzheng` — 宣政殿前广场
- `#view=zichen` — 紫宸殿内庭
- 顶部魔术棒按钮启动自动巡游，每段约 7 秒
- URL 深链：
- `#h=18` 设置初始时刻
- `#view=palace` 直跳大明宫
- `#tour=1` 启动时自动巡游
### 🗨️ 交互系统
- **18 个**可点击热点（新增宣政殿、紫宸殿）
- 每个场景独立的多人对话剧本（老者×子游 角色扮演）
- 时间滑块：0-24 小时手动控制 / 切换自动模式
### 🎮 RPG 游戏模式 (V7)
- 顶部 🎮 按钮：弹出 4 角色选择卡（士子 / 商贾 / 仕女 / 游侠）
- WASD 第三人称漫游，相机平滑跟随
- 主角头顶金色光环 + 箭头标识
- 走近 NPC → `E` 提示 → 弹出对话框（含背景、连续 3-5 行剧本）
- 5 步主线任务《初到长安》
- 触发雁塔 mini-game 联动（题名后任务推进）
- 8 类身份化 NPC 段子（兵卒/官员/商贾/学子/儒生/百姓/胡商/僧侣）
- 任务面板 + Toast 通知 + 控制提示常驻
- `Esc` 退出回到上帝视角
### 👀 FPS 第一人称 (V8)
- 游戏中按 `V` 切换第三/第一人称
- 点击画布锁定鼠标（PointerLockControls）→ 鼠标看 / WASD 走 / Shift 疾走
- 头部位置 (y=1.6) + 走路微晃
- `Esc` 释放鼠标，再按 `V` 切回 TPS
### 🖼 360° 殿宇展厅 (V8)
- 5 座展厅：含元殿 / 宣政殿 / 紫宸殿 / 大雁塔 / 曲江亭
- 走到殿门 8 单位内 → 屏幕显示 `F 入 XX 看壁画`
- 进入展厅 = FPS + 球形房间 + 4-8 面墙挂壁画 + 中央木匾牌
- 看向壁画 (≥ 0.85 朝向 dot) → 底部弹出 **标题 + 注释卡**
- 程序化壁画：暖色底 + 描金边 + 题字 + 注解，每幅独立色调
- **支持真实素材**：丢图到 `murals/`，自动替换占位
- `F` / `Esc` 礼出展厅
### ⛈ 天气增强 (V8)
- 雨天每 6-20 秒概率闪电：**屏幕白闪 220ms** + 0.8-3s 后 **低频雷鸣**（Web Audio 合成）
- 雨：风向 `(-0.6, 0.3)` → 雨条整体 -7° 斜倾
- 沙：风向 `(1.4, 0.15)` 强度 3.0 → 阵风调制（gust = 1+0.5sin）
- 雾：风弱，几乎静止
- 晴：微风从东吹
## UI / 控制
| 操作 | 效果 |
| ---- | ---- |
| 拖动 / 鼠标右键 | 旋转视角 |
| 滚轮 / 双指捏合 | 缩放（受限） |
| 鼠标左键 / 触摸 | 点击物体看历史介绍 / 点击 NPC 看段子 |
| 右侧 1-9 编号按钮 | 切换 9 大场景 |
| 顶部 ☀ 图标 | 切换自动昼夜 |
| 顶部 ✦ 魔术棒图标 | 启动自动巡游 |
| 顶部 ◁ 喇叭图标 | 音效开关 |
| 顶部 ☷ 诗图标 | 切换诗心模式 |
| 顶部 ⊕ 圈图标 | 打开小游戏 |
| 顶部 ⏱ 时间轴图标 | 打开历史事件轴 |
| 顶部 🎮 角色图标 | 进入 RPG 游戏模式 |
| 左下春夏秋冬 | 切换季节 |
| 左下晴雨沙雾 | 切换天气 |
| 底部时间滑块 | 手动调节小时 |
| **游戏模式** WASD / 方向键 | 控制主角行走 |
| **游戏模式** Shift | 长按疾走 |
| **游戏模式** E / Space / Enter | 与最近 NPC 对话 |
| **游戏模式** V | 切换 第三人称 / 第一人称 |
| **游戏模式** F | 入殿看壁画 / 退展厅 |
| **游戏模式** Esc | 释放鼠标 / 退展厅 / 退游戏 |
| **FPS 模式** 点击画布 | 锁定鼠标进入真实视角 |
| **FPS 模式** 鼠标 | 转头看世界 |
| **展厅模式** 鼠标 + WASD | 在 360° 房间内自由游走，看向壁画看注释 |
| `#h=X` URL 参数 | 设定初始小时（0-23.99） |
| `#view=KEY` | 直跳视点 |
| `#tour=1` | 启动时自动巡游 |
## 文件结构
han-diorama/
├── index.html ← UI 框架 + CSS + 顶栏底栏 + 场景栏 + 时间滑块 + modal/overlay + 游戏模式 HUD
├── scene.js ← Three.js 主程序（~6600 行）
└── README.md
## 渲染特性
- **正交相机**（OrthographicCamera）+ frustum=64，sandbox 俯视感（游戏模式相机 zoom=1.4 + 平滑 lerp 跟随主角）
- 阴影范围 ±100（覆盖 120×160 单位地图）
- 雾默认 200-450 单位（天气切换会变窄）
- 后期：OutlinePass（拾取高亮）+ UnrealBloom（灯笼 / 烽火 / 金顶辉光）
- 性能：~1200+ 网格、217 NPC、移动端 30+ FPS
- 游戏模式：WASD 输入捕获 + 60Hz 主角位姿更新 + 屏幕空间最近 NPC 查询
## Phase 11 路线（继续可做）
- [ ] **Mode 1 区分**：把现有漫游变成"5 主题策展导览"（自动相机巡线 + 字幕 + 解说音）
- [ ] **价格浮动**：早市 / 午市 / 晚市差价，跨市套利
- [ ] **NPC 雇佣 / 短工**：上午帮工 → 下午结算 → 给铜钱
- [ ] **科举系统**：以一次性诗会大测验解锁"进士印"凭证
- [ ] **接入名家 NPC**：李白 / 杜甫 / 王维，各开诗仙赞解锁支线
- [ ] **安史之乱触发 cutscene**：财产损失判定 + 选阵营
- [ ] **着装影响 NPC 称呼**：着青衫 → 文士叫你"君"；着乌纱 → 商贾叫你"大人"
## Phase 10 路线（继续可做）
- [ ] **酒令系统**：曲水流觞中真的实现行酒令 (击鼓传花 / 五色筹 / 雅令俗令分级)
- [ ] **诗词填空**：给一句缺 1-2 字的名句，玩家从 4 字中补出（更高级别）
- [ ] **诗仙赞累积**：累计获得 3 张诗仙赞墨色腰牌 → 解锁李白 NPC 邀你登黄鹤楼
- [ ] **更大诗库**：扩到 50 副对联 + 16 个飞花令关键字（添风/雨/夜/星/泪/愁/梦/酒等）
- [ ] **NPC 出题难度**：根据 NPC 角色生成不同难度（文士出冷门，童子出热门）
## Phase 9 路线（继续可做）
- [ ] **更多街头游戏**：投壶 / 双陆 / 蹴鞠 / 围棋开局猜白先黑先
- [ ] **赏品装备化**：腰牌 / 锦帕 → 解锁特殊对话或区域
- [ ] **NPC 个性表情**：胜场加倍兴奋、败场摆鬼脸的连续表情动画
- [ ] **连胜奖品爆发**：连续 3 胜后概率掉落"东海明珠"等顶级藏品
## Phase 8 路线（继续可做）
1. **真实壁画素材** — 用户提供图片后接入 5 座展厅
2. **多支线任务** — 加"长安八景巡礼""坊间公案"等支线
3. **战斗系统** — 边塞场景接入弓射 mini-game 作为简易战斗
4. **多人物联动剧情** — 主角间互动
5. **物品栏 / 装备** — 拾取笔墨纸砚、腰牌、钱袋
6. **更多殿宇展厅** — 麟德殿 / 太极殿 / 兴庆宫
7. **天气过渡动画** — 切天气时雾参数渐变
8. **历史事件 cutscene** — 安史之乱触发后烽火台炸开
9. **VR / WebXR** — 头显沉浸式漫游
10. **多人联机** — WebSocket 同步漫游
11. **碰撞检测** — 让主角不能穿墙穿建筑
12. **环境音** — 不同坊里的环境声（市集喧哗 / 寺院钟鸣 / 边塞马蹄）
## GitHub 部署
静态站点可托管在 **GitHub Pages**（含 CI 自动发布）。步骤见 [docs/GITHUB_DEPLOY.md](docs/GITHUB_DEPLOY.md)。
gh auth login
chmod +x scripts/push-to-github.sh
./scripts/push-to-github.sh tang-changan # 仓库名可自定
线上示例 URL：`https://<你的用户名>.github.io/tang-changan/index.html?world=new`
## 致谢
- Three.js / OrbitControls / postprocessing / EffectComposer
- 营造法式 / 唐两京城坊考 / 大唐六典 / 资治通鉴 — 历史参考
- 《全唐诗》 — 诗歌素材标签：3D微缩模型, Agora, RPG, Web游戏, 互动沙盘, 历史科普, 多模态安全, 移动端适配, 自定义脚本