World

This part refers to the class IWorld.cs, which can be accessed through Context.World. This will allow you to get and interact with blocks. The IBlock class is heavily integrated into this class and will further allow you to interact with the world.

Methods
GetBlock
GetBlocks
GetBlockId
GetBlockMetadata
GetBlockEntityData
GetLookingAt
GetPathableLocationsFrom
PlaceAt
PlaceOn
Dig
FindFrom
FindClosestTo
Find
FindClosest

Methods

GetBlock

Returns an IBlock which is an instance of a block at the given position. This is the most important function of the world class, as the IBlock class allows you to interact with the block, such as hit it, use it, break it, etc.

IBlock

IBlock GetBlock(ILocation location);
IBlock GetBlock(IPosition position);
IBlock GetBlock(int x, int y, int z);

GetBlocks

Returns a list of IBlock, where each entry corresponds to a block from the given location list.

IBlock

IEnumerable<IBlock> GetBlocks(IEnumerable<ILocation> locations);

GetBlockRaw

Returns the raw data of a block (how Minecraft sends it between server and client). The value contains both the ID of the block and the metadata. Each value can be extracted by doing data >> 4 (ID) and data & 15 (metadata).

This should be mainly used for performance critical operations, as it does not create any new objects and has both the id and metadata in a single location lookup.

ushort GetBlockRaw(ILocation location);

GetBlockId

Returns the ID of a block at the given position. Reference https://minecraft-ids.grahamedgecombe.com/

ushort GetBlockId(ILocation location);
ushort GetBlockId(IPosition position);
ushort GetBlockId(int x, int y, int z);

GetBlockMetadata

Returns the metadata of a block at the given position.

byte GetBlockMetadata(ILocation location);
byte GetBlockMetadata(IPosition position);
byte GetBlockMetadata(int x, int y, int z);

GetBlockEntityData

Returns block entity data (e.g.: sign text) for blocks that have it, otherwise null is returned. The returned type is IBlockEntity data which by it self has a Type property, which further specifies the entity data type (e.g.: sign). A full list of BlockEntity types can be found here.

IBlockEntity GetBlockEntityData(ILocation location);
IBlockEntity GetBlockEntityData(IPosition position);
IBlockEntity GetBlockEntityData(int x, int y, int z);
// the result is a generic type which can then be converted like this:
// if(blockEntityData.Type == BlockEntityType.Sign) {
//     var convertedData = (SignBlockEntity)blockEntityData;
//     var signText = convertedData.GetContinuousText();
// }

GetLookingAt

Returns the block that the bot is looking at. This may return Null if there is no block in front of the bot, or it is out of interaction range (around 5 blocks).

IBlock

IBlock GetLookingAt(); 

GetPathableLocationsFrom

Returns an array of ILocation. The first block is always the specified location. The range specifies how far away a block can be from the location in order to be considered. The area considered is circular. This task can take a long time, depending on the range, therefore it is a Task that should be awaited for. * MapOptions - specifies the pathing options to considered (e.g.: max fall distance). If left null it will use the bots default MapOptions.

// If no location is specified it will use the bot's location.
Task<ILocation[]> GetPathableBlocksFrom(uint range, MapOptions mapOptions = null);
Task<ILocation[]> GetPathableBlocksFrom(ILocation location, uint range, MapOptions mapOptions = null);
Task<ILocation[]> GetPathableBlocksFrom(IPosition position, uint range, MapOptions mapOptions = null);
Task<ILocation[]> GetPathableBlocksFrom(int x, int y, int z, uint range, MapOptions mapOptions = null);

PlaceAt

Attempts to place a block that the bot is currently holding (does not validate if the bot is holding a block, that is up to the developer) at the given location. This is done by getting the nearby block faces and checking whether we can place on them. This does consider the visibility of faces. If no visible face is found then false is returned, otherwise true. Note: this does not check whether the server cancelled the block placement (removed the placed block), nor does this function move the player to the range of the block (that is up to developer to do).

Task<bool> PlaceAt(ILocation location);
Task<bool> PlaceAt(IPosition position);
Task<bool> PlaceAt(int x, int y, int z);

PlaceOn

Attempts to place a block that the bot is currently holding by right clicking a block in the specified location on the specified face (side). The visibility of a face is not verified. Note: this function does not move the player to the range of the block (that is up to developer to do).

Face Value	Face Representation
0	Bottom (-Y)
1	Top (+Y)
2	North (-Z)
3	South (+Z)
4	West (-X)
5	East (+X)

Task PlaceOn(FaceData faceData);
Task PlaceOn(ILocation location,  sbyte face);
Task PlaceOn(IPosition position,  sbyte face);
Task PlaceOn(int x, int y, int z, sbyte face);

Dig

Attempts to break the block at the given location. You can optionally specify the face (side) that will be used to dig the block. This does rotate the bots head to the appropriate block's face. If no face data is specified and no visible face is found then it will default to breaking the block using the Top (+Y) face.

The function returns Task<IDigAction> which completes once the block is broken or instantly if the dig action was invalid (e.g.: attempting to break bedrock). The variables cancelled and/or completed can be used to determine the dig actions outcome.

Task<IDigAction> Dig(FaceData faceData);
Task<IDigAction> Dig(ILocation location, sbyte face);
Task<IDigAction> Dig(ILocation location);
Task<IDigAction> Dig(IPosition position);
Task<IDigAction> Dig(int x, int y, int z);

FindFrom

Scans the world for a block with the given id(s). If a block with the specified id(s) is found then optionalIsPickable is called, where the developer can define custom block criteria. The scanned area starts from the specified location and spans the width in all directions (east, west, north, south) and the height in both direction (up, down). Note: As scanning the world can take a long time (depending on the width/height) the function is limited to X ms per tick, where cpuMode determines how long the function can be on the cpu for. CpuMode.High_Usage will usually max out the users cpu, but will scan the area the fastest, whereas CpuMode.Low_Usage will take the longest but will use less cpu per tick.

Task<IBlock[]> FindFrom(ILocation location, int width, int height, ushort id, CpuMode cpuMode, Func<IBlock, bool> optionalIsPickable = null);
Task<IBlock[]> FindFrom(ILocation location, int width, int height, ushort[] ids, CpuMode cpuMode, Func<IBlock, bool> optionalIsPickable = null);

Find

Wrapper function for FindFrom where FindFrom gets called with the location of the bot.

Task<IBlock[]> Find(int width, int height, ushort id, CpuMode cpuMode, Func<IBlock, bool> optionalIsPickable = null);
Task<IBlock[]> Find(int width, int height, ushort[] ids, CpuMode cpuMode, Func<IBlock, bool> optionalIsPickable = null);

FindClosestTo

Scans the world for the first occurrence of a block that matches the specified Id(s) and optionally if optionalIsPickable returns true. The scanned area starts from the specified location and spans the width in all directions (east, west, north, south) and the height in both direction (up, down). Note: As scanning the world can take a long time (depending on the width/height) the function is limited to X ms per tick, where cpuMode determines how long the function can be on the cpu for. CpuMode.High_Usage will usually max out the users cpu, but will scan the area the fastest, whereas CpuMode.Low_Usage will take the longest but will use less cpu per tick.

Task<IBlock> FindClosestTo(ILocation location, int width, int height, ushort id, CpuMode cpuMode, Func<IBlock, bool> optionalIsPickable = null);
Task<IBlock> FindClosestTo(ILocation location, int width, int height, ushort[] ids, CpuMode cpuMode, Func<IBlock, bool> optionalIsPickable = null);

FindClosest

Wrapper function for FindClosestTo where FindClosestTo gets called with the location of the bot.

Task<IBlock> FindClosest(int width, int height, ushort id, CpuMode cpuMode, Func<IBlock, bool> optionalIsPickable = null);
Task<IBlock> FindClosest(int width, int height, ushort[] ids, CpuMode cpuMode, Func<IBlock, bool> optionalIsPickable = null);

Example code using World

The code below searches for the closest torch block within a close range to the bot (10x10x4 area). If no block is found with the id 50 (torch), then the bot does nothing, otherwise it will break the block.

Commented Code

public async void OnTick() {
    IBlock closestBlock = await Context.World.FindClosest(5, // width of search
                                                          2, // height of search
                                                          50); // id of the block we are searching for, 50 stands for torch.
    if(closestBlock != null) {
        // closestBlock variable is not null, that means that 
        // we found a torch block nearby.
        Console.WriteLine($"Found torch at {closestBlock.GetLocation()}, breaking it");
        // Attempt to dig the block. We use await to wait for the dig
        // task to complete, as we don't want the next tick to execute
        // until we have broken the block, otherwise the bot could try
        // to mine two blocks at once or the same block multiple times.
        await closestBlock.Dig();
    }
}

Raw Code

public async void OnTick() {
    IBlock closestBlock = await Context.World.FindClosest(5, 2, 50);
    
    if(closestBlock != null) {
        Console.WriteLine($"Found torch at {closestBlock.GetLocation()}, breaking it");
        await closestBlock.Dig();
    }
}