简体中文 | Protocol specification

Overview

TerraLink connects Terraria tModLoader servers to applications built with NoneBot2 through a documented WebSocket protocol. It exposes game-server events, operational controls, performance data, and game-content queries as bot-side capabilities that can be integrated into existing automation workflows.

The project consists of this NoneBot2 plugin and the companion TerraNoneBridge tModLoader mod (source). The two components communicate through an authenticated protocol and can be deployed independently.

Key capabilities

• Bidirectional event bridge — forward chat and server events between tModLoader and a configured bot conversation.
• Server operations — execute administrative actions such as saving the world, managing players, changing time, and cleaning hostile entities.
• Game-data queries — inspect items, recipes, inventories, progression, online players, and server status.
• Structured rendering — render inventories, item details, recipe trees, and operational data as HTML/CSS-based images.
• Multi-server routing — manage multiple tModLoader servers from a single NoneBot2 deployment.
• Authenticated transport — isolate server connections with per-link tokens.
• Asynchronous architecture — use asyncio and websockets for concurrent connections and event delivery.

Architecture and adapter support

TerraLink separates the tModLoader protocol, connection management, rendering, and command services from the bot-platform-facing message handlers. This makes the core integration reusable when adding support for other NoneBot2 adapters.

The bundled transport currently targets OneBot V11 group contexts. Message events, conversation identifiers, and permission checks belong to this adapter-facing layer. Supporting another NoneBot2 adapter requires a transport implementation that maps its conversation and permission model onto TerraLink's existing core services; the tModLoader protocol and server-side integration do not need to be redesigned.

Ecosystem and use cases

TerraLink extends a general-purpose bot framework into a game-server operations interface. Server operators can incorporate live tModLoader events, remote administration, monitoring, and game-data lookup into the same bot workflows they already use for moderation, notifications, scheduled tasks, and community operations.

By keeping the game-server protocol independent from the bot-facing transport, the project provides a practical foundation for additional adapters, management interfaces, and automation scenarios. The Python plugin is distributed through PyPI, and the companion mod is available through the Steam Workshop.

Installation

Using nb-cli:

nb plugin install nonebot-plugin-terralink

Using pip:

pip install nonebot-plugin-terralink

Install and configure the companion TerraNoneBridge mod on each tModLoader server that should connect to the bot.

Configuration

Add the following options to the NoneBot .env or .env.prod file:

# Plugin master switch
terralink_enabled=true

# WebSocket listening port used by TerraNoneBridge
terralink_port=7778

# Prefix for TerraLink commands in the bot conversation
terralink_cmd_prefix=/

# Local path containing textures exported by TerraNoneBridge
# Configure a custom export path in the mod, then run "/tnb exportassets"
# in single-player or local-host mode. Copy the exported files to a location
# accessible to the NoneBot2 process.
terralink_resource_path="data/terralink/tmodass"

# Persistent state file for per-conversation bridge controls
# Leave empty to use data/terralink/group_settings.json
terralink_state_path=""

# Server-to-conversation mappings
# In the current OneBot V11 transport, group_id is the destination group ID.
terralink_links=[
    {"token": "your_secret_token_1", "group_id": 123456789, "name": "Survival Server"},
    {"token": "your_secret_token_2", "group_id": 987654321, "name": "Calamity Server"}
]

Each token must match the token configured in the corresponding TerraNoneBridge instance.

Commands

Bridge controls

In the bundled OneBot V11 transport, these commands are available to the SuperUser, group owner, and group administrators. Settings are persisted per bound group.

• Show status: /terralink status
• Toggle event forwarding: /terralink event <on/off> (master switch for system broadcasts)
• Toggle event forwarding by category: /terralink filter <category/all> <on/off>
• Toggle the complete bridge: /terralink bridge <on/off>
• Toggle bot-to-server chat: /terralink group <on/off>
• Toggle server-to-bot chat: /terralink server <on/off> (everything sent from the server to the bot)
• Reset bridge settings: /terralink reset
• Aliases: tl, 群服管理

Broadcast categories accepted by filter (requires TerraNoneBridge 0.9.0 or later):

Category	Description
join_leave	Player join/leave
death	Player deaths, including custom death reasons from other mods
boss	Boss awakened/defeated and boss warnings
event	Invasions, Blood Moon/eclipse, meteors, world progression (e.g. "Screams echo around you..."), player teleports and other vanilla events
npc	Town NPC arrivals, deaths and departures
mod	Server-wide broadcasts from other mods (e.g. damage reports, auto-fishing notices)
server	Server start/stop notices and console say messages

Server operators can also filter at the source in the mod config ModConfigs/TerraNoneBridge_ServerConfig.json: EnableChatSync controls two-way player chat, EnableEventBroadcast is the master switch for system broadcasts, the Broadcast* switches filter by the categories above, and BlockedKeywords drops messages containing specific keywords. Item, color and other chat tags are converted to readable text on the server before forwarding.

Administrative commands

Administrative commands require NoneBot SuperUser permission.

boss

Show world progression and defeated bosses.

/boss

buff

Apply a buff to one player or all players.

/buff <player/all> <BuffName> [seconds]

butcher

Remove hostile entities from the server.

/butcher

exportassets

Request export of game assets. Because this operation can be expensive, the bot intercepts accidental remote execution.

/export
/exportassets

give

Give an item to a player.

/give <player> <ItemName> [amount]

kick

Remove a player from the server.

/kick <player> [reason]

save

Force-save the current world.

/save

settle

Force world liquids to settle.

/settle

time

Query or change the world time.

/time [dawn/noon/dusk/midnight]

Query commands

help

Display the command menu.

/help

Aliases: 帮助, 菜单

inv

Render a player's inventory, armor, and accessories.

/inv <player>

Aliases: inventory, 查背包

list

List online players.

/list

Aliases: 在线, who, ls

query

Show item statistics, drops, NPC sales, and direct recipes.

/query <ItemName/ID>

Aliases: 查询, 属性

recipe

Generate a complete crafting tree for an item.

/recipe <ItemName/ID>

Aliases: 合成, 配方

search

Search for item names.

/search <keyword>

Aliases: 搜索, 查找

tps

Show server performance, memory usage, and entity counts.

/tps

Aliases: status, 性能

Protocol

The communication contract between the plugin and TerraNoneBridge is documented in the protocol specification.

License

Copyright © 2026 newcovid.

This project is licensed under the GNU General Public License v3.0 only (GPL-3.0-only).