{"id":16134482,"url":"https://github.com/piegamesde/nbt","last_synced_at":"2025-08-21T08:12:48.228Z","repository":{"id":134164785,"uuid":"136232319","full_name":"piegamesde/nbt","owner":"piegamesde","description":"Named Binary Tag (NBT) library for Java with focus on usability and performance","archived":false,"fork":false,"pushed_at":"2021-12-04T16:11:36.000Z","size":10212,"stargazers_count":5,"open_issues_count":0,"forks_count":0,"subscribers_count":3,"default_branch":"develop","last_synced_at":"2024-12-20T02:41:58.146Z","etag":null,"topics":["minecraft","nbt-library"],"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/piegamesde.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","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}},"created_at":"2018-06-05T20:39:56.000Z","updated_at":"2024-11-16T12:25:57.000Z","dependencies_parsed_at":null,"dependency_job_id":"50dbd0cd-ac0a-4db4-bc42-144a65a5d317","html_url":"https://github.com/piegamesde/nbt","commit_stats":null,"previous_names":[],"tags_count":5,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/piegamesde%2Fnbt","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/piegamesde%2Fnbt/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/piegamesde%2Fnbt/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/piegamesde%2Fnbt/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/piegamesde","download_url":"https://codeload.github.com/piegamesde/nbt/tar.gz/refs/heads/develop","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":238557017,"owners_count":19491945,"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","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","nbt-library"],"created_at":"2024-10-09T22:49:03.453Z","updated_at":"2025-02-12T21:48:43.905Z","avatar_url":"https://github.com/piegamesde.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"# NBT [![](https://jitpack.io/v/piegamesde/nbt.svg)](https://jitpack.io/#piegamesde/nbt)\n\nNamed Binary Tag (NBT) library for Java at the end of a long fork chain. This has been forked from flow-nbt, which itself has its root in JNBT.\n\nNBT is a tag based binary format designed to carry large amounts of binary data with smaller amounts of additional data. See [one of the wikis](https://wiki.vg/NBT) for more information\n\n## Features\n\n- Hide the pain through the usage of Java 8's `Optional`\n- Parse whole Region files in the Anvil format\n- Helper methods to analyse a chunk's content (e.g. parse the Minecraft packed palette data)\n- Option to keep all arrays as `byte[]` to improve performance\n- Compatible with Minecraft 1.16\n\n## Getting started\n\nGo to [Jitpack.io](https://jitpack.io/#piegamesde/gson-fire) and follow the instructions.\n\nDependency string in Gradle:\n```groovy\ndependencies {\n\timplementation 'com.github.piegamesde:nbt:3.0.1'\n}\n```\n\nMaven:\n```xml\n\u003cdependency\u003e\n\t\u003cgroupId\u003ecom.github.piegamesde\u003c/groupId\u003e\n\t\u003cartifactId\u003enbt\u003c/artifactId\u003e\n\t\u003cversion\u003e3.0.1\u003c/version\u003e\n\u003c/dependency\u003e\n```\n\n## Usage\n\n### NBT file usage\n\nEntry points to the API are the `NBTInputStream` and `NBTOutputStream` classes, which are used to read or write one complex NBT tag. Different data compressions are available. NBT data is stored in a `Tag`. A tag has a name and a value, there is one sub-class for each tag type. Because casting yourself around the NBT tree is not a lot of fun, there are a ton of helper methods that return the cast type if possible, or an empty `Optional` if not. This leverages the whole power and syntax sugar of Java's `Optional` class.\n\nIf you don't like `Optional`, you can still call `Tag::getValue` and manually cast things around. There are cases where this is actually preferable.\n\n```java\ntry (NBTInputStream in = new NBTInputStream(Files.newInputStream(myPath), NBTInputStream.GZIP_COMPRESSION)) {\n\t/* Read all the data into a tag */\n\tTag\u003c?\u003e dataRaw = in.readTag();\n\t/* Those helper method give an `Optional\u003cFooTag\u003e` that's better to use than a plain downcast */\n\tCompoundTag data = dataRaw.getAsCompoundTag().get();\n\t\n\t// Do something with the data in here:\n\t\n\t/* Directly access child values with the correct type, if present */\n\tint version = data.getIntValue(\"version\").get();\n\t/* Get sub tags (not only their value) as well */\n\tCompoundTag subData = data.getCompoundTag(\"subDataTag\");\n\t\n\t/* Reald-world use case example (simplified): get the player dimension of a Minecraft level.dat, but the data type changed from int to string over time. */\n\tvar dimension = subData.getIntValue(\"Dimension\")\n\t\t\t.map(dim -\u003e (new String[] { \"Overworld\", \"Nether\", \"End\"})[dim])\n\t\t\t.orElseGet(() -\u003e subData.getStringValue(\"Dimension\").get());\n}\n```\n\n### Region/Anvil file usage\n\nA Minecraft save file can be loaded using class `RegionFile`. It allows reading and writing chunks and metadata. The (lazily) loaded data of a chunk is represented through a `Chunk` object, which may give access to its data (usually containing a `ComoundTag`). Saving modified chunks back to the region file is also supported.\n\n```java\ntry (RegionFile regionFile = new RegionFile(Paths.get(myWorld, \"region\", \"r.0.0.mca\"))) {\n\tList\u003cInteger\u003e list = regionFile.listChunks();\n\tfor (int i : list) {\n\t\tChunk chunk = regionFile.loadChunk(i);\n\t\tCompoundTag data = chunk.readTag();\n\t}\n}\n```\n\n### Primitive array optimization\n\n- Pass `rawArrays = true` when initializing the `NBTInputStream`\n- All primitive arrays will now be parsed as `ByteArrayTag`\n- Use methods like `ByteArrayTag::getShortArrayValue` to lazily convert the bytes as needed\n- If a specialized `Tag` subclass is somehow required, this can be done as well using e.g. `ByteArrayTag::getAsIntArrayTag`\n\n```java\ntry (NBTInputStream in = new NBTInputStream(Files.newInputStream(myPath), NBTInputStream.GZIP_COMPRESSION, true)) {\n\tCompoundTag data = in.readTag().getAsCompoundTag().get();\n\t\n\tByteArrayTag array = data.getByteArrayValue(\"uuid\").get();\n\tint[] uuid = array.getIntArrayValue();\n}\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpiegamesde%2Fnbt","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpiegamesde%2Fnbt","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpiegamesde%2Fnbt/lists"}