Minecraft-Console-Client/docs/guide/creating-bots.md

---
title: Creating Chat Bots
---

# Creating Chat Bots

-   [Notes](#notes)
-   [Requirements](#requirements)
-   [Quick Introduction](#quick-introduction)
-   [Examples](#examples)
-   [AI-Assisted Bot Authoring](#ai-assisted-bot-authoring)
-   [C# API](#c#-api)

## Notes

<div class="custom-container tip"><p class="custom-container-title">Tip</p>

**This page covers the basics of the Chat Bot API. For the full surface area, read [ChatBot.cs](https://github.com/MCCTeam/Minecraft-Console-Client/blob/master/MinecraftClient/Scripting/ChatBot.cs) and the example scripts linked below.**

</div>

**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:

-   [C# Crash Course playlist by Teddy Smit](https://www.youtube.com/watch?v=67oWw9TanOk&list=PL82C6-O4XrHfoN_Y4MwGvJz5BntiL0z0D)

More in-depth:

-   [Learn C# YouTube Playlist by Microsoft](https://www.youtube.com/playlist?list=PLdo4fOcmZ0oVxKLQCHpiUWun7vlJJvUiN)
-   [Getting started with C# (an index of tutorials and documentation) by Microsoft](https://learn.microsoft.com/en-us/dotnet/csharp/)

## Quick Introduction

This introduction assumes that you have the basic knowledge of C#.

<div class="custom-container tip"><p class="custom-container-title">Tip</p>

**In this page, "Chat Bot" and "Script" are used interchangeably.**

</div>

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:

```csharp
//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>`.

<div class="custom-container tip"><p class="custom-container-title">Tip</p>

**Avoid adding whitespace between `//` and keywords**

</div>

By default, the following namespaces are loaded:

```csharp
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:

```csharp
//using System.Collections.Immutable
//dll MyDll.dll
```

Full Example:

```csharp
//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.

<div class="custom-container tip"><p class="custom-container-title">Tip</p>

**For allocating resources like a database connection, we recommend allocating them in `AfterGameJoined` and freeing them in `OnDisconnect`**

</div>

## Examples

You can find more examples in the [ChatBots](https://github.com/MCCTeam/Minecraft-Console-Client/tree/master/MinecraftClient/ChatBots) and [config](https://github.com/MCCTeam/Minecraft-Console-Client/tree/master/MinecraftClient/config) folders in the GitHub repository.

## AI-Assisted Bot Authoring

If you are using an AI coding agent on this repository, use the `mcc-chatbot-authoring` skill for bot work.

Skill links:

-   [Browse the skill on GitHub](https://github.com/MCCTeam/Minecraft-Console-Client/tree/master/.skills/mcc-chatbot-authoring)
-   [Download the skill directory](https://download-directory.github.io/?url=https%3A%2F%2Fgithub.com%2FMCCTeam%2FMinecraft-Console-Client%2Ftree%2Fmaster%2F.skills%2Fmcc-chatbot-authoring)

This skill is meant for:

-   standalone `/script` bots
-   built-in MCC chat bots
-   bot repairs and ports
-   event handlers, movement logic, inventory logic, and plugin-channel work

Its default behavior is important: if you ask for "a bot" without saying otherwise, it should prefer a standalone `//MCCScript` bot loaded with `/script`. It should only choose a built-in bot when you explicitly ask for repo wiring, automatic config loading, or a compiled MCC bot.

The skill also follows MCC-specific rules, for example:

-   do not send chat from `Initialize()`
-   use `AfterGameJoined()` for chat or commands after login
-   normalize chat with `GetVerbatim(text)` before `IsChatMessage(...)` or `IsPrivateMessage(...)`
-   fully clean up commands, timers, plugin channels, and movement locks

### Example prompts

```text
Create a standalone MCC /script bot that watches public chat for the word "auction" and logs matching messages to the console. Use the mcc-chatbot-authoring skill.
```

```text
Fix this existing MCC script bot so it stops sending chat from Initialize() and moves the startup command to AfterGameJoined(). Use the mcc-chatbot-authoring skill.
```

```text
Make a built-in MCC chat bot named AutoTorch and wire it fully into the repo config and bot registration. Use the mcc-chatbot-authoring skill.
```

```text
Create a standalone MCC /script bot that follows private messages, uses GetVerbatim(text), and replies only to bot owners. Use the mcc-chatbot-authoring skill.
```

## C# API

The authoritative reference for the C# API is [ChatBot.cs](https://github.com/MCCTeam/Minecraft-Console-Client/blob/master/MinecraftClient/Scripting/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.