{"id":20218251,"url":"https://github.com/querz/nbt","last_synced_at":"2025-04-12T22:27:42.846Z","repository":{"id":15043523,"uuid":"77476835","full_name":"Querz/NBT","owner":"Querz","description":"A java implementation of the NBT protocol, including a way to implement custom tags.","archived":false,"fork":false,"pushed_at":"2025-03-04T21:44:52.000Z","size":15721,"stargazers_count":192,"open_issues_count":27,"forks_count":48,"subscribers_count":5,"default_branch":"master","last_synced_at":"2025-04-04T02:05:26.662Z","etag":null,"topics":["compression","customizable","deserialization","java","java-library","mca","mca-file","mca-files","mca-region","minecraft","nbt","nbt-parser","nbt-protocol","nbt-structure","serialization"],"latest_commit_sha":null,"homepage":null,"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/Querz.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}},"created_at":"2016-12-27T19:04:49.000Z","updated_at":"2025-03-19T01:53:50.000Z","dependencies_parsed_at":"2024-04-18T22:27:06.615Z","dependency_job_id":"320a2f65-93e9-4a98-9f03-a47867b6bba6","html_url":"https://github.com/Querz/NBT","commit_stats":null,"previous_names":[],"tags_count":21,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Querz%2FNBT","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Querz%2FNBT/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Querz%2FNBT/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Querz%2FNBT/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Querz","download_url":"https://codeload.github.com/Querz/NBT/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248639180,"owners_count":21137794,"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":["compression","customizable","deserialization","java","java-library","mca","mca-file","mca-files","mca-region","minecraft","nbt","nbt-parser","nbt-protocol","nbt-structure","serialization"],"created_at":"2024-11-14T06:37:44.483Z","updated_at":"2025-04-12T22:27:42.826Z","avatar_url":"https://github.com/Querz.png","language":"Java","readme":"# NBT\n[![Build Status](https://travis-ci.org/Querz/NBT.svg?branch=master)](https://travis-ci.org/Querz/NBT) [![Coverage Status](https://img.shields.io/coveralls/github/Querz/NBT/master.svg)](https://coveralls.io/github/Querz/NBT?branch=master) [![Release](https://jitpack.io/v/Querz/NBT.svg)](https://jitpack.io/#Querz/NBT)\n#### A java implementation of the [NBT protocol](https://minecraft.gamepedia.com/NBT_format) for Minecraft Java Edition.\n---\n### Specification\nAccording to the [specification](https://minecraft.gamepedia.com/NBT_format), there are currently 13 different types of tags:\n\n| Tag class    | Superclass | ID | Payload |\n| ---------    | ---------- | -- | ----------- |\n| [EndTag](src/main/java/net/querz/nbt/tag/EndTag.java)             | [Tag](src/main/java/net/querz/nbt/tag/Tag.java)               | 0  | None |\n| [ByteTag](src/main/java/net/querz/nbt/tag/ByteTag.java)           | [NumberTag](src/main/java/net/querz/nbt/tag/NumberTag.java)   | 1  | 1 byte / 8 bits, signed |\n| [ShortTag](src/main/java/net/querz/nbt/tag/ShortTag.java)         | [NumberTag](src/main/java/net/querz/nbt/tag/NumberTag.java)   | 2  | 2 bytes / 16 bits, signed, big endian |\n| [IntTag](src/main/java/net/querz/nbt/tag/IntTag.java)             | [NumberTag](src/main/java/net/querz/nbt/tag/NumberTag.java)   | 3  | 4 bytes / 32 bits, signed, big endian |\n| [LongTag](src/main/java/net/querz/nbt/tag/LongTag.java)           | [NumberTag](src/main/java/net/querz/nbt/tag/NumberTag.java)   | 4  | 8 bytes / 64 bits, signed, big endian |\n| [FloatTag](src/main/java/net/querz/nbt/tag/FloatTag.java)         | [NumberTag](src/main/java/net/querz/nbt/tag/NumberTag.java)   | 5  | 4 bytes / 32 bits, signed, big endian, IEEE 754-2008, binary32 |\n| [DoubleTag](src/main/java/net/querz/nbt/tag/DoubleTag.java)       | [NumberTag](src/main/java/net/querz/nbt/tag/NumberTag.java)   | 6  | 8 bytes / 64 bits, signed, big endian, IEEE 754-2008, binary64 |\n| [ByteArrayTag](src/main/java/net/querz/nbt/tag/ByteArrayTag.java) | [ArrayTag](src/main/java/net/querz/nbt/tag/ArrayTag.java)     | 7  | `IntTag` payload *size*, then *size* `ByteTag` payloads |\n| [StringTag](src/main/java/net/querz/nbt/tag/StringTag.java)       | [Tag](src/main/java/net/querz/nbt/tag/Tag.java)               | 8  | `ShortTag` payload *length*, then a UTF-8 string with size *length* |\n| [ListTag](src/main/java/net/querz/nbt/tag/ListTag.java)           | [Tag](src/main/java/net/querz/nbt/tag/Tag.java)               | 9  | `ByteTag` payload *tagId*, then `IntTag` payload *size*, then *size* tags' payloads, all of type *tagId* |\n| [CompoundTag](src/main/java/net/querz/nbt/tag/CompoundTag.java)   | [Tag](src/main/java/net/querz/nbt/tag/Tag.java)               | 10 | Fully formed tags, followed by an `EndTag` |\n| [IntArrayTag](src/main/java/net/querz/nbt/tag/IntArrayTag.java)   | [ArrayTag](src/main/java/net/querz/nbt/tag/ArrayTag.java)     | 11 | `IntTag` payload *size*, then *size* `IntTag` payloads |\n| [LongArrayTag](src/main/java/net/querz/nbt/tag/LongArrayTag.java) | [ArrayTag](src/main/java/net/querz/nbt/tag/ArrayTag.java)     | 12 | `IntTag` payload *size*, then *size* `LongTag` payloads |\n\n* The `EndTag` is only used to mark the end of a `CompoundTag` in its serialized state or an empty `ListTag`.\n\n* The maximum depth of the NBT structure is 512. If the depth exceeds this restriction during serialization, deserialization or String conversion, a `MaxDepthReachedException` is thrown. This usually happens when a circular reference exists in the NBT structure. The NBT specification does not allow circular references, as there is no tag to represent this.\n\n### Add the library as a dependency using Gradle:\nAdd Jitpack to your `repositories`:\n```\nrepositories {\n\t...\n\tmaven { url 'https://jitpack.io/' }\n}\n```\nAnd then add it as a dependency as usual:\n```\ndependencies {\n\t...\n\timplementation 'com.github.Querz:NBT:6.1'\n}\n```\n\n### Add the library as a dependency using Maven:\nAdd Jitpack:\n```\n\u003crepositories\u003e\n\t\u003crepository\u003e\n\t\t\u003cid\u003ejitpack.io\u003c/id\u003e\n\t\t\u003curl\u003ehttps://jitpack.io\u003c/url\u003e\n\t\u003c/repository\u003e\n\u003c/repositories\u003e\n```\nDependency:\n```\n\u003cdependency\u003e\n\t\u003cgroupId\u003ecom.github.Querz\u003c/groupId\u003e\n\t\u003cartifactId\u003eNBT\u003c/artifactId\u003e\n\t\u003cversion\u003e6.1\u003c/version\u003e\n\u003c/dependency\u003e\n```\n\n---\n### Example usage:\nThe following code snippet shows how to create a `CompoundTag`:\n```java\nCompoundTag ct = new CompoundTag();\n\nct.put(\"byte\", new ByteTag((byte) 1));\nct.put(\"double\", new DoubleTag(1.234));\nct.putString(\"string\", \"stringValue\");\n```\nAn example how to use a `ListTag`:\n```java\nListTag\u003cFloatTag\u003e fl = new ListTag\u003c\u003e(FloatTag.class);\n\nfl.add(new FloatTag(1.234f);\nfl.addFloat(5.678f);\n```\n\n#### Nesting\nAll methods serializing instances or deserializing data track the nesting levels to prevent circular references or malicious data which could, when deserialized, result in thousands of instances causing a denial of service.\n\nThese methods have a parameter for the maximum nesting depth they are allowed to traverse. A value of `0` means that only the object itself, but no nested object may be processed.\n\nIf an instance is nested further than allowed, a [MaxDepthReachedException](src/main/java/net/querz/nbt/MaxDepthReachedException.java) will be thrown. A negative maximum depth will cause an `IllegalArgumentException`.\n\nSome methods do not provide a parameter to specify the maximum depth, but instead use `Tag.DEFAULT_MAX_DEPTH` (`512`) which is also the maximum used in Minecraft.\n\n---\n### Utility\nThere are several utility methods to make your life easier if you use this library.\n#### NBTUtil\n`NBTUtil.write()` lets you write a Tag into a gzip compressed or uncompressed file in one line (not counting exception handling). Files are gzip compressed by default.\n\nExample usage:\n```java\nNBTUtil.write(namedTag, \"filename.dat\");\n```\n`NBTUtil.read()` reads any file containing NBT data. No worry about compression, it will automatically uncompress gzip compressed files.\n\nExample usage:\n```java\nNamedTag namedTag = NBTUtil.read(\"filename.dat\");\n```\n#### Playing Minecraft?\nEach tag can be converted into an NBT String (SNBT) used in Minecraft commands.\n\nExample usage:\n```java\nCompoundTag c = new CompoundTag();\nc.putByte(\"blah\", (byte) 5);\nc.putString(\"foo\", \"bär\");\nListTag\u003cStringTag\u003e s = new ListTag\u003c\u003e(StringTag.class);\ns.addString(\"test\");\ns.add(new StringTag(\"text\"));\nc.add(\"list\", s);\nSystem.out.println(SNBTUtil.toSNBT(c)); // {blah:5b,foo:\"bär\",list:[test,text]}\n\n```\nThere is also a tool to read, change and write MCA files.\n\nHere are some examples:\n```java\n// This changes the InhabitedTime field of the chunk at x=68, z=81 to 0\nMCAFile mcaFile = MCAUtil.readMCAFile(\"r.2.2.mca\");\nChunk chunk = mcaFile.getChunk(68, 81);\nchunk.setInhabitedTime(0);\nMCAUtil.writeMCAFile(\"r.2.2.mca\", mcaFile);\n```\nThere is also an optimized api to retrieve and set block information (BlockStates) in MCA files.\n\nExample:\n```java\n// Retrieves block information from the MCA file\nCompoundTag blockState = mcaFile.getBlockStateAt(1090, 25, 1301);\n\n// Retrieves block information from a single chunk\nCompoundTag blockState = chunk.getBlockStateAt(2, 25, 5);\n\n// Set block information\nCompoundTag stone = new CompoundTag();\nstone.putString(\"Name\", \"minecraft:stone\");\nmcaFile.setBlockStateAt(1090, 25, 1301, stone, false);\n```\nTo ensure good performance even when setting a lot of blocks and / or editing sections with a huge palette of block states, the size of the BlockStates array is only updated when the size of the palette requires it. This means there might be blocks in the palette that are not actually used in the BlockStates array.\nYou can trigger a cleanup process by calling one of the following three methods, depending on the desired depth:\n```java\nmcaFile.cleanupPalettesAndBlockStates();\nchunk.cleanupPalettesAndBlockStates();\nsection.cleanupPaletteAndBlockStates();\n```\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fquerz%2Fnbt","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fquerz%2Fnbt","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fquerz%2Fnbt/lists"}