{"id":19826267,"url":"https://github.com/aternosorg/hawk","last_synced_at":"2025-08-01T15:11:38.745Z","repository":{"id":38246011,"uuid":"498315524","full_name":"aternosorg/hawk","owner":"aternosorg","description":"PHP library to get, replace and delete blocks/entities out of Minecraft region files","archived":false,"fork":false,"pushed_at":"2025-07-17T13:26:54.000Z","size":212402,"stargazers_count":9,"open_issues_count":0,"forks_count":2,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-07-22T02:29:00.962Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://packagist.org/packages/aternos/hawk","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/aternosorg.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null}},"created_at":"2022-05-31T11:55:32.000Z","updated_at":"2025-07-17T13:26:59.000Z","dependencies_parsed_at":"2024-04-17T14:26:45.293Z","dependency_job_id":"5f860f75-b8e0-4409-90a5-6c23d828e008","html_url":"https://github.com/aternosorg/hawk","commit_stats":{"total_commits":19,"total_committers":2,"mean_commits":9.5,"dds":"0.052631578947368474","last_synced_commit":"4f5c3c8fb7c62d060ec7badd301ec2241c46313f"},"previous_names":[],"tags_count":11,"template":false,"template_full_name":null,"purl":"pkg:github/aternosorg/hawk","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aternosorg%2Fhawk","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aternosorg%2Fhawk/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aternosorg%2Fhawk/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aternosorg%2Fhawk/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/aternosorg","download_url":"https://codeload.github.com/aternosorg/hawk/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aternosorg%2Fhawk/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":268248766,"owners_count":24219558,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-01T02:00:08.611Z","response_time":67,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-12T11:09:55.997Z","updated_at":"2025-08-01T15:11:38.684Z","avatar_url":"https://github.com/aternosorg.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Hawk\n\n### About\n\nHawk is a PHP library to get and/or replace blocks and get and/or delete entities in Minecraft region files.\nThis allows the user to replace blocks or delete entities that will crash the server when loaded.\n\nCurrently, following versions are supported:\n\n    1.12+ for entities\n    1.16+ for blocks\n\n### Installation\n\n```bash\ncomposer require aternos/hawk\n```\n\n## Usage\n\n### Class File\n\nHow to get a file from disk:\n```php\n$file = new File(\"your/region/file\");\n```\n\nHow to use setContent() to set up a file stream and getContent() to get the content out of the stream:\n```php\n$file = new File();\n$file-\u003esetContent(file_get_contents(\"your/region/file\"));\n$file-\u003esetFileName(\"your/file/name\");\n\"...do stuff here...\"\n$contentToBeWritten = $file-\u003egetContent();\n```\n\n### Class Hawk\n\n#### Setups:\n\nSetup for blocks and block entities in any supported version:\n\n```php\n// New block coordinates\n$blockPos = new McCoordinates3D(1, 2, 3);\n\n// Path to your region file and calculating the filename from the coordinates\n$inputPath = \"/your/world/region/directory\";\n$blockFiles[] = new File($inputPath . \"/\" . Region::getRegionFileNameFromBlock($blockPos));\n\n// Instantiating Hawk only with blockFiles\n$hawk = new Hawk(blockFiles: $blockFiles);\n```\n\nSetup for entities prior 1.17:\n\n```php\n// New entity coordinates\n$entityPos = new McCoordinatesFloat(1.2, 2.3, 3.4);\n\n// Path to your region file and calculating the filename from the coordinates\n$inputPath = \"/your/world/region/directory\";\n$entitiesFiles[] = new File($inputPath . \"/\" . Region::getRegionFileNameFromBlock(McCoordinatesFloat::get3DCoordinates($entityPos)));\n\n// Instantiating Hawk only with blockFiles because entities used to be in the same file\n$hawk = new Hawk(blockFiles: $entitiesFiles);\n```\n\nSetup for entities starting from 1.17:\n\n```php\n// Path to your entities directory and calculating the filename from the coordinates\n$inputPath = \"/your/world/entities/directory\";\n$entitiesFiles[] = new File($inputPath . \"/\" . Region::getRegionFileNameFromBlock(McCoordinatesFloat::get3DCoordinates($entityPos)));\n\n$hawk = new Hawk(entitiesFiles: $entitiesFiles);\n```\n\n#### How to read a block:\n\n```php\n$block = $hawk-\u003egetBlock($blockPos);\n```\n\n#### How to replace a block at x = 1, y = 2, z = 3 with wool(default is minecraft:stone):\n\n```php\n$hawk-\u003ereplaceBlock($blockPos, \"minecraft:wool\");\n$hawk-\u003esave();\n```\n\n#### Get all entities in a specific chunk:\n\n```php\n$entities = $hawk-\u003egetAllEntitiesFromChunk(McCoordinatesFloat::get3DCoordinates($entityPos));\n```\n\n#### How to get all entities next to float coordinates (there could be more than just one):\n\n```php\n$entities = $hawk-\u003egetEntities($entityName,$entityPos);\n```\n\n#### How to delete an entity:\n\n```php\n$entities = $hawk-\u003egetEntities($entityName,$entityPos);\n$hawk-\u003edeleteEntity($entities[0]);\n$hawk-\u003esave();\n\n```\n#### Get all block entities in a specific chunk:\n\n```php\n$entities = $hawk-\u003egetAllBlockEntitiesFromChunk(McCoordinatesFloat::get3DCoordinates($entityPos));\n```\n\n#### How to get all block entities next to float coordinates (there could be more than just one):\n\n```php\n$entities = $hawk-\u003egetBlockEntities($entityName,$entityPos);\n```\n\n#### How to delete a block entity:\n\n```php\n$entities = $hawk-\u003egetBlockEntities($entityName,$entityPos);\n$hawk-\u003edeleteBlockEntity($entities[0]);\n$hawk-\u003esave();\n```\n\nFor more information see these examples: [getBlock.php](examples/getBlock.php), [replaceBlock.php](examples/replaceBlock.php), [getEntity.php](examples/getEntity.php), [getAllEntitiesInChunk.php](examples/getAllEntitiesInChunk.php), [deleteEntity.php](examples/deleteEntity.php).\n\n#### Methods\n\n| Name                                                                                                         | Return type                   | Description                                                                                                |\n|--------------------------------------------------------------------------------------------------------------|-------------------------------|------------------------------------------------------------------------------------------------------------|\n| loadBlockRegions([File](src/File.php)[] $files)                                                              | void                          | Load extra \"block\"(\"world/region\") regions from $files into Hawk                                           |\n| loadEntitiesRegions([File](src/File.php)[] $files)                                                           | void                          | Load extra \"entities\"(\"world/entities\") regions from $files into Hawk                                      |\n| getBlockRegionFromBlock([McCoordinates3D](src/McCoordinates3D.php) $coordinates)                             | [Region](src/BlockRegion.php) | Get block region from block at $coordinates                                                                |\n| getEntitiesRegionFromBlock([McCoordinates3D](src/McCoordinates3D.php) $coordinates)                          | [Region](src/BlockRegion.php) | Get entities region from block at $coordinates (see McCoordinatesFloat::get3DCoordinates for entity coords) |\n| getBlock([McCoordinates3D](src/McCoordinates3D.php) $coordinates)                                            | [DataBlock](src/DataBlock.php) | Get block at $coordinates                                                                                  |\n| replaceBlock([McCoordinates3D](src/McCoordinates3D.php) $coordinates, string $blockName = \"minecraft:stone\") | void                          | Replace block at $coordinates with block $blockName                                                        |\n| getEntities(string $name, [McCoordinatesFloat](src/McCoordinatesFloat.php) $coordinates)                     | [Entity](src/Entity.php)[]    | Gets one or multiple entities at $coordinates                                                              |\n| getAllEntitiesFromChunk([McCoordinates3D](src/McCoordinates3D.php) $blockCoordinates)                        | [Entity](src/Entity.php)[]    | Gets all entities in chunk based on $coordinates                                                           |\n| deleteEntity([Entity](src/Entity.php) $entity)                                                               | void                          | Deletes an entity object                                                                                   |\n| getEntities(string $name, [McCoordinatesFloat](src/McCoordinatesFloat.php) $coordinates)                     | [Entity](src/Entity.php)[]    | Gets one or multiple entities at $coordinates                                                              |\n| getAllEntitiesFromChunk([McCoordinates3D](src/McCoordinates3D.php) $blockCoordinates)                        | [Entity](src/Entity.php)[]    | Gets all entities in chunk based on $coordinates                                                           |\n| deleteEntity([Entity](src/Entity.php) $entity)                                                               | void                          | Deletes an entity object                                                                                   |\n| save()                                                                                                       | void                          | Save changes to file                                                                                       |\n\n### Class Region\n\nA region object represents a Minecraft region file. \nThe main tasks of a region object is to read/decompress and write/compress chunks from/to its region file.\nAdditionally, it provides static functions to calculate region coordinates and its file name.\n\n#### Methods\n\n| Name                                                                                                     | Return type                                | Description                                   |\n|----------------------------------------------------------------------------------------------------------|--------------------------------------------|-----------------------------------------------|\n| static getRegionFileNameFromBlock([McCoordinates3D](src/McCoordinates3D.php) $coordinates)               | string                                     | Get region file name out of block coordinates |\n| static getRegionCoordinatesFromFile([AbstractFile](src/AbstractFile.php) $file)                          | [McCoordinates2D](src/McCoordinates2D.php) | Get region coordinates from file name         | \n| static getRegionCoordinatesFromBlockCoordinates([McCoordinates3D](src/McCoordinates3D.php) $coordinates) | [McCoordinates2D](src/McCoordinates2D.php) | Get region coordinates from block coordinates |\n| static getRegionCoordinatesFromChunkCoordinates([McCoordinates2D](src/McCoordinates2D.php) $coordinates) | [McCoordinates2D](src/McCoordinates2D.php) | Get region coordinates from chunk coordinates |\n\n### Class Chunk\n\nA chunk object represents a Minecraft chunk in Mojangs [chunk format](https://minecraft.fandom.com/wiki/Chunk_format).\nThe 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.\nAdditionally, it provides a static function to calculate chunk coordinates.\n\n#### Methods\n\n| Name                                                                                | Return type                                | Description                                  |\n|-------------------------------------------------------------------------------------|--------------------------------------------|----------------------------------------------|\n| static getChunkCoordinates([McCoordinates3D](src/McCoordinates3D.php) $coordinates) | [McCoordinates2D](src/McCoordinates2D.php) | Get chunk coordinates from block coordinates |\n\n### Class Section\n\nA section object represents a single section tag.\n\n#### Methods\n\n| Name                                                                                   | Return type                                | Description                                     |\n|----------------------------------------------------------------------------------------|--------------------------------------------|-------------------------------------------------|\n| static getSectionCoordinates([McCoordinates3D](src/McCoordinates3D.php) $coordinates)  | [McCoordinates3D](src/McCoordinates3D.php) | Get section coordinates from block coordinates  |\n| static getBlockCoordinates([McCoordinates3D](src/McCoordinates3D.php) $coordinates)    | [McCoordinates3D](src/McCoordinates3D.php) | Get block coordinates relative to its section   |\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faternosorg%2Fhawk","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Faternosorg%2Fhawk","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faternosorg%2Fhawk/lists"}