Modding:Basic Property Modification

Work In Progress!

This article or section is currently in the process of an expansion or major restructuring.
You are welcome to assist in its construction by editing it as well.

Last edited by Zoniventris on 2020-06-09 02:42:37.

Introduction

This tutorial explains how to modify existing items using a patch file.

Requirements

This guide assumes you have unpacked the base game assets and created a mod folder, as explained by the first two steps in Modding Basics.

Summary

1. Inside your mod's folder, create a directory structure mirroring that of the asset being modified inside your mod's folder.
2. Create a new file with the same name as the original asset's file but with ".patch" added to the end.
3. Open your file and write a list of patches describing how to modify the original asset.
4. Verify your patch worked with a fresh character and universe.

Patch file structure

Patch files are written in JSON, and they contain a list of patch objects that describe how to modify the original asset.

All patch objects must contain the following two fields:

• op: The kind of modification to make. See the "Patch Operations" table for a list of possible values.
• path: The object field to modify. This can be a top-level field like "/itemName", a nested field like "/defaultBlueprints/tier1", or an entry in a list like "/groups/2". List items start at index 0, and the end of the list can be accessed with "-" (e.g. "/groups/-").

Most objects will also contain a third field, depending on which operation is being performed:

• value: The value to apply to the given path.
• from: The path containing the value to apply to the first path.

Patch Operations

Value	Additional Field	Notes
add	value
remove	n/a
replace	value
test	value	Aborts the patch if the specified path does not match the given value.
move	from
copy	from

Example

Creating the patch file

Let's say you want to edit the Campfire Banana recipe to be craftable at a campfire. The original recipe asset is located at "path/to/unpacked/recipes/cookingtable1/desserts/campfirebanana.recipe". In your mod's folder (e.g. "mods/MyMod/"), create a new folder called "recipes", then inside that a "cookingtable1" folder, and inside that a "desserts" folder. Finally, create a file named "campfirebanana.recipe.patch" in your "desserts" folder. The final file path should be "mods/MyMod/recipes/cookingtable1/desserts/campfirebanana.recipe.patch".

Writing the patch

Crafting recipes are assigned to crafting stations (and crafting station tabs) with the "groups" parameter. The original Campfire Banana recipe has the groups "craftingfood" and "desserts", which causes it to show up in the cooking table's desserts tab. In contrast, campfire recipes like Roasted Carrots (found under "recipes/campfire/roastedcarrot.recipe") have the group "campfire".

Putting all of that together, we want to write a patch that adds "campfire" to the end of Campfire Banana's list of groups:

[
  {
    "op" : "add",
    "path" : "/groups/-",
    "value" : "campfire"
  }
]

Testing the patch

You can quickly and safely test the Campfire Banana patch using the following steps:

1. Backup your existing universe and characters by renaming the "storage" directory to something else, such as "storage_bak".
2. Open the game and create a new character. (It's probably a good idea to set the difficult to Casual and to skip the intro mission, but character creation doesn't matter beyond that.)
3. Open the command line (the default key is "/") and enter /admin. This allows us to spawn items with commands and also unlocks all recipes.
4. Make sure the mouse cursor is over an accessible, empty space, then spawn a campfire with /spawnitem campfire, followed by a cooking table with /spawnitem woodencookingtable.
5. Place the campfire and cooking table and verify that the Campfire Banana recipe appears in both.

Troubleshooting

If the patch is not working as expected, try looking for error messages in the game logs located at "path/to/starbound/storage/starbound.log". This can help identify errors in the file's syntax, among other things. If there are no error messages, verify that the patch file's path exactly mirrors that of the original asset.

External Links

Dev Blog: August 19 – The day when all your mods died.

Quick Navigation

Modding

Portal - Basics - JSON - Lua - Assets - Guides

Modding