echo-nexus/docs/07-星潮事件系统-v0.3.md

回响星核 v0.3 — 星潮事件系统（周期性全局玩法修饰）

版本：v0.3
日期：2026-06-23
范围：6 种星潮事件、周期触发、全屏视觉叠层、程序化音效、寂静期补偿机制

---

一、设计动机

回应 Gitea Issue #1「就一直连连看？」的玩法单一反馈。星潮事件为放置循环注入动态变化：深空中偶发的「星潮」会短暂改变物理法则，让玩家在 75 秒内体验产能翻倍、解码加成、探险增强等不同玩法侧重，打破单调感。

二、6 种星潮事件

类型	名称	效果	色调	性质
crystal	晶体潮	采矿产能 ×2	翠绿	正面
resonance	谐振风暴	解码奖励 ×1.6	玫红	正面
ruins	遗迹共振	探险力 +5、生命 +30	琥珀	正面
void	虚空低语	洞见获取 ×2	紫红	正面
core	星核悸动	接触率 ×3、脉冲威力 ×2	青色	正面
silence	寂静期	产能 ×0.5；结束时按时长补偿洞见	灰蓝	负面（有补偿）

三、触发机制

• 首次星潮：游戏开始 30 秒后触发（TIDE_CONFIG.firstDelay）
• 常规间隙：星潮结束后 40 秒触发下一次（TIDE_CONFIG.gap）
• 持续时间：75 秒（TIDE_CONFIG.duration）
• 权重抽取：6 种事件按权重随机（正面事件权重高，寂静期权重最低 10%）
• 飞升重置：飞升后清空当前星潮，重置计时，30 秒后重新开始

四、修饰器应用层

修饰器	应用点
crystalsPerSecMult	tick() 即时乘（显示基础值，实际翻倍积累）
pulsePowerMult	pulse() 即时乘
decodeRewardMult	clickNode() / autoDecodeTick() 结算时乘
insightMultAdd	进 recomputeStats 缓存（星潮起止时重算）
contactRateMult	进 recomputeStats 缓存
expeditionPowerBonus / hpBonus	startExpedition() 即时加
silenceInsightPerSec	星潮结束时 computeSilenceCompensation 结算

五、UI 表现

顶部指示器（StarTideIndicator）

• 活跃时在 header 右侧显示彩色芯片：图标 + 名称 + 倒计时秒数
• 芯片背景为对应色半透明，带光晕，进度条随时间推进

全屏背景叠层（StarTideOverlay）

• 顶部 + 底部对应色渐变色带
• 边缘 inset box-shadow 呼吸光效（3 秒周期）
• 活跃时整页笼罩对应色调氛围

通知（StarTideNotifier）

• 星潮降临时 Toast + tideStart 音效（神秘扫频）
• 星潮结束时 Toast + tideEnd 音效（柔和消退）
• 寂静期结束时显示「虚空回赠 N 洞见」+ techBuy 音效

Footer 联动

• 活跃时 footer 提示文字变为「✺ 星潮「晶体潮」进行中 · 深空晶体涌动…」
• footer 边框点亮对应色光晕

六、程序化音效

新增 2 种音效（audio.ts）：

• tideStart：330→660Hz 正弦扫频 + 440→880Hz 三角波 + 523/784Hz 长音（神秘降临感）
• tideEnd：659→523→392Hz 下行三音（柔和消退）

七、状态与兼容

• GameState 新增 activeTide: StarTide | null、lastTideEnd: number
• 旧存档兼容：init() 补全字段为 null/0
• partialize 排除运行时队列 _tideEvents
• performPrestige 重置星潮（清空 activeTide，lastTideEnd 设为 now）

八、QA 验证

agent-browser 自动化

• ✅ 强制触发星潮：lastTideEnd=0 → 重载 → 30s 内自动触发，状态显示 activeTide: crystal
• ✅ 顶部指示器渲染：「✺ 晶体潮 64s」绿色芯片
• ✅ 背景叠层：VLM 确认绿色调背景光晕 + 顶部/底部色带 + 边缘呼吸光
• ✅ 寂静期补偿：设置 type=silence, endsAt=now+3s → 等待结束 → insights 从 50 增至 81（补偿 30）
• ✅ Footer 联动：活跃时显示「✺ 星潮「晶体潮」进行中 · 深空晶体涌动…」
• ✅ 版本号 v0.3 显示
• ✅ lint 零错误，HTTP 200，无运行时错误

VLM 视觉确认

• 指示器芯片：绿色文字「晶体潮 11s」
• 背景光晕：深绿色，顶部/底部色带 + 边缘呼吸光
• 视觉完成度：界面清晰、风格统一、细节良好

九、文件变更清单

新增：

• src/lib/game/starTide.ts — 星潮定义、修饰器、触发逻辑
• src/components/game/StarTide.tsx — 指示器 + 叠层 + 通知三组件

修改：

• src/lib/game/types.ts — GameState 新增 activeTide / lastTideEnd
• src/lib/game/config.ts — INITIAL_STATE 新增潮汐字段
• src/lib/game/engine.ts — recomputeStats 应用 insightMultAdd/contactRateMult；performPrestige/createInitialState 处理潮汐
• src/lib/game/audio.ts — 新增 tideStart / tideEnd 音效
• src/store/gameStore.ts — tickTide / consumeTideEvents；tick/pulse/clickNode/autoDecodeTick/startExpedition 应用修饰器；init/hardReset/partialize 兼容
• src/hooks/useGameLoop.ts — 主循环调用 tickTide，可见性恢复补检测
• src/app/page.tsx — 接入 StarTideOverlay/Indicator/Notifier；Footer 联动；版本号 v0.3

十、下一步规划

• v0.3 已完成客户端星潮（原计划 socket 全局事件，现以单机版先行，后续可扩展为多人同步）
• v0.4：云存档 + 排行榜
• v0.5：全 5 纪元叙事扩展
• 持续关注 Gitea 工单