幸运转盘 SPgacha

一句话：玩家用一张「抽奖券」转动八格转盘，格子逐格点亮、越跑越慢、最后停在中奖那一格，奖品直接进背包，全服都看得到谁抽到了什么。
八个格子放什么、各自多少概率、券怎么来、稀有奖要不要全服播报 —— 全部写在配置文件里，服主不用改一行代码。

适合谁：想给玩家一个「每天有点念想」的服的服主 —— PVE 服、长期服、活动服、带商城的服。
为什么有用：抽奖是最好做、也最容易做砸的一类玩法。做砸通常是三件事没做到：概率看不见、过程没感觉、抽完没人围观。这个插件把三件事都补上了：转盘一圈一圈亮给你看，稀有奖全服横幅 2 秒，中奖记录全服可见且实时刷新。
技术底子：单文件 C#（Oxide / uMod），自绘 CUI 面板，无数据库、无外部依赖（只用 ImageLibrary 做贴图服务），重启不掉档，热重载不丢玩家数据，客户端不需要装任何东西。

一、它到底做了什么

八格转盘	一格 45°，八格放八种奖励；每格显示该奖励自己的图标，抽中哪格就停在哪格
逐格点亮代替旋转	不是整盘转 —— 是灯在格子上跑：起步快、中段稳、最后减速，17 格走完约 2.2 秒停在中奖格
全服中奖记录	面板里显示最近 3 条，谁都看得见「谁抽中了什么」；稀有奖励固定置顶，不会被普通奖刷下去；落盘保留最近 40 条
稀有全服广播	抽到标记为「稀有」的奖励，屏幕上方弹出全服横幅 2 秒（同时发一条聊天公告，可关）
十连 + 保底	单抽 / 十连两个按钮；十连可设「必出一个稀有」；另有 N 抽必得稀有 的保底计数，面板底条实时显示进度
抽奖券	一张自定义外观的「券」物品，签到 / 材料兑换 / 打怪 / 开箱四条路都能来；券可以交易，服主不用发钱
状态实时刷新	抽完一张、兑换一张，面板上的券数和保底进度立刻变，不用关掉重开
防刷	同一个箱子只判一次概率（反复开关刷不出券）；抽奖期间连点会被拦；兑换有 1 秒冷却；玩家被打死自动收面板

二、玩家看到的界面

面板 520×696，贴在屏幕正中，四条视线从上到下：

最上面是标题与一句话状态：抽奖券 × 29　·　每 30 抽必得稀有 —— 玩家一打开就知道自己有几张券、离保底还差多少。

中间是转盘：金环包着八格彩色扇区，每格中间放这一格奖励的图标（宝石、券、废料、布卷、金属管都行）。中心是一个金色圆钮，顶部有一个金色指针指着「中奖就是这一格」。

转盘下面是记录卡：三行，每行「彩色头像 + 玩家名 + 抽中 + 奖品名 + 时间」。头像不需要下载任何图片 —— 用玩家名字首字生成彩色圆片，颜色按名字自动分配，永远不会撞图。稀有那几行会带金边并置顶。

最下面是两个按钮 + 一条底条：左边粉色「单抽」、右边金色「十连 ×10」；左下一个小的金色「兑券」按钮（用材料直接换券）；底条写当前规则摘要，比如 单抽 1 张券 · 十连 10 张 · 保底进度 0/30。

三、跑灯怎么跑（这是「有感觉」的关键）

真转盘在 CUI 里做不到 —— Rust 的界面元素没有旋转属性，硬换整图会闪卡（这条限制在第十三节写清楚）。所以走的是现实抽奖机的做法：灯在格子上跑，越跑越慢，最后停住。出厂节奏是 17 格：

阶段	每格停留	跑几格	做了什么
起步	60ms	5	快跑一段，让人看清八个格子都在哪
中段	100ms	5	第二圈，节奏明显下来，开始紧张
减速	160ms	4	一格一格挪，玩家开始喊「停这里」
收尾	250ms	3	最后三格，慢得让人憋气
定格	—	—	中奖格留住，响一声成功音，发奖 + 写记录

合计 5×60 + 5×100 + 4×160 + 3×250 = 2190ms，也就是约 2.2 秒走完 17 格（两圈多一点）。这个时长是调过的：低于 1.5 秒没感觉，超过 3 秒玩家会骂娘。配置文件里可以直接改（动画时长秒，允许 0.6~6，改完所有阶段按比例一起缩放）。

跑灯过程中会响 5 次「哒」的机械音（第 0 / 4 / 9 / 13 / 16 格各一次，越往后间隔越大），定格响一声成功音。音效是游戏内置 prefab，玩家听到的是自己客户端的声音，不占带宽也不占服务器 CPU。

四、消耗与保底（玩家最关心的一张表）

项目	默认值	说明
单抽	1 张券	跑一次灯，拿走一格
十连	10 张券	一次扣 10 张，十条结果一起结算；想给优惠就填 9
十连必出稀有	开启	十次里至少一次命中「稀有」档，防止十连白给
保底次数	30	累计 30 抽必得一个稀有；填 0 = 关闭保底（不要理解成「0 次必中」）
券的获取速率	服主自己定	签到 / 兑换 / 打怪 / 开箱四条路的数量全在配置里，见第六节

券不够时点按钮，面板会直接告诉你「还差几张」，不会静默失败。抽奖顺序是先判够不够 → 再扣券 → 再 roll 结果 → 最后发奖，不存在扣了券没出货；即使发奖环节出异常，抽奖锁也会释放，玩家不会卡在「正在抽奖」。

连点也拦了：动画没跑完再点，会提示「正在抽奖，等这次转完再点」，不会出现两套灯同时打、最后给两份奖的情况。

五、概率表（默认八格，可以全改）

概率不是百分比写死的，而是填权重，插件自己换算 —— 你想把某格从 34 改成 3，不用重算总百分比。下面是出厂默认（总权重 100.3，插件启动会把换算后的真实概率逐条打进服务器控制台，方便你核对）：

格	显示名	实际物品	数量	权重	折算概率	稀有
1	碎裂石 ×1	bone.fragments	1	34	33.90%	—
2	废料 ×500	scrap	500	24	23.93%	—
3	普通石 ×1	bone.fragments	1	20	19.94%	—
4	抽奖券 ×1	paper	1	12	11.96%	—
5	精制石 ×1	bone.fragments	1	6	5.98%	—
6	布 ×100	cloth	100	3	2.99%	—
7	至臻石 ×1	bone.fragments	1	1	1.00%	✓
8	金属管 ×10	metalpipe	10	0.3	0.30%	✓

这一格抽奖券（11.96%）是「抽到券」的回血设计 —— 平均八九抽能回一张，玩家不容易抽断。

八格是固定的（转盘几何和素材绑死了）。想要 6 种奖，不是删条目，而是把不要的两格权重改 0：权重 0 的格子永不中奖，也不会在盘上画图标。奖励池必须正好 8 项，多了截断、少了补空位占位格。

六、抽奖券从哪来（四条路，数值你自己定）

券是整套玩法的闸门：你给多少券，等于你定玩家多久能抽一次。四条路各自独立开关、数值全可配，出厂默认是「一天一张 + 打怪开箱偶尔掉」：

签到	每天首次醒来给 1 张；连签每多一天多给 1 张，最多加成 3 张。所以连签第 4 天起是 4 张/天。这是最稳的一条来源，也是让玩家「每天上线」的理由。
材料兑换	默认 100 废料 = 1 张券，点左下角「兑券」立刻到账。你可以换成任何物品、任何数量，也可以配多条（比如废料 100、布 50、金属管 10 各换 1 张）。这条给了 PVE 玩家一条「废料有用」的去处。
打怪掉落	按击杀目标的 prefab 短名配概率：默认科学家 3%、熊 4%、狼 3%、野猪 2%，其它目标 0%（不触发）。想鼓励去哪打，就把那的气概率调高。
开箱	按箱子 prefab 配概率：默认普通箱 4%、精英箱 8%、布拉德利 20%、直升机箱 20%。同一个箱子只判一次，反复开关同一个箱子刷不出第二张。

券本体是 Rust 原版 paper（纸）换了个创意工坊外观：粉色票根 + 中央金球。皮肤 ID 3837765643，创意工坊搜这个 ID 就能订阅：
https://steamcommunity.com/sharedfiles/filedetails/?id=3837765643

关于图标：订阅了创意工坊的玩家看到粉票；没订阅的玩家看到原版白纸（不会报错、不会丢东西）。想让所有人都看到，就把这张 512×512 的图放到你服的创意工坊合集里，让玩家一键订阅。

七、服主怎么装（5 步，5 分钟）

1	确认服上装了 ImageLibrary（Oxide 官方插件，用来托管贴图）。没装的话先装，否则面板显示不出来。
2	把压缩包解压到服务器根目录。oxide/plugins/SPgacha.cs、oxide/config/SPgacha.json、oxide/data/SPgacha/icons/ 会自动归位。图标那 20 张 png 必须一起放进去。
3	在控制台执行 oxide.reload SPgacha，看到 [SPgacha] SPgacha 就绪：奖励 8 项，总权重 100.3，保底 30 抽，记录保留 40 条 就成了。紧接着会逐条打印每格的真实概率，顺手核对一下。
4	进游戏打 /spgacha 打开面板。第一眼先确认「素材注入 20/20 张」，少于 20 说明 icons 没放全。
5	给自己发几张券试抽：spgacha.give 你的名字 10，然后 spgacha.test 你的名字 10，看跑灯、发奖、记录、广播是否正常。试完把发的物品丢掉就行。

热更新不用重启服：改完配置执行 spgacha.reload 即可（它会重读配置并重算概率）。换图标素材也是 reload 生效，手工拷 png 不 reload 的话客户端会继续显示旧图。

八、配置文件怎么改（全表）

所有键名都是中文，路径 oxide/config/SPgacha.json。改完 spgacha.reload，不用重启服。下面按分组列全，每一个键都能改，没有任何一项写死在代码里（除了第十三节说的形态类限制）。

1. 通用

启用插件	true	总开关。关掉后命令、面板、以及券来源（签到/兑换/打怪/开箱）全部停，不会有人偷偷攒券
需要 spgacha.use 权限	false	false = 全服谁都能抽；true = 只有管理员和被授权的玩家能抽，未授权玩家连券都不会掉
音效开关	true	跑灯的「哒」与定格成功音

2. 抽奖

单抽消耗券	1	单抽扣几张券
十连消耗券	10	十连扣几张。填 9 就是「十连打九折」，最常见的促销手法
保底次数（0=关闭）	30	累计多少抽必得一个「稀有」。填 0 是关闭保底
十连必出一个稀有	true	十连里至少一次命中稀有档
动画时长秒	2.1	跑灯总时长，自动夹在 0.6~6 之间。1.5~2.5 手感最好

3. 抽奖券

载体物品短名	paper	券用哪个游戏物品承载。换成 scrap 之类也行，但请确保它在你服不稀缺
显示名称	抽奖券	背包里显示的名字
皮肤ID（用于识别，别和别的物品撞）	3837765643	券粉票外观的创意工坊 ID。同时是插件识别「这张纸是券不是我服别的纸」的唯一依据，改它之前先确认新 ID 在你服没有别的插件在用
背包描述	在幸运转盘里抽奖用，可交易	生成堆叠时写入的说明文字（见第十三节的限制）

4. 券来源

签到.启用	true	每天首次醒来发券
签到.每天给几张	1	基础值
签到.连签加成	1	每多连签一天，额外多给几张
签到.连签加成上限	3	加成最多加几张，防止签到奖励滚太大
兑换.启用	true	左下角「兑券」按钮是否可用
兑换.每次兑换给几张券	1	一次兑换到账的券数
兑换.消耗材料	scrap ×100	列表，可配多条（物品短名 + 数量）。缺任意一条兑换不成立
打怪掉落.启用	true	击杀是否可能掉券
打怪掉落.每次掉落几张	1	命中概率后掉几张
打怪掉落.按目标 prefab 短名配概率%	scientist 3 / bear 4 / wolf 3 / boar 2	列表，键是 prefab 短名，值是百分比
打怪掉落.默认概率%	0	没匹配到规则时用这个。默认 0 = 不触发，想「打什么都可能掉」就填个 0.5
宝箱.启用	true	开箱是否可能出券
宝箱.每次给几张	1	命中后给几张
宝箱.按箱子 prefab 短名配概率%	crate_normal 4 / crate_elite 8 / bradley_crate 20 / heli_crate 20	列表，格式同上。加一个新箱子只需加一条

5. 奖励池（8 项）

显示名	碎裂石 ×1	面板记录、聊天、广播里写的名字。建议带上数量
物品短名	bone.fragments	Rust 原版 shortname，如 scrap、cloth、metalpipe、lowgrade
数量	1	一次给几个
权重	34	相对概率。填 0 = 这格永不中奖
稀有（全服广播+置顶）	false	true 才会横幅广播、聊天公告、记录置顶，也才受保底保护
皮肤ID	0	0 = 用原版物品外观；填了你服已订阅的创意工坊 ID 才有自定义外观（出厂那几颗宝石是示例值）
自定义物品名	留空	留空用原版名；填了就给这个堆叠改名，背包里显示你填的字
扇区图标文件	gem0.png	转盘这一格画的图标，取 oxide/data/SPgacha/icons/ 里的文件名；留空 = 自动用游戏内该物品的图标
抽中提示语	留空	抽中时单独发给中奖者的一句话（如「至臻配方材料」），留空则用默认文案

奖励池必须正好 8 项。多于 8 项，插件只保留前 8 项；少于 8 项会自动补「（空位）」占位格 —— 占位格权重 0、永不中奖、盘上也不画图标，但你在面板上会看到那个格子是空的。想少几种奖，正确做法是把不要的那几格权重改 0，而不是删条目。

6. 记录

面板显示条数（面板只有 3 行位置，1~3）	3	面板里能看到几条。面板只有 3 行位置，填 1~3，填再大也只画 3 行
稀有置顶条数	5	稀有记录强制排在前几条，不被普通奖刷下去
内存保留条数	40	落盘保留多少条（1~500），重启后还在。40 条约 8KB，随便调

7. 广播

稀有横幅显示秒	2	全服顶部横幅停多久。3 秒以上会挡视线，2 秒刚好
同时发一条聊天全服公告	true	除横幅再发一条聊天消息。怕刷屏就关掉，只留横幅

九、命令表

命令	谁能用	作用
/spgacha	玩家	打开幸运转盘面板
/spgacha 兑	玩家	不用开面板，直接用材料换券
/spgacha 券	玩家	聊天栏回一句「你有几张券 / 离保底还差几次」
spgacha.give 玩家 数量	管理员	给某人发券（活动补偿、抽奖送券、直播奖励都用它）
spgacha.test 玩家 1|10	管理员	替某人跑一次单抽或十连（照常扣券、照常发奖、照常写记录），用来验收配置
spgacha.reload	管理员	重读配置并重算概率，不用重启服
oxide.reload SPgacha	管理员	整体重载（改了代码或换了 icons 里的图之后用这个，才会重新注入素材）

面板上的四个按钮（单抽 / 十连 / 兑券 / 关闭）走的是服务端命令 spgacha.spin / spgacha.ex / spgacha.close，玩家不用记，也不需要权限 —— 面板自己会带上身份，玩家在游戏里手动发这几条命令也不会额外拿到东西（权限和券数都会二次校验）。

十、权限与授权

默认是「全服都能抽」，不需要配任何权限——开箱即用，适合大多数服。

如果你想把抽奖做成会员特权 / 活动门槛，两步：

第一步，打开开关：配置文件 通用.需要 spgacha.use 权限 = true，然后 spgacha.reload。

第二步，给权限：

oxide.grant user 76561198000000000 spgacha.use	给单个玩家（SteamID64）
oxide.grant group vip spgacha.use	给整个用户组，组里的人自动继承（最省事的会员做法）
oxide.revoke user 76561198000000000 spgacha.use	收回权限
oxide.show user 76561198000000000	查这个人到底有哪些权限，排查「他为什么抽不了」用

打开权限门之后会同时生效三件事，这点很重要：

① 未授权的玩家打 /spgacha 会提示「你没有权限使用幸运转盘」，看不到面板；
② 就算他用 F1 控制台硬发 spgacha.spin，服务端也会拒——权限在扣券和发奖之前校验，绕不过去；
③ 签到、打怪、开箱三条券来源也同步停发，未授权玩家不会攒一堆用不掉的券占背包。兑换按钮同样不可用。

管理员永远不受权限限制（Oxide 的 admin 身份自带通行），所以你随时能 spgacha.test 验收。

十一、服主最常改的 6 件事（照着改就行）

① 想让抽奖更值钱 / 更稀有一点
把 抽奖.单抽消耗券 从 1 改成 2，玩家抽一次要攒两天签到。或者反过来，把券来源调松（签到.每天给几张 改成 2）让节奏加快。不要同时改两头，否则你自己也说不清玩家一天能抽几次。

② 想换掉奖励，但保留「宝石」那套视觉
只改 奖励池[n].物品短名 和 数量 即可，扇区图标文件 还能继续用现有的 gem0~3.png，玩家看到的盘面不变。显示名 一定要跟着改，否则记录里写的名字和实际物品对不上。

③ 想关掉保底（做成纯随机赌服）
抽奖.保底次数（0=关闭） 填 0，同时建议把 十连必出一个稀有 也设 false。注意：0 是关闭，不是「0 次必中」。关掉后玩家面板底条的保底进度不再显示。

④ 想做成 VIP 专属
见第十节，两步：开 需要 spgacha.use 权限 + oxide.grant group vip spgacha.use。这样做之后普通玩家连券都不会掉，所以如果你的服已经在跑「签到给券」，改之前先在群里说一声。

⑤ 想换券的图标或名字
名字改 抽奖券.显示名称。图标不能改 —— 它来自创意工坊皮肤（皮肤ID），换图标等于换一个创意工坊物品 ID，还要让玩家重新订阅。想换个颜色就自己上传工坊，把新 ID 填进 皮肤ID（填之前确认这个 ID 在你服没被别的插件占用，否则券会被别的插件误认）。

⑥ 想加一个新箱子 / 新怪物能掉券
在对应的列表里加一条就行，格式是「prefab 短名 + 概率%」。短名就是游戏里那个实体的 prefab 名（比如 crate_normal_2、scientist_gunner）。加完 spgacha.reload。调查概率不用改代码，也不用重启。

十二、性能：它到底占多少

先说结论：空闲时测不出开销，抽奖瞬间的开销落在 2.2 秒的动画里，且几乎全在客户端。下面是实测，不是估计。

测法：同一台 12 核 / 64GB 的测试服，不重启、不换世界，读 Rust 进程 /proc/<pid>/stat 的 utime+stime 算 CPU 秒，做「加载中 → 卸载 → 再加载」三段各 45 秒的交替采样，用加载段的均值减卸载段，得到插件自己的增量。

采样段	窗口	CPU 时间	单核占用
插件加载中（第 1 段）	45s	24.10s	53.6%
插件已卸载	45s	23.48s	52.2%
插件加载中（第 2 段）	45s	22.38s	49.7%
插件增量	45s	-0.24s	-0.53%

增量是负数 —— 不是插件「省了 CPU」，而是它自己的开销小于世界模拟本身的正常波动（同一服两段加载采样自己就差了 1.7 秒，约 ±4%）。45 秒的窗口下都测不出来，说明空闲态的开销低于这套方法的噪声地板，这就是我能给出的最硬的口径：单核 1% 以内 + 内存 2MB。折算到 12 核整机是 -0.04%，可以按 0 看待。

其它可核对的数：

Oxide 编译耗时	0.10s（oxide.plugins 里直接能看到）
常驻内存	2 MB
初始化耗时	load 时注入 20 张贴图 + 算 8 格概率，实测在 200ms 量级
抽奖瞬间	2.2 秒内共 17 次贴图更新，每次只 销毁并新建一个贴图元素，不重建面板
落盘	只在一次抽奖/兑换结束时各写一次，记录封顶 40 条（约 8KB）
定时器	只在抽奖的 2.2 秒内存在，跑完即销毁；平时没有任何常驻 tick

为什么它天生轻：Rust 的 CUI 是客户端渲染 —— 服务端做的是「拼一份界面描述，发给这个玩家的客户端」，画面由客户端画。所以面板再花哨，服务端付出的也只是几十个元素的序列化，跟画质、动画、贴图数量几乎无关。这也是为什么它敢画磨砂、敢 17 格跑灯，却仍测不出 CPU。

十三、先说清楚的限制（不吹）

以下都是结构上的限制，不是没做完 —— 想改得改代码重画素材，不是改配置能解决的：

转盘固定 8 格	几何、扇区、图标位置和素材绑死。想要 6 种奖就权重填 0，不能改成 6 格
不能整盘旋转	Rust 的 CUI 元素没有旋转属性。所以用「逐格点亮」代替，这也是真抽奖机的做法，不是妥协版
面板尺寸固定 520×696	所有坐标和底图都按这个尺寸画的，屏幕正中固定。要改尺寸等于重排整套界面
配色在图里，不在配置里	紫黑磨砂底、金环、霓虹边画在 panel.png / dial.png 里。想换色需要重画这两张图（包里附了源素材），不是配置项
记录区固定 3 行	面板只有 3 行位置，所以「面板显示条数」只能填 1~3
音效只能用游戏内置	Rust 插件不能给客户端下发音频文件，只能播 prefab。所以要换音色得换 prefab 名（这部分在代码里，不在配置）
券的物品说明改不了	背包里鼠标悬停那段描述来自客户端本地的物品定义，服务端改不了。你会看到原版「制作建筑蓝图和笔记的主要材料」——这是 Rust 的行为，不是插件的问题。背包描述 只对新生成的堆叠生效，效果有限
没订阅创意工坊看不到粉票	自定义外观依赖客户端订阅。没订阅的玩家看到原版白纸，但不影响功能
依赖 ImageLibrary	贴图托管要用它。没装的话面板显示不出来，这是唯一的硬依赖

十四、下载包里有什么

oxide/plugins/SPgacha.cs	插件本体，单文件约 51KB
oxide/config/SPgacha.json	出厂配置（就是第八节那张全表），第一次加载会自动生成，这份是给你先看着改的
oxide/data/SPgacha/icons/	20 张 png：panel.png（磨砂面板底）、dial.png（转盘盘面）、light-0~7.png（8 格高亮）、avatar.png、8 个奖励图标、ticket.png（券图标）
SPGacha-使用说明.md	服主手册：安装、配置全表、命令、常见改法、排错。放在包里方便你随时查

压缩包共 23 个文件，解压后直接覆盖到服务器根目录即可，不会覆盖你已有的其它插件与配置（文件名都带 SPgacha）。

十五、更新记录

v1.0.0

首个版本。八格转盘 + 逐格点亮 + 保底 + 十连 + 全服记录 + 稀有广播 + 四条券来源 + 紫黑磨砂界面。发布前做了一轮完整回归，修掉了 10 个问题：开箱可无限刷券、总开关关掉后券来源仍在发券、非法参数导致异常、连点跑两套动画、券皮肤默认值是占位值、「显示条数」配置不生效、抽完券数不刷新、死亡后面板残留、兑换无冷却、空位格画纸片图标；另外补上了权限在抽奖/兑换入口的二次校验，避免玩家用控制台绕过权限门。