lxc-streamutils/docs/components/gift-effect.md

全屏礼物特效组件

gift_effect 是每个账户自动拥有且不可删除的单例组件。它消费账户级直播源中的 live.gift 和 live.guard.buy，使用独立只读 token 作为透明 OBS 浏览器源；不订阅 live.gift.combo，避免一次连击重复触发完整特效。

展示行为

jade-starfall 主题中，普通礼物从视口左侧生成一组带青玉、金色星尘拖尾的流星，礼物图片或 GIF 是流星主体，并从右侧完全飞出。原始价值按 highValueThreshold 和 featuredValueThreshold 分为普通、高价、特别高价三档，每档分别设置流星数量、基准尺寸和飞行速度。图片加载失败时使用内置星光图形，不依赖外部主题素材。

舰长、提督或总督使用同一个 live.guard.buy 路径，临时显示不透明星河、闪耀粒子、身份和用户昵称。多个普通礼物可并发；大航海展示选择最新事件。

moonlit-water（“静夜曲水”）则采用“月下清供”：价值低于 50 元（原始 totalPrice < 50000）的礼物以右侧水纹短笺展示图标、用户、名称和价格；50 元及以上礼物在整张浏览器源上展开月轮、水纹、礼物图标和文字。舰长、提督、总督也使用全屏月夜祝贺。该主题的全屏动效仍不绘制不透明底色，OBS 场景始终可见。

尺寸与性能

OBS 建议从 1920×1080 开始，但渲染器没有固定画布。ResizeObserver 按浏览器源实际宽高缩放流星，宽屏、竖屏或自定义分辨率都保持全视口透明。控制台可调整：

• 三档数量、尺寸和速度；
• 拖尾强度和最大并发特效数；
• 大航海星数和全屏持续时间；
• 中文字体与文字亮度；
• 低性能模式（限制粒子和流星数量）。

扩展主题

后端设置的 themeId 使用稳定 kebab-case ID。前端主题统一在 apps/overlay/src/giftThemes.ts 注册颜色、动效标识和本地化资源键；主题 CSS 只作用于 .gift-effect-overlay，不得改变页面根背景或控制台。新增主题时同时扩展 Rust/TypeScript 类型、设置迁移、两种语言资源和降级测试。