ChatBot の作成

メモ
必要条件
簡単な紹介
サンプル
AI-Assisted Bot Authoring
C# API

メモ

Note

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 には ChatBot（プラグイン）を作成することができる豊富な C# API があり、複雑な自動化システムを作成するのに便利です。

必要条件

C# の基礎知識
テキストエディター

C# に関する基本的な知識がない場合は、C# の基本に慣れてください。

短期集中コース

Teddy Smit による C# 学習の YouTube 再生リスト（英語）

より深く学ぶには:

簡単な紹介

C# の基本的な知識があることを前提としています。

Note

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

MCC がインストールされているフォルダーと同じ場所に、新しい C# ソースファイル ExampleChatBot.cs を作成します。

次のサンプルコードを貼り付けます。

//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);
        }
    }
}

MCC を起動し、サーバーに接続して、内部コマンド /script ExampleChatBot.cs を実行します。

If everything worked, you should see [Example Chat Bot] An example Chat Bot has been initialized! in the console.

ChatBot の構造

ChatBot（スクリプト）の構造は次のとおりです。

<script metadata>
<chat bot class>

Script Metadata は、コメントを使用して C# と MCC の形式を組み合わせたカスタム形式のセクションです。

すべての ChatBot（スクリプト）の最初にこのセクションが必要です。

Script Metadata 形式

//MCCScript 1.0 は、Script Metadata セクションの開始を示します。最初の行に書かれていないと、ChatBot（スクリプト）が読み込まれず、エラーが発生します。

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

サンプルコード:

MCC.LoadBot(new YourChatBotClassNameHere());

The Script Metadata section also lets you include namespaces and DLL references with //using <namespace> and //dll <dll name>.

Note

// と文字列の間に空白を追加しないでください。

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;

サンプル:

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

サンプル:

//MCCScript 1.0

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

MCC.LoadBot(new ExampleChatBot());

//MCCScript Extensions

ChatBot クラス

After the Script Metadata section, you can define any number of helper classes. The main bot class must extend ChatBot.

すべて任意のメソッドで、必須ではありません。

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.

Note

データベース接続などのリソースの割り当てについては、AfterGameJoined で割り当て、OnDisconnect で解放することをお勧めします。

サンプル

You can find more examples in the ChatBots and 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:

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

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.

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.

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.

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.

Achievements And Advancements

Chat bots and C# scripts can read the current achievement state and react to updates.

Useful methods:

GetAchievements()
GetUnlockedAchievements()
GetLockedAchievements()
OnAchievementUpdate(IReadOnlyList<Achievement> updated, IReadOnlyList<string> removedIds, bool reset)

Things worth knowing:

On 1.8 to 1.11.2, ids use the legacy achievement.* format.
On 1.12+, ids use advancement resource ids such as minecraft:story/root.
Legacy achievements usually have Title = null and Description = null because the server does not send display metadata in the statistics packet.
On newer versions, revoking an advancement may remove it from the current set instead of turning it into a locked entry, so removedIds matters.

サンプル:

//MCCScript 1.0

MCC.LoadBot(new AchievementWatcher());

//MCCScript Extensions

public class AchievementWatcher : ChatBot
{
    public override void AfterGameJoined()
    {
        Achievement[] known = GetAchievements();
        LogToConsole($"Known achievements: {known.Length}");
    }

    public override void OnAchievementUpdate(IReadOnlyList<Achievement> updated, IReadOnlyList<string> removedIds, bool reset)
    {
        LogToConsole($"Achievement update: reset={reset}, updated={updated.Count}, removed={removedIds.Count}");

        foreach (Achievement achievement in updated)
        {
            string title = achievement.Title ?? achievement.Id;
            string state = achievement.IsCompleted ? "done" : "todo";
            LogToConsole($" - {title}: {state}");
        }

        foreach (string removedId in removedIds)
            LogToConsole($" - removed: {removedId}");
    }
}

Scoreboard teams

Chat bots and C# scripts can read the current team state and react to team changes.

Useful methods and events:

GetTeams() - returns a snapshot of all teams the server has sent
GetPlayerTeam(playerName) - returns the team a specific player is on, or null
OnTeam(teamName, method, displayName, friendlyFlags, nameTagVisibility, collisionRule, color, prefix, suffix, players) - called whenever a team packet arrives

The method byte tells you what changed:

0 - team created (includes full parameters and initial member list)
1 - team removed
2 - team parameters updated (display name, colors, rules)
3 - players added to the team
4 - players removed from the team

The color field is a ChatFormatting enum ordinal. Common values: 0=black, 9=blue, 10=green, 12=red, 14=yellow, -1=none/reset.

The nameTagVisibility and collisionRule strings take values from the Minecraft wiki: "always", "never", "hideForOtherTeams", "hideForOwnTeam" (visibility) or "pushOtherTeams", "pushOwnTeam" (collision).

サンプル:

//MCCScript 1.0

MCC.LoadBot(new TeamWatcher());

//MCCScript Extensions

public class TeamWatcher : ChatBot
{
    public override void AfterGameJoined()
    {
        foreach (var team in GetTeams().Values)
            LogToConsole($"Team '{team.Name}' has {team.Members.Count} member(s)");
    }

    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($"Team '{teamName}' created with {players.Count} member(s)");
                break;
            case 1:
                LogToConsole($"Team '{teamName}' removed");
                break;
            case 3:
                LogToConsole($"{string.Join(", ", players)} joined team '{teamName}'");
                break;
            case 4:
                LogToConsole($"{string.Join(", ", players)} left team '{teamName}'");
                break;
        }
    }
}

C# API

The authoritative reference for the C# API is ChatBot.cs.

各メソッドは、標準の C# ドキュメントコメントで詳しく説明されています。

This page intentionally stays focused on the basics. For newer hooks and overloads, check the source file directly.