diff --git a/docs/guide/ai-assisted-development.md b/docs/guide/ai-assisted-development.md index b7785c19..3d9a764e 100644 --- a/docs/guide/ai-assisted-development.md +++ b/docs/guide/ai-assisted-development.md @@ -6,6 +6,8 @@ title: AI-Assisted Development This guide documents the MCC AI-assisted development workflow as a real working loop, not a patch generator running on guesses. The goal is to give the agent an environment it can drive on its own: build MCC, start a local server, send commands, inspect logs, and repeat. Once that loop is in place, iteration is faster and regressions are easier to catch. +If you are looking for the broader contributor entry point first, start with [Contributing](contibuting.md) and then come back here for the agent workflow. + The practical goal is a closed loop: ```mermaid diff --git a/docs/guide/contibuting.md b/docs/guide/contibuting.md index a59279a7..f1c8b597 100644 --- a/docs/guide/contibuting.md +++ b/docs/guide/contibuting.md @@ -4,12 +4,18 @@ title: Contributing # Contributing -This page is still being filled in. For now, use the links below for the current contributor workflow. +This page is still being filled in. For now, use the sections below as the current contributor entry points for code, docs, and translation work. -If you are working with SWE AI agents, start with [AI-Assisted Development](ai-assisted-development.md). It covers the shell setup, local server loop, and the skills in `.skills/`. +If you are doing maintainer-style work with coding agents, start with [AI-Assisted Development](ai-assisted-development.md). It covers the shell setup, local server loop, and the skills in `.skills/`. You can also use the guide in the [GitHub repository wiki](https://github.com/MCCTeam/Minecraft-Console-Client/wiki/Update-console-client-to-new-version) written by [ReinforceZwei](https://github.com/ReinforceZwei). +For now, the project has three main contribution paths: + +- code and bot work in the main MCC client +- documentation updates in `docs/` +- translations through Crowdin + ## Translations To improve translations for MCC, please visit: [Crowdin - Minecraft Console Client](https://crwd.in/minecraft-console-client). diff --git a/docs/guide/creating-bots.md b/docs/guide/creating-bots.md index 6d0f6342..0dacd8fa 100644 --- a/docs/guide/creating-bots.md +++ b/docs/guide/creating-bots.md @@ -8,6 +8,7 @@ title: Creating Chat Bots - [Requirements](#requirements) - [Quick Introduction](#quick-introduction) - [Examples](#examples) +- [AI-Assisted Bot Authoring](#ai-assisted-bot-authoring) - [C# API](#c#-api) ## Notes @@ -33,8 +34,8 @@ Crash courses: 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 the documentation) by Microsoft](https://docs.microsoft.com/en-us/dotnet/csharp/) +- [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 @@ -185,6 +186,44 @@ Use it to initialize state such as dictionaries or cached values. 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. + +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). diff --git a/docs/guide/installation.md b/docs/guide/installation.md index f9e66687..91b13369 100644 --- a/docs/guide/installation.md +++ b/docs/guide/installation.md @@ -95,13 +95,31 @@ If the build succeeds, the published binary `MinecraftClient.exe` will be in `Mi 1. Open the `Minecraft-Console-Client` folder you've cloned or downloaded 2. Open the PowerShell (`Right-Click` on the whitespace and click `Open PowerShell`, or in Windows Explorer: `File -> Open PowerShell`) -3. Run the following command to build the project: +3. Install the .NET 10 SDK if you do not already have it. The easiest current option on Windows is: + +```powershell +winget install Microsoft.DotNet.SDK.10 +``` + +4. Run the following command for a normal local build: + +```bash +dotnet build MinecraftClient.sln -c Release +``` + +5. If you want a release-like published binary that matches the repo's CI workflow, run: ```bash dotnet publish MinecraftClient.sln -f net10.0 -r win-x64 --self-contained=true -c Release -p:UseAppHost=true -p:IncludeNativeLibrariesForSelfExtract=true -p:EnableCompressionInSingleFile=true -p:DebugType=Embedded ``` -If the build succeeds, the published binary `MinecraftClient.exe` will be in `MinecraftClient/bin/Release/net10.0/win-x64/publish/`. +6. Verify the SDK installation if needed: + +```bash +dotnet --info +``` + +If the publish step succeeds, the published binary `MinecraftClient.exe` will be in `MinecraftClient/bin/Release/net10.0/win-x64/publish/`. ### Linux, macOS @@ -121,8 +139,9 @@ Requirements: - .NET 10 SDK - - [Install .NET on Linux](https://docs.microsoft.com/en-us/dotnet/core/install/linux) - - [Install .NET on macOS](https://docs.microsoft.com/en-us/dotnet/core/install/macos) + - [Install .NET on Linux](https://learn.microsoft.com/en-us/dotnet/core/install/linux) + - [Install .NET on Ubuntu](https://learn.microsoft.com/en-us/dotnet/core/install/linux-ubuntu-install) + - [Install .NET on macOS](https://learn.microsoft.com/en-us/dotnet/core/install/macos) #### Cloning using Git @@ -134,8 +153,25 @@ git clone https://github.com/MCCTeam/Minecraft-Console-Client.git --recursive ``` 3. Go to the folder you've cloned (should be `Minecraft-Console-Client`) -4. If you want to download translation resources, please check out [Download translation resources](#download-translation-resources-optional) -5. Run the following command to build the project: +4. Install the .NET 10 SDK. + + - On Ubuntu 24.04 LTS, use the built-in Ubuntu package feeds: + + ```bash + sudo apt-get update && \ + sudo apt-get install -y dotnet-sdk-10.0 + ``` + + - On macOS, the normal path is to use the official installer from the [.NET download page](https://dotnet.microsoft.com/en-us/download). Pick `Arm64` for Apple Silicon and `x64` for Intel Macs. + +5. If you want to download translation resources, please check out [Download translation resources](#download-translation-resources-optional) +6. Run the following command for a normal local build: + + ```bash + dotnet build MinecraftClient.sln -c Release + ``` + +7. Run the following command if you want a release-like published binary that matches the repo's CI workflow: - On Linux: @@ -166,6 +202,12 @@ If the build has succeeded, the compiled binary `MinecraftClient` will be in: - Linux: `MinecraftClient/bin/Release/net10.0/linux-x64/publish/` - macOS: `MinecraftClient/bin/Release/net10.0/osx-x64/publish/` +You can verify the SDK installation with: + +```bash +dotnet --info +``` + ## Using Docker Requirements: @@ -257,7 +299,7 @@ docker-compose down ## Run on Android -It is possible to run Minecraft Console Client on Android through Termux and Ubuntu 22.04, but it requires a manual setup with a lot of commands, so be careful not to skip any steps. Depending on your technical background, internet speed, and device speed, this can take anywhere from 10 to 20 minutes or more. +It is possible to run Minecraft Console Client on Android through Termux and Ubuntu 24.04, but it requires a manual setup with a lot of commands, so be careful not to skip any steps. Depending on your technical background, internet speed, and device speed, this can take anywhere from 10 to 20 minutes or more.

Tip

@@ -301,20 +343,20 @@ Go to [the latest Termux GitHub release](https://github.com/termux/termux-app/re
-#### Installing Ubuntu 22.04 +#### Installing Ubuntu 24.04 At this stage, you have 2 options: 1. Following this textual tutorial -2. Watching a [Youtube tutorial for installing Ubuntu](https://www.youtube.com/watch?v=5yit2t7smpM) +2. Watching a [YouTube tutorial for installing Ubuntu](https://www.youtube.com/watch?v=5yit2t7smpM)

Tip

-**If you decide to watch the Youtube tutorial, watch only up to `1:58`, the steps after are not needed and might just confuse you.** +**If you decide to watch the YouTube tutorial, watch only up to `1:58`. The steps after that are not needed here and might just confuse you.**
-In order to install Ubuntu 22.04 in Termux you require `wget` and `proot`, we're going to install them in the next step. +In order to install Ubuntu 24.04 in Termux you require `wget` and `proot`, and we are going to install them in the next step. Once you have Termux installed open it up and run the following command one after other (in order): @@ -380,7 +422,7 @@ Navigate to your `/root` home directory with the following command: cd /root ``` -Download a current .NET SDK tarball for your platform from Microsoft. For example: +Download a current .NET SDK tarball for your platform from Microsoft. Replace the placeholder below with the actual current download URL from the [.NET download page](https://dotnet.microsoft.com/en-us/download): ```bash wget @@ -394,7 +436,7 @@ wget

Tip

-**This tutorial assumes Ubuntu 22.04. If you are using a different distro, get the current SDK archive for your platform from the [.NET download page](https://dotnet.microsoft.com/en-us/download).** +**This tutorial assumes Ubuntu 24.04. If you are using a different distro, get the current SDK archive for your platform from the [.NET download page](https://dotnet.microsoft.com/en-us/download).**
@@ -404,7 +446,7 @@ Once the file has been downloaded, you need to run the following commands in ord

Warning

- **If you're using a different download link, update the file name in this command to match your version.** + **Replace the placeholder with the exact filename you downloaded. If you are using a different archive, update this value to match it exactly.**
@@ -423,7 +465,7 @@ Now we need to tell our shell to know where the `dotnet` command is, for future

Warning

-**You will need a basic knowledge of Nano text editor, if you do not know how to use it, watch this [Youtube video tutorial](https://www.youtube.com/watch?v=DLeATFgGM-A)** +**You will need a basic knowledge of the Nano text editor. If you do not know how to use it, watch this [YouTube tutorial](https://www.youtube.com/watch?v=DLeATFgGM-A).**
@@ -564,13 +606,13 @@ VPS stands for a **V**irtual **P**rivate **S**erver, it's basically a remote vir You can use a VPS for hosting a website, or a an app, or a game server, or your own VPN, or the Minecraft Console Client. -Here is a [Youtube video](https://youtu.be/42fwh_1KP_o) that explains it in more detail if you're interested. +Here is a [YouTube video](https://youtu.be/42fwh_1KP_o) that explains it in more detail if you are interested. ### Prerequisites -1. Gitbash (if you're on Windows) +1. Git Bash (if you are on Windows) - Download and install [Gitbash](https://git-scm.com/downloads). + Download and install [Git Bash](https://git-scm.com/downloads).

Tip

@@ -578,7 +620,7 @@ Here is a [Youtube video](https://youtu.be/42fwh_1KP_o) that explains it in more
-2. `ssh` and `ssh-keygen` commands (On Windows they're available with Gitbash, on macOs and Linux they should be available by default, it not, search on how to install them) +2. `ssh` and `ssh-keygen` commands (on Windows they are available with Git Bash; on macOS and Linux they should be available by default. If not, install them first.) 3. Basic knowledge of Linux shell commands, terminal emulator usage, SSH and Nano editor. @@ -613,7 +655,7 @@ The MCC is not expensive to run, so it can run on basically any hardware, you do

Danger

-**In this tutorial we will be using `Ubuntu 22.04`, make sure to select it as the OS when buying a VPS.** +**In this tutorial we will be using `Ubuntu 24.04 LTS`, so pick that family when choosing your VPS image.**
@@ -625,7 +667,7 @@ Some of the reliable and cheap hosting providers (sorted for price/performance):

Tip

- **Does not have Ubuntu 22.04 in the dropdown menu when ordering, you will have to re-install later or ask support to do it.** + **If Ubuntu 24.04 LTS is not in the dropdown when ordering, you may need to reinstall later or ask support to do it.**
@@ -701,7 +743,7 @@ Fill out the `Name` field with a name of your preference. ![VPS Name](/images/guide/VPS_Name.png) -For the **Application and OS images** select `Ubuntu Server 22.04 LTS (HVM), SSD Volume Type`. +For the **Application and OS images** select the current `Ubuntu Server 24.04 LTS` image. The exact AWS label may vary slightly by point release.

Danger

@@ -787,7 +829,7 @@ When you order the VPS, most likely you will be asked to provide the root accoun Other option is that you will get your login info in the email once the setup is done. -Once you have the root login account info, you need [Gitbash](https://git-scm.com/downloads) on Windows and `ssh` if you're on macOS or Linux (if you do not have it by some chance, search on how to install it, it is simple). +Once you have the root login account info, you need [Git Bash](https://git-scm.com/downloads) on Windows and `ssh` on macOS or Linux. If you're on Windows open `Git Bash`, on mac OS and Linux open a `Terminal` and type the following command: @@ -1009,9 +1051,9 @@ If did everything correctly you should see a Linux prompt and a welcome message You can do `whoami` to see your username. -Now you can install .NET Core 7 and MCC. +Now you can install the .NET 10 SDK and MCC. -### Installing .NET Core 7 +### Installing .NET 10 SDK

Tip

@@ -1019,12 +1061,6 @@ Now you can install .NET Core 7 and MCC.
-

Warning

- -**With newer versions of .NET Core 7 on Ubuntu 22.04 you might get the following error: `A fatal error occurred, the folder [/usr/share/dotnet/host/fxr] does not contain any version-numbered child folders`, if you get it, use [this solution](https://github.com/dotnet/sdk/issues/27082#issuecomment-1211143446)** - -
- Log in as the user you've created. Update the system packages and package manager repositories: @@ -1033,42 +1069,18 @@ Update the system packages and package manager repositories: sudo apt update -y && sudo apt upgrade -y ``` -Install `wget`: - -```bash -sudo apt install wget -y -``` - -Go to your home directory with: - -```bash -cd ~ -``` - -Download the Microsoft repository file: - -```bash -wget https://packages.microsoft.com/config/ubuntu/22.04/packages-microsoft-prod.deb -O packages-microsoft-prod.deb -``` - -Add Microsoft repositories to the package manager: - -```bash -sudo dpkg -i packages-microsoft-prod.deb -``` - -Remove the file, we do not need it anymore: - -```bash -rm packages-microsoft-prod.deb -``` - -Finally, install the current .NET SDK: +On Ubuntu 24.04 LTS, the official Microsoft docs say .NET is available directly from the Ubuntu package feeds, so you do not need to add the old Microsoft package repository for .NET 10. Install the SDK with: ```bash sudo apt-get update -y && sudo apt-get install -y dotnet-sdk-10.0 ``` +You can verify the installation with: + +```bash +dotnet --info +``` + Run the following command to check if everything was installed correctly: ```bash @@ -1091,7 +1103,7 @@ path-to-application: The path to an application .dll file to execute. ``` -If you do not get this output and the installation was not successful, [try other methods](https://docs.microsoft.com/en-us/dotnet/core/install/linux-ubuntu#2204). +If you do not get this output and the installation was not successful, [try other methods](https://learn.microsoft.com/en-us/dotnet/core/install/linux-ubuntu-install). If it was successful, you can now install MCC. @@ -1105,7 +1117,7 @@ Now that you have the .NET SDK and a user account, install the `screen` utility.
-You also can learn about the screen command from [this Youtube tutorial](https://youtu.be/_ZJiEX4rmN4). +You can also learn about the `screen` command from [this YouTube tutorial](https://youtu.be/_ZJiEX4rmN4). To install the `screen` execute the following command: diff --git a/docs/guide/websocket/Commands.md b/docs/guide/websocket/Commands.md deleted file mode 100644 index 25f196e7..00000000 --- a/docs/guide/websocket/Commands.md +++ /dev/null @@ -1,5 +0,0 @@ -# WebSocket Commands - -This page is archived. - -The command list that used to live here documented an older WebSocket bot that is no longer present in the current MCC codebase. There is no current in-tree implementation backing those commands, so keeping the old catalog here as if it were active would be misleading. diff --git a/docs/guide/websocket/Events.md b/docs/guide/websocket/Events.md deleted file mode 100644 index 5b17eaec..00000000 --- a/docs/guide/websocket/Events.md +++ /dev/null @@ -1,5 +0,0 @@ -# WebSocket Events - -This page is archived. - -The event list that used to live here documented an older WebSocket bot protocol that is not implemented in the current MCC tree. The old event names and payloads no longer match the codebase, so this page should not be treated as current API documentation. diff --git a/docs/guide/websocket/README.md b/docs/guide/websocket/README.md deleted file mode 100644 index deb6d0f5..00000000 --- a/docs/guide/websocket/README.md +++ /dev/null @@ -1,7 +0,0 @@ -# WebSocket Chat Bot - -The in-tree WebSocket chat bot is not part of the current MCC codebase. - -These pages are kept only as historical placeholders because older documentation linked to them. Current mainline builds do not ship a `WebSocketBot`, and there is no supported WebSocket protocol to configure or rely on in the current project state. - -If this feature returns in a future release, this section should be rewritten from the implementation instead of from the old archived docs.