aternos/hawk

PHP library to get, replace and delete blocks/entities out of Minecraft region files

v1.6.3 2024-07-24 14:57 UTC

Requires

• php: >=8.0
• ext-readline: *
• aternos/nbt: >=1.4

Requires (Dev)

• phpunit/phpunit: <10.0

MIT

• Riccardo

README

About

Hawk is a PHP library to get and/or replace blocks and get and/or delete entities in Minecraft region files. This allows the user to replace blocks or delete entities that will crash the server when loaded.

Currently, following versions are supported:

1.12+ for entities
1.16+ for blocks

Installation

composer require aternos/hawk

Usage

Class File

How to get a file from disk:

$file = new File("your/region/file");

How to use setContent() to set up a file stream and getContent() to get the content out of the stream:

$file = new File();
$file->setContent(file_get_contents("your/region/file"));
$file->setFileName("your/file/name");
"...do stuff here..."
$contentToBeWritten = $file->getContent();

Class Hawk

Setups:

Setup for blocks and block entities in any supported version:

// New block coordinates
$blockPos = new McCoordinates3D(1, 2, 3);

// Path to your region file and calculating the filename from the coordinates
$inputPath = "/your/world/region/directory";
$blockFiles[] = new File($inputPath . "/" . Region::getRegionFileNameFromBlock($blockPos));

// Instantiating Hawk only with blockFiles
$hawk = new Hawk(blockFiles: $blockFiles);

Setup for entities prior 1.17:

// New entity coordinates
$entityPos = new McCoordinatesFloat(1.2, 2.3, 3.4);

// Path to your region file and calculating the filename from the coordinates
$inputPath = "/your/world/region/directory";
$entitiesFiles[] = new File($inputPath . "/" . Region::getRegionFileNameFromBlock(McCoordinatesFloat::get3DCoordinates($entityPos)));

// Instantiating Hawk only with blockFiles because entities used to be in the same file
$hawk = new Hawk(blockFiles: $entitiesFiles);

Setup for entities starting from 1.17:

// Path to your entities directory and calculating the filename from the coordinates
$inputPath = "/your/world/entities/directory";
$entitiesFiles[] = new File($inputPath . "/" . Region::getRegionFileNameFromBlock(McCoordinatesFloat::get3DCoordinates($entityPos)));

$hawk = new Hawk(entitiesFiles: $entitiesFiles);

How to read a block:

$block = $hawk->getBlock($blockPos);

How to replace a block at x = 1, y = 2, z = 3 with wool(default is minecraft:stone):

$hawk->replaceBlock($blockPos, "minecraft:wool");
$hawk->save();

Get all entities in a specific chunk:

$entities = $hawk->getAllEntitiesFromChunk(McCoordinatesFloat::get3DCoordinates($entityPos));

How to get all entities next to float coordinates (there could be more than just one):

$entities = $hawk->getEntities($entityName,$entityPos);

How to delete an entity:

$entities = $hawk->getEntities($entityName,$entityPos);
$hawk->deleteEntity($entities[0]);
$hawk->save();

Get all block entities in a specific chunk:

$entities = $hawk->getAllBlockEntitiesFromChunk(McCoordinatesFloat::get3DCoordinates($entityPos));

How to get all block entities next to float coordinates (there could be more than just one):

$entities = $hawk->getBlockEntities($entityName,$entityPos);

How to delete a block entity:

$entities = $hawk->getBlockEntities($entityName,$entityPos);
$hawk->deleteBlockEntity($entities[0]);
$hawk->save();

For more information see these examples: getBlock.php, replaceBlock.php, getEntity.php, getAllEntitiesInChunk.php, deleteEntity.php.

Methods

Class Region

A region object represents a Minecraft region file. The main tasks of a region object is to read/decompress and write/compress chunks from/to its region file. Additionally, it provides static functions to calculate region coordinates and its file name.

Methods

Class Chunk

A chunk object represents a Minecraft chunk in Mojangs chunk format. The main task of a chunk object is to replace the sections tag of the NBT structure, compress the new chunk data and provide it to its region. Additionally, it provides a static function to calculate chunk coordinates.

Methods

Class Section

A section object represents a single section tag.

Methods