{"id":19527309,"url":"https://github.com/papermc/sectortool","last_synced_at":"2025-07-29T04:04:35.180Z","repository":{"id":221555792,"uuid":"749067052","full_name":"PaperMC/SectorTool","owner":"PaperMC","description":null,"archived":false,"fork":false,"pushed_at":"2024-06-22T21:49:41.000Z","size":218,"stargazers_count":23,"open_issues_count":1,"forks_count":3,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-07-22T22:30:57.952Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/PaperMC.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"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},"funding":{"github":"PaperMC","open_collective":"PaperMC"}},"created_at":"2024-01-27T13:49:10.000Z","updated_at":"2025-04-04T03:35:26.000Z","dependencies_parsed_at":"2024-02-08T17:49:06.524Z","dependency_job_id":"4bc859f4-2680-4b42-989d-16709845f153","html_url":"https://github.com/PaperMC/SectorTool","commit_stats":{"total_commits":18,"total_committers":1,"mean_commits":18.0,"dds":0.0,"last_synced_commit":"2ebdb32b6f08c89a4bd39b5879f2709b23a77acf"},"previous_names":["papermc/sectortool"],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/PaperMC/SectorTool","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PaperMC%2FSectorTool","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PaperMC%2FSectorTool/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PaperMC%2FSectorTool/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PaperMC%2FSectorTool/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/PaperMC","download_url":"https://codeload.github.com/PaperMC/SectorTool/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PaperMC%2FSectorTool/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":267626671,"owners_count":24117700,"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-07-29T02:00:12.549Z","response_time":2574,"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-11T01:14:35.683Z","updated_at":"2025-07-29T04:04:35.150Z","avatar_url":"https://github.com/PaperMC.png","language":"Java","readme":"# SectorTool\n\nSectorTool primarily performs conversion and deconversion of worlds from/to\nthe SectorFile format. It can also perform benchmarks or other analysis of\nRegionFiles.\n\nIt's highly recommended to only use this tool on **COPIES** of worlds.\n\nThe test branch does not contain any conversion code, you **MUST** use this tool\nto convert.\n\nThis tool does not attempt to fix errors in RegionFiles. Make sure your world\nhas no errors in your RegionFiles before converting.\n\nSectorTool can perform one of these operations:\n1. [Convert to SectorFile](#conversion-to-sectorfile-from-regionfile)\n2. [Deconvert from SectorFile](#conversion-from-sectorfile-to-regionfile-deconversion)\n3. [Verify consistency from RegionFile to SectorFile](#verification-test)\n4. [Perform compression tests on RegionFiles](#compression-test)\n5. [Read results from compression tests](#read-compression-test)\n6. [Analyse sector allocation for RegionFiles](#analyse-regionfiles)\n\nSee [the specification](SPECIFICATION.MD) for exact details on the SectorFile\nformat.\n\n## World Layout\n\nDescribed are the folder layouts of world data in Vanilla and Bukkit.\n\n### Vanilla\n\nVanilla has the overworld under the `world` directory, with its data being placed\ndirectly in the `world` folder. The nether's data is placed under `world/DIM-1`,\nthe end's data is placed under `world/DIM1`.\n\n### Bukkit (Spigot/Paper/Folia)\n\nIf you run Bukkit, Spigot, Paper, or Folia your worlds are formatted in the \"Bukkit\"\nlayout. The Bukkit layout places the overworld in the `world` folder in the root\nserver directory. The nether is placed in the `world_nether` folder in the root\nserver directory, however its data (excluding level.dat and friends) is placed\nunder `world_nether/DIM-1`, similar to how Vanilla would store under `world/DIM-1`.\nThe end is placed in the `world_the_end` folder in the root server directory, \nwith its data being stored in `world_the_end/DIM1`.\n\n### Changes\n\nInstead of data being stored under `entities`, `poi`, and `region` data will\nonly be stored under the `sectors` directory. SectorFiles contain entities, \npoi, and region data under one SectorFile rather than multiple RegionFiles.\n\n## Primary Usages\n\n### Conversion to SectorFile from RegionFile\n\nConverts a single world to the SectorFile format. The old RegionFiles\nwill not be deleted (folders: entities, poi, region), it is recommended \nthat you move them after conversion. By moving the old data once you have\nconverted, it will be easier to convert back to RegionFile.\n\n#### Behavior for already converted worlds\n\nAdditionally, there are no checks in-place to detect worlds already converted. \nConversion will simply write the data found in the RegionFiles to the SectorFiles,\nso if the SectorFiles have additional data for chunks not present in the original\nRegionFiles they will be unaffected - but the chunks present in the RegionFiles\nwill be copied.\n\nIf you do not want this merging behavior then delete the `sectors` folder.\n\n#### Command and options\n\n```shell\njava -Dop=conv \\\n -Dthreads=\u003cthreads\u003e \\\n -Dinput=\"\u003cinput\u003e\" \\\n -Dcompress=\u003ccompress type id\u003e \\\n -jar sectortool.jar\n```\n\n#### threads (optional)\n\nSpecified number of threads to use. Use 1 for HDDs, use larger amounts\nfor SSDs. Defaults to 1/2 of available processors.\n\n#### input\n\nInput root world directory. For Vanilla worlds, this is plainly just the \nroot world directory. For Bukkit worlds, you will want to run the tool for \neach dimension, using the root world directory as input (i.e. point to \n`world`, `world_nether`, and `world_the_end`) for each dimension.\n\n#### compress\n\nThe compression type to use on the new SectorFiles. Values:\n* GZIP (id = 1)\n* DEFLATE (id = 2)\n* NONE (id = 3)\n* LZ4 (id = 4)\n* ZSTD (id = 5)\n* COPY (id = -1)\n\nDEFLATE (id = 2) is the current default. LZ4 (id = 4) is fast but not space \nefficient. ZSTD (id = 5) is fast and slightly less space efficient than DEFLATE.\n\nThe COPY compression type will copy the compressed data from the source \nRegionFiles. Note that the COPY compression type will not perform \ndecompression/recompression, unlike the rest of the compression options, \nwhich should greatly reduce CPU load.\n\n\n### Conversion from SectorFile to RegionFile (Deconversion)\n\nConverts a world from SectorFile format back to RegionFile format. It is \nhighly recommended that you ensure that no RegionFiles are in the current world\n(just move them to a separate directory), as the original conversion process from\nRegionFile to SectorFile done by this tool **WILL NOT** delete RegionFiles. Note \nthat the converted SectorFiles will not be deleted, you will need to do that.\n\n#### Command and options\n\n```shell\njava -Dop=deconv \\\n -Dthreads=\u003cthreads\u003e \\\n -Dinput=\"\u003cinput\u003e\" \\\n -Dcompress=\u003ccompress type id\u003e \\\n -jar sectortool.jar\n```\n\n#### threads (optional)\n\nSpecified number of threads to use. Use 1 for HDDs, use larger amounts\nfor SSDs. Defaults to 1/2 of available processors.\n\n#### input\n\nInput root world directory. For Vanilla worlds, this is plainly just the\nroot world directory. For Bukkit worlds, you will want to run the tool for\neach dimension, using the root world directory as input (i.e. point to\n`world`, `world_nether`, and `world_the_end`) for each dimension.\n\n#### compress\n\nThe compression type to use on the RegionFiles. Values:\n* GZIP (id = 1)\n* DEFLATE (id = 2)\n* NONE (id = 3)\n* LZ4 (id = 4)\n\nDEFLATE (id = 2) is the current default for Vanilla. LZ4 (id = 4) is \n**NOT** supported outside the latest snapshot, so do **NOT** use LZ4 \nunless it is **FOR** snapshot worlds.\n\nNote that ZSTD is not present because Vanilla RegionFile does not support ZSTD.\n\n### Verification Test\n\nVerifies that all data contained in the RegionFiles are contained in\nthe SectorFiles. This will not detect extra data in the SectorFiles.\n\n#### Command and options\n\n```shell\njava -Dop=verify \\\n -Dthreads=\u003cthreads\u003e \\\n -Dinput=\"\u003cinput\u003e\" \\\n -Dcompress=\u003ccompress type id\u003e \\\n -jar sectortool.jar\n```\n\n#### threads (optional)\n\nSpecified number of threads to use. Use 1 for HDDs, use larger amounts\nfor SSDs. Defaults to 1/2 of available processors.\n\n#### input\n\nInput root world directory. For Vanilla worlds, this is plainly just the\nroot world directory. For Bukkit worlds, you will want to run the tool for\neach dimension, using the root world directory as input (i.e. point to\n`world`, `world_nether`, and `world_the_end`) for each dimension.\n\n#### compress (required but unused, pick one)\n\nValues:\n* GZIP (id = 1)\n* DEFLATE (id = 2)\n* NONE (id = 3)\n* LZ4 (id = 4)\n* ZSTD (id = 5)\n\n## Secondary Usages\n\n### Compression Test\n\nPerforms compression tests (time to decompress, compress, and resulting \ncompression ratios) and store the results in a file which may be later \nused by the [Compression Read](#read-compression-test) operation.\n\n```shell\njava -Dop=test \\\n -Dthreads=\u003cthreads\u003e \\\n -Dinput=\"\u003cinput\u003e\" \\\n -Doutput=\"\u003coutput\u003e\" \\\n -Dmax_regions=\u003cmax regions\u003e \\\n -jar sectortool.jar\n```\n\n#### input\n\nInput directory of RegionFiles to run tests on. This is not a world directory,\nit is a directory containing `.mca` files.\n\n#### output\n\nFile to store test results in. This file should not exist, the tool will exit\nif it does.\n\n#### max_regions (optional)\n\nThe maximum number of RegionFiles to test on. Defaults to infinity.\n\n#### threads (optional)\n\nSpecified number of threads to use. Use 1 for HDDs, use larger amounts\nfor SSDs. Defaults to 1/2 of available processors.\n\n\n### Read Compression Test\n\nReads result file from a compression test, converting the data to some \nsummary stats printed to stdout as well as converting the results to raw data\nprinted to `results.psv` in the working directory.\n\n\n```shell\njava -Dop=read \\\n -Dinput=\"\u003cinput\u003e\" \\\n -jar sectortool.jar\n```\n\n#### input\n\nResults file generated by the compression test.\n\n### Analyse RegionFiles\n\nComputes the total number of 4096 byte sectors used by RegionFiles on disk \n(\"file sectors\"), the number of 4096 byte sectors allocated to live data by \nRegionFiles on disk (\"allocated sectors\"), the theoretical number of 512 byte \nsectors allocated (\"alternate allocated sectors\"), the total size of compressed \ndata in bytes (\"total data size\"), and the number of obvious (header offsets/length\nare invalid or point outside of file) errors in RegionFile headers (\"errors\").\n\nComputing `allocated sectors / file sectors` gives some indication of RegionFile\nfragmentation.\n\nComputing `allocated sectors / alternate allocated sectors * (4096/512)` gives\nsome indication of the improvements expected to come by using SectorFile.\n\n#### Command and options\n\n```shell\njava -Dop=analyse \\\n -Dthreads=\u003cthreads\u003e \\\n -Dinput=\"\u003cinput\u003e\" \\\n -jar sectortool.jar\n```\n\n#### threads (optional)\n\nSpecified number of threads to use. Use 1 for HDDs, use larger amounts\nfor SSDs. Defaults to 1/2 of available processors.\n\n#### input\n\nInput root world directory. For Vanilla worlds, this is plainly just the\nroot world directory. For Bukkit worlds, you will want to run the tool for\neach dimension, using the root world directory as input (i.e. point to\n`world`, `world_nether`, and `world_the_end`) for each dimension.","funding_links":["https://github.com/sponsors/PaperMC","https://opencollective.com/PaperMC"],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpapermc%2Fsectortool","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpapermc%2Fsectortool","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpapermc%2Fsectortool/lists"}