koishi-plugin-ggcevo-game/readme.md

《星际争霸2》咕咕虫-evolved地图的专属游戏助手插件，集成天梯排行、抽奖系统、签到福利、兑换商城等丰富功能。

# koishi-plugin-ggcevo-game

[![npm](https://img.shields.io/npm/v/koishi-plugin-ggcevo-game?style=flat-square)](https://www.npmjs.com/package/koishi-plugin-ggcevo-game)

《星际争霸2》咕咕虫-evolved地图的专属游戏助手插件，集成天梯排行、抽奖系统、签到福利、兑换商城等丰富功能。

## 功能清单

### 核心系统
- 🎰 **保底抽奖系统**：支持单抽/十连抽，隐藏奖励机制
- 📅 **智能签到系统**：结合游戏对局验证的签到机制
- 🏆 **天梯排名系统**：自动同步胜点数据，动态排行榜
- 🛍️ **兑换商城系统**：多层级奖品池，赛季限定物品

### 特色功能
- ⚔️ **玩家对战系统**：金币PK玩法，动态胜率计算
- 🚨 **违规监控系统**：大厅玩家行为监控，黑名单管理
- 🎁 **活动管理系统**：福利活动创建与发放
- 📊 **数据统计系统**：玩家成就、背包、抽奖记录等全维度统计

## 安装配置

1. 安装插件
```bash
npm install koishi-plugin-ggcevo-game
```

2. 基础配置
```yaml
plugins:
  ggcevo-game:
    proxyAgent: ''             # 代理地址（如需）
    ggcqun: '你的群号'         # 绑定游戏群组
    rankseason: 'S1'           # 当前赛季名称
    signrequire: true          # 对局签到要求
    autorank: true             # 自动同步天梯数据
    dailyPKLimit: 3            # 每日最大PK次数
    admins: [管理员QQ列表]      # 管理员权限
```

## 使用说明

### 玩家命令
```bash
每日签到
/签到

抽奖系统
/单抽
/十连抽
/抽奖记录

天梯系统
/胜点榜
/排名 @玩家

对战系统
/pk @玩家
/切换pk状态

兑换系统
/兑换
/兑换扭蛋币
```

### 管理命令
```bash
活动管理
/创建活动 <名称> <描述> <奖励数量>

玩家管理
/活动拉黑
/胜点榜拉黑

数据维护
/胜点榜数据同步
```

## 数据模型
```
📦 数据库结构
├── 用户背包 (ggcevo_backpack)
├── 签到记录 (ggcevo_sign)
├── 天梯数据 (ggcevo_rank)
├── 对战记录 (ggcevo_pk_logs)
├── 兑换记录 (ggcevo_exchange)
└── 活动管理 (ggcevo_activity)
```

## 注意事项

1. **敏感词检测**：需要配置第三方API（示例使用 api.iminbk.com）
2. **定时任务**：自动天梯同步默认每小时执行，请根据需求调整频率
3. **赛季设置**：兑换系统依赖 `rankseason` 配置项，赛季变更时需更新
4. **代理配置**：国内服务器建议配置代理访问SC2Arcade API

> 提示：使用前请确保已安装 [koishi-plugin-sc2arcade-search](https://www.npmjs.com/package/koishi-plugin-sc2arcade-search) 作为前置插件