Hyvote

Hyvote

适用于 Hytale 的安全投票监听插件，允许投票网站向您的服务器发送投票通知。

功能特性

• 混合加密协议：采用 RSA + AES-256 加密，确保投票传输的安全性和灵活性
• 可配置动作：在收到投票或玩家加入时，自动执行预设命令
• 开发者 API：触发自定义事件，将投票处理集成到您自己的插件中
• 重放保护：内置时间戳和随机数验证，防止重复投票
• 多协议支持：版本字段允许未来协议更新，且不破坏现有集成

安装步骤

1. 下载最新版本
2. 将 Hyvote.jar 放入服务器插件文件夹
3. 启动服务器——settings.json 将自动生成
4. 配置您的设置（见下文）
5. 将您的 RSA 公钥分享给投票网站（位于 keys/public.pem）

配置文件

设置存储在 settings.json 中：

{
  "port": 2250,
  "database": {
    "type": "sqlite",
    "host": "localhost",
    "port": 3306,
    "username": "hytale",
    "password": "supersecretdatabasepassword",
    "database": "hyvote"
  },
  "actions": [
    {
      "on": "vote",
      "type": "command",
      "command": "say ${player} just voted on ${voteSite}!"
    },
    {
      "on": "join",
      "type": "command",
      "command": "say Welcome back ${player}! Thanks for voting on ${voteSite}"
    }
  ]
}

配置选项

port：投票监听绑定的 TCP 端口（默认：2250）

database：数据库的配置选项

actions：收到投票时执行的动作数组

数据库属性

数据库用于跟踪已使用的随机数，并在玩家离线时收到投票但需要玩家在线时才执行动作时，暂存投票。

• type：使用的数据库类型（支持 MySQL、MariaDB、SQLite、PostgreSQL）
• host：数据库主机（使用 SQLite 时忽略）
• port：数据库监听的端口（使用 SQLite 时忽略）
• username：数据库用户名（使用 SQLite 时忽略）
• password：数据库用户密码（使用 SQLite 时忽略）
• database：使用的数据库（使用 SQLite 时忽略）

动作属性

• on：执行动作的时机

  • vote - 投票处理完成后立即执行
  • join - 玩家加入时执行（若已在线则立即执行）

• type：动作类型（目前仅支持 command）

• command：要执行的命令。支持以下占位符：

  • ${player} - 投票玩家的用户名
  • ${voteSite} - 投票网站名称
  • ${uuid} - 投票玩家的 UUID
  • ${timestamp} - 投票时间戳

开发者 API

Hyvote 提供事件系统，供插件开发者集成自定义投票处理。

监听投票事件

import uk.co.deveroonie.hyvote.api.VoteEventManager;
import uk.co.deveroonie.hyvote.api.VoteReceivedEvent;

// 注册监听器
VoteEventManager.registerListener(event -> {
    Vote vote = event.getVote();

    // 访问投票数据
    String player = vote.playerName;
    String site = vote.voteSite;
    long timestamp = vote.timestamp;

    // 可选：取消默认处理
    event.setCancelled(true);

    // 实现您的自定义逻辑
    myPlugin.giveCustomReward(player);
});

Vote 对象

public class Vote {
    public String uuid;          // 玩家 UUID
    public String playerName;    // 玩家用户名
    public String voteSite;      // 投票网站标识
    public long timestamp;       // Unix 时间戳
    public String nonce;         // 重放保护随机数
}

注销监听器

VoteListener myListener = event -> { /* ... */ };
VoteEventManager.registerListener(myListener);

// 稍后...
VoteEventManager.unregisterListener(myListener);

协议规范

Hyvote 使用自定义二进制协议（HV01）传输投票：

消息格式

[4 字节] 魔术字："HV01"
[4 字节] 加密后的 AES 密钥长度（大端整数）
[N 字节] RSA 加密的 AES-256 密钥
[4 字节] 加密后的负载长度（大端整数）
[M 字节] AES 加密的 JSON 负载

加密过程

1. 生成随机的 256 位 AES 密钥
2. 使用 AES-256-CBC 加密投票 JSON（包含附加在密文前的 16 字节 IV）
3. 使用服务器的 RSA 公钥加密 AES 密钥（PKCS1 或 OAEP 填充）
4. 按照上述消息格式打包并发送

JSON 负载结构

{
  "uuid": "player-uuid-here",
  "playerName": "PlayerName",
  "voteSite": "VotingSiteName",
  "timestamp": 1737000000000,
  "nonce": "unique-random-string"
}

客户端库

官方客户端库即将支持：

• Java
• JavaScript/Node.js

安全性

• 所有投票数据通过混合 RSA + AES 加密实现端到端加密
• 通过随机数机制防范重放攻击
• 格式错误的消息在处理前会被拒绝

支持

如遇问题、需要功能请求或有协议相关疑问，请访问我们的 GitHub 仓库。

许可协议

MIT