Kawa's Starbound JSON Lab

Schemas

Links

RFC 6902

The actual reference document for JSON Patch, not really a tool but still a good read.

Instance validator

Can be used to confirm if a config file meets expectations. Does not tolerate comments, unlike the validator on this page.

Patch tester

Can be used to validate a patch and confirm its results. Also does not tolerate comments.

Patch generator

Can create a patch from original and edited data. Does not tolerate comments, and output is not copypaste-friendly.

SB Patch examples

Old __merge to patch migration examples, focuses on species mods.

SBVJ format docs

A quick guide on how to parse .player files and such.

Batch Patch Validator

Recursively scans through all .patch files in the given directory to look for missing value keys.

Tools

• Linter
• Validator
• Patcher

Application

Starbound mods can alter a given file that was loaded earlier in one of two ways: replace it entirely, or patch it. Any file can be replaced, but only JSON files can be patched. Either way, to alter a file you give its replacement the same name and relative path. That is, to alter /humanoid/any/dummybody.png, your mod's folder must contain that same path, mods/your mod/humanoid/any/dummybody.png. Again, this goes for all straight-up replacements of files that were loaded earlier.

JSON files can also be patched, which is what most of this page is all about. To tell the difference between a patch and a full replacement, the former has .patch appended to it: /interface/windowconfig/charcreation.config is altered by /interface/windowconfig/charcreation.config.patch. Again, this only applies to JSON files. Their extensions don't matter, but the content does.

Extensions

Starbound has a few extra features, extending the RFC. These include patch lists and a slightly different behavior for the test operation.

A patch is a list of operations. If one of these fails to apply, the entire process is cancelled. A patch list extends this behavior, allowing a single file to contain multiple smaller attempts:

[
	[
		{ "op": "test", "path": "/foo", "inverse" : true },
		{ "op": "add", "path": "/foo", "value": [] }
	],
	[
		{ "op": "add", "path": "/foo/-", "value": 4 },
		{ "op": "add", "path": "/foo/-", "value": 5 },
		{ "op": "add", "path": "/foo/-", "value": 6 }
	]
]

This is a list of lists of operations. If the first one fails, the rest of it, the add operation, is not applied at all, and application continues to the next patch list.

Imagine a target file with { "foo": [ 1, 2, 3 ] }. You can't be certain foo exists — by default it doesn't, but some mod applied earlier may have added it. Adding values to it becomes pretty much impossible.

The test operation normally requires a value to compare against. In Starbound, this has been extended; if the value parameter is missing, it instead checks for the existence of the node pointed at by path. The check can be turned around by the optional inverse parameter. Thus, { "op": "test", "path": "/foo", "inverse" : true } will fail if foo does in fact exist already, and the add is never applied. There are more ways to use the inverse flag in Starbound, but this is the only one supported by this site.

The next patch list is applied, regardless of the first one's failure or success, and adds three more values to the now guaranteed to exist foo.

Comments