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
composer require aternos/hawkHow 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();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);$block = $hawk->getBlock($blockPos);$hawk->replaceBlock($blockPos, "minecraft:wool");
$hawk->save();$entities = $hawk->getAllEntitiesFromChunk(McCoordinatesFloat::get3DCoordinates($entityPos));$entities = $hawk->getEntities($entityName,$entityPos);$entities = $hawk->getEntities($entityName,$entityPos);
$hawk->deleteEntity($entities[0]);
$hawk->save();$entities = $hawk->getAllBlockEntitiesFromChunk(McCoordinatesFloat::get3DCoordinates($entityPos));$entities = $hawk->getBlockEntities($entityName,$entityPos);$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.
| 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 |
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.
| 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 |
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.
| Name | Return type | Description |
|---|---|---|
| static getChunkCoordinates(McCoordinates3D $coordinates) | McCoordinates2D | Get chunk coordinates from block coordinates |
A section object represents a single section tag.
| 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 |