koishi-plugin-vsinger-gacha 0.0.0-stage → 1.1.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 vsinger-gacha contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,136 @@
-# Temporary Holding Version
+# koishi-plugin-vsinger-gacha
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[![npm](https://img.shields.io/npm/v/koishi-plugin-vsinger-gacha?style=flat-square)](https://www.npmjs.com/package/koishi-plugin-vsinger-gacha)
+[![license](https://img.shields.io/github/license/zb23333ww/koishi-plugin-vsinger-gacha?style=flat-square)](LICENSE)
+
+> 六位 VSinger 角色的 B 站收藏集抽卡插件：423 张官方卡、43 个奖池、真实概率 + 保底、镭射版、签到积分与图鉴长图。
+
+VSinger 收藏集抽卡插件（Koishi 4.x）：六位角色的官方收藏集卡池、签到积分、图鉴长图，一次性安装即可用。
+
+## 功能
+
+- **423 张官方卡 / 43 个奖池**（含已下架奖池），按系列分组
+- **三级抽取范围**：全部卡池 / 整个系列 / 单个奖池（`/卡池` 合并转发给出编号，`/换池 01` 切换）
+- **合并转发**：抽卡结果与图鉴以「群聊的聊天记录」发送（不支持时自动退回普通消息）
+- **动态卡**：抽到动态卡额外单独发 mp4
+- **官方抽卡机制**：`card_scarcity` 真实概率、**400 抽大隐藏保底 / 40 抽隐藏保底**、同稀有度未拥有优先
+- **镭射版**：普卡 15% 概率出全息镭射图，抽到会记入图鉴
+- **积分系统内置**（不依赖签到插件）：签到、打工、蹭饭、摸鱼、每日红包
+- **图鉴长图**：液态玻璃背景 + 官方「大隐藏/小隐藏」角标 + 镭射标，超大图自动分张防 OOM
+- **管理指令**：给卡（管理员可凭空发，普通用户须自己拥有）、设/加积分、查积分
+
+## 安装（选择一种）
+
+### 方式 A：npm 一行装（推荐）
+
+```bash
+npm i koishi-plugin-vsinger-gacha
+```
+
+`koishi.yml` 加一行后重启：
+
+```yaml
+plugins:
+  vsinger-gacha: {}
+```
+
+### 方式 B：下载 tgz 直装（npm 不可用时）
+
+```bash
+npm i https://github.com/zb23333ww/koishi-plugin-vsinger-gacha/releases/latest/download/koishi-plugin-vsinger-gacha.tgz
+```
+
+### 方式 C：下载 zip 手动放
+
+[koishi-plugin-vsinger-gacha.zip](https://github.com/zb23333ww/koishi-plugin-vsinger-gacha/releases/latest/download/koishi-plugin-vsinger-gacha.zip) → 解压 → 整个文件夹放进 Koishi 的 `node_modules/` → 配置 → 重启。
+
+### 图鉴（可选）
+
+`/抽卡`、`/签到`、积分、管理指令**零依赖**即可用。
+只有 `/图鉴` 需要画布库，用到时再装：
+
+```bash
+npm i @napi-rs/canvas
+```
+
+没装时 `/图鉴` 会提示这一行，不影响其它功能。
+
+### 卡图
+
+- 抽到/查看的卡图**缺哪张自动下哪张**（约 1MB/张，可在配置里 `autoDownload: false` 关掉）
+- 想一次性缓存全部：`npm run fetch-assets -- --dir data/vsinger-gacha/cards`
+- 要动态卡 mp4（1.1GB）：下载 Release 的 `assets-videos.tar` 解压到 `cards/`
+
+## 指令
+
+| 指令 | 说明 |
+| --- | --- |
+| `签到` | 每日领积分 |
+| `抽卡 [张数]` | 抽卡，默认 1 张（每张 10 分，最多 10 张） |
+| `卡池` / `换池 <序号或名称>` | 查看/切换奖池（`00` = 全部奖池） |
+| `获取卡 <卡名>` | 把已拥有的卡发出来 |
+| `图鉴` | 生成收藏集长图（超大时自动分 2~3 张） |
+| `打工` / `打工状态` / `蹭饭` / `摸鱼` / `每日红包` | 挂机攒积分 |
+| `查积分 [@某人]` | 查积分 |
+| `给卡 @某人 <卡名>` | 管理员直接发放；普通用户转为「自己有 → 转赠」 |
+| `设积分 @某人 N` / `加积分 @某人 N` | 管理员设置/增减积分 |
+| `抽卡帮助` | 指令一览 |
+
+## 配置项
+
+| 配置 | 默认 | 说明 |
+| --- | --- | --- |
+| `cardsDir` | `data/vsinger-gacha/cards` | 卡图目录 |
+| `laserChance` | `0.15` | 普卡出镭射的概率 |
+| `adminUsers` | `[]` | 管理员 ID（平台主人自动算管理员） |
+| `pointsPerDraw` | `10` | 单抽消耗 |
+| `maxDrawOnce` | `10` | 单次最多抽几张 |
+| `signMin` / `signMax` | `10` / `30` | 签到积分范围 |
+| `workCap` / `workHours` | `200` / `12` | 打工上限与所需小时 |
+| `eatCdMin` / `moyuCdMin` | `30` / `10` | 蹭饭/摸鱼冷却（分钟） |
+| `bonusMin` / `bonusMax` | `5` / `20` | 每日红包范围 |
+
+## 用户 ID 说明（很重要）
+
+- **主键用 QQ 号**：`onebot:123456789`
+- **openid 只作为别名反查**：官方机器人（QQ 官机）的 openid **每个机器人都不一样**，
+  换一个官机同一个人就是另一个 openid，**绝不能拿来当主键**
+- 可选配置 `idMapFile`（QQ ↔ openid 映射表，JSON 形如 `{"users":{"QQ":"openid"}}`），
+  老数据是 openid 时会自动反查成 QQ，保证换机器人不丢数据
+
+## 数据与目录
+
+```
+<baseDir>/data/vsinger-gacha/
+├── gacha.json      # 每个人拥有的卡、保底计数、镭射记录、各会话当前奖池
+├── points.json     # 积分/签到/打工/冷却
+├── cards/          # 卡图（fetch-assets 下载）
+└── out/            # 图鉴输出
+```
+
+## 素材来源
+
+卡图与卡池信息来自 B 站「收藏集」公开接口（`asset_bag` / `lottery`），仅供个人收藏展示使用，版权归哔哩哔哩及原作者所有。
+
+## License
+
+MIT
+
+
+## 素材库（卡图 + 动态卡）
+
+插件包只带**缩略图**（图鉴用）+ 卡池数据，原图和动态卡单独放在 Releases 的「素材库」：
+
+| 附件 | 大小 | 内容 |
+| --- | --- | --- |
+| [`assets-cards.tar`](https://github.com/zb23333ww/koishi-plugin-vsinger-gacha/releases/download/v1.0.0/assets-cards.tar) | 1.6 GB | 423 张官方原图（1242×1863）+ 274 张镭射版 |
+| [`assets-videos.tar`](https://github.com/zb23333ww/koishi-plugin-vsinger-gacha/releases/download/v1.0.0/assets-videos.tar) | 1.1 GB | 145 个动态卡 mp4 |
+
+解压到 `cardsDir`（默认 `data/vsinger-gacha/cards`）：
+
+```bash
+tar xf assets-cards.tar  -C data/vsinger-gacha/cards
+tar xf assets-videos.tar -C data/vsinger-gacha/cards
+```
+
+**不装也能用**：卡图按需单张自动下载（约 1MB/张），图鉴直接用包内缩略图。

package/assets/README.md

@@ -0,0 +1,26 @@
+# 素材说明
+
+本目录随 npm 包发布的内容：
+
+| 文件 | 说明 |
+| --- | --- |
+| `catalog.json` | 423 张卡的基础数据（名称、档位、概率、所属奖池、act_id） |
+| `pool_rules.json` | 43 个奖池的保底规则（400 抽大隐藏 / 40 抽隐藏） |
+| `thumbs/` | 423 张 140×200 缩略图（图鉴直接用，共约 4.7MB） |
+| `tags/` | 官方「大隐藏 / 小隐藏」角标 + 社区复刻「镭射款」角标 |
+
+## 原图与动态卡
+
+原图 1366MB（423 张 PNG 1242×1863）和动态卡 1059MB（145 个 mp4）不进 git 仓库，
+放在 GitHub Releases 的 `assets-cards.tar` / `assets-videos.tar` 里。
+
+下载后解压到 `cardsDir`（默认 `data/vsinger-gacha/cards`）：
+
+```
+cards/
+├── 0a1b2c....png      # catalog.json 里 file 字段对应的文件名
+├── videos/0a1b2c....mp4
+└── holo/0a1b2c....jpg # 可选：镭射版（普卡的 15% 全息版）
+```
+
+也可以直接跑 `npm run fetch-assets -- --dir <cardsDir>` 从 B 站接口重新抓取。