#QQ bridge

Two backends (qq_config.json → qq_backend):

SFMC only bridges messages; the MC envelope remains /api/sfmc/messages.

#Message path

#Official (qq_backend: "official")

QQ → MC:  Official Gateway ─WS→ qq-bridge ─POST→ db-server
MC → QQ:  db-server ─HTTPS→ OpenAPI /v2/groups/{group_openid}/messages

• QQ→MC: only @bot group messages (GROUP_AT_MESSAGE_CREATE)
• MC→QQ: active group push (group owner must allow the bot to speak proactively; rate limits apply)

#LLBot (qq_backend: "llbot")

QQ → MC:  LLBot ─WS:3002→ qq-bridge ─POST→ db-server
MC → QQ:  db-server ─HTTP:3004→ LLBot

#Configuration

Edit configs/qq_config.json (defaults are created on first start):

#Obtaining official.group_openid

1. Configure AppID/Secret, add the bot to the group, subscribe to group @ events
2. Start the qq service and @ the bot in the group
3. If openid is unset, qq-bridge logs the received group_openid
4. Copy it into official.group_openid, then restart db-server and qq-bridge

#Official checklist

1. Subscribe to GROUP_AT_MESSAGE_CREATE in the console
2. Bot is in the target group
3. Group owner enables proactive bot messages
4. Sandbox: configure a sandbox group and set official.sandbox: true
5. If IP allowlist is on, add the server public IP (production only)

#LLBot setup

When qq_backend: "llbot", configure reverse WebSocket:

ws://127.0.0.1:3002

Upgrading from older installs: set "qq_backend": "llbot" explicitly; otherwise the default is official.

#QQ-side commands (no MC required)

qq-bridge intercepts commands before forwarding to MC. Same command registry; presentation differs by backend:

Admin commands are hidden from the main menu and official C2C quick menu. The bot no longer kicks players.

• official: @bot then send the trigger; optional sync to custom menu / command panel (sync-menu console command). C2C messages also hit the command router. With interaction intent, approval uses callback buttons (INTERACTION_CREATE).
• llbot: same triggers; numbered replies within 60s; no native panel / INTERACTION — use 通过/拒绝 <id>.
• Non-command group messages enter the game's read-only qq channel.
• status: world day and difficulty on separate lines; official adds a QQ group summary when APIs allow.

#In-game chat bridge

The chat module creates a read-only qq channel for incoming group messages. Players, including administrators, cannot speak in it.

LLBot outbound chat still needs HTTP (default 3004).

Check: configure + restart → @bot hello appears in game → game chat appears in QQ → 频道 / channel shows whether set.

#QQ↔MC binding

Platform APIs on db-server (loopback): POST /api/sfmc/qq/bind/{request,confirm,unbind} and GET /api/sfmc/qq/bind/me.

#Join approval & dual admin sides

The platform never writes BDS allowlist.json directly. QQ bot management does not enqueue kicks. Chat between the game and QQ is owned by the chat module (forward_to_qq and QQ-sourced channels), not a removed bridge_channel_id setting.

If BDS is down, approvals can queue and apply after restart. Stopping BDS does not block read-only 群信息 (OpenAPI only).

#Join switches (platform config configs/qq_link.json)

Owned by the platform QQ bind host, not the SDK / qq_config. Defaults are created on first read/write (wizard / db-server seed):

Bot (official.admin_openids, or group admins when the flag above is on): 配置 opens a button panel (official INTERACTION / llbot numbers); text 配置 白名单|审批 开|关 still works. API: GET/POST /api/sfmc/qq/join/settings (POST cannot change treat_group_admins_as_admins).

#Group OpenAPI allowlist (error 11253)

GET /v2/groups/{group_openid}/info and bot_state may require a platform allowlist. When blocked, status / 群信息 show a clear tip; chat bridge and join flow still work.

Game side is built into the platform behavior-pack host (same pattern as runtime monitoring): /c:bind, the unbound visitor gate, and join/leave/death reporting. Rebuild/deploy the platform BP after SDK upgrades. qq-link / feature-qq-link are retired modules — CLI refuses install/enable.

Read-only ops: public GET /api/sfmc/status backs status / online. Payload includes host (uptime/memory/CPU) and processes.bds / processes.db (process uptime; BDS from .sfmc/bds.pid or bedrock_server probe).

#Event push

Join / leave / death / BDS lifecycle posts to the QQ group independently of chat forwarding. Every event is sent immediately as its own message; nothing is batched.

Outbound still goes db-server → official OpenAPI / LLBot HTTP (same as MC→QQ; llbot needs port 3004). Official proactive group messages are rate-limited by QQ; turn off noisy event types if the group gets throttled.

Config (qq_config.json → qq_events; restart db-server after edits). The legacy window_sec field is deprecated and ignored:

"qq_events": {
  "enabled": true,
  "join": true,
  "leave": true,
  "death": true,
  "crash": true,
  "start": true
}

enabled: false disables all. API: POST /api/sfmc/qq/events (loopback; one object or { "events": [...] }, max 100).

Manual stop does not emit crash; crash auto-restart emits crash then start. Not in scope: achievements, chat mirroring via this path.

#Start

sfmc> start db
sfmc> start qq
# or
sfmc> start -all

Recommended order: db, then qq (llbot is started only for the llbot backend when enabled), then bds. See Service management.

#Loop prevention

• Drop messages from the bot itself
• Dedupe identical message ids within ~5 seconds

Troubleshooting: Troubleshooting.