{"id":19207625,"url":"https://github.com/danilafe/kt-starbound","last_synced_at":"2026-05-17T03:04:41.382Z","repository":{"id":80322068,"uuid":"91632721","full_name":"DanilaFe/kt-starbound","owner":"DanilaFe","description":"A Kotlin implementation of a Starbound file format parsing library. ","archived":false,"fork":false,"pushed_at":"2017-05-18T00:46:26.000Z","size":22,"stargazers_count":4,"open_issues_count":0,"forks_count":0,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-01-04T15:38:44.949Z","etag":null,"topics":["java","kotlin","starbound"],"latest_commit_sha":null,"homepage":null,"language":"Kotlin","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/DanilaFe.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","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":"2017-05-18T00:44:43.000Z","updated_at":"2021-12-31T21:15:41.000Z","dependencies_parsed_at":"2023-06-05T10:30:38.139Z","dependency_job_id":null,"html_url":"https://github.com/DanilaFe/kt-starbound","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DanilaFe%2Fkt-starbound","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DanilaFe%2Fkt-starbound/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DanilaFe%2Fkt-starbound/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DanilaFe%2Fkt-starbound/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/DanilaFe","download_url":"https://codeload.github.com/DanilaFe/kt-starbound/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":240280821,"owners_count":19776414,"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":["java","kotlin","starbound"],"created_at":"2024-11-09T13:21:04.330Z","updated_at":"2025-11-14T03:01:36.817Z","avatar_url":"https://github.com/DanilaFe.png","language":"Kotlin","funding_links":[],"categories":[],"sub_categories":[],"readme":"# kt-starbound\nA Starbound file format reading library for Kotlin and Java\n## Disclaimer(s)\n__This library is an early prototype, and should be used with extra caution!__\n\n__A lot of the information for this library was found using the [py-starbound](https://github.com/blixt/py-starbound) repository! Please check it out if you're interested in a Python or Go implementation. I do not claim credit for reverse engineering the Starbound file formats.__\n\n__I will be attempting to both contribute to py-starbound's format documentation, as well as write my own. At the moment, there is no complete documentation on Starbound's file formats.__\n## Why?\nThere are very few libraries for reading Starbound files. The two that I've found the best were written by the same person, [blixt](https://github.com/blixt), and even their own documentations of Starbound's file formats were sometimes lacking. In order to both discover the file format of Starbound's files and to provide a generic library for working with them, I wrote kt-starbound.\n### Why Kotlin?\nThe initial prototype of the library was in pure Java. However, Kotlin appears to be a very nice language, and works excellently with Java. It's got a lot of convenience features like preventing a lot of boilerplate code (like data classes) and has the ability to check for null-related issues with the type system. This library was partially written to try out the language itself, and is my first attempt at writing Kotlin.\n## Usage\n### BTreeDB5\nCurrently, the kt-starbound provides three separate classes that represent Starbound file formats. The first is BTreeDB5. This is the most algorithmically complicated format, and if you want to understand how it works I encourage you to take a look into [B-Trees](https://en.wikipedia.org/wiki/B-tree). The format's most important application is in the `.world ` files. The library provides a class that reads a generic BTreeDB5 file, `BTreeDB5` (surprise) as well as a separate class, `World`, that handles some functions related to `.world` files, like extracting some metadata.\n\nAt the moment, a `World` instance is created as such:\n```Java\nWorld world = new World(new File(\"/path/to/file.world\"));\n```\n\nOr, if you're using Kotlin:\n```Kotlin\nval world = World(File(\"/path/to/file.world\"))\n```\n\nFrom there, at the moment, you can only use the `getMetadata()` function (or just `metadata` if you're using Kotlin).\n### SBAsset6\nThe SBAsset file is used for `packed.pak` and all other mod files. It's fairly primitive, and the library provides an `SBAsset6` class that takes a Java file and parses it. The library currently uses RandomAccessFile, which gives it the ability to read even large asset files without much overhead.\n\nBelow is an example of printing out all the files in a packed asset file:\n```Java\nSBAsset6 asset = new SBAsset6(new File(\"/path/to/packed.pak\"));\nasset.getFiles().keySet().forEach(System.out::println);\n```\n### SBVJ06\nWhat appears to be a serialized JSON format, this format is also fairly simple. Just like JSON, it has several data types, including ones that can be nested. It's used frequently in many places, like player data, and a similar type of encoding is used in world files. kt-starbound provides a Dynamic class and several children (`DynamicDouble`, `DynamicString`, etc), as well as a `SBVJ06` class to read this kind of file. \n\nThe `SBVJ06` class's most important field is `versionedData`, which is more common encoding type across all of Starbound's file formats (SBVJ06 is always a whole file, while VersionedData is simply serialized JSON that can be found inside of other data structures). \n\nThe `VersionedData` class has a `root` variable, which represents the top-level Dynamic object. The type of the object can then be checked with `instanceof` (or `when .. is` in Kotlin), and after casting, its value can be accessed using `getData()`. A simple example of accessing data from an SBVJ06 file is:\n```Java\nSBVJ06 jv = new SBVJ06(new File(\"/path/to/sbasset\"));\nDynamicMap rootElement = (DynamicMap) jv.getVersionedData().getRootElement();\nrootElement.getData().keySet().forEach(System.out::println);\n```","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdanilafe%2Fkt-starbound","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdanilafe%2Fkt-starbound","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdanilafe%2Fkt-starbound/lists"}