helpy4/Minecraft-Console-Client
1
0
Fork 0
mirror of https://github.com/MCCTeam/Minecraft-Console-Client synced 2026-08-15 13:04:36 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 1

Lint and format docs/guide markdown with mdformat, fix empty warning in chat-bots.md

Browse source 
Co-authored-by: milutinke <441903+milutinke@users.noreply.github.com>
Agent-Logs-Url: https://github.com/MCCTeam/Minecraft-Console-Client/sessions/3040312a-cbdf-43fe-918b-133ef19fc30f
This commit is contained in:
copilot-swe-agent[bot] 2026-03-25 16:58:16 +00:00
parent a242f97c14
commit cb4eb15784
12 changed files with 3252 additions and 3286 deletions
Download patch file Download diff file Expand all files Collapse all files

105
docs/guide/README.md
View file

@ -32,46 +32,63 @@ It was originally made by [ORelio](https://github.com/ORelio) in 2012 on the [Mi
## Features
- Chat
- Chat
- Send and receive chat messages
- [Log chat history](chat-bots.md#chat-log)
- [Get alerted on certain keywords](chat-bots.md#alerts)
- [Auto Respond](chat-bots.md#auto-respond)
- Send and receive chat messages
- [Log chat history](chat-bots.md#chat-log)
- [Get alerted on certain keywords](chat-bots.md#alerts)
- [Auto Respond](chat-bots.md#auto-respond)
- Microsoft account authentication with 2FA support (OAuth 2.0 device code flow)
- [Anti AFK](chat-bots.md#anti-afk)
- [Auto Relog](chat-bots.md#auto-relog)
- [Script Scheduler](chat-bots.md#script-scheduler)
- [Remote Control](chat-bots.md#remote-control)
- [Auto Respond](chat-bots.md#auto-respond)
- [Auto Attack](chat-bots.md#auto-attack)
- [Auto Fishing](chat-bots.md#auto-fishing)
- [Auto Eat](chat-bots.md#auto-eat)
- [Auto Craft](chat-bots.md#auto-craft)
- [Mailer Bot](chat-bots.md#mailer)
- [Auto Drop](chat-bots.md#auto-drop)
- [Replay Mod](chat-bots.md#replay-mod)
- [API for creating Bots in C#](creating-bots.md#creating-chat-bots)
- [Docker Support](installation.md#using-docker)
- [Inventory Handling](usage.md#inventory)
- [Terrain Traversing](usage.md#move)
- Entity Handling
- Microsoft account authentication with 2FA support (OAuth 2.0 device code flow)
- [Anti AFK](chat-bots.md#anti-afk)
- [Auto Relog](chat-bots.md#auto-relog)
- [Script Scheduler](chat-bots.md#script-scheduler)
- [Remote Control](chat-bots.md#remote-control)
- [Auto Respond](chat-bots.md#auto-respond)
- [Auto Attack](chat-bots.md#auto-attack)
- [Auto Fishing](chat-bots.md#auto-fishing)
- [Auto Eat](chat-bots.md#auto-eat)
- [Auto Craft](chat-bots.md#auto-craft)
- [Mailer Bot](chat-bots.md#mailer)
- [Auto Drop](chat-bots.md#auto-drop)
- [Replay Mod](chat-bots.md#replay-mod)
- [API for creating Bots in C#](creating-bots.md#creating-chat-bots)
- [Docker Support](installation.md#using-docker)
- [Inventory Handling](usage.md#inventory)
- [Terrain Traversing](usage.md#move)
- Entity Handling
_Note: Some of these features are disabled by default. You need to enable them in the configuration file, and some also require additional setup._
## Why Minecraft Console Client?
- Easy to use
- Helpful community
- Open-Source
- Fast performance
- Easy Scripting/Automation
- Cross-Platform
- Docker Support
- 10 years of continuous development
- Active contributors
- Widely used
- Easy to use
- Helpful community
- Open-Source
- Fast performance
- Easy Scripting/Automation
- Cross-Platform
- Docker Support
- 10 years of continuous development
- Active contributors
- Widely used
## Quick Intro
@ -81,13 +98,13 @@ If you do not want to read through the documentation right away, the community h
Installation:
- [Installation on Windows by Daenges](https://www.youtube.com/watch?v=BkCqOCa2uQw)
- [Installation on Windows + Auto AFK and More by Dexter113](https://www.youtube.com/watch?v=FxJ0KFIHDrY)
- [Installation on Windows by Daenges](https://www.youtube.com/watch?v=BkCqOCa2uQw)
- [Installation on Windows + Auto AFK and More by Dexter113](https://www.youtube.com/watch?v=FxJ0KFIHDrY)
Using Commands, Scripts and other features:
- [Minecraft Console Client | Tutorial | Commands, Scripts, AppVars, Matches, Tasks and C# Scripts by Daenges](https://youtu.be/JbDpwwETEnU)
- [Console Client Tutorial - Scripting by Zixxter](https://www.youtube.com/watch?v=XE7rYBFJxn0)
- [Minecraft Console Client | Tutorial | Commands, Scripts, AppVars, Matches, Tasks and C# Scripts by Daenges](https://youtu.be/JbDpwwETEnU)
- [Console Client Tutorial - Scripting by Zixxter](https://www.youtube.com/watch?v=XE7rYBFJxn0)
## Getting Help
@ -97,8 +114,8 @@ Click [here](https://github.com/MCCTeam/Minecraft-Console-Client/discussions) to
### Before getting help
- **Please use the search option here or in the discussion section and read the documentation so we avoid duplicate questions. Thank you!**
- **Please be kind and patient, respect others as they're the ones using their time to help you**
- **Please use the search option here or in the discussion section and read the documentation so we avoid duplicate questions. Thank you!**
- **Please be kind and patient, respect others as they're the ones using their time to help you**
## Bugs, Ideas, Feature Requests
@ -112,8 +129,8 @@ If you are reporting a bug, be as specific as possible. Explain how to reproduce
### Before submitting
- **Please use the search option here or in the `Issues` section and read the documentation so we avoid duplicate questions/ideas/reports. Thank you!**
- **Please be kind, patient and respect others. Thank you!**
- **Please use the search option here or in the `Issues` section and read the documentation so we avoid duplicate questions/ideas/reports. Thank you!**
- **Please be kind, patient and respect others. Thank you!**
## AI-Assisted Development
@ -137,10 +154,11 @@ If there was a major game update, and the MCC hasn't been updated to support the
### Path-Finding and Physics
MCC now uses A* path-finding together with a physics-based movement system for movement and collision handling.
MCC now uses A\* path-finding together with a physics-based movement system for movement and collision handling.
What is supported and works:
- Terrain navigation with A* path-finding and physics-driven movement
- Terrain navigation with A\* path-finding and physics-driven movement
- Collision-aware movement using real block shapes
- Automatic jumping when the path requires moving up
- Step-up movement for slabs and similar low obstacles
@ -150,6 +168,7 @@ What is supported and works:
- Gravity, friction, and block speed modifiers such as ice, soul sand, soul soil, and honey blocks
Current limitations:
- Path-finding is still block-based, so very complex terrain can still fail
- Automatic route planning still avoids underwater routes by default, so this is not a full swimming path-finder yet
- Knockback and other external velocity effects are not simulated yet

258
docs/guide/ai-assisted-development.md
View file

@ -28,31 +28,31 @@ If you develop on Windows, use WSL2. This workflow is built around Unix-style sh
## Index
- [What This Workflow Covers](#what-this-workflow-covers)
- [Setup](#setup)
- [How The Harness Works](#how-the-harness-works)
- [Repository Tools](#repository-tools)
- [Skills](#skills)
- [Standard Development Loop](#standard-development-loop)
- [Testing And Validation](#testing-and-validation)
- [Version Adaptation Notes](#version-adaptation-notes)
- [Example Workflows](#example-workflows)
- [What This Workflow Covers](#what-this-workflow-covers)
- [Setup](#setup)
- [How The Harness Works](#how-the-harness-works)
- [Repository Tools](#repository-tools)
- [Skills](#skills)
- [Standard Development Loop](#standard-development-loop)
- [Testing And Validation](#testing-and-validation)
- [Version Adaptation Notes](#version-adaptation-notes)
- [Example Workflows](#example-workflows)
## What This Workflow Covers
This is the workflow for:
- local MCC development
- local offline server testing
- AI-assisted debugging
- bot authoring
- protocol and version adaptation work
- documentation work that should still follow the same disciplined loop
- local MCC development
- local offline server testing
- AI-assisted debugging
- bot authoring
- protocol and version adaptation work
- documentation work that should still follow the same disciplined loop
It is built around two layers:
- repo tools in `tools/`, which do the actual work
- AI skills in `.skills/`, which tell the agent when and how to use those tools
- repo tools in `tools/`, which do the actual work
- AI skills in `.skills/`, which tell the agent when and how to use those tools
## Setup
@ -100,9 +100,9 @@ echo $SHELL
Notes:
- Bash is the normal baseline on Linux.
- Zsh is the default interactive shell on modern macOS.
- The helper script `tools/mcc-env.sh` can be sourced from either `~/.bashrc` or `~/.zshrc`.
- Bash is the normal baseline on Linux.
- Zsh is the default interactive shell on modern macOS.
- The helper script `tools/mcc-env.sh` can be sourced from either `~/.bashrc` or `~/.zshrc`.
</details>
@ -187,9 +187,9 @@ dotnet --version
References:
- [Install .NET on Ubuntu](https://learn.microsoft.com/dotnet/core/install/linux-ubuntu)
- [Install .NET on Debian](https://learn.microsoft.com/dotnet/core/install/linux-debian)
- [Homebrew `dotnet-sdk` cask](https://formulae.brew.sh/cask/dotnet-sdk)
- [Install .NET on Ubuntu](https://learn.microsoft.com/dotnet/core/install/linux-ubuntu)
- [Install .NET on Debian](https://learn.microsoft.com/dotnet/core/install/linux-debian)
- [Homebrew `dotnet-sdk` cask](https://formulae.brew.sh/cask/dotnet-sdk)
</details>
@ -232,9 +232,9 @@ java -version
References:
- [Ubuntu `openjdk-21-jdk` package](https://packages.ubuntu.com/noble/openjdk-21-jdk)
- [Arch `jdk21-openjdk` package](https://archlinux.org/packages/extra/x86_64/jdk21-openjdk/)
- [Homebrew `openjdk@21` formula](https://formulae.brew.sh/formula/openjdk@21)
- [Ubuntu `openjdk-21-jdk` package](https://packages.ubuntu.com/noble/openjdk-21-jdk)
- [Arch `jdk21-openjdk` package](https://archlinux.org/packages/extra/x86_64/jdk21-openjdk/)
- [Homebrew `openjdk@21` formula](https://formulae.brew.sh/formula/openjdk@21)
</details>
@ -272,9 +272,9 @@ python3 --version
References:
- [Ubuntu `python3` package](https://packages.ubuntu.com/noble/python/python3)
- [Arch `python` package](https://archlinux.org/packages/core/x86_64/python/)
- [Homebrew Python formula](https://formulae.brew.sh/formula/python@3.14)
- [Ubuntu `python3` package](https://packages.ubuntu.com/noble/python/python3)
- [Arch `python` package](https://archlinux.org/packages/core/x86_64/python/)
- [Homebrew Python formula](https://formulae.brew.sh/formula/python@3.14)
</details>
@ -338,8 +338,8 @@ tools/decompile.sh --version 1.20.6
That creates the paths used by the harness and the version-adaptation workflow:
- `$MCC_SERVERS/1.20.6/server.jar`
- `MinecraftOfficial/1.20.6-decompiled/`
- `$MCC_SERVERS/1.20.6/server.jar`
- `MinecraftOfficial/1.20.6-decompiled/`
If you are doing protocol work, this step is not optional.
@ -362,16 +362,16 @@ source ~/.bashrc
This gives you the helper functions used by the workflow:
- `mc-start`
- `mc-stop`
- `mc-cmd`
- `mc-log`
- `mc-rcon`
- `mcc-build`
- `mcc-run`
- `mcc-cmd`
- `mcc-kill`
- `mcc-reload`
- `mc-start`
- `mc-stop`
- `mc-cmd`
- `mc-log`
- `mc-rcon`
- `mcc-build`
- `mcc-run`
- `mcc-cmd`
- `mcc-kill`
- `mcc-reload`
</details>
@ -423,11 +423,11 @@ AI agents do not get a rich interactive terminal in the same way a human does. T
The moving parts are:
- a local Minecraft server running in `tmux`
- `mc-rcon` for server-side commands such as `/op`, `/give`, `/summon`, or gamerule setup
- MCC started with `MCC_FILE_INPUT=1`
- `FileInputBot`, which watches `mcc_input.txt` and turns file lines into MCC commands or server chat
- logs from MCC and the local server, which the agent can inspect between runs
- a local Minecraft server running in `tmux`
- `mc-rcon` for server-side commands such as `/op`, `/give`, `/summon`, or gamerule setup
- MCC started with `MCC_FILE_INPUT=1`
- `FileInputBot`, which watches `mcc_input.txt` and turns file lines into MCC commands or server chat
- logs from MCC and the local server, which the agent can inspect between runs
The result is simple: the agent can change code, rebuild, start the app, inject commands, and read the result without waiting for a human to sit in the terminal.
@ -435,51 +435,51 @@ The result is simple: the agent can change code, rebuild, start the app, inject
These are the repo-level tools that make the workflow practical.
| Path | Purpose |
| --- | --- |
| `tools/mcc-env.sh` | Loads the shell helper functions used for the normal loop. |
| `tools/start-server.sh` | Starts a local Minecraft server in a named `tmux` session with a FIFO for stdin. |
| `tools/mc-rcon.sh` | Sends RCON commands to the local server using `python3`. |
| `tools/decompile.sh` | Downloads `MinecraftDecompiler.jar` if needed, decompiles the requested Minecraft version, and fetches `server.jar` for server-side work. |
| `tools/diff_registries.py` | Compares registries between two Minecraft versions to show which palettes need updates. |
| `tools/gen_item_palette.py` | Generates item palette source from decompiled or reported registry data. |
| `tools/gen_block_palette.py` | Generates block palette source from authoritative block reports. |
| `tools/gen_entity_palette.py` | Generates entity palette source from registry reports. |
| `tools/gen_entity_metadata_palette.py` | Generates entity metadata palette source from serializer registration order. |
| `tools/gen_command_argument_registry.py` | Helps update modern declare-commands registry order. |
| `tools/gen_block_shapes.py` | Downloads and compacts collision shape data for physics support. |
| Path | Purpose |
| ---------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| `tools/mcc-env.sh` | Loads the shell helper functions used for the normal loop. |
| `tools/start-server.sh` | Starts a local Minecraft server in a named `tmux` session with a FIFO for stdin. |
| `tools/mc-rcon.sh` | Sends RCON commands to the local server using `python3`. |
| `tools/decompile.sh` | Downloads `MinecraftDecompiler.jar` if needed, decompiles the requested Minecraft version, and fetches `server.jar` for server-side work. |
| `tools/diff_registries.py` | Compares registries between two Minecraft versions to show which palettes need updates. |
| `tools/gen_item_palette.py` | Generates item palette source from decompiled or reported registry data. |
| `tools/gen_block_palette.py` | Generates block palette source from authoritative block reports. |
| `tools/gen_entity_palette.py` | Generates entity palette source from registry reports. |
| `tools/gen_entity_metadata_palette.py` | Generates entity metadata palette source from serializer registration order. |
| `tools/gen_command_argument_registry.py` | Helps update modern declare-commands registry order. |
| `tools/gen_block_shapes.py` | Downloads and compacts collision shape data for physics support. |
There is one more piece worth calling out:
- `MinecraftClient/ChatBots/FileInputBot.cs` is what makes file-driven command injection possible.
- It is loaded when `MCC_FILE_INPUT=1` is set.
- `mcc-run` in `tools/mcc-env.sh` already sets that flag for you.
- `MinecraftClient/ChatBots/FileInputBot.cs` is what makes file-driven command injection possible.
- It is loaded when `MCC_FILE_INPUT=1` is set.
- `mcc-run` in `tools/mcc-env.sh` already sets that flag for you.
## Skills
The tools above do the work. The skills in `.skills/` tell the AI when to use them and what good output looks like.
| Skill | What it is for | Notes |
| --- | --- | --- |
| `mcc-dev-workflow` | The default build, run, debug, and local server loop. | This is the skill to use for most day-to-day MCC debugging. It assumes WSL, `tmux`, Java, and the local harness. |
| `mcc-integration-testing` | Repeatable end-to-end testing against a local offline server. | This skill bundles its own scripts under `.skills/mcc-integration-testing/scripts/`. Those are skill resources, not top-level repo scripts. |
| `mcc-version-adaptation` | Protocol and palette updates for new Minecraft versions. | Use this when routing, registries, metadata, palettes, or structured components change. |
| `mcc-chatbot-authoring` | Authoring or repairing built-in bots and standalone `/script` bots. | This skill bundles references and templates under `.skills/mcc-chatbot-authoring/`. It defaults to standalone `/script` bots unless built-in wiring is requested. |
| `csharp-best-practices` | C# 14 / .NET 10 coding guidance for this repo. | Use it whenever the change touches MCC runtime code. |
| `humanizer` | Documentation and prose cleanup. | Use it for docs, guides, release notes, and anything that starts sounding machine-written. |
| `mcc-prompt-engineer` | Generating structured prompts for MCC development tasks. | Manually triggered. Interviews the user, explores the codebase, and produces a self-contained prompt with reasoning framework, skill references, and sub-agent directives. |
| `skill-creator` | Creating or evolving skills themselves. | This is for improving the AI workflow, not for normal MCC feature work. |
| Skill | What it is for | Notes |
| ------------------------- | ------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `mcc-dev-workflow` | The default build, run, debug, and local server loop. | This is the skill to use for most day-to-day MCC debugging. It assumes WSL, `tmux`, Java, and the local harness. |
| `mcc-integration-testing` | Repeatable end-to-end testing against a local offline server. | This skill bundles its own scripts under `.skills/mcc-integration-testing/scripts/`. Those are skill resources, not top-level repo scripts. |
| `mcc-version-adaptation` | Protocol and palette updates for new Minecraft versions. | Use this when routing, registries, metadata, palettes, or structured components change. |
| `mcc-chatbot-authoring` | Authoring or repairing built-in bots and standalone `/script` bots. | This skill bundles references and templates under `.skills/mcc-chatbot-authoring/`. It defaults to standalone `/script` bots unless built-in wiring is requested. |
| `csharp-best-practices` | C# 14 / .NET 10 coding guidance for this repo. | Use it whenever the change touches MCC runtime code. |
| `humanizer` | Documentation and prose cleanup. | Use it for docs, guides, release notes, and anything that starts sounding machine-written. |
| `mcc-prompt-engineer` | Generating structured prompts for MCC development tasks. | Manually triggered. Interviews the user, explores the codebase, and produces a self-contained prompt with reasoning framework, skill references, and sub-agent directives. |
| `skill-creator` | Creating or evolving skills themselves. | This is for improving the AI workflow, not for normal MCC feature work. |
The important distinction is this:
- repo tools are executable scripts and source files
- skills are instructions, references, templates, and workflow constraints for the AI
- repo tools are executable scripts and source files
- skills are instructions, references, templates, and workflow constraints for the AI
Some skills also carry their own bundled resources:
- `mcc-integration-testing` bundles scripts and a command matrix reference
- `mcc-chatbot-authoring` bundles references and bot templates
- `skill-creator` bundles scripts, eval tooling, and reviewer assets
- `mcc-integration-testing` bundles scripts and a command matrix reference
- `mcc-chatbot-authoring` bundles references and bot templates
- `skill-creator` bundles scripts, eval tooling, and reviewer assets
## Standard Development Loop
@ -538,9 +538,9 @@ mcc-cmd "/gamemode creative"
Behavior:
- lines starting with `/` are sent as server commands or chat
- lines without `/` are treated as MCC internal commands first
- if a line is not an MCC internal command, it falls back to normal chat sending
- lines starting with `/` are sent as server commands or chat
- lines without `/` are treated as MCC internal commands first
- if a line is not an MCC internal command, it falls back to normal chat sending
### 6. Inspect the result
@ -562,19 +562,19 @@ There are two main testing styles in this workflow.
This is enough for smaller changes:
- join the local server
- grant operator privileges with `mc-rcon`
- run internal MCC commands through `mcc-cmd`
- trigger gameplay or server state changes through `mc-rcon`
- inspect logs for parsing errors, disconnects, or wrong output
- join the local server
- grant operator privileges with `mc-rcon`
- run internal MCC commands through `mcc-cmd`
- trigger gameplay or server state changes through `mc-rcon`
- inspect logs for parsing errors, disconnects, or wrong output
Typical manual checks:
- inventory listing and creative item injection
- entity tracking after `summon`
- terrain and chunk handling after join
- chat and command flow
- explosion, particle, and sound events
- inventory listing and creative item injection
- entity tracking after `summon`
- terrain and chunk handling after join
- chat and command flow
- explosion, particle, and sound events
### Scripted full-spectrum testing
@ -584,21 +584,21 @@ Treat those scripts as skill-owned resources. Read the skill before running them
That skill is designed for repeatable offline validation of:
- chat
- slash commands
- MCC internal commands
- inventory handling
- entity handling
- particles and sounds
- TNT and explosion handling
- chat
- slash commands
- MCC internal commands
- inventory handling
- entity handling
- particles and sounds
- TNT and explosion handling
Server settings that matter for AI-driven offline testing:
- `eula=true`
- `online-mode=false`
- `enforce-secure-profile=false`
- `enable-rcon=true`
- `rcon.password=test123`
- `eula=true`
- `online-mode=false`
- `enforce-secure-profile=false`
- `enable-rcon=true`
- `rcon.password=test123`
If those are wrong, the loop gets noisy fast.
@ -608,19 +608,19 @@ Version work needs a stricter process than normal bug fixing.
The important rule is simple:
- for newer versions, especially `1.21.9+`, use server data reports as the authority for items and blocks
- use decompiled source for implementation details, field order, codecs, and serializer logic
- do not stop at a palette diff; finish with a build and a live server test
- for newer versions, especially `1.21.9+`, use server data reports as the authority for items and blocks
- use decompiled source for implementation details, field order, codecs, and serializer logic
- do not stop at a palette diff; finish with a build and a live server test
The usual order is:
1. `tools/decompile.sh --version <ver>`
2. generate server reports from `server.jar`
3. run `tools/diff_registries.py`
4. regenerate the palettes that actually changed
5. update version routing and packet handling
6. build MCC
7. test against the real target version
1. generate server reports from `server.jar`
1. run `tools/diff_registries.py`
1. regenerate the palettes that actually changed
1. update version routing and packet handling
1. build MCC
1. test against the real target version
That is exactly the sort of work `mcc-version-adaptation` is meant to guide.
@ -632,8 +632,8 @@ These are four common patterns this guide is meant to support.
Use skills:
- `mcc-dev-workflow`
- `csharp-best-practices`
- `mcc-dev-workflow`
- `csharp-best-practices`
Typical loop:
@ -656,18 +656,18 @@ mcc-reload
Use skills:
- `mcc-chatbot-authoring`
- `csharp-best-practices`
- `mcc-dev-workflow`
- `mcc-chatbot-authoring`
- `csharp-best-practices`
- `mcc-dev-workflow`
Typical flow:
1. Decide whether this should be a standalone `/script` bot or a built-in bot.
2. Use the authoring skill's references and templates.
3. Build MCC.
4. Start a local server and join it.
5. Test the bot behavior through live commands, chat, or event-driven actions.
6. Make sure cleanup paths such as `OnUnload()` are correct.
1. Use the authoring skill's references and templates.
1. Build MCC.
1. Start a local server and join it.
1. Test the bot behavior through live commands, chat, or event-driven actions.
1. Make sure cleanup paths such as `OnUnload()` are correct.
For standalone script work, the skill defaults to `/script` unless built-in repo wiring is explicitly needed.
@ -675,9 +675,9 @@ For standalone script work, the skill defaults to `/script` unless built-in repo
Use skills:
- `mcc-version-adaptation`
- `mcc-dev-workflow`
- `mcc-integration-testing`
- `mcc-version-adaptation`
- `mcc-dev-workflow`
- `mcc-integration-testing`
Typical flow:
@ -706,12 +706,12 @@ Then regenerate the palettes that changed, update routing, build MCC, start a lo
Use skills:
- `humanizer`
- `skill-creator`, if you are changing the skills rather than just the docs
- `humanizer`
- `skill-creator`, if you are changing the skills rather than just the docs
Typical flow:
1. Re-read the relevant skill files and repo tools.
2. Update the guide so the written process matches the real process.
3. Keep the instructions concrete enough that another contributor can follow them without guessing.
4. If the workflow itself changed, update the relevant skill too instead of leaving the docs ahead of the automation.
1. Update the guide so the written process matches the real process.
1. Keep the instructions concrete enough that another contributor can follow them without guessing.
1. If the workflow itself changed, update the relevant skill too instead of leaving the docs ahead of the automation.

3138
docs/guide/chat-bots.md
View file

File diff suppressed because it is too large Load diff

1343
docs/guide/configuration.md
View file

File diff suppressed because it is too large Load diff

6
docs/guide/contibuting.md
View file

@ -12,9 +12,9 @@ You can also use the guide in the [GitHub repository wiki](https://github.com/MC
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
- code and bot work in the main MCC client
- documentation updates in `docs/`
- translations through Crowdin
## Translations

42
docs/guide/creating-bots.md
View file

@ -4,12 +4,12 @@ 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](#notes)
- [Requirements](#requirements)
- [Quick Introduction](#quick-introduction)
- [Examples](#examples)
- [AI-Assisted Bot Authoring](#ai-assisted-bot-authoring)
- [C# API](#c#-api)
## Notes
@ -23,19 +23,19 @@ title: Creating Chat Bots
## Requirements
- A basic knowledge of C# programming language
- A text editor
- 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)
- [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/)
- [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
@ -192,24 +192,24 @@ If you are using an AI coding agent on this repository, use the `mcc-chatbot-aut
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)
- [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
- 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
- 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

1
docs/guide/creating-text-script.md
View file

@ -11,6 +11,7 @@ Application variables defined with the `set` command or in the `[AppVars]` confi
## Example
`sample-script.txt`: Send a hello message, wait 60 seconds and disconnect from server.
```
# This is a sample script for Minecraft Console Client
# Any line beginning with "#" is ignored and treated as a comment.

260
docs/guide/installation.md
View file

@ -4,19 +4,19 @@ title: Installation
# Installation
- [YouTube Tutorials](#youtube-tutorials)
- [Download a compiled binary](#download-a-compiled-binary)
- [Building from the source code](#building-from-the-source-code)
- [Run using Docker](#using-docker)
- [Run on Android](#run-on-android)
- [Run MCC 24/7 on a VPS](#run-on-a-vps)
- [YouTube Tutorials](#youtube-tutorials)
- [Download a compiled binary](#download-a-compiled-binary)
- [Building from the source code](#building-from-the-source-code)
- [Run using Docker](#using-docker)
- [Run on Android](#run-on-android)
- [Run MCC 24/7 on a VPS](#run-on-a-vps)
## YouTube Tutorials
If you're not the kind of person that likes textual tutorials, our community has made video tutorials available on YouTube.
- [Installation on Windows by Daenges](https://www.youtube.com/watch?v=BkCqOCa2uQw)
- [Installation on Windows + Auto AFK and More by Dexter113](https://www.youtube.com/watch?v=FxJ0KFIHDrY)
- [Installation on Windows by Daenges](https://www.youtube.com/watch?v=BkCqOCa2uQw)
- [Installation on Windows + Auto AFK and More by Dexter113](https://www.youtube.com/watch?v=FxJ0KFIHDrY)
## Download a compiled binary
@ -24,7 +24,7 @@ You can download a compiled binary of the latest build from the [GitHub Releases
## Building from the source code
We recommend you to download our precompiled binary file from [GitHub](https://github.com/MCCTeam/Minecraft-Console-Client/releases).
We recommend you to download our precompiled binary file from [GitHub](https://github.com/MCCTeam/Minecraft-Console-Client/releases).
However, if you want to build the program from source code, please follow the guide.
@ -35,8 +35,8 @@ However, if you want to build the program from source code, please follow the gu
Requirements:
- [Git](https://www.git-scm.com/)
- [.NET 10 SDK](https://dotnet.microsoft.com/en-us/download) or [Visual Studio](https://visualstudio.microsoft.com/) configured for C# app development
- [Git](https://www.git-scm.com/)
- [.NET 10 SDK](https://dotnet.microsoft.com/en-us/download) or [Visual Studio](https://visualstudio.microsoft.com/) configured for C# app development
::: tip
If you want to modify the code and you are new to C# or programming in general, the tutorials listed in [Creating Bots](creating-bots.md#requirements) are a good starting point.
@ -47,9 +47,9 @@ If you want to modify the code and you are new to C# or programming in general,
Install [Git](https://www.git-scm.com/)
1. Make a new folder where you want to keep the source code
2. Then open it up, hold `SHIFT` and do a `right-click` on the empty white space in the folder
3. Click on `Git Bash Here` in the context menu
4. Clone the [GitHub repository](https://github.com/MCCTeam/Minecraft-Console-Client) by running:
1. Then open it up, hold `SHIFT` and do a `right-click` on the empty white space in the folder
1. Click on `Git Bash Here` in the context menu
1. Clone the [GitHub repository](https://github.com/MCCTeam/Minecraft-Console-Client) by running:
```bash
git clone https://github.com/MCCTeam/Minecraft-Console-Client.git --recursive
@ -62,41 +62,41 @@ git submodule update --init --recursive
```
5. Once the repository has been cloned, you can close the `Git Bash` terminal emulator
6. Open up the new cloned folder
1. Open up the new cloned folder
#### Download translation resources (optional)
1. Visit [MCC project's homepage on Crowdin](https://crowdin.com/project/minecraft-console-client).
2. You will need to log in to your Crowdin account in order to download.
3. Click on the language you want to download the translation for.
4. Find `MinecraftClient` -> `Resources` -> `Translations` -> `MCC in-app text`
5. Click the button `•••` at the end of the line.
6. Click Download and save the file to folder `/MinecraftClient/Resources/Translations/`.
7. Find `MinecraftClient` -> `Resources` -> `ConfigComments` -> `Comments in the settings file`
8. Click the button `•••` at the end of the line.
9. Click Download and save the file to folder `/MinecraftClient/Resources/ConfigComments/`.
10. Find `MinecraftClient` -> `Resources` -> `AsciiArt` -> `ASCII Arts (Please use fixed-width fonts for editing)`
11. Click the button `•••` at the end of the line.
12. Click Download and save the file to folder `/MinecraftClient/Resources/AsciiArt/`.
13. If you need to download a translation in another language, go to step 3 to continue.
1. You will need to log in to your Crowdin account in order to download.
1. Click on the language you want to download the translation for.
1. Find `MinecraftClient` -> `Resources` -> `Translations` -> `MCC in-app text`
1. Click the button `•••` at the end of the line.
1. Click Download and save the file to folder `/MinecraftClient/Resources/Translations/`.
1. Find `MinecraftClient` -> `Resources` -> `ConfigComments` -> `Comments in the settings file`
1. Click the button `•••` at the end of the line.
1. Click Download and save the file to folder `/MinecraftClient/Resources/ConfigComments/`.
1. Find `MinecraftClient` -> `Resources` -> `AsciiArt` -> `ASCII Arts (Please use fixed-width fonts for editing)`
1. Click the button `•••` at the end of the line.
1. Click Download and save the file to folder `/MinecraftClient/Resources/AsciiArt/`.
1. If you need to download a translation in another language, go to step 3 to continue.
#### Building using the Visual Studio
1. Open up the `MinecraftClient.sln` via Visual Studio
2. Right click on `MinecraftClient` solution in the `Solution Explorer`
3. Click on `Properties`
4. Open up the `Build` tab and select configuration `Release`
5. Press `CTRL + S` and close the file
6. Right click on `MinecraftClient` solution in the `Solution Explorer`
7. Click `Build`
1. Right click on `MinecraftClient` solution in the `Solution Explorer`
1. Click on `Properties`
1. Open up the `Build` tab and select configuration `Release`
1. Press `CTRL + S` and close the file
1. Right click on `MinecraftClient` solution in the `Solution Explorer`
1. Click `Build`
If the build succeeds, the published binary `MinecraftClient.exe` will be in `MinecraftClient/bin/Release/net10.0/win-x64/publish/`.
#### Building using .NET manually without Visual Studio
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. Install the .NET 10 SDK if you do not already have it. The easiest current option on Windows is:
1. Open the PowerShell (`Right-Click` on the whitespace and click `Open PowerShell`, or in Windows Explorer: `File -> Open PowerShell`)
1. 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
@ -131,82 +131,84 @@ If the publish step succeeds, the published binary `MinecraftClient.exe` will be
<div class="custom-container tip"><p class="custom-container-title">Tip</p>
**If you're using Linux we will assume that you should be able to install git on your own. If you don't know how, search it up for your distribution, it should be easy. (Debian based distros: `apt install git`, Arch based: `pacman -S git`)**
**If you're using Linux we will assume that you should be able to install git on your own. If you don't know how, search it up for your distribution, it should be easy. (Debian based distros: `apt install git`, Arch based: `pacman -S git`)**
</div>
Requirements:
- Git
- Git
- Linux:
- Linux:
- [Install Git on macOS](https://git-scm.com/download/mac)
- [Install Git on macOS](https://git-scm.com/download/mac)
- .NET 10 SDK
- .NET 10 SDK
- [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)
- [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
1. Open up a terminal emulator and navigate to the folder where you will store the MCC
2. Recursively clone the [GitHub repository](https://github.com/MCCTeam/Minecraft-Console-Client) by running:
1. Recursively clone the [GitHub repository](https://github.com/MCCTeam/Minecraft-Console-Client) by running:
```bash
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. Install the .NET 10 SDK.
- On Ubuntu 24.04 LTS, use the built-in Ubuntu package feeds:
1. Install the .NET 10 SDK.
```bash
sudo apt-get update && \
sudo apt-get install -y dotnet-sdk-10.0
```
- On Ubuntu 24.04 LTS, use the built-in Ubuntu package feeds:
- 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.
```bash
sudo apt-get update && \
sudo apt-get install -y dotnet-sdk-10.0
```
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:
- 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.
```bash
dotnet build MinecraftClient.sln -c Release
```
1. If you want to download translation resources, please check out [Download translation resources](#download-translation-resources-optional)
7. Run the following command if you want a release-like published binary that matches the repo's CI workflow:
1. Run the following command for a normal local build:
- On Linux:
```bash
dotnet build MinecraftClient.sln -c Release
```
```bash
dotnet publish MinecraftClient.sln -f net10.0 -r linux-x64 --self-contained=true -c Release -p:UseAppHost=true -p:IncludeNativeLibrariesForSelfExtract=true -p:EnableCompressionInSingleFile=true -p:DebugType=Embedded
```
1. Run the following command if you want a release-like published binary that matches the repo's CI workflow:
<div class="custom-container tip"><p class="custom-container-title">Tip</p>
- On Linux:
**If you are using Linux on ARM, 32-bit, RHEL-based distributions, or Musl, [pick the appropriate RID](https://learn.microsoft.com/en-us/dotnet/core/rid-catalog#linux-rids) for your platform and replace `-r linux-x64` with it, for example `-r linux-arm64`.**
```bash
dotnet publish MinecraftClient.sln -f net10.0 -r linux-x64 --self-contained=true -c Release -p:UseAppHost=true -p:IncludeNativeLibrariesForSelfExtract=true -p:EnableCompressionInSingleFile=true -p:DebugType=Embedded
```
</div>
<div class="custom-container tip"><p class="custom-container-title">Tip</p>
- On macOS:
**If you are using Linux on ARM, 32-bit, RHEL-based distributions, or Musl, [pick the appropriate RID](https://learn.microsoft.com/en-us/dotnet/core/rid-catalog#linux-rids) for your platform and replace `-r linux-x64` with it, for example `-r linux-arm64`.**
```bash
dotnet publish MinecraftClient.sln -f net10.0 -r osx-x64 --self-contained=true -c Release -p:UseAppHost=true -p:IncludeNativeLibrariesForSelfExtract=true -p:EnableCompressionInSingleFile=true -p:DebugType=Embedded
```
</div>
<div class="custom-container tip"><p class="custom-container-title">Tip</p>
- On macOS:
**If you are not using an Intel Mac, [pick the appropriate RID](https://learn.microsoft.com/en-us/dotnet/core/rid-catalog#macos-rids) for your processor and replace `-r osx-x64` with it, for example `-r osx-arm64`.**
```bash
dotnet publish MinecraftClient.sln -f net10.0 -r osx-x64 --self-contained=true -c Release -p:UseAppHost=true -p:IncludeNativeLibrariesForSelfExtract=true -p:EnableCompressionInSingleFile=true -p:DebugType=Embedded
```
</div>
<div class="custom-container tip"><p class="custom-container-title">Tip</p>
**If you are not using an Intel Mac, [pick the appropriate RID](https://learn.microsoft.com/en-us/dotnet/core/rid-catalog#macos-rids) for your processor and replace `-r osx-x64` with it, for example `-r osx-arm64`.**
</div>
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/`
- 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:
@ -223,8 +225,8 @@ dotnet --info
Requirements:
- Git
- Docker
- Git
- Docker
<div class="custom-container tip"><p class="custom-container-title">Tip</p>
@ -245,7 +247,7 @@ git clone https://github.com/MCCTeam/Minecraft-Console-Client.git --recursive
```
2. Navigate to `Minecraft-Console-Client/Docker`
3. Build the image using the following command
1. Build the image using the following command
```bash
docker build -t minecraft-console-client:latest .
@ -368,8 +370,8 @@ We use `proot-distro`, an official Termux utility, to install Ubuntu. It will in
Open Termux and run the following commands one at a time, in order:
1. `pkg update`
2. `pkg upgrade`
3. `pkg install proot-distro`
1. `pkg upgrade`
1. `pkg install proot-distro`
<div class="custom-container tip"><p class="custom-container-title">Tip</p>
@ -506,10 +508,10 @@ For downloading files, you can use the `wget` file we have installed, simply run
Also, here are some linux tutorials for people who are new to it:
- [Linux Terminal Introduction by ExplainingComputers](https://www.youtube.com/watch?v=SkB-eRCzWIU)
- [Linux Crash Course - nano (command-line text editor) by Learn Linux TV](https://www.youtube.com/watch?v=DLeATFgGM-A)
- [Linux Crash Course - The wget Command by Learn Linux TV](https://www.youtube.com/watch?v=F80Z5qd2b_4)
- [Linux Basics: How to Untar and Unzip Files (tar, gzip) by webpwnized](https://www.youtube.com/watch?v=1DF0dTscHHs)
- [Linux Terminal Introduction by ExplainingComputers](https://www.youtube.com/watch?v=SkB-eRCzWIU)
- [Linux Crash Course - nano (command-line text editor) by Learn Linux TV](https://www.youtube.com/watch?v=DLeATFgGM-A)
- [Linux Crash Course - The wget Command by Learn Linux TV](https://www.youtube.com/watch?v=F80Z5qd2b_4)
- [Linux Basics: How to Untar and Unzip Files (tar, gzip) by webpwnized](https://www.youtube.com/watch?v=1DF0dTscHHs)
</details>
@ -523,14 +525,14 @@ Also, here are some linux tutorials for people who are new to it:
The **Minecraft Console Client** can be run on a VPS 24 hours, 7 days a week.
- [What is a VPS?](#what-is-a-vps)
- [Prerequisites](#prerequisites)
- [Where to get a VPS](#where-to-get-a-vps)
- [Initial Amazon VPS setup](#initial-amazon-vps-setup)
- [Initial VPS setup](#initial-vps-setup)
- [Creating a new user account](#creating-a-new-user)
- [Installing .NET Core 6](#installing-net-core-6)
- [Installing the Minecraft Console Client](#installing-mcc-on-a-vps)
- [What is a VPS?](#what-is-a-vps)
- [Prerequisites](#prerequisites)
- [Where to get a VPS](#where-to-get-a-vps)
- [Initial Amazon VPS setup](#initial-amazon-vps-setup)
- [Initial VPS setup](#initial-vps-setup)
- [Creating a new user account](#creating-a-new-user)
- [Installing .NET Core 6](#installing-net-core-6)
- [Installing the Minecraft Console Client](#installing-mcc-on-a-vps)
### What is a VPS?
@ -544,29 +546,29 @@ Here is a [YouTube video](https://youtu.be/42fwh_1KP_o) that explains it in more
1. Git Bash (if you are on Windows)
Download and install [Git Bash](https://git-scm.com/downloads).
Download and install [Git Bash](https://git-scm.com/downloads).
<div class="custom-container tip"><p class="custom-container-title">Tip</p>
<div class="custom-container tip"><p class="custom-container-title">Tip</p>
**Make sure to allow the installation to add it to the context menu**
**Make sure to allow the installation to add it to the context menu**
</div>
</div>
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.)
1. `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.
1. Basic knowledge of Linux shell commands, terminal emulator usage, SSH and Nano editor.
If you already know this, feel free to skip.
If you already know this, feel free to skip.
if you get stuck, watch those tutorials.
if you get stuck, watch those tutorials.
If you're new to this, you can learn about it here:
If you're new to this, you can learn about it here:
- [What is Linux? by Bennett Bytes](https://www.youtube.com/watch?v=JsWQUOEL0N8)
- [Linux Terminal Introduction by ExplainingComputers](https://www.youtube.com/watch?v=SkB-eRCzWIU)
- [Linux Crash Course - nano (command-line text editor) by Learn Linux TV](https://www.youtube.com/watch?v=DLeATFgGM-A)
- [Linux Crash Course - The wget Command by Learn Linux TV](https://www.youtube.com/watch?v=F80Z5qd2b_4)
- [Linux Basics: How to Untar and Unzip Files (tar, gzip) by webpwnized](https://www.youtube.com/watch?v=1DF0dTscHHs)
- [What is Linux? by Bennett Bytes](https://www.youtube.com/watch?v=JsWQUOEL0N8)
- [Linux Terminal Introduction by ExplainingComputers](https://www.youtube.com/watch?v=SkB-eRCzWIU)
- [Linux Crash Course - nano (command-line text editor) by Learn Linux TV](https://www.youtube.com/watch?v=DLeATFgGM-A)
- [Linux Crash Course - The wget Command by Learn Linux TV](https://www.youtube.com/watch?v=F80Z5qd2b_4)
- [Linux Basics: How to Untar and Unzip Files (tar, gzip) by webpwnized](https://www.youtube.com/watch?v=1DF0dTscHHs)
### Where to get a VPS
@ -575,8 +577,8 @@ Here is a [YouTube video](https://youtu.be/42fwh_1KP_o) that explains it in more
You have 2 options:
- [Buying a VPS](#buying-a-vps)
- [Getting an AWS EC2 VPS for free (12 months free trial)](#aws-ec2-vps)
- [Buying a VPS](#buying-a-vps)
- [Getting an AWS EC2 VPS for free (12 months free trial)](#aws-ec2-vps)
#### Buying a VPS
@ -596,33 +598,33 @@ The MCC is not expensive to run, so it can run on basically any hardware, you do
Some of the reliable and cheap hosting providers (sorted for price/performance):
- [E-Trail](https://e-trail.net/vps)
- [E-Trail](https://e-trail.net/vps)
**Minimum price**: `2.50 EUR / month`
**Minimum price**: `2.50 EUR / month`
<div class="custom-container tip"><p class="custom-container-title">Tip</p>
<div class="custom-container tip"><p class="custom-container-title">Tip</p>
**If Ubuntu 24.04 LTS is not in the dropdown when ordering, you may need to reinstall 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.**
</div>
</div>
- [OVH Cloud](https://www.ovhcloud.com/de/vps/)
- [OVH Cloud](https://www.ovhcloud.com/de/vps/)
**Minimum price**: `3.57 EUR / month`
**Minimum price**: `3.57 EUR / month`
- [Hetzner Cloud](https://www.hetzner.com/cloud)
- [Hetzner Cloud](https://www.hetzner.com/cloud)
**Minimum price**: `4.51 EUR / month`
**Minimum price**: `4.51 EUR / month`
- [Digital Ocean](https://www.digitalocean.com/pricing/droplets)
- [Digital Ocean](https://www.digitalocean.com/pricing/droplets)
**Minimum price**: `4 EUR / month`
**Minimum price**: `4 EUR / month`
- [Contabo](https://contabo.com/en/vps/)
- [Contabo](https://contabo.com/en/vps/)
**Minimum price**: `7 EUR / month`
**Minimum price**: `7 EUR / month`
**More serious VPS able to host multiple applications, 4 CPU cores and 8 GB of RAM, 200 GB SSD**
**More serious VPS able to host multiple applications, 4 CPU cores and 8 GB of RAM, 200 GB SSD**
You also may want to search for better deals.
@ -707,9 +709,9 @@ For the **Key pair (login)** click on **Create new key pair** and name it `VpsRo
For the **Network settings** check the following checkboxes on:
- `Allow SSH traffic from` (Anywhere)
- `Allow HTTPs traffic from the internet`
- `Allow HTTP traffic from the internet`
- `Allow SSH traffic from` (Anywhere)
- `Allow HTTPs traffic from the internet`
- `Allow HTTP traffic from the internet`
<div class="custom-container tip"><p class="custom-container-title">Tip</p>
@ -951,9 +953,9 @@ Then find the `#AuthorizedKeysFile .ssh/authorized_keys .ssh/authorized_keys2` l
Additionally for better security you can do the following:
- Set `PermitRootLogin` to `yes`
- Change the `Port` to some number of your choice (22-65000) (Make sure it's at least 2 digits and avoid common ports used by other apps like: 21, 80, 35, 8080, 3000, etc...)
- Uncomment `#PasswordAuthentication yes` by removing the `#` in front and set it to `yes` (This will disable password login, you will be able to login with SSH keys only!)
- Set `PermitRootLogin` to `yes`
- Change the `Port` to some number of your choice (22-65000) (Make sure it's at least 2 digits and avoid common ports used by other apps like: 21, 80, 35, 8080, 3000, etc...)
- Uncomment `#PasswordAuthentication yes` by removing the `#` in front and set it to `yes` (This will disable password login, you will be able to login with SSH keys only!)
Save the file with `CTRL + O`, hit Enter, close it with `CTRL + X`.
@ -1087,9 +1089,9 @@ sudo apt install screen -y
Now you can install the MCC:
- [Download a compiled binary](#download-a-compiled-binary)
- [Building from the source code](#building-from-the-source-code)
- [Run using Docker](#using-docker) (Doesn't require the `screen` command)
- [Download a compiled binary](#download-a-compiled-binary)
- [Building from the source code](#building-from-the-source-code)
- [Run using Docker](#using-docker) (Doesn't require the `screen` command)
How to use the `screen` command?

1213
docs/guide/usage.md
View file

File diff suppressed because it is too large Load diff

126
docs/guide/websocket/Commands.md
View file

@ -23,10 +23,11 @@ Must be called before any other command (except `ChangeSessionId`).
**Parameters:**
| Index | Type | Description |
|-------|--------|-------------|
| ----- | ------ | ----------- |
| 0 | string | Password |
**Example:**
```json
{
"command": "Authenticate",
@ -43,10 +44,11 @@ The new ID must be 1-32 characters and not already taken.
**Parameters:**
| Index | Type | Description |
|-------|--------|----------------|
| ----- | ------ | -------------- |
| 0 | string | New session ID |
**Example:**
```json
{
"command": "ChangeSessionId",
@ -64,7 +66,7 @@ Log a message to the MCC console.
**Parameters:**
| Index | Type | Description |
|-------|--------|-------------|
| ----- | ------ | ----------- |
| 0 | string | Message |
### `LogDebugToConsole`
@ -74,7 +76,7 @@ Log a debug message to the MCC console (only visible in debug mode).
**Parameters:**
| Index | Type | Description |
|-------|--------|-------------|
| ----- | ------ | ----------- |
| 0 | string | Message |
### `LogToConsoleTranslated`
@ -83,9 +85,9 @@ Log a translated message using an MCC translation key.
**Parameters:**
| Index | Type | Description |
|-------|--------|------------------|
| 0 | string | Translation key |
| Index | Type | Description |
| ----- | ------ | --------------- |
| 0 | string | Translation key |
### `LogDebugToConsoleTranslated`
@ -93,9 +95,9 @@ Log a translated debug message.
**Parameters:**
| Index | Type | Description |
|-------|--------|------------------|
| 0 | string | Translation key |
| Index | Type | Description |
| ----- | ------ | --------------- |
| 0 | string | Translation key |
## Session Commands
@ -105,10 +107,10 @@ Reconnect to the Minecraft server.
**Parameters:**
| Index | Type | Description |
|-------|------|-------------------------------------|
| 0 | int | Extra reconnect attempts (default 3)|
| 1 | int | Delay in seconds (default 0) |
| Index | Type | Description |
| ----- | ---- | ------------------------------------ |
| 0 | int | Extra reconnect attempts (default 3) |
| 1 | int | Delay in seconds (default 0) |
### `DisconnectAndExit`
@ -123,10 +125,10 @@ Send a private message to a player.
**Parameters:**
| Index | Type | Description |
|-------|--------|---------------|
| 0 | string | Player name |
| 1 | string | Message |
| Index | Type | Description |
| ----- | ------ | ----------- |
| 0 | string | Player name |
| 1 | string | Message |
## Script Commands
@ -137,7 +139,7 @@ Run an MCC script file.
**Parameters:**
| Index | Type | Description |
|-------|--------|-------------|
| ----- | ------ | ----------- |
| 0 | string | File name |
## World and Terrain Commands
@ -154,7 +156,7 @@ Enable or disable terrain handling.
**Parameters:**
| Index | Type | Description |
|-------|------|-------------|
| ----- | ---- | ----------- |
| 0 | bool | Enabled |
### `GetWorld`
@ -169,12 +171,12 @@ Validates the block is within 6 blocks and is not air.
**Parameters:**
| Index | Type | Description |
|-------|---------|--------------------------------|
| 0 | double | X coordinate |
| 1 | double | Y coordinate |
| 2 | double | Z coordinate |
| 3 | string | Direction (optional, e.g. "Down") |
| Index | Type | Description |
| ----- | ------ | --------------------------------- |
| 0 | double | X coordinate |
| 1 | double | Y coordinate |
| 2 | double | Z coordinate |
| 3 | string | Direction (optional, e.g. "Down") |
The `Direction` parameter accepts string names: `Down`, `Up`, `North`, `South`, `West`, `East`.
@ -198,11 +200,11 @@ Interact with an entity.
**Parameters:**
| Index | Type | Description |
|-------|--------|--------------------------------------|
| 0 | int | Entity ID |
| Index | Type | Description |
| ----- | ------ | ----------------------------------------------------- |
| 0 | int | Entity ID |
| 1 | string | Interaction type (`Interact`, `Attack`, `InteractAt`) |
| 2 | string | Hand (optional, `MainHand` or `OffHand`) |
| 2 | string | Hand (optional, `MainHand` or `OffHand`) |
### `SendEntityAction`
@ -210,8 +212,8 @@ Send an entity action.
**Parameters:**
| Index | Type | Description |
|-------|--------|------------------------------|
| Index | Type | Description |
| ----- | ------ | -------------------------------------------------- |
| 0 | string | Action type (e.g. `StartSneaking`, `StopSneaking`) |
### `Sneak`
@ -220,8 +222,8 @@ Toggle sneaking.
**Parameters:**
| Index | Type | Description |
|-------|------|------------------|
| Index | Type | Description |
| ----- | ---- | ---------------------------- |
| 0 | bool | true to sneak, false to stop |
## Movement Commands
@ -238,7 +240,7 @@ Move the player to a location using pathfinding.
**Parameters:**
| Index | Type | Description |
|-------|--------|----------------------------------|
| ----- | ------ | -------------------------------- |
| 0 | double | X coordinate |
| 1 | double | Y coordinate |
| 2 | double | Z coordinate |
@ -259,7 +261,7 @@ Make the player look at coordinates.
**Parameters:**
| Index | Type | Description |
|-------|--------|-------------|
| ----- | ------ | ----------- |
| 0 | double | X |
| 1 | double | Y |
| 2 | double | Z |
@ -363,10 +365,10 @@ Perform a window/inventory action.
**Parameters:**
| Index | Type | Description |
|-------|--------|---------------------------------------------------|
| 0 | int | Inventory ID |
| 1 | int | Slot ID |
| Index | Type | Description |
| ----- | ------ | ------------------------------------------------------------- |
| 0 | int | Inventory ID |
| 1 | int | Slot ID |
| 2 | string | Action type (e.g. `LeftClick`, `RightClick`, `DropItemStack`) |
### `ChangeSlot`
@ -376,7 +378,7 @@ Change the active hotbar slot.
**Parameters:**
| Index | Type | Description |
|-------|-------|-------------------|
| ----- | ----- | ----------------- |
| 0 | short | Slot number (0-8) |
### `GetCurrentSlot`
@ -391,7 +393,7 @@ Set the active slot (legacy command).
**Parameters:**
| Index | Type | Description |
|-------|------|-------------|
| ----- | ---- | ----------- |
| 0 | int | Slot number |
### `ClearInventories`
@ -406,7 +408,7 @@ Close an inventory window.
**Parameters:**
| Index | Type | Description |
|-------|------|--------------|
| ----- | ---- | ------------ |
| 0 | int | Inventory ID |
## Creative Mode Commands
@ -418,7 +420,7 @@ Give an item in creative mode.
**Parameters:**
| Index | Type | Description |
|-------|--------|--------------------------------------------|
| ----- | ------ | ------------------------------------------ |
| 0 | int | Slot ID |
| 1 | string | Item type (e.g. `"DiamondSword"` or `798`) |
| 2 | int | Count |
@ -430,7 +432,7 @@ Delete an item from a slot in creative mode.
**Parameters:**
| Index | Type | Description |
|-------|------|-------------|
| ----- | ---- | ----------- |
| 0 | int | Slot ID |
## Block Interaction Commands
@ -441,12 +443,12 @@ Place a block.
**Parameters:**
| Index | Type | Description |
|-------|--------|--------------------------|
| 0 | double | X coordinate |
| 1 | double | Y coordinate |
| 2 | double | Z coordinate |
| 3 | string | Direction (e.g. `"Up"`) |
| Index | Type | Description |
| ----- | ------ | -------------------------------------------- |
| 0 | double | X coordinate |
| 1 | double | Y coordinate |
| 2 | double | Z coordinate |
| 3 | string | Direction (e.g. `"Up"`) |
| 4 | string | Hand (optional, `"MainHand"` or `"OffHand"`) |
### `SendAnimation`
@ -455,8 +457,8 @@ Play arm swing animation.
**Parameters:**
| Index | Type | Description |
|-------|--------|------------------------------------|
| Index | Type | Description |
| ----- | ------ | ------------------------------------- |
| 0 | string | Hand (optional, default `"MainHand"`) |
### `UseItemInHand`
@ -471,7 +473,7 @@ Update text on a sign.
**Parameters:**
| Index | Type | Description |
|-------|--------|--------------|
| ----- | ------ | ------------ |
| 0 | double | X coordinate |
| 1 | double | Y coordinate |
| 2 | double | Z coordinate |
@ -486,14 +488,14 @@ Update a command block.
**Parameters:**
| Index | Type | Description |
|-------|--------|-------------------------|
| 0 | double | X coordinate |
| 1 | double | Y coordinate |
| 2 | double | Z coordinate |
| 3 | string | Command |
| Index | Type | Description |
| ----- | ------ | ------------------------------------------------ |
| 0 | double | X coordinate |
| 1 | double | Y coordinate |
| 2 | double | Z coordinate |
| 3 | string | Command |
| 4 | string | Mode (e.g. `"Sequence"`, `"Auto"`, `"Redstone"`) |
| 5 | string | Flags |
| 5 | string | Flags |
## Trading Commands
@ -504,7 +506,7 @@ Select a villager trade.
**Parameters:**
| Index | Type | Description |
|-------|------|-------------|
| ----- | ---- | ----------- |
| 0 | int | Trade index |
### `Respawn`

34
docs/guide/websocket/Events.md
View file

@ -21,6 +21,7 @@ All enum values are serialized as **string names** (e.g., `"Zombie"` instead of
Sent after every command execution.
**Payload:**
```json
{
"success": true,
@ -36,6 +37,7 @@ Match the `requestId` to track which command produced this response.
Sent when a plain-text MCC command (starting with `/`) is executed.
**Payload:**
```json
{
"command": "move north",
@ -66,6 +68,7 @@ Payload: `"N/A"`
Sent for every incoming chat message, including the raw JSON.
**Payload:**
```json
{
"text": "Formatted text content",
@ -78,6 +81,7 @@ Sent for every incoming chat message, including the raw JSON.
Sent when a public chat message is detected.
**Payload:**
```json
{
"sender": "PlayerName",
@ -91,6 +95,7 @@ Sent when a public chat message is detected.
Sent when a private message is detected.
**Payload:**
```json
{
"sender": "PlayerName",
@ -104,6 +109,7 @@ Sent when a private message is detected.
Sent when a teleport request is detected.
**Payload:**
```json
{
"sender": "PlayerName",
@ -118,6 +124,7 @@ Sent when a teleport request is detected.
Sent when MCC disconnects from the server.
**Payload:**
```json
{
"reason": "ConnectionLost",
@ -154,6 +161,7 @@ Sent when an entity moves.
Sent when an entity plays an animation.
**Payload:**
```json
{
"entity": { ... },
@ -166,6 +174,7 @@ Sent when an entity plays an animation.
Sent when an entity's health changes.
**Payload:**
```json
{
"entity": { ... },
@ -178,6 +187,7 @@ Sent when an entity's health changes.
Sent when entity metadata updates.
**Payload:**
```json
{
"entity": { ... },
@ -190,6 +200,7 @@ Sent when entity metadata updates.
Sent when an entity's equipment changes.
**Payload:**
```json
{
"entity": { ... },
@ -205,6 +216,7 @@ Item types are string names (e.g., `"DiamondSword"`).
Sent when an entity gets an effect.
**Payload:**
```json
{
"entity": { ... },
@ -220,6 +232,7 @@ Sent when an entity gets an effect.
Sent when a block break animation plays.
**Payload:**
```json
{
"entity": { ... },
@ -235,6 +248,7 @@ Sent when a block break animation plays.
Sent when a player joins the server.
**Payload:**
```json
{
"uuid": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
@ -247,6 +261,7 @@ Sent when a player joins the server.
Sent when a player leaves the server.
**Payload:**
```json
{
"uuid": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
@ -265,6 +280,7 @@ Sent when player properties update (e.g., speed, attack damage).
Sent when the player's status changes.
**Payload:**
```json
{
"statusId": 0
@ -288,6 +304,7 @@ Payload: `"N/A"`
Sent when the player's health or food level changes.
**Payload:**
```json
{
"health": 20.0,
@ -300,6 +317,7 @@ Sent when the player's health or food level changes.
Sent when experience updates.
**Payload:**
```json
{
"experienceBar": 0.5,
@ -315,6 +333,7 @@ Sent when experience updates.
Sent when a player's gamemode changes.
**Payload:**
```json
{
"playerName": "Steve",
@ -328,6 +347,7 @@ Sent when a player's gamemode changes.
Sent when a player's latency changes.
**Payload:**
```json
{
"playerName": "Steve",
@ -341,6 +361,7 @@ Sent when a player's latency changes.
Sent when the held item slot changes.
**Payload:**
```json
{
"slot": 0
@ -352,6 +373,7 @@ Sent when the held item slot changes.
Sent when an explosion occurs.
**Payload:**
```json
{
"location": { "x": 10, "y": 64, "z": -20 },
@ -365,6 +387,7 @@ Sent when an explosion occurs.
Sent when a title, subtitle, or action bar message is displayed.
**Payload:**
```json
{
"action": 0,
@ -385,6 +408,7 @@ Sent when a title, subtitle, or action bar message is displayed.
Sent when the server TPS updates.
**Payload:**
```json
{
"tps": 20.0
@ -396,6 +420,7 @@ Sent when the server TPS updates.
Sent when the world time updates.
**Payload:**
```json
{
"worldAge": 1000000,
@ -408,6 +433,7 @@ Sent when the world time updates.
Sent when an MCC internal command is executed.
**Payload:**
```json
{
"commandName": "move",
@ -426,6 +452,7 @@ Sent when an MCC internal command is executed.
Sent when an inventory's contents change.
**Payload:**
```json
{
"inventoryId": 0
@ -437,6 +464,7 @@ Sent when an inventory's contents change.
Sent when an inventory window opens.
**Payload:**
```json
{
"inventoryId": 1
@ -448,6 +476,7 @@ Sent when an inventory window opens.
Sent when an inventory window closes.
**Payload:**
```json
{
"inventoryId": 1
@ -461,6 +490,7 @@ Sent when an inventory window closes.
Sent when a scoreboard objective updates.
**Payload:**
```json
{
"objectiveName": "health",
@ -477,6 +507,7 @@ Sent when a scoreboard objective updates.
Sent when a scoreboard score updates.
**Payload:**
```json
{
"entityName": "Steve",
@ -495,6 +526,7 @@ Sent when a scoreboard score updates.
Sent when map data updates.
**Payload:**
```json
{
"mapId": 0,
@ -517,6 +549,7 @@ Note: `colors` is base64-encoded when present, `null` otherwise.
Sent when a villager trade list is received.
**Payload:**
```json
{
"windowId": 1,
@ -532,6 +565,7 @@ Sent when a villager trade list is received.
Sent for every network packet (when subscribed).
**Payload:**
```json
{
"packetID": 42,

12
docs/guide/websocket/README.md
View file

@ -11,18 +11,18 @@ You load it as a standalone script with `/script ChatBots/WebSocketBot.cs`.
## Quick Start
1. Copy `config/ChatBots/WebSocketBot.cs` into your MCC `config/ChatBots/` folder (it ships in the repo under that path).
2. Open the file and edit the line near the top:
1. Open the file and edit the line near the top:
```csharp
MCC.LoadBot(new WebSocketBot("127.0.0.1", 8043, "CHANGE_THIS_PASSWORD"));
```
- Replace `127.0.0.1` with the IP to bind (use `+` or `*` for all interfaces).
- Replace `8043` with your preferred port.
- Replace `CHANGE_THIS_PASSWORD` with a strong, unique password.
3. Optionally enable debug logging:
1. Optionally enable debug logging:
```csharp
MCC.LoadBot(new WebSocketBot("127.0.0.1", 8043, "mypassword", debugMode: true));
```
4. In MCC, run: `/script ChatBots/WebSocketBot.cs`
1. In MCC, run: `/script ChatBots/WebSocketBot.cs`
The bot starts a WebSocket server. Connect to `ws://127.0.0.1:8043/` with any WebSocket client.
@ -66,6 +66,7 @@ Every command produces an `OnWsCommandResponse` event with `success`, `requestId
### Sending Plain Text
You can also send plain text directly:
- Text starting with `/` is forwarded to MCC as an internal command (e.g., `/move north`).
- Other text is sent as chat.
@ -87,20 +88,25 @@ The `data` field is a JSON string that you parse separately to get the event pay
All enum values (ItemType, EntityType, Direction, Hand, etc.) are serialized as **string names**, not numeric IDs.
For example, an entity of type `Zombie` appears as:
```json
{ "type": "Zombie", "location": { "x": 10, "y": 64, "z": -20 } }
```
When sending commands that accept enum parameters, you can pass **either** a string name or a numeric value:
```json
{ "command": "InteractEntity", "requestId": "abc", "parameters": [42, "Interact", "MainHand"] }
```
or:
```json
{ "command": "InteractEntity", "requestId": "abc", "parameters": [42, 0, 0] }
```
Two dedicated commands let you query the full mapping tables:
- `GetItemTypeMappings` returns `{ "DiamondSword": 798, "Stone": 1, ... }`
- `GetEntityTypeMappings` returns `{ "Player": 128, "Zombie": 119, ... }`