5.9 KiB
| title |
|---|
| Creating Chat Bots |
Creating Chat Bots
Notes
Tip
This page covers the basics of the Chat Bot API. For the full surface area, read ChatBot.cs and the example scripts linked below.
Minecraft Console Client has a rich C# API which allows you to create Chat Bots (effectively plugins) which can help you create complex automations which normal scripts may not be able to do.
Requirements
- A basic knowledge of C# programming language
- A text editor
If you're not familiar with the C# programming language, we suggest taking a look at the following resources:
Crash courses:
More in-depth:
- Learn C# Youtube Playlist by Microsoft
- Getting started with C# (An index of tutorials and the documentation) by Microsoft
Quick Introduction
This introduction assumes that you have the basic knowledge of C#.
Tip
In this page, "Chat Bot" and "Script" are used interchangeably.
Create a new empty file and name it ExampleChatBot.cs in the same folder where you have your MCC installed.
Paste the following example code:
//MCCScript 1.0
MCC.LoadBot(new ExampleChatBot());
//MCCScript Extensions
// The code and comments above are defining a "Script Metadata" section
// Every chat bot script must define a class that extends ChatBot.
// Instantiate that class in the script metadata section and pass it to 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);
}
}
}
Start MCC, connect to a server and run the following internal command: /script ExampleChatBot.cs.
If everything worked, you should see [Example Chat Bot] An example Chat Bot has been initialized! in the console.
Structure of Chat Bots
Chat Bot (Script) structure is the following:
<script metadata>
<chat bot class>
Script Metadata is a section with a custom format that mixes in C# with our format using comments.
Every single Chat Bot (Script) must have this section at the beginning in order to work.
Script Metadata Format
//MCCScript 1.0 marks the beginning of the Script Metadata section, this must always be on the first line or the Chat Bot (Script) will not load and will throw an error.
//MCCScript Extensions marks the end of the Script Metadata section. It must appear before the Chat Bot class.
To load a Chat Bot script, instantiate the bot class between //MCCScript 1.0 and //MCCScript Extensions, then pass it to MCC.LoadBot.
Example code:
MCC.LoadBot(new YourChatBotClassNameHere());
The Script Metadata section also lets you include namespaces and DLL references with //using <namespace> and //dll <dll name>.
Tip
Avoid adding whitespace between // and keywords
By default, the following namespaces are loaded:
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;
Example:
//using System.Collections.Immutable
//dll MyDll.dll
Full Example:
//MCCScript 1.0
//using System.Collections.Immutable
//dll MyDll.dll
MCC.LoadBot(new ExampleChatBot());
//MCCScript Extensions
Chat Bot Class
After the Script Metadata section, you can define any number of helper classes. The main bot class must extend ChatBot.
There are no required methods, everything is optional.
When the Chat Bot is initialized for the first time, the Initialize method is called.
Use it to initialize state such as dictionaries or cached values.
Tip
For allocating resources like a database connection, we recommend allocating them in AfterGameJoined and freeing them in OnDisconnect
Examples
You can find more examples in the ChatBots and config folders in the GitHub repository.
C# API
The authoritative reference for the C# API is ChatBot.cs.
Each method is well documented with standard C# documentation comments.
This page intentionally stays focused on the basics. For newer hooks and overloads, check the source file directly.