# Introduction
This is the official documentation of OQ.MineBot \[www\.minecraftbot.com] plugin API.
## Creating Project
1\. Firstly you must create a new Class Library (.NET Framework):
## Installation
You can set-up the plugin API in a few different ways, however some are considered better practices and others are easier. There are 3 different methods listed below, ranked by best practice.
{% hint style="info" %}
Watch our environment setup tutorial [here](https://www.youtube.com/watch?v=OiqslWioVso).
{% endhint %}
1. **NuGet package**
1. Open NuGet package manager\
2. Install the **OQ.MineBot.PluginBase** package\
*(When a bot update is released you must go into the package manager, select the OQ.MineBot.PluginBase package and click the Update button)*
2. **Github clone**
1. Clone the MineBot API () into a local folder.\
2. Add cloned project into your solution.\
3. Reference it in your plugin project.\
*(When a bot update is released you must update the local repository with "git pull")*
3. **Dll**
1. Download the latest dll from [Github](https://github.com/OnlyQubes/OQ.MineBot.PluginBase/releases).
2. Reference it in your plugin project.\
*(When a bot update is released you must redownload the dll file and re-add the reference to the new one)*
## File Structure
Plugins are made up of two types of classes: IStartPlugin and ITask. A plugin must have one IStartPlugin class, which is generally named PluginCore, and can have many Task classes. Below you will find the explanation and purpose of each type.\
It is good practice to store the tasks in a separate folder like this:
* Then you will need to have an OnLoad method which will be called once the plugin is loaded/reloaded, which is usually when the bot is started. The settings are optional and can be overwritten if you don't want to include any settings:\
* Finally, you will need an OnStart method which will register all of your task classes and is called as soon as the plugin is started on a bot:\
### Part 2: creating tasks
* Create a task class, which will allow you to interact with the bot and it's environment.
* Inherit from ITask (and optionally any of the [Listeners](https://github.com/OnlyQubes/OQ.MineBot.PluginBase/tree/master/Base/Plugin/Listeners)):\
* Implement Exec, which will tell the bot if any of the Listeners can be called, and add any listener code:\
:tada: **That's it, now you can build the plugin and test it on the bot**:tada: \
For a more in-depth guide check out the [Introduction page](https://docs.minecraftbot.com/).
{% file src="/files/-LpZclX-neFHbqt9fVm6" %}
Download Template Code Here
{% endfile %}
# Start Plugins
Start plugins have a checkbox in the Plugins tab and are usually started on all of the connected accounts.
# Events (basic)
A basic code example that shows you how to make a plugin listen for certain events.
#### EventTask.cs
Task class that will be registered in PluginBase.cs and will be responsible to handle/report events that we receive from the server.
{% tabs %}
{% tab title="Commented Code" %}
```csharp
public class EventTask : ITask, IDeathListener, ITickListener {
// Start gets called once the Task is registered by
// PluginCore.cs using RegisterTask(). This ensures that
// the Context variable has been set to the current bot's context.
public override async Task Start() {
// We can register events here for the events that do
// not have an inheritable listener class.
// (unlike inheritable listeners these events will ignore
// the Exec() function)
EventsContext.Events.onChat += OnChatMessageReceived;
}
// The stop method is called once the plugin is stopped for this bot.
public override async Task Stop() {
// It is important to unregister any events that we register manually
// (in Start).
Context.Events.onChat -= OnChatMessageReceived;
}
// Determines wether the listeners (IDeathListener, ITickListener) will execute.
// If this returns true then the listeners do execute normally,
// otherwise the events will not be called.
public override bool Exec() {
// Always execute.
return true;
}
// Event is called when bot dies and Exec() returns true,
// this is because we inherit from IDeathListener.
public async Task OnDeath() {
Console.WriteLine($"Oh no, the bot {Context.Player.GetUsername()} just died!");
}
public async Task OnTick() {
// This is called each tick (~50ms) while Exec() returns true.
}
public void OnChatMessageReceived(IBotContext context, IChat message, byte position) {
if (!Exec()) return; // manually check if Exec tells us to execute.
Console.WriteLine($"Message received: {message.GetText()}");
}
}
```
{% endtab %}
{% tab title="Raw Code" %}
```csharp
public class EventTask : ITask, IDeathListener, ITickListener {
public override async Task Start() {
Context.Events.onChat += OnChatMessageReceived;
}
public override async Task Stop() {
Context.Events.onChat -= OnChatMessageReceived;
}
public override bool Exec() {
return true;
}
public async Task OnDeath() {
Console.WriteLine($"Oh no, the bot {Context.Player.GetUsername()} just died!");
}
public async Task OnTick() { }
public void OnChatMessageReceived(IBotContext context, IChat message, byte position) {
if (!Exec()) return;
Console.WriteLine($"Message received: {message.GetText()}");
}
}
```
{% endtab %}
{% endtabs %}
{% hint style="info" %}
You can find out all of the available inheritable Listener classes [here](https://github.com/OnlyQubes/OQ.MineBot.PluginBase/tree/master/Base/Plugin/Listeners).
{% endhint %}
# Movement (basic)
A basic code example that shows you how to make the bot move between two locations.
#### MovementTask.cs
Task class that will be registered in PluginBase.cs and will be responsible for Movement in this plugin.\
While the player is not then this task will move between two Locations.
{% tabs %}
{% tab title="Commented Code" %}
```csharp
public class MovementTask : ITask, ITickListener {
public static ILocation Location1 = new Location(100, 10, 100);
public static ILocation Location2 = new Location( 1, 10, 100);
public override bool Exec() {
// Do not execute 'OnTick' if the bot is dead.
return !Context.Player.IsDead();
}
public async Task OnTick() {
// The 'await' keyword waits until MoveTo completes/fails and
// only then continues the execution.
var moveResult = await Context.Player.MoveTo(Location1).Task;
if(moveResult.Result != MoveResultType.Completed) {
// Failed to move to the location, lets output an error
// to the console and return.
Console.WriteLine($"Failed to move to {Location1}!");
return;
}
// We have successfully reached Location1,
// now we can start moving to Location2.
var moveTask = Context.Player.MoveTo(Location2);
/*
As the MoveTo(Location2) code does not have the 'await' keyword
we can execute other actions parallel and optionally await later
for the task to complete.
*/
// Wait until MoveTo completes/fails to Location2. We do not care
// if it succeeded therefore we do no assign the result to any variable.
await moveTask.Task;
}
}
```
{% endtab %}
{% tab title="Raw Code" %}
```csharp
public class MovementTask : ITask, ITickListener {
public static ILocation Location1 = new Location(100, 10, 100);
public static ILocation Location2 = new Location( 1, 10, 100);
public override bool Exec() {
return !Context.Player.IsDead();
}
public async Task OnTick() {
var moveResult = await Context.Player.MoveTo(Location1).Task;
if(moveResult.Result != MoveResultType.Completed) {
Console.WriteLine($"Failed to move to {Location1}!");
return;
}
await Context.Player.MoveTo(Location2).Task;
}
}
```
{% endtab %}
{% endtabs %}
{% hint style="info" %}
It is usually desirable to use the 'await' keyword as it will pause all execution until the task completes and then the result can be used. Not awaiting for tasks to complete can cause another function (e.g.: OnTick) to start while a task is running (e.g.: while still moving).
\
Don't know what async programming is? Check out Microsoft's documentation [here](https://docs.microsoft.com/en-us/dotnet/csharp/programming-guide/concepts/async/).
{% endhint %}
# Killaura (intermediate)
This example will show you code for a basic plugin that will follow and attack the closest target-able player. The plugin incorporates multiple tasks and therefore is marked as intermediate.
**FightTask.cs**
This task is responsible for targeting, moving, and attacking the closest non-friendly player.
{% tabs %}
{% tab title="Commented Code" %}
```csharp
public class FightTask : ITask, ITickListener
{
private string[] Friendly;
public FightTask(string[] friendly) {
this.Friendly = friendly;
}
public override bool Exec() {
return !Context.Player.IsDead() && !Context.Player.State.Eating;
}
public async Task OnTick() {
// Get the closest player to us that is not in our friends list.
var target = Context.Entities.GetClosestPlayer(false,
entity => !Friendly.Contains(entity.GetName()));
if (target == null)
// No target found, so do nothing this tick.
// Optionally you could make the bot roam in this case.
return;
// Begin moving towards the target. We do not await for the task
// to complete since we also want to attack the target while we
// are running.
var movementTask = target.Follow();
// Find the best sword in our inventory and attempt to select it.
// This should/could be in a different task, as this task should
// be only responsible for moving and attacking targets.
var sword = Inventory.FindBest(EquipmentType.Sword);
if(sword != null) await sword.Select();
// Run this for as long as we are chasing this player OR
// if we are already very close to the target player.
while (movementTask.IsMoving() ||
target.Position.Distance(Context.Player.GetPosition()) < 2) {
// Only attack the player if it is within 4 blocks to us.
if(target.Position.Distance(Context.Player.GetPosition()) < 5)
target.Attack();
// Wait 2 ticks before each attack.
await Context.TickManager.Sleep(2);
}
}
}
```
{% endtab %}
{% tab title="Raw Code" %}
```csharp
public class FightTask : ITask, ITickListener
{
private string[] Friendly;
public FightTask(string[] friendly) {
this.Friendly = friendly;
}
public override bool Exec() {
return !Context.Player.IsDead() && !Context.Player.State.Eating;
}
public async Task OnTick() {
var target = Context.Entities.GetClosestPlayer(false, entity => !Friendly.Contains(entity.GetName()));
if (target == null) return;
var movementTask = target.Follow();
var sword = Inventory.FindBest(EquipmentType.Sword);
if(sword != null) await sword.Select();
while (movementTask.IsMoving() ||
target.Position.Distance(Context.Player.GetPosition()) < 2) {
if(target.Position.Distance(Context.Player.GetPosition()) < 5)
target.Attack();
await Context.TickManager.Sleep(2);
}
}
}
```
{% endtab %}
{% endtabs %}
**RespawnTask.cs**
This task is responsible for respawning the bot when it dies.
```csharp
public class RespawnTask : ITask, IDeathListener
{
public override bool Exec() {
return true;
}
public async Task OnDeath() {
await Context.Player.Respawn();
}
}
```
{% file src="/files/-LtGcvuNGvR0xvdmwDq7" %}
Full Plugin Source Code
{% endfile %}
# Wheat Farmer (intermediate)
This will show you code for a wheat farmer, meaning that it finds the closest fully grown wheat blocks, moves to them, breaks them, and finally replants them.
**FarmTask.cs**
Task responsible for finding, breaking, and replanting wheat.
{% tabs %}
{% tab title="Commented Code" %}
```csharp
public class FarmTask : ITask, ITickListener
{
// Add additional costs to Jumping in order to discourage
// the bot from jumping on our crops.
private static MapOptions MO = new MapOptions()
{
AdditionalWeights = new MapOptionWeights()
{
JumpGap = 25,
JumpUp = 25
}
};
// https://docs.minecraftbot.com/api/utility/locationblacklistcollection
private static LocationBlacklistCollection BLACKLIST = LocationBlacklistCollection.CreateGlobal(3, // blacklist location globally after 3 bots fail to reach it.
600000, 1); // blacklist location for 10 minutes.
private const int GROWN_WHEAT_METADATA = 7;
private const int WHEAT_ID = 59;
private const int SEED_ID = 295;
public override bool Exec() {
return !Context.Player.IsDead() &&
!Context.Player.State.Eating && !Context.Player.State.EatRequestQueued && // do not run if we are about to eat/are eating.
!Inventory.IsFull() && Context.Containers.GetOpenWindow() == null; // do not run if a chest is open or our inventory is full, as in that case the store task is running.
}
public async Task OnTick() {
var block = await Context.World.FindClosest(64, 8, // search 64x64x8 area
WHEAT_ID, CpuMode.Medium_Usage,
consideredBlock => consideredBlock.GetMetadata() == GROWN_WHEAT_METADATA // filter to only fully grown blocks (determined by metadata).
&& !BLACKLIST.IsBlocked(Context, consideredBlock.GetLocation())); // filter by blacklist as well.
if (block == null)
// We didn't find any grown wheat blocks close to the bot.
return;
if ((await block.MoveTo(MO).Task).Result == MoveResultType.Completed) {
// Successfully moved to block, attempt to mine it.
var mineAction = await block.Dig();
await mineAction.DigTask;
// Attempt to replant at the position that we mined at.
if(await Inventory.Select(SEED_ID))
await block.PlaceAt(); // attempt to place the seeds at the block that we just mined.
}
else {
// Could not path to the block, add it to our temporary block.
BLACKLIST.AddToBlockCounter(Context, block.GetLocation());
}
}
}
```
{% endtab %}
{% tab title="Raw Code" %}
```csharp
public class FarmTask : ITask, ITickListener
{
private static MapOptions MO = new MapOptions()
{
AdditionalWeights = new MapOptionWeights() { JumpGap = 25, JumpUp = 25 }
};
private static LocationBlacklistCollection BLACKLIST = LocationBlacklistCollection.CreateGlobal(3, 600000, 1);
private const int GROWN_WHEAT_METADATA = 7;
private const int WHEAT_ID = 59;
private const int SEED_ID = 295;
public override bool Exec() {
return !Context.Player.IsDead() &&
!Context.Player.State.Eating && !Context.Player.State.EatRequestQueued &&
!Inventory.IsFull() && Context.Containers.GetOpenWindow() == null;
}
public async Task OnTick() {
var block = await Context.World.FindClosest(64, 8,
WHEAT_ID, CpuMode.Medium_Usage,
consideredBlock => consideredBlock.GetMetadata() == GROWN_WHEAT_METADATA
&& !BLACKLIST.IsBlocked(Context, consideredBlock.GetLocation()));
if (block == null) return;
if ((await block.MoveTo(MO).Task).Result == MoveResultType.Completed) {
var mineAction = await block.Dig();
await mineAction.DigTask;
if(await Inventory.Select(SEED_ID))
await block.PlaceAt();
else {
BLACKLIST.AddToBlockCounter(Context, block.GetLocation());
}
}
}
```
{% endtab %}
{% endtabs %}
**StoreTask.cs**
Task responsible for storing items into the nearest non-full chest when the bot's inventory is full.
{% tabs %}
{% tab title="Commented Code" %}
```csharp
public class StoreTask : ITask, ITickListener
{
public override bool Exec() {
return !Context.Player.IsDead() &&
!Context.Player.State.Eating && !Context.Player.State.EatRequestQueued && // do not run if we are about to eat/are eating.
(Inventory.IsFull() || Context.Containers.GetOpenWindow() != null); // run when our inventory is full or we have a chest open.
}
public async Task OnTick() {
// Locate the nearest chests.
var chestMap = Context.Functions.CreateChestMap();
await chestMap.UpdateChestList();
// Attempt to open a chest that is not full.
var window = await chestMap.Open(ChestStatus.NotFull);
if (window == null) return;
// In this case we deposite all of our items, however
// you could extend this by not storing food.
await window.Deposit();
await window.Close();
}
}
```
{% endtab %}
{% tab title="Raw Code" %}
```csharp
public class StoreTask : ITask, ITickListener
{
public override bool Exec() {
return !Context.Player.IsDead() &&
!Context.Player.State.Eating && !Context.Player.State.EatRequestQueued &&
(Inventory.IsFull() || Context.Containers.GetOpenWindow() != null);
}
public async Task OnTick() {
var chestMap = Context.Functions.CreateChestMap();
await chestMap.UpdateChestList();
var window = await chestMap.Open(ChestStatus.NotFull);
if (window == null) return;
await window.Deposit();
await window.Close();
}
}
```
{% endtab %}
{% endtabs %}
{% file src="/files/-LtGklFWfTGaYXyZJES4" %}
Full Plugin Source Code
{% endfile %}
# Request Plugins
Request plugins are the ones that can only be invoked on one or more account through the Accounts tab. This means that they do not have a checkmark in the Plugins tab and usually don't run on all bots
{% hint style="warning" %}
Usually developers should use [Start Plugins](https://docs.minecraftbot.com/examples/start-plugins). This is for more niche plugins that should be only ran on one (or a few) bots at a time, such as Chat Spy or Container Viewer.
{% endhint %}
{% content-ref url="/pages/-LnDc8BhjNDQrsR9zi1V" %}
[Start Plugins](/examples/start-plugins)
{% endcontent-ref %}
# Chat (advanced)
# Macro Component Additions
Plugins can also add custom components to the macro builder. Regular plugin api functions can be used within the Execute method. This page describes how to make a plugin that registers new components.
**PluginCore.cs**
```csharp
[Plugin(1, "Extra Macro Component Plugin", "Adds new macro components to the macro builder!")]
public class PluginCore : IStartPlugin
{
///
/// Should be used to check compatability with the
/// current version of the bot.
///
public override void OnLoad(int version, int subversion, int buildversion) { }
public override PluginResponse OnEnable(IBotSettings botSettings) {
/* Regular plugin content */
return base.OnEnable(botSettings);
}
}
public class TestMacroComponent : IExternalMacroComponent {
public TestMacroComponent() {
this.Category = MacroComponentCategory.Misc;
this.Outputs = new IMacroOutputCollection(
new KeyValuePair("success", new ExternalMacroOutput("Success", "This output gets called once the call finishes", true)),
new KeyValuePair("output_internal_name", new ExternalMacroOutput("Error", "This output will never get called", false))
);
this.Variables = new IMacroVariableCollection(
new KeyValuePair("variable_internal_name1", new ExternalMacroVariable(typeof(string), "Message", "What message should we send to chat?", "my default message!"))
);
}
public override string GetName() {
return "Test macro component";
}
public override string GetInternalName() {
return "ex:test_macro_component";
}
public override string GetDescription() {
return "This is a test macro component";
}
public override string GetInteractiveDescription() {
var variableValue = GetVariable("variable_internal_name1");
return
string.IsNullOrWhiteSpace(variableValue) ? GetDescription()
: $"I will say {variableValue}.";
}
public override string Execute(IBotContext Context) {
Context.Functions.Chat("My message: " + GetVariable("variable_internal_name1"));
return "success"; // or return "output_internal_name"
}
}
```
## Outputs
