{"id":36419838,"url":"https://github.com/hollow-cube/polar","last_synced_at":"2026-01-11T17:05:27.769Z","repository":{"id":170342041,"uuid":"646329737","full_name":"hollow-cube/polar","owner":"hollow-cube","description":"Fast and small world format for Minestom","archived":false,"fork":false,"pushed_at":"2025-10-06T19:55:13.000Z","size":72106,"stargazers_count":140,"open_issues_count":7,"forks_count":14,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-10-06T21:28:47.531Z","etag":null,"topics":["minecraft","minestom","minestom-library","world-format"],"latest_commit_sha":null,"homepage":"","language":"Java","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/hollow-cube.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,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2023-05-28T03:19:14.000Z","updated_at":"2025-10-01T17:07:39.000Z","dependencies_parsed_at":"2024-03-22T01:47:26.322Z","dependency_job_id":"9b01d164-3fe2-4ca4-988b-88dd7b4ac3e6","html_url":"https://github.com/hollow-cube/polar","commit_stats":null,"previous_names":["hollow-cube/polar"],"tags_count":49,"template":false,"template_full_name":null,"purl":"pkg:github/hollow-cube/polar","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hollow-cube%2Fpolar","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hollow-cube%2Fpolar/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hollow-cube%2Fpolar/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hollow-cube%2Fpolar/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/hollow-cube","download_url":"https://codeload.github.com/hollow-cube/polar/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hollow-cube%2Fpolar/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28314264,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-11T14:58:17.114Z","status":"ssl_error","status_checked_at":"2026-01-11T14:55:53.580Z","response_time":60,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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":["minecraft","minestom","minestom-library","world-format"],"created_at":"2026-01-11T17:05:27.222Z","updated_at":"2026-01-11T17:05:27.763Z","avatar_url":"https://github.com/hollow-cube.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Polar\n\n[![license](https://img.shields.io/github/license/Minestom/MinestomDataGenerator.svg)](LICENSE)\n\nA world format for Minestom designed for simpler and smaller handling of small worlds, particularly for user generated\ncontent where size matters.\n\nPolar generally should not be used for large worlds, since it stores worlds in a single file and does not\nallow random access of chunks (the entire world must be loaded to read chunks). As a general rule of thumb,\nPolar should only be used for worlds small enough that they are OK being completely kept in memory.\n\nThe Polar format is described in [FORMAT.md](FORMAT.md).\n\n## Features\n\n* [Fast to load](#benchmark)\n* [Small file size](#benchmark)\n* Simple to use\n* [Anvil conversion](#anvil-interop)\n\n## Install\n\nPolar is available on [maven central](https://search.maven.org/search?q=g:dev.hollowcube%20AND%20a:polar).\n\n```groovy\nrepositories {\n    mavenCentral()\n}\n\ndependencies {\n    implementation 'dev.hollowcube:polar:\u003csee releases\u003e'\n}\n```\n\n## Usage\n\nPolar provides a `ChunkLoader` implementation for use with Minestom `Instance`s.\n\n```\n// Loading\nInstance instance=...;\ninstance.setChunkLoader(new PolarLoader(Path.of(\"/path/to/file.polar\")));\n\n// Saving\ninstance.saveChunksToStorage();\n```\n\n### Anvil interop\n\nAnvil conversion utilities are also included, and can be used something like the following.\n\n\u003e Note: Anvil conversion is only guaranteed to work on the latest version worlds. Try loading and saving the world in a\n\u003e vanilla client or server if it doesnt work!\n\n```\nvar polarWorld = AnvilPolar.anvilToPolar(Path.of(\"/path/to/anvil/world/dir\"));\nvar polarWorldBytes=PolarWriter.write(polarWorld);\n```\n\n### ChunkSelector\n\nMost Polar functions take a `ChunkSelector` as an optional parameter to select which chunks to include in that\noperation.\nFor example, to convert an anvil world while only selecting a 5 chunk radius around 0,0, you could do the following:\n\n```\nAnvilPolar.anvilToPolar(Path.of(\"/path/to/anvil/world/dir\"), ChunkSelector.radius(5));\n```\n\n### User data \u0026 callbacks\n\nBy default, Polar only stores blocks, biomes, block entities, and light data. However, in many cases it is desirable\nto have some additional user specific data stored in the world. To accommodate this use case, Polar chunks each have\na \"user data\" field, which can contain any arbitrary data. To work with it, you must implement `PolarWorldAccess`,\nand provide an instance to the `PolarLoader` for example, the following will write the time of save in each chunks\nuser data:\n\n```java\npublic class UpdateTimeWorldAccess implements PolarWorldAccess {\n    private static final Logger logger = LoggerFactory.getLogger(UpdateTimeWorldAccess.class);\n\n    @Override\n    public void loadChunkData(@NotNull Chunk chunk, @Nullable NetworkBuffer userData) {\n        if (userData == null) return; // No saved data, probably first load\n\n        long lastSaveTime = userData.read(NetworkBuffer.LONG);\n        logger.info(\"loading chunk {}, {} which was saved at {}.\", chunk.getChunkX(), chunk.getChunkZ(), lastSaveTime);\n    }\n\n    @Override\n    public void saveChunkData(@NotNull Chunk chunk, @NotNull NetworkBuffer userData) {\n        userData.write(NetworkBuffer.LONG, System.currentTimeMillis());\n    }\n}\n```\n\nUsing a `PolarWorldAccess` implementation is as simple as attaching it to the `PolarLoader`:\n`new PolarLoader(world).setWorldAccess(new UpdateTimeWorldAccess())`\n\n## Comparison to others\n\n### \"Benchmark\"\n\nUsing a very basic benchmark, we can make some rough guesses about performance between Polar, Anvil, and TNT.\nThe benchmark loads a single region 10 times, averaging the runtime of each iteration.\nMore information about the test can be found in [BENCHMARK.md](BENCHMARK.md)\n\n| Scenario        | Iterations | Polar (v1, zstd) | Polar (v1, uncompressed) | TNT (v1)       | Anvil          |\n|-----------------|------------|------------------|--------------------------|----------------|----------------|\n| 1.19.4 Region   | 10         | 0.61400 s/iter   | 0.56449 s/iter           | 3.56732 s/iter | 9.65274 s/iter |\n| EmortalMC Lobby | 10         | 0.06565 s/iter   | 0.04759 s/iter           | 0.05501 s/iter | 0.56378 s/iter |\n| EmortalMC Lobby | 500        | 0.06777 s/iter   | 0.06650 s/iter           | 0.07553 s/iter | -              |\n\n| Scenario        | Polar (v1, zstd) | Polar (v1, uncompressed) | TNT (v1) | Anvil |\n|-----------------|------------------|--------------------------|----------|-------|\n| 1.19.4 Region   | 5.9mb            | 26.1mb                   | 115.9mb  | 9.7mb |\n| EmortalMC Lobby | 105kb            | 800kb                    | 1.3mb    | 13mb* |\n\n* This is not a fair comparison. Polar and TNT are only covering the 10x10 relevant chunks, anvil has 4 regions.\n\n1.19.4 Region is a single 32x32 chunk region created in 1.19.4, see `src/test/resources/bench` for the world.\n\nEmortalMC Lobby is 10x10 chunk world, see `mc.emortal.dev` for more info.\n\n## Contributing\n\nContributions via PRs and issues are always welcome.\n\n## License\n\nThis project is licensed under the [MIT License](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhollow-cube%2Fpolar","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhollow-cube%2Fpolar","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhollow-cube%2Fpolar/lists"}