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

Name	Return type	Description
loadBlockRegions(File[] $files)	void	Load extra "block"("world/region") regions from $files into Hawk
loadEntitiesRegions(File[] $files)	void	Load extra "entities"("world/entities") regions from $files into Hawk
getBlockRegionFromBlock(McCoordinates3D $coordinates)	Region	Get block region from block at $coordinates
getEntitiesRegionFromBlock(McCoordinates3D $coordinates)	Region	Get entities region from block at $coordinates (see McCoordinatesFloat::get3DCoordinates for entity coords)
getBlock(McCoordinates3D $coordinates)	DataBlock	Get block at $coordinates
replaceBlock(McCoordinates3D $coordinates, string $blockName = "minecraft:stone")	void	Replace block at $coordinates with block $blockName
getEntities(string $name, McCoordinatesFloat $coordinates)	Entity[]	Gets one or multiple entities at $coordinates
getAllEntitiesFromChunk(McCoordinates3D $blockCoordinates)	Entity[]	Gets all entities in chunk based on $coordinates
deleteEntity(Entity $entity)	void	Deletes an entity object
getEntities(string $name, McCoordinatesFloat $coordinates)	Entity[]	Gets one or multiple entities at $coordinates
getAllEntitiesFromChunk(McCoordinates3D $blockCoordinates)	Entity[]	Gets all entities in chunk based on $coordinates
deleteEntity(Entity $entity)	void	Deletes an entity object
save()	void	Save changes to file

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

Name	Return type	Description
static getRegionFileNameFromBlock(McCoordinates3D $coordinates)	string	Get region file name out of block coordinates
static getRegionCoordinatesFromFile(AbstractFile $file)	McCoordinates2D	Get region coordinates from file name
static getRegionCoordinatesFromBlockCoordinates(McCoordinates3D $coordinates)	McCoordinates2D	Get region coordinates from block coordinates
static getRegionCoordinatesFromChunkCoordinates(McCoordinates2D $coordinates)	McCoordinates2D	Get region coordinates from chunk coordinates

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

Name	Return type	Description
static getChunkCoordinates(McCoordinates3D $coordinates)	McCoordinates2D	Get chunk coordinates from block coordinates

Class Section

A section object represents a single section tag.

Methods

Name	Return type	Description
static getSectionCoordinates(McCoordinates3D $coordinates)	McCoordinates3D	Get section coordinates from block coordinates
static getBlockCoordinates(McCoordinates3D $coordinates)	McCoordinates3D	Get block coordinates relative to its section