QQBot

QQBot — Minecraft QQBot Mod

A server-side mod based on Minecraft Forge 1.20.1. It connects to a QQBotProxy over WebSocket, enabling server info queries in QQ groups/private chats, secure game-account binding, and player login reminders.

• Package: cn.citprobe
• Mod ID: qqbot
• Main class: QQBot
• Server-side installation only

---

Table of Contents

• Features
• Requirements
• Getting Started
• QQ Commands
• In-Game Commands
• Binding Flow
• Configuration
• Language Files
• Data Files
• Project Structure
• FAQ

---

Features

• Server info queries: online player count, TPS/MSPT, and player latency.
• QQ account binding: bind QQ to a game ID through a secure "8-character verification code + in-game confirmation" flow.
• Login reminders: send a private message to the bound QQ when a bound player logs in.
• Auto-reconnect: automatically reconnect to the Proxy at a configurable interval after disconnection.
• Bilingual support: built-in Simplified Chinese and English language files.
• Externalized configuration: connection URL, command prefix, server name, and other frequently changed options live in the config file.

---

Requirements

Item	Requirement
Minecraft	1.20.1
Java	17+
Proxy	QQBotProxy (WebSocket service, default port 18080)

---

Getting Started

1. Download

2. Deploy

1. Put qqbot-<version>.jar into the server's mods/ folder.
2. Start the server. qqbot.toml is generated under config/ on first start.
3. Edit config/qqbot.toml and point wsUrl to your Proxy.
4. Restart the server to apply changes.

Clients do not need to install this mod.

3. Verify

• The server log showing 已连接QQ机器人中转站 means the connection is successful.
• Send /help in a QQ group; receiving the help text means everything works.

---

QQ Commands

The default prefix is / (configurable). Available in both group and private chats.

Command	Description
/list	Show the online player count (current/max + player list)
/tps	Show the server TPS and MSPT
/ping [gameID]	Show latency; queries the bound game ID if omitted
/bind <gameID>	Start binding (triggers the verification-code flow)
/unbind	Unbind the current QQ from its game ID
/me	Show your binding info and online status
/help	Show help

---

In-Game Commands

Entered in the Minecraft chat (not QQ):

Command	Description
/bind accept <code>	Complete binding (code sent via QQ private message)
/unbind	Unbind the current game ID from its QQ

---

Binding Flow

1. The user sends /bind <gameID> in QQ.
2. The bot sends an 8-character verification code (letters + digits, ambiguous characters like 0/O/1/I/L excluded) via private message, valid for 5 minutes.
3. The player logs in with that game ID and enters /bind accept <code> in chat.
4. The server validates the code (exists, not expired, and matches the current player name), then completes the binding.
5. On success, the player gets an in-game message and the QQ user gets a private notification.

Re-binding with the same QQ overwrites the previous code; expired codes are invalidated and cleaned up automatically.

---

Configuration

File: config/qqbot.toml

Key	Description	Default
enabled	Enable the bot	true
wsUrl	Proxy WebSocket URL	ws://127.0.0.1:18080
reconnectDelaySeconds	Reconnect interval (seconds)	5
commandPrefix	QQ command prefix	/
language	Message language (zh_cn / en_us)	zh_cn
serverName	Server name (appended to query and reminder messages)	我的服务器

Example:

[qqbot]
enabled = true
wsUrl = "ws://127.0.0.1:18080"
reconnectDelaySeconds = 5
commandPrefix = "/"
language = "zh_cn"
serverName = "我的服务器"

---

Language Files

• assets/qqbot/lang/zh_cn.json — Simplified Chinese
• assets/qqbot/lang/en_us.json — English

---

Data Files

• config/qqbot-bindings.json — binding records between openids and game IDs, persisted automatically and kept across restarts.
• Verification codes are kept in memory only, not written to disk, and expired codes are cleaned up automatically.

---

Project Structure

qqbot/
├── build.gradle
├── gradle.properties
├── settings.gradle
└── src/main/
    ├── java/cn/citprobe/
    │   ├── QQBot.java                    # Main class
    │   ├── bind/
    │   │   ├── BindingManager.java       # Binding persistence
    │   │   └── VerificationManager.java  # Verification code management
    │   ├── bot/
    │   │   ├── CommandHandler.java       # QQ command handling
    │   │   └── MessageHandler.java       # WebSocket message dispatch
    │   ├── config/
    │   │   └── ModConfig.java            # Config entries
    │   ├── i18n/
    │   │   └── Lang.java                 # Translation loading
    │   ├── model/
    │   │   └── IncomingMessage.java      # Message DTO
    │   ├── util/
    │   │   └── TpsTracker.java           # TPS calculation
    │   └── websocket/
    │       └── BotWebSocketClient.java   # WebSocket client
    └── resources/
        ├── META-INF/mods.toml
        └── assets/qqbot/lang/
            ├── zh_cn.json
            └── en_us.json

---

FAQ

Q: Do clients need to install this mod? No, it is server-side only.

Q: I didn't receive the verification code? Make sure the Proxy's private messaging works, and check whether QQ security policies are blocking private messages.

Q: The verification code expired? Codes expire after 5 minutes. Send /bind <gameID> in QQ again.

Q: How do I switch languages? Set language = "en_us" in config/qqbot.toml and restart.

Q: Where are binding data stored? config/qqbot-bindings.json. Deleting this file clears all bindings.

---

License

This project is licensed under the [MIT License].