PHPackages                             aternos/thanos - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Utility & Helpers](/categories/utility)
4. /
5. aternos/thanos

ActiveLibrary[Utility & Helpers](/categories/utility)

aternos/thanos
==============

Simple library to detect and remove unused chunks from a Minecraft world.

v3.0.0(3mo ago)263586.9k↑106.3%26[2 issues](https://github.com/aternosorg/thanos/issues)MITPHPPHP >=8.4CI passing

Since Sep 2Pushed 2mo ago9 watchersCompare

[ Source](https://github.com/aternosorg/thanos)[ Packagist](https://packagist.org/packages/aternos/thanos)[ RSS](/packages/aternos-thanos/feed)WikiDiscussions master Synced 1mo ago

READMEChangelog (10)Dependencies (8)Versions (31)Used By (0)

Thanos
======

[](#thanos)

About
-----

[](#about)

Thanos is a PHP library to automatically detect and remove unused chunks from Minecraft worlds. This can reduce the file size of a world by more than 50%.

Other than existing tools, this library does not use blocklists. Instead, the inhabited time value is used to determine whether a chunk is used or not. This prevents used chunks from sometimes being removed by accident and makes this library compatible with most mods and plugins.

Only Minecraft: Java Edition worlds are supported.

Installation
------------

[](#installation)

```
composer require aternos/thanos
```

To work with LZ4 compressed chunks (Minecraft 1.20.5+), you should also install the [PHP LZ4 extension](https://github.com/kjdev/php-ext-lz4).

Known issues
------------

[](#known-issues)

World features like trees that cross chunk borders can sometimes look cut off, if the chunk containing half of the feature is removed while the other half is not. Details can be found in this issue: [\#20](https://github.com/aternosorg/thanos/issues/20)

CLI usage
---------

[](#cli-usage)

This library includes a simple cli tool.

```
./thanos.php /path/to/world/directory [/path/to/output/directory]
```

Thanos uses [Taskmaster](https://github.com/aternosorg/taskmaster) for asynchronous tasks, which can be configured [using environment variables](https://github.com/aternosorg/taskmaster#defining-workers-using-environment-variables).

### Windows support

[](#windows-support)

While Thanos will generally work on Windows, it will be much slower since asynchronous tasks are not supported. It is therefore recommended to use the [Windows Subsystem for Linux](https://learn.microsoft.com/en-us/windows/wsl/install) to run Thanos on Windows.

Library usage
-------------

[](#library-usage)

To use Thanos as a library, create a Thanos object that is configured with the desired Patterns to match chunks which should be kept.

```
$thanos = new \Aternos\Thanos\Thanos([
    new \Aternos\Thanos\Pattern\RangePattern(0, 0, 16, 16), //keep chunks in range x:0 z:0 to x:16 z:16
]);
```

You can then pass a World object and a destination directory to the `snap` method to remove chunks that match none of the patterns.

```
$world = \Aternos\Thanos\World\World::open("/path/to/world/");
$destination = new \Aternos\IO\System\Directory\Directory("/path/to/output/");
$removedChunks = $thanos->snap($world, $destination);
echo "Removed " . $removedChunks . " chunks\n";
```

### Chunk patterns

[](#chunk-patterns)

To decide which chunks should be kept, Thanos uses chunk patterns, which implement the `ChunkPatternInterface`. Built-in patterns include a `ListPattern`, which keeps chunks based on a predefined list of chunk coordinates, and a `RangePattern`, which keeps all chunks in a defined rectangular area.

#### Pattern factories

[](#pattern-factories)

Sometimes a pattern cannot be defined statically, but needs to be created based on the world data. It is therefore possible to also pass instances of `WorldPatternFactoryInterface` for world-based pattern creation, and `DimensionPatternFactoryInterface` for dimension-based pattern creation to the Thanos constructor.

An example for a dimension-based pattern factory is the `ForceLoadedChunksPatternFactory`. This factory reads the list of force-loaded chunks for a dimension and creates a `ListPattern` to keep those chunks.

```
$thanos = new \Aternos\Thanos\Thanos([
    new \Aternos\Thanos\Pattern\Factory\ForceLoadedChunkPatternFactory()
]);
```

### MCA reader and writer

[](#mca-reader-and-writer)

Thanos includes an implementation that can be used to interact with Minecraft MCA files directly.

### McaReader

[](#mcareader)

```
$reader = \Aternos\Thanos\Mca\McaReader::open("/path/to/world/region/r.0.0.mca");
$chunk = $reader->getChunk(123); //Get at index 123 in region file
$chunk = $reader->getChunkAt(12, 23); //Get chunk at chunk coordinates x:12 z:23

// Iterate over all chunks in the region file
foreach ($reader->getChunks() as $chunk) {
    //Do something with chunk
}

$reader->close();
```

### McaWriter

[](#mcawriter)

```
$writer = \Aternos\Thanos\Mca\McaWriter::open("/path/to/world/region/r.0.0.mca");
$writer->writeEntry($chunk); // Write a chunk to the MCA file

$writer->close(); // Finalize and close the MCA file
```

###  Health Score

63

—

FairBetter than 99% of packages

Maintenance83

Actively maintained with recent releases

Popularity51

Moderate usage in the ecosystem

Community20

Small or concentrated contributor base

Maturity79

Established project with proven stability

 Bus Factor1

Top contributor holds 88.3% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~62 days

Recently: every ~19 days

Total

27

Last Release

103d ago

Major Versions

v0.12.0 → v2.x-dev2025-11-18

v2.2.0 → v3.0.02026-02-04

PHP version history (4 changes)v0.2.3PHP ^7.2

v0.3.0PHP ^7.4 || ^8.0

v0.7.0PHP >=8.1

v2.x-devPHP >=8.4

### Community

Maintainers

![](https://www.gravatar.com/avatar/182e603c02f308d1036a1ecaba0b994665e87d13a86ff4550a96c9189a92c544?d=identicon)[aternos](/maintainers/aternos)

---

Top Contributors

[![KurtThiemann](https://avatars.githubusercontent.com/u/26512466?v=4)](https://github.com/KurtThiemann "KurtThiemann (68 commits)")[![pavog](https://avatars.githubusercontent.com/u/4786628?v=4)](https://github.com/pavog "pavog (6 commits)")[![matthi4s](https://avatars.githubusercontent.com/u/8943286?v=4)](https://github.com/matthi4s "matthi4s (2 commits)")[![pavel-redkin](https://avatars.githubusercontent.com/u/11919506?v=4)](https://github.com/pavel-redkin "pavel-redkin (1 commits)")

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/aternos-thanos/health.svg)

```
[![Health](https://phpackages.com/badges/aternos-thanos/health.svg)](https://phpackages.com/packages/aternos-thanos)
```

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)