Modding:Merge
NOTE: "__merge" style patches no longer work. See this article for details.
Beta version Angry Koala added a "__merge" feature that allows modders to manipulate Starbound JSON without overwriting the complete file. The most notable improvement this offers is the ability to add a known tier blueprint to player.config, so that additional items are craftable, but compatibility with other mods is still achievable.
Contents
Basic Usage
Each object and array can have a "__merge" entry containing an array of merge rules for the other entries. This array may be empty. To use merging, the top level object must have a merge entry, causing the whole file to be merged with the original instead of replacing it. The top level merge entry follows the rules for #Object merging below.
Merge Rules
A merge rule is an array containing a command, followed by the key of the entry it should be applied to for objects, or by a slightly more complex item specifier for arrays. If no explicit merge rule exists for an entry, it will be merged using default rules, depending on its type: Strings and numbers are overwritten, arrays are appended, and objects are merged (see #Default Behavior below).
The general syntax for an object merge rule is:
[ <command> : <key> ]
The general syntax for an array merge rule is:
[ <command> : { "item" : <item> } ]
For some configs you can make the game treat a file as deleted by assigning nil instead of a merge rule array to the top level merge entry, i.e. using { "__merge" : nil } as top level object.
Object Merging
Available commands for object merge rules:
| Command | Effect |
|---|---|
| "delete" | Delete the entry |
| "overwrite" | Overwrite the old value of the entry |
The following example uses a nested "__merge" entry in "defaultBlueprints" to delete the "portable3dprinter" entry and assign an empty array to the "tier2" entry:
{
"__merge" : [],
"defaultBlueprints" : {
"__merge" : [
["delete", "portable3dprinter" ]
[ "overwrite", "tier2" ]
],
"tier1" : [ { "item" : "grapplinghook" } ],
"tier2" : []
}
}
There is no explicit merge rule for "tier1", so it will be appended to the original value. Without the merge rule for "tier2", the new value (an empty array) would be appended, having no effect.
Array Merging
To have extended control over how an array is merged, an object with a special merge entry value must be used. Instead of directly assigning the merge rule array, an array with the string "list" as first item, followed by the merge rule array has to be used. Available commands for array merge rules:
| Command | Effect |
|---|---|
| "update" | replace the item specified with the third item in the rule (TODO clarify) |
| "delete" | delete the specified item from the array |
| "append" | add the specified item to the end of the array |
| "prepend" | add the specified item to the start of the array |
The following example demonstrates each of those on items in the "tier1" array:
{
"__merge" : [],
"defaultBlueprints" : {
"tier1" : { "__merge" : [ "list", [
[ "update", { "item" : "bandage" }, { "item" : "nanowrap" } ],
[ "delete", { "item" : "torch" } ],
[ "append", { "item" : "peanutbutter" } ],
[ "prepend", { "item" : "timer" } ]
] ] }
}
}
Default Behavior
Before:
{
"string" : "hello world",
"number" : 3,
"object" : { "one" : 1, "two" : "zwei" },
"array" : [ "foo", "bar" ],
"oldEntry" : "don't merge me, bro!"
}
Merge:
{
"__merge" : [],
"string" : "hi universe",
"number" : 9001,
"object" : { "two" : 2, "three" : 3 },
"array" : [ "foo", "stuff", "things" ],
"newEntry" : "wow! such merge! many compatibility!"
}
After:
{
"string" : "hi universe",
"number" : 9001,
"object" : { "one" : 1, "two" : 2, "three" : 3 },
"array" : [ "foo", "bar", "foo", "stuff", "things" ],
"oldEntry" : "don't merge me, bro!",
"newEntry" : "wow! such merge! many compatibility!"
}
Important Notes
- Always add a top level merge entry!
- Mods can still be incompatible if they modify the same entries!
- Some files cannot be merged (v. Enraged Koala). The merging will fail for at least the following (please add to this list if you found more):
- items/defaultParameters.config
Examples
Paths are relative to the assets folder!
items/generic/crafting/coalore.item - Increase the fuel value of coal:
{
"__merge" : [],
"description" : "Super Powered Coal.",
"fuelAmount" : 500
}
items/swords/randomgenerated/crappyspear.generatedsword - Make crappyspears crap again:
{
"__merge" : [],
"primaryStances" : {
"directional" : false
}
}
External References
- Merge functionality announcement
- Extended merge support with list operations
- Merging behavior tables
