创建 Chat Bots
注意事项
注意
本页面介绍聊天机器人 API 的基础知识。 如需了解完整功能,请参阅 ChatBot.cs 以及下方链接中的示例脚本。
Minecraft 命令行客户端 拥有丰富的 C# API ,允许您创建Chat Bot(即插件),从而帮你实现普通脚本难以完成的复杂自动化任务。
要求
- C# 编程语言的基本知识
- 文本编辑器
如果您不熟悉C# 编程语言,我们建议查看以下资源:
速成教学
更深入的内容:
快速入门
本教程假定你已经具备 C# 的基础知识
注意
在本页面中,“聊天机器人”与“脚本”可互换使用。
在您安装MCC的同一文件夹中创建一个空文件,并重命名为 ExampleChatBot.cs
粘贴下面的示例代码:
//MCC脚本 1.0
MCC.LoadBot(new 示例聊天机器人());
//MCC脚本扩展
// 上面的代码和注释定义了一个“脚本元数据”部分
// 每个聊天机器人脚本都必须定义一个继承自ChatBot的类。
// 在脚本元数据部分实例化该类,并将其传递给 MCC.LoadBot。
class ExampleChatBot : ChatBot
{
// This method will be called when the script has been initialized for the first time, it's called only once
// Here you can initialize variables, eg. Dictionaries. etc...
public override void Initialize()
{
LogToConsole("An example Chat Bot has been initialized!");
}
// This is a function that will be run when we get a chat message from a server
// In this example it just detects the type of the message and prints it out
public override void GetText(string text)
{
string message = "";
string username = "";
text = GetVerbatim(text);
if (IsPrivateMessage(text, ref message, ref username))
{
LogToConsole(username + " has sent you a private message: " + message);
}
else if (IsChatMessage(text, ref message, ref username))
{
LogToConsole(username + " has said: " + message);
}
}
}启动 MCC,连接到服务器并运行: /script ExampleChatBot.cs.
如果一切正常,你应该会在控制台看到 [示例聊天机器人] 示例聊天机器人已初始化!。
Chat Bot的结构
Chat Bot (Script) 的结构如下:
<script metadata>
<chat bot class>Script Metadata是一个有着特殊格式的区域,通过注释来区分C#代码和MCC的专有内容。
每个Chat Bot (Script) 都必须在开头包含这一部分才能运行。
Script Metadata 的格式
//MCCScript 1.0 标志着Script Metadata部分的开始,这行代码必须始终位于第一行,否则Chat Bot (Script) 将不会被加载并报错。
//MCCScript 扩展 标记着脚本元数据部分的结束。 它必须出现在 ChatBot 类之前。
要加载聊天机器人脚本,请在 //MCCScript 1.0 和 //MCCScript Extensions 之间实例化机器人类,然后将其传递给 MCC.LoadBot。
例子
MCC.LoadBot(new YourChatBotClassNameHere());在脚本元数据部分,你还可以使用//using <命名空间>和//dll <DLL名称>来引入命名空间和 DLL 引用。
注意
请勿在 // 和关键字之间添加空格
默认情况下,会加载以下命名空间:
using System;
using System.Collections.Generic;
using System.Text.RegularExpressions;
using System.Linq;
using System.Text;
using System.IO;
using System.Net;
using System.Threading;
using MinecraftClient;
using MinecraftClient.Mapping;
using MinecraftClient.Inventory;示例:
//using System.Collections.Immutable
//dll MyDll.dll完整示例:
//MCCScript 1.0
//using System.Collections.Immutable
//dll MyDll.dll
MCC.LoadBot(new ExampleChatBot());
//MCCScript ExtensionsChat Bot Class
在脚本元数据部分之后,您可以定义任意数量的辅助类。 主机器人类必须继承 ChatBot。
没有任何强制要求的方法,一切都是可选的。
当聊天机器人首次初始化时,会调用Initialize方法。
用于初始化状态,例如字典或缓存值。
注意
如果是像数据库连接这种资源,最好是在 AfterGameJoined(加入游戏后)里建立,然后在OnDisconnect(断开连接时)里关闭
示例
你可以在 GitHub 仓库的 ChatBots 和 config 文件夹中找到更多示例。
AI 辅助机器人编写
如果您在此仓库中使用 AI 编程代理,请为机器人相关工作使用 mcc-chatbot-authoring 技能。
技能链接:
此技能适用于:
- 独立
/script机器人 - 内置的MCC聊天机器人
- 机器人修复与端口
- 事件处理器、移动逻辑、库存逻辑以及插件通道相关工作
它的默认行为很重要:如果你只说“一个bot”而没有特别说明,它应该优先选择通过/script加载的独立//MCCScript bot。 只有在您明确要求进行仓库配置、自动加载配置或使用编译后的 MCC 机器人时,才应选择内置机器人。
该技能也遵循MCC特有的规则,例如:
- 不要从
Initialize()发送聊天消息 - 登录后使用
AfterGameJoined()处理聊天或命令 - 在调用
IsChatMessage(...)或IsPrivateMessage(...)之前,请先使用GetVerbatim(text)对聊天消息进行标准化处理。 - 彻底清理命令、计时器、插件通道和移动锁定
示例提示
创建一个独立的 MCC /script 脚本机器人,监听公共聊天中的“auction”一词,并将匹配的消息记录到控制台。 使用mcc-聊天机器人创作技能。修复这个现有的 MCC 脚本机器人,使其不再在 Initialize() 中发送聊天消息,并将启动命令移至 AfterGameJoined()。 使用mcc-聊天机器人创作技能。创建一个名为 AutoTorch 的 MCC 内置聊天机器人,并将其完整地集成到仓库配置和机器人注册中。 使用mcc-聊天机器人创作技能。创建一个独立的 MCC /script 机器人,它会监听私聊消息,使用 GetVerbatim(文本) 函数,并且只回复机器人所有者。 使用mcc-聊天机器人创作技能。成就与进度
聊天机器人和 C# 脚本可以读取当前的成就状态,并对状态更新作出反应。
有用的方法:
获取成就()获取已解锁成就()获取已锁定成就()成就更新事件(只读成就列表 updated, 只读字符串列表 removedIds, 重置标志 reset)
值得了解的事:
- 在
1.8到1.11.2版本中,标识符使用旧版的achievement.*格式。 - 在
1.12+版本中,ID 使用成就资源 ID,例如minecraft:story/root。 - 遗留成就通常会将
标题 = 无和描述 = 无,这是因为服务器在统计数据包中不会发送显示元数据。 - 在较新版本中,撤销一个进度可能会将其从当前进度列表中移除,而不是将其变为已锁定状态,因此
removedIds参数很重要。
示例:
//MCC脚本 1.0
MCC.LoadBot(new AchievementWatcher());
//MCC脚本扩展
public class AchievementWatcher : ChatBot
{
public override void AfterGameJoined()
{
Achievement[] known = GetAchievements();
LogToConsole($"已知成就:{known.Length}");
}
public override void OnAchievementUpdate(IReadOnlyList<Achievement> updated, IReadOnlyList<string> removedIds, bool reset)
{
LogToConsole($"成就更新:重置={reset}, 更新={updated.Count}, 移除={removedIds.Count}");
foreach (Achievement achievement in updated)
{
string title = achievement.Title ?? 成就.编号;
字符串 状态 = 成就.是否完成 ? "完成" : "待办";
LogToConsole($" - {title}: {state}");
}
foreach (string removedId in removedIds)
LogToConsole($" - 已移除: {removedId}");
}
}记分板队伍
聊天机器人和 C# 脚本可以读取当前队伍状态,并对队伍变化作出响应。
有用的方法和事件:
GetTeams()- 返回服务器发送的所有队伍的快照GetPlayerTeam(玩家名)- 返回指定玩家所在的队伍,或返回nullOnTeam(队伍名, 方法, 显示名, 友好标志, 名称标签可见性, 碰撞规则, 颜色, 前缀, 后缀, 玩家)- 每当收到队伍数据包时调用
method 字节告诉你发生了什么变化:
0- 队伍已创建(包含完整参数和初始成员列表)1- 小组已移除2- 队伍参数已更新(显示名称、颜色、规则)3- 已添加到队伍的玩家4- 从团队中移除的玩家
color 字段是一个 ChatFormatting 枚举的序号。 常用值:0=黑色,9=蓝色,10=绿色,12=红色,14=黄色,-1=无/重置。
nameTagVisibility 和 collisionRule 字符串的取值来自 Minecraft 维基:对于可见性,可选 "always"、"never"、"hideForOtherTeams"、"hideForOwnTeam";对于碰撞规则,可选 "pushOtherTeams"、"pushOwnTeam"。
示例:
//MCC脚本 1.0
MCC.LoadBot(new TeamWatcher());
//MCC脚本扩展
public class TeamWatcher : ChatBot
{
public override void AfterGameJoined()
{
foreach (var team in GetTeams().Values)
LogToConsole($"队伍 '{team.Name}' 有 {team.Members.Count} 名成员");
}
public override void OnTeam(string teamName, byte method, string displayName,
byte friendlyFlags, string nameTagVisibility, string collisionRule,
int color, string prefix, string suffix, List<string> players)
{
switch (method)
{
case 0:
LogToConsole($"队伍 '{teamName}' 已创建,包含 {players.Count} 名成员");
break;
case 1:
LogToConsole($"队伍 '{teamName}' 已移除");
break;
case 3:
LogToConsole($"{string.Join(", ", players)} 加入了队伍 '{teamName}'");
break;
case 4:
LogToConsole($"{string.Join(", ", players)} 离开了队伍 '{teamName}'");
break;
}
}
}C# API
C# API 的权威参考文档是 ChatBot.cs。
每种方法都通过标准 C# 文档注释进行了详细注释。
本页有意保持内容简洁,只介绍基础知识。 当翻译时,请优先使用《我的世界》游戏内的官方术语。如果玩家社区已广泛采用其他术语,则应选择更易识别的用法。翻译时请遵循《我的世界》客户端工具领域的风格。 对于较新的钩子和重载,请直接查看源代码文件。
