复刻 Expeditione™ 风格的互动微缩沙盘，主题 大唐百年史。120×160 单位级地图、三大殿纵轴（含元 → 宣政 → 紫宸）、跨河桥梁、七层大雁塔、曲江画舫、朱雀城门、东西二市、稻麦水利、胡旋舞乐——配以 昼夜流转 · 四季流转 · 宵禁夜禁 · 唐诗节点 · 寺钟鸡鸣 · 天气切换（雨/沙/雾 + 闪电雷声 + 风向斜飘）· NPC 市井段子 · 历史事件轴 · 4 款 mini-game · 移动端适配 · 🎮 RPG 模式 · 👀 第一人称 FPS 模式 · 🖼 5 座 360° 殿宇展厅，一幅可漫游、可对话、可吟诗、可游戏、可扮演、可入殿看展、可穿越百年的盛唐画卷。

• 科普教程 Markdown：docs/05_从设计到完成_开发过程科普教程.md
• 精排 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 排查。

游戏 (Mode 2) 与展示 (Mode 1) 至此真正分家 —— Mode 2 多出一套有源有汇的经济：

店招实地建模：立柱 + 灯笼 + 牌匾（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 → 玩家直接成为"长安第一才子"（彩蛋）

旧的 REWARDS_GOOD/SMALL/CONSOL/PERFECT → 统一迁到 LOOT_TABLES (win/draw/lose/perfect)，全部用 itemId 引用。币奖单独用 COIN_10 / COIN_3 / SILK_1 token 处理。所有路径（猜拳/猜谜/对诗）共享一致 grantReward。

古人云：花间一壶酒，独酌无相亲；举杯邀明月，对影成三人。

街头三玩之外再开一种 盛唐文人雅集 —— 走到 NPC 旁 E 开对话，到末尾会出现紫粉色按钮 🍷 对诗（文士 / 仕女 / 老人 / 僧人 100%，兵卒 / 农夫 30%）。点开后随机抽 3 轮，混合两种唐风玩法：

3 巡定胜负 · 奖品分级：

题库规模：

• 飞花令：8 个关键字 × 每字 ~6 含字句 + ~6 不含字句，组合数 >180
• 对联：18 副名联（王勃 / 李白 / 王维 / 柳宗元 / 杜甫 / 白居易 / 王翰 / 王之涣 / 张九龄…）

对诗 UI 与街头小游戏统一 .sg-card 风格，但配色改为 暗夜紫 + 桃花粉，提示气泡用 STKaiti 楷体 + 紫色左竖条，呼应"花间一壶酒"的雅意。

游戏模式中靠近任意路人，按 E 打开对话；在对话最后一行会出现两枚按钮：

胜负判定 → 不同奖品池：

• 胜 → 十文开元通宝 / 西凉铜镜 / 滕王阁序拓本 / 龙井香囊 / 葡萄酒 / 东海明珠 / 织锦帕 / 酥山
• 平 → 三文铜钱 / 胡饼 / 打油诗 / 炒栗子 / 竹簪
• 负 → 路人一笑 / "再来" / 鬼脸（安慰，无价值但有趣）

NPC 角色对游戏的态度：

行囊系统 (Inventory)：

• 屏幕右上 Inventory 胸牌: 🪙 X 文 · 🎁 Y 件 · [最近 3 件 icon]
• 点击胸牌弹出总览面板：分行显示所有藏品（含数量×N）
• 中央赏赐 Toast 飘字：王翁 赏你 🪞 一面西凉铜镜

12 题谜库：

「身穿绿衣衫，肚里水汪汪，生的子儿多，个个黑脸膛」答：西瓜 「头戴红帽子，身披白褂子，说话伸脖子，走路摆架子」答：鹅 「弟兄六七个，围着柱子坐，大家一分手，衣服全扯破」答：蒜 「青枝绿叶不是树，开花结桃不是桃，剥开桃子白花花」答：棉花 「腰里长出胡须来，没有须时还能吃，有了须时吃不来」答：玉米 「上有半截草，下有一池水」答：茫 "床前明月光" 是谁所作？答：李白 安史之乱在哪位皇帝在位？答：唐玄宗 玄奘西行多少年？答：十七年 ……

新增三件大事：

1. 天气升级：雨天 5-20 秒概率触发 闪电屏闪 + 低频雷鸣；雨/沙/雾各有风向 → 雨条斜飘、沙粒阵风吹拂、雾色阴沉
2. 第一人称 (FPS) 模式：游戏中按 V 切换第三/第一人称；点击锁鼠标真实视角看世界；按 Esc 释放
3. 大殿 360° 展厅：走到 5 个殿门口（含元殿 / 宣政殿 / 紫宸殿 / 大雁塔 / 曲江亭）→ 按 F 入展 → FPS 在展厅内自由游走，看向壁画时屏幕底部显示标题 + 注释；按 F 或 Esc 礼出展厅

每幅壁画现在是程序化占位（暖金色调底 + 题字 + 注解）。想换真实素材：把图片放进 murals/，命名 {galleryId}_{index}.jpg，详见 murals/README.md。

点击顶栏 🎮 游戏模式 按钮，从 4 个角色预设（士子 / 商贾 / 仕女 / 游侠）中挑选你的长安身份，输入名字，进入第三人称漫游：

• 主线任务：《初到长安》5 步剧情链：朱雀门 → 西市张掌柜 → 大雁塔题名 → 大明宫含元殿 → 名垂长安
• 场景自动联动：与 217 个 NPC 都可对话；不同坊里的人物会按身份（守门将/商贾/学子/儒生/百姓/官员/胡商/僧侣）说出不同的市井段子
• 任务驱动：在朱雀门附近的兵卒、西市的商贾、大雁塔下的学子会触发任务专属台词与剧情推进
• HUD：左上任务条 / 下方按键提示 / 顶部 toast 通知 / 底部对话框
• 镜头：相机从俯瞰沙盘平滑过渡到主角第三人称跟随，主角头顶有金色光环 + 箭头标识

纯前端（HTML + Three.js + 原生 JS），无构建步骤，浏览器直接打开即可。

cd /Users/andyhu/Downloads/Company/han-diorama
python3 -m http.server 8088
# 访问 http://localhost:8088/

因为用了 ES Module + Import Map，必须经 HTTP 服务，直接双击 index.html 跑不起来。

        ┌─────────────────────────────────────┐
        │   🏛 紫宸殿  (内殿/皇帝寝兴)         │  z=-89
        │   私密单层 · 飞檐高耸 · 4 近臣 + 琴师 │
        └────────────────┬────────────────────┘
                         │←連廊
        ┌────────────────┴────────────────────┐
        │   🏛 宣政殿  (常朝/政务)            │  z=-76
        │   重檐两层 · 8 朝臣紫绯 · 4 带刀侍卫 │
        └────────────────┬────────────────────┘
                         │←連廊
        ┌────────────────┴────────────────────┐
        │   🏛 含元殿  (大朝/万邦来朝)        │  z=-60
        │   三层金顶 · 龙凤丹墀 · 翔鸾栖凤双阙 │
        │   12 御林军 + 8 朝臣 + 苍松石狮     │
        └────────────────┬────────────────────┘
        ┌────────────────┴────────────────────┐
        │   🏯 朱雀门 (皇城南正门)             │
        └────────────────┬────────────────────┘
        ┌────────────────┴────────────────────┐
        │   ⚔️ 边塞战场 / 突厥穹庐 / 烽燧     │
        └────────────────┬────────────────────┘
 ┌────────┐ ┌────────────┴────────────┐ ┌─────────────────┐
 │ 🐫 驼商│ │                          │ │                  │
 │ + 🏛西市│←┤ 朱雀大街 · 22 行人坊灯 28 ├→│ 🌾 田畴 筒车曲辕犁│
 │ 胡旋舞 │ │ 官吏马队 · 宵禁可见      │ │ 弯腰插秧农夫     │
 └────────┘ └────────────┬─────────────┘ └─────────────────┘
            ┌────────────┴─────────────┐
            │ 🌊 灞河 + 渭水 + 拱桥     │
            └────────────┬─────────────┘
        ┌────────────────┴────────────────────┐
        │ 🌅 曲江池 (西南)   🏯 大雁塔 (东南)   │
        │ 画舫 · 亭台 · 柳岸 · 慈恩寺 · 石狮香炉 │
        └─────────────────────────────────────┘

• 大明宫三大殿（V6）— 含元殿 + 宣政殿 + 紫宸殿 三层纵轴，双侧長廊相连
  • 含元殿 — 三层金顶高台、龙凤丹墀龙尾道、翔鸾·栖凤双阙、12 御林军 + 8 朝臣
  • 宣政殿（新）— 重檐两层、9 柱前廊、8 紫绯朝臣 + 4 甲士
  • 紫宸殿（新）— 单层精巧高翘飞檐、4 近臣 + 仕女琴师、后花园松柏假山
• 大雁塔（慈恩寺塔）— 7 层方塔、攒尖砖石、四面拱窗、金顶刹
• 朱雀门城楼 — 三门道、九五至尊八十一钉、重檐两层、龙凤双旗
• 曲江池 — 22×18 大水面、中央水亭、2 艘画舫、垂柳成行
• 东市/西市 — 双市制、围墙·市门牌坊·8 摊位·胡姬舞台
• 灞河 / 渭水 — 贯穿南北 + 东西的双河系统、跨河石拱桥
• 筒车 / 曲辕犁 — 唐代标志性农具
• 朱雀大街坊灯 — 28 盏路灯，夜间发光

• 文士 / 农夫 / 商人 / 西域胡商 / 仕女 / 进贤冠学者 / 童子 / 兵卒 / 突厥
• 胡姬胡旋舞（4 人围圈旋转，袖飞带飘）
• 弯腰插秧农夫（4 人，pose=bend / squat / kneel）
• 朱雀大街 22 名行人（宵禁时隐去）+ 3 队官吏马队
• 含元殿御林军 12 + 紫绯朝臣 8 + 宣政殿朝臣 8 + 紫宸殿近臣 4
• 朱雀门下 6 名出入旅人 + 城上 4 名甲士 + 门外 3 骑迎送
• 慈恩寺塔前 8 名香客/僧侣 + 曲江池 8 名游赏人

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 · 街禁闭坊"徽章

切换在左下角"晴雨沙雾"按钮（季节按钮上方）。

顶部时间轴按钮（⏱）打开年代切换，自动调整 NPC 分布 + 环境光 + 烽火状态，并弹出 8 秒历史信息横幅。

• 217 个 NPC 全部可点击（屏幕半径 32 像素匹配）
• 8 类身份各 4-6 句市井段子：
  • 里坊百姓 / 市井商贾 / 深闺仕女 / 士林文士 / 军中兵卒 / 孩童 / 西域胡商 / 北蕃突厥
• 点击弹出气泡（角色标签 + 段子），4.2 秒自动淡出

例：

军中·兵卒  "边塞月明夜，闻笛能让壮士落泪。"
市井·商贾  "西州瓜，安息香，要不要看看？三十文一斤。"
深闺·仕女  "今春流行高髻簪花，鬓边再贴个红色花钿。"

• 寺钟（早朝 6:00 / 午时 12:00 / 暮鼓 18:00）— 三泛音合成
• 关坊鼓（22:00）— 低音 + 噪声击打
• 鸡鸣（5:00）— 锯齿波频扫
• 切换场景轻铃 + 持续环境底音
• 顶部喇叭按钮可一键静音
• 弓射 mini-game 中击中靶心马蹄音

顶部"诗"按钮开启诗心模式，9 个场景各配一首唐诗：

• 朱雀大街 ·《长安古意》卢照邻
• 大明宫 ·《和贾舍人早朝大明宫之作》王维
• 大雁塔 ·《与高适薛据登慈恩寺浮图》岑参
• 曲江池 ·《丽人行》杜甫
• 东市 ·《长安道》储光羲
• 田畴 ·《观刈麦》白居易
• 朱雀门 ·《和贾至舍人早朝大明宫》杜甫
• 边塞 ·《从军行》王昌龄
• 驼商 ·《凉州词》王翰

诗签为羊皮纸色衬线竖排，浮于右上。

• ≤ 900px 自动切换：侧栏改为汉堡抽屉
• 顶部·底部 HUD 缩小重排，场景按钮横排
• OrbitControls 内置双指捏合缩放
• 切换场景自动收起侧栏

顶部 ⊕ 按钮打开 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 小时手动控制 / 切换自动模式

• 顶部 🎮 按钮：弹出 4 角色选择卡（士子 / 商贾 / 仕女 / 游侠）
• WASD 第三人称漫游，相机平滑跟随
• 主角头顶金色光环 + 箭头标识
• 走近 NPC → E 提示 → 弹出对话框（含背景、连续 3-5 行剧本）
• 5 步主线任务《初到长安》
• 触发雁塔 mini-game 联动（题名后任务推进）
• 8 类身份化 NPC 段子（兵卒/官员/商贾/学子/儒生/百姓/胡商/僧侣）
• 任务面板 + Toast 通知 + 控制提示常驻
• Esc 退出回到上帝视角

• 游戏中按 V 切换第三/第一人称
• 点击画布锁定鼠标（PointerLockControls）→ 鼠标看 / WASD 走 / Shift 疾走
• 头部位置 (y=1.6) + 走路微晃
• Esc 释放鼠标，再按 V 切回 TPS

• 5 座展厅：含元殿 / 宣政殿 / 紫宸殿 / 大雁塔 / 曲江亭
• 走到殿门 8 单位内 → 屏幕显示 F 入 XX 看壁画
• 进入展厅 = FPS + 球形房间 + 4-8 面墙挂壁画 + 中央木匾牌
• 看向壁画 (≥ 0.85 朝向 dot) → 底部弹出 标题 + 注释卡
• 程序化壁画：暖色底 + 描金边 + 题字 + 注解，每幅独立色调
• 支持真实素材：丢图到 murals/，自动替换占位
• F / Esc 礼出展厅

• 雨天每 6-20 秒概率闪电：屏幕白闪 220ms + 0.8-3s 后 低频雷鸣（Web Audio 合成）
• 雨：风向 (-0.6, 0.3) → 雨条整体 -7° 斜倾
• 沙：风向 (1.4, 0.15) 强度 3.0 → 阵风调制（gust = 1+0.5sin）
• 雾：风弱，几乎静止
• 晴：微风从东吹

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 查询

• Mode 1 区分：把现有漫游变成"5 主题策展导览"（自动相机巡线 + 字幕 + 解说音）
• 价格浮动：早市 / 午市 / 晚市差价，跨市套利
• NPC 雇佣 / 短工：上午帮工 → 下午结算 → 给铜钱
• 科举系统：以一次性诗会大测验解锁"进士印"凭证
• 接入名家 NPC：李白 / 杜甫 / 王维，各开诗仙赞解锁支线
• 安史之乱触发 cutscene：财产损失判定 + 选阵营
• 着装影响 NPC 称呼：着青衫 → 文士叫你"君"；着乌纱 → 商贾叫你"大人"

• 酒令系统：曲水流觞中真的实现行酒令 (击鼓传花 / 五色筹 / 雅令俗令分级)
• 诗词填空：给一句缺 1-2 字的名句，玩家从 4 字中补出（更高级别）
• 诗仙赞累积：累计获得 3 张诗仙赞墨色腰牌 → 解锁李白 NPC 邀你登黄鹤楼
• 更大诗库：扩到 50 副对联 + 16 个飞花令关键字（添风/雨/夜/星/泪/愁/梦/酒等）
• NPC 出题难度：根据 NPC 角色生成不同难度（文士出冷门，童子出热门）

• 更多街头游戏：投壶 / 双陆 / 蹴鞠 / 围棋开局猜白先黑先
• 赏品装备化：腰牌 / 锦帕 → 解锁特殊对话或区域
• NPC 个性表情：胜场加倍兴奋、败场摆鬼脸的连续表情动画
• 连胜奖品爆发：连续 3 胜后概率掉落"东海明珠"等顶级藏品

1. 真实壁画素材 — 用户提供图片后接入 5 座展厅
2. 多支线任务 — 加"长安八景巡礼""坊间公案"等支线
3. 战斗系统 — 边塞场景接入弓射 mini-game 作为简易战斗
4. 多人物联动剧情 — 主角间互动
5. 物品栏 / 装备 — 拾取笔墨纸砚、腰牌、钱袋
6. 更多殿宇展厅 — 麟德殿 / 太极殿 / 兴庆宫
7. 天气过渡动画 — 切天气时雾参数渐变
8. 历史事件 cutscene — 安史之乱触发后烽火台炸开
9. VR / WebXR — 头显沉浸式漫游
10. 多人联机 — WebSocket 同步漫游
11. 碰撞检测 — 让主角不能穿墙穿建筑
12. 环境音 — 不同坊里的环境声（市集喧哗 / 寺院钟鸣 / 边塞马蹄）

静态站点可托管在 GitHub Pages（含 CI 自动发布）。步骤见 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
• 营造法式 / 唐两京城坊考 / 大唐六典 / 资治通鉴 — 历史参考
• 《全唐诗》 — 诗歌素材