# 全屏礼物特效组件

`gift_effect`
在账户注册时创建一个初始实例，并允许为不同 OBS 场景添加多个独立样式实例。每个实例只消费账户级直播源中的
`live.gift`，使用自己的只读 token 作为透明 OBS 浏览器源；不订阅 `live.guard.buy` 或
`live.gift.combo`。大航海事件由独立的 [`guard_effect`](guard-effect.md) 组件处理。

## 展示行为

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

实时礼物进入浏览器内存中的有界 FIFO。画布始终只播放队首的一笔礼物，当前流星组、短笺或月下清供动画结束后才取出下一笔，因此密集投喂不会叠加特效或同时放大粒子负载。队列按事件到达顺序排列并去重，容量可在控制台设置；达到上限时保留正在播放及已等待的事件，忽略新到达事件。该视觉队列不写入数据库，OBS 断线重连后只接收新事件。

`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 类型、设置迁移、两种语言资源和降级测试。