黄石公园宏观生态互动科学玩具。当前交付边界是 伪 3D 旋转地球开场 → 黄石公园 2D 动画风景 → 三项决策 → Day 100 结局。主线《拉马谷的最后 100 天》让玩家以自然资源调配专员身份，在暴风雪、野火和春季评估之间完成一轮约三分钟的观察。
本作品为简化互动科学玩具，不代表真实黄石生态预测。
推送到 main 后，GitHub Actions 会自动完成检查、构建并发布到 GitHub Pages：
https://wattson-law.github.io/eartch_simulation/
工作流文件为 .github/workflows/deploy-pages.yml。首次启用时，在仓库的 Settings → Pages → Build and deployment 将来源设为 GitHub Actions；之后每次 main 更新都会自动部署。
环境要求：Node.js 22.12+（也支持 20.19+ 的 20.x 分支）；本次验证使用 Node.js 22.18.0。
npm ci
npm run dev浏览器打开终端提示的本地地址（通常为 http://localhost:5173/eartch_simulation/）。
生产构建：
npm run build
npm run preview默认页面是面向展示的单主舞台：小地球、黄石分层场景、灰狼/美洲赤鹿/野兔三位代表个体、巡护电台、三项一次性决策和种群证据面板。聊天侧栏、开放式中文指令和因果级联弹层保留在代码库中供后续实验，但不再进入默认演示路径。
维护时优先修改 public/assets/ecosystem-v1/ 的素材和 src/sim/campaign.ts 的故事文案；不要为展示新增渲染引擎、后端或运行时模型接口。
- Vite 8 + React 19 + TypeScript 6 单页应用，实际版本以
package-lock.json为准 - Canvas 2D：地球入口与黄石分层 2D 场景；地球把绘本世界地图连续投影到球面，呈现伪 3D 自转
- Sprite Sheet / 序列帧 +
requestAnimationFrame：Canvas 只播放三位代表个体的确定性视觉状态切片；CSS 负责界面过渡 - SVG：种群数量曲线（无第三方图表库）
- 纯规则中文 NLP 仍保留为实验模块（无后端、无 LLM API、无 Three.js），默认展示不开放自由输入
- 解耦的时间步：
src/sim/tick.ts只更新宏观 JSON 状态，src/sim/visualSlice.ts只把状态切成待机、坐卧、缓慢游走和事件姿态；视觉层不会回写种群。 - Oxlint 静态检查，
npm run build执行 TypeScript 检查与 Vite 构建
- 确认的方向：地球作为伪 3D 自转入口，主体验为可动画化的黄石 2D 风景。沿用现有技术栈，无需真实 3D 地球、3D 地形或自由相机。
- 已接入素材包：
public/assets/ecosystem-v1/提供 48 帧地球图集、灰狼/美洲赤鹿/野兔的待机/移动/特殊动作、2048×1152 黄石天空/山体/草甸/森林/河流/前景图层，以及水面 mask 和树木、灌木、石头、花草、芦苇、云等 props。 - 已完成渲染：地球入口用绘本世界地图做连续 Canvas 2D 球面投影，外围由深空底色、青紫星云、柔和银河带和远中近三层星群构成，并叠加大气辉光与轨道线。黄石场景以拉马谷的雪山、鼠尾草草甸、针叶林、蜿蜒河流和前景岸线分层合成；山体和森林图层保留深度拼接，河流使用跨全景连续曲线，避免镜像接缝反向。水面鱼群、植物轻摆、云漂移、动物动作和季节/天气状态连续变化。缺失素材仍有程序绘制回退；原地球图集保留在素材验收页。
- 可交互的小地球：鼠标或手指左右拖动旋转，松手后惯性减速；支持暂停自转、定位黄石、点击地理标记或按钮进入。方向键旋转，空格切换自转，Home 定位，Enter 进入。黄石标记与地图使用同一投影，转到背面时隐藏；系统减少动态偏好默认关闭自转。星群使用确定性分布，随时间轻微闪烁和漂移，并按地球经度产生分层视差；暂停会同时冻结地球和宇宙背景。
- 已提供验收页：打开
http://localhost:5173/eartch_simulation/?view=assets可逐项预览地球、动物动作和分层背景，并暂停、调 FPS、逐帧或关闭图层。 - 手机与桌面观察：场景是约 2.4 个视口宽的横向全景，可用鼠标、触控、滚轮、方向键、Home / End 左右浏览；动物按视口宽度缩放并显示代表个体。捕食记录位于场景下方，不遮挡风景或统计。工具栏支持暂停 / 继续观察，停止时间推进与动物、环境动画。
- 叙事观察线：画面只跟随灰狼、美洲赤鹿、野兔各一位代表个体，宏观数量仍记录整个拉马谷。五个昼夜节点（清晨、上午、中午、傍晚、夜间）组成一条轻量巡护故事线；潜行、追逐、倒地和脱险会临时接管故事卡，事件结束后回到安静的日常。重复捕食记录在访客简报中合并，保留转折而不制造信息噪声。
- 《拉马谷的最后 100 天》：故事从 Day 1 开始，Day 30 固定触发暴风雪，Day 60 固定触发雷击野火，Day 100 生成绿色奇迹、谨慎的复苏、荒漠化的代价或狼群过量的回声。投喂草料、引入狼群、人工隔离均为一次性受限命令；故事状态只组织观察顺序，不直接改写宏观种群。
- 可持续观察窗口：生态时钟只在黄石场景可见且页面处于前台时推进；默认食物链参数按数分钟的连续观察校准，季节、降雨和野火仍会改变种群曲线，切到后台或停留在小地球入口不会悄悄消耗种群。
- 自然活动与捕食：
visualSlice.ts为每个可见物种只保留一个代表个体，沿短距离安全观察线缓慢换位；大部分时间停留在呼吸、觅食、饮水、坐卧、藏匿和探出等原地姿态，只有事件阶段短暂切换为潜行/追逐姿态。画面不运行逐只寻路、避障、碰撞或捕食物理，狼和猎物不会在河面上追撞。宏观捕食压力仍由确定性模型计算；视觉事件只读取已发生的lastPredation，按潜行 → 追逐 → 倒地/进食 → 脱险切片表现，动画结束不再次扣减种群。 - 动作与遮挡细化：9 组移动和特殊动作由 8 张原始姿态补为 32 帧，保留周期和落脚锚点；相邻帧补间、减速、固定观察线上的平滑转向、朝向交叉淡化、呼吸和起伏共同避免僵硬翻面。动物在预设草丛观察点使用遮挡渐变显露，捕食后不会在空地突然淡入。
- 天空与水中生命：静态天空移除了原先烘焙的云，3 层云独立飘动并在画外循环；暖色太阳带有柔和光晕和水面反光。鱼沿水域内的路线游动、转向、摆尾和摆鳍，受水面遮罩约束；它们是视觉代表，不新增种群方程。
- 仍可迭代：当前包是第一版统一视觉基调；后续可以按用户确认的画风继续替换单个物种或动作，不改变模拟器与资源 manifest 契约。故事层暂不接入 LLM，也不把简化模型包装成真实 Yellowstone 预测。
- 数据约束：动画只读取模拟状态和事件，不能直接改变种群；展示按钮只调用受限命令；Gemini 用于离线素材制作，不参与运行时数值计算。
完整决策见 PROJECT.md，下一轮画风、动画和素材约定见 docs/VISUAL_BRIEF.md。
运行 npm test 验证帧采样、翻转锚点、旧版几何边界、视觉切片的三位代表个体/暂停/30–60fps 一致性/河流安全/分阶段捕食、云循环、游鱼路线、补间素材的周期约束，以及地球投影、地图采样、经度接缝和三层星群视差。修改动画后同时运行 npm run build 和 npm run lint。
原始画稿保留在素材包内。使用已安装的 Python、Pillow、NumPy 和 OpenCV 运行 python scripts/build-smooth-sprites.py 可重新生成补间动作；python scripts/build-clear-sky.py 重建移除静止云朵的天空。这些工具只用于离线素材处理，网页运行时没有新增依赖。补间来自原始绘本姿态的局部变形，不是重新生成的逐帧动画。
- 物种仅含：草、灌木、兔子、麋鹿、狼。
- 食物链：植物 → 兔子/麋鹿 → 狼。
- 离散时间步；季节影响温度/降雨/植物生长；火灾暂时减少植被。
- 不做年龄结构、迁移、疾病或逐个个体的生态数值结算；画面中的确定性行为状态机只用于三位代表动物的展示，不参与模型计算。
- 数值有上下界夹紧，保证非负与可演示稳定性。
- 因果级联面板与水狸/河岸故事为叙事层，不新增水狸种群方程。
- 展示页的「黄石巡护员 · Ranger Lin」只用第一人称野外简报解释模拟器已经执行的结果；自由聊天属于后续实验入口。
- 所有种群与环境数值变化只发生在确定性
tick/applyCommand中。 - 事件日志为「自然野外考察简报」风格；内部仍保留
source字段。 - 离谱指令统一中文拒绝，绝不静默忽略。
- 情景注入：暴风雪提前、雷击野火、游客投喂冲突
- 环境：下雨、下雨三周、发生火灾、更冷、升温
- 物种：增加十只狼、减少五只兔子
- 时间：快进到冬天、暂停、继续、快进 8 步
- 观察：现在谁最多、为什么兔子变少了、状态
「增加十只狼」或「雷击野火」会打开 连锁影响 故事面板（狼群回归 → 植被/河岸 → 水狸与河流；或野火三段叙事）。阶段随后续 tick 解锁，数字仍只走模拟器。
- 自研宏观生态状态机：
EcosystemState+ 纯函数tick/applyCommand，可复现。 - 规则中文指令协议：
src/nlp/parse.ts关键词/模板 → 结构化事件 + 统一拒绝话术。 - 可复现事件日志：每条记录来源字段，UI 与聊天解释均基于日志/状态。
- 叙事因果级联：
src/sim/cascade.ts故事队列，与种群结算解耦。 - 个体悬停名片：名片跟随场景内移动的动物，显示当前行为。
- 野外观察动画：同款绘本图集组成三位代表个体的缓慢巡游与分阶段事件；纯视觉状态切片读取模拟捕食结果，不改数值。
- 素材致谢：第三方 CC0 资源清单见
public/assets/CREDITS.md。
src/
sim/ 宏观状态、边界、tick、命令、因果级联、视觉状态切片
nlp/ 中文规则解析与巡护员话术（实验入口）
ui/ 地球、生态区、巡护故事线、曲线、简报、捕食动画；聊天和级联面板为实验组件
App.tsx 单页装配
public/assets/ecosystem-v1/
manifest.json 地球、动物、图层和 props 的统一资源契约
earth/ 48 帧伪 3D 地球图集
animals/ 原始 8 帧姿态与待机图集
animals-smooth/ 32 帧补间动作图集
layers/ 天空、山体、草甸、森林、河流、前景与水面 mask
props/ 树木、灌木、石头、花草、芦苇和云
本作品为简化互动科学玩具，不代表真实黄石生态预测。
备用美术素材来自 CC0 资源，详见 public/assets/CREDITS.md（Kenney Planets、Pixel Earth Animation、ScratchIO Animated Wild Animals、Kenney Foliage Pack / Foliage Sprites）。生成的绘本素材另见 public/assets/ecosystem-v1/manifest.json 中的来源记录，不继承备用素材的 CC0 声明。