# 礼物菜单组件

`gift_menu`
是每个账户自动拥有且不可删除的单例组件。它把直播间礼物或大航海投喂映射为主播提供的内容说明，并以独立只读 token 输出透明 OBS 浏览器源。

## 目录与触发器

账户直播监听器调用 Bilibili `giftPanel/roomGiftList`
并定时刷新按账户隔离的内存目录；控制台读取同一份缓存，也可以主动刷新。接口无需 Cookie，返回礼物 ID、名称、价格、静态图和 GIF。字段说明见
[礼物 API 文档](https://github.com/pskdje/bilibili-API-collect/blob/main/docs/live/gift.md)。上游失败时保留最后一次成功目录。

菜单项按顺序保存在经过后端校验的组件 settings 中，最多 100 项，支持：

- 指定礼物 ID；事件缺少 ID 时以保存的名称降级匹配；
- 舰长、提督或总督；
- 指定礼物单价，单位为电池，例如 `150`。

礼物事件先匹配指定礼物 ID（事件缺少 ID 时匹配名称）；命中后只高亮具体礼物。如果没有具体礼物命中，才按单价电池数回退匹配。组件只消费
`live.gift`，不消费连击更新，避免重复触发。Bilibili 接口中的 `price` 是金瓜子而不是电池；后端统一按
`price / 100` 换算（例如 `100` 金瓜子为 `1` 电池）。盲盒事件优先使用 `blind_gift.original_*`
的盲盒 ID、名称与原价，不使用开出的奖品价值。对于 protobuf
`SEND_GIFT_V2`，后端复用同一礼物管线，并优先使用非零 `discount_price`
作为实际支付单价；`transaction_id` 用作稳定事件 ID。当前 V2
schema 没有提供盲盒原始 ID/名称，因此这类事件可以按实际电池价值回退匹配，但不能保证命中具体盲盒条目。

## OBS 行为

每行横向展示图标、触发条件与主播自定义说明。行数、行高、中文字体、文字亮度、文字比例、滚动速度、高亮时长和动效强度均可调整。仅当内容超过实际视口高度时滚动；渲染器复制三组菜单并在等价位置间无缝归一化，实现最后一行之后紧接第一行。

命中时浏览器选择距离当前滚动位置最近的匹配副本，将它平滑对齐到视口第一行、暂停自动滚动并播放流金渐变与星花粒子。触发用户名称作为整行前景居中显示，覆盖原礼物图标和说明，并允许长名称换行。滚动器保留亚像素余量，低速设置也保持线性。低性能模式和系统减少动态效果偏好会关闭装饰粒子。舰长、提督和总督使用随前端打包的透明图标。

`jade-banquet`
复用仓库内已有且记录许可的花枝 SVG。`moonlit-water`（“静夜曲水”）提供另一种完全透明的排版：行项目没有卡片底色或外框，只以青黛、米金文字和细金线区分，触发时以水纹扫光高亮。新增主题必须在
`giftMenuThemes.ts` 注册稳定 ID、资源键和局部 CSS 变量。