Modding:Advanced Modding

From Starbounder - Starbound Wiki
Jump to: navigation, search
Mining Hazard Sign.png
Work In Progress!
Mining Hazard Sign.png

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 ColonolNutty on 2017-07-13 18:47:52.

Description

Hello and welcome to the Advanced Modding page! This is for users who are familiar with JSON and LUA and want to know how to make something a bit more complex, like a crafting tree, or armor, or a whole new mission, then this is the place to be! If you are here to know how to extract the assets and begin modding, please check out the Modding Basics section for more information. Or if you are new to the wiki and wanting to help, check out the "How Can I Help The Wiki?" page.

This page will be for those who are interested into making more advanced features in Starbound. Each section will govern a tutorial on how to make that specific subject and if you want to add your own, please include it in own section below!

For sections that are needing more information, please use {{Stub}} for incomplete tutorials.

For user specific incomplete tutorials that you're doing and don't want others to touch, please say so!

If you messed up something...

So you start up the game and BAM! It crashes, this could mean that you forgot something 'very' important inside a file, the log file will most likely give some insight into what caused the crash and if possible, state a location (such line X, Column Y in the file) of where the error occured. Some errors will correct themselves and load a "missingasset" image as a placeholder, which makes the object invisible, other times it will give a Perfectly Generic Item upon dropping, or pickup.

File Types

.patch

Penguin-Jump.gif
Article Stub

This article has been marked as a stub because:
(Editor's Note: This is based off the tutorial that "The Suit" did on the forums, Try to pull information from this)

Description

A .patch file (sometimes called dot-patch or just patch) is a system that many mods in Starbound use to modify an existing file without replacing the file altogether. This is one of the most important files inside many mods, as without it, the mod wont function in conjunction with other mods if modifies the same file. This is something that many users will usually work with, and patches can provide some safer alternatives to modifying files without much hassle.

There are plenty of good reasons that a patch file can do that a direct copy of the original can't do, such as modifying different types of .config files to add an argument or change a value to that of another, or to test if a file has a certain item or number inside and if it does, apply any changes. This is used to make sure that multiple mods running side by side can add a bunch of arguments into the same file without having the game crashing.

Some things to note that if you're trying to add something like "VALUE:7.0" instead of "{VALUE:7.0}", the game will crash as it requires the argument to be in brackets for it to work, however, you may not want to use brackets in certain situations for certain files, this will be explained later.

Operations

Patch files follow a system were it uses different "operators" to test for, add, remove, or replace certain bracketed values in Starbound files.

The current operations available are: “test”, “add”, “remove”, “move”, “copy”, and “replace”

  • Test is used to detect for a certain set of arguments in order for the rest of the patch to work properly, if the test fails, the patch files isn't applied, if it succeeds it applies the patch. This can be used to see if a certain item is in the game and if it is, replace the item or add a new one.
  • Add does what says, it adds a whole new argument into a file, this is commonly used inside the player.config file to add new recipes.
  • Remove deletes an argument specified inside a directory, while not used commonly, it can be useful to change or delete a feature in starbound.
  • Move (If you know what this does inside a .patch file, please update this!)
  • Copy (If you know what this does inside a .patch file, please update this!)
  • Replace goes and take the previous value and substitute it in with the new value, making it similar to a "remove" operation followed by an "add" operation.

Structure

The structure that a patch file goes is always in a form of this, in the case of it patching 4 arguments:

 [
 {
 "op": "OPERATION",
 "path": "/location",
 "value":
   ARGUMENT
 },
 {
 "op": "OPERATION",
 "path": "/location/sublocation",
 "value":
   ARGUMENT
 },
 {
 "op": "OPERATION",
 "path": "/location/-",
 "value": 
   ARGUMENT
 },
 {
 "op": "OPERATION",
 "path": "/location/0",
 "value":
   ARGUMENT
 }
 ]

What it all means

The group of code above is a common layout for patch files and with that comes to pattern similar to that to a computers directory. Such as: C:\Program Files (x86)\Steam\steamapps\common\Starbound\mods\, the operation will occur at "location" at the top of the list by default.

The second line is similar to the first one, but it specifies a certain part of code with "location" named "sublocation" and it will check at the top of the list and do the operation there.

The third line is an important one for users wanting to add something with crafting involved, as it does the operation at the end of the "location" area, so the bottom of "location". This is important for users to add recipes as SB uses the order of items to give the correct crafting items, as it will shift stuff around and we don't want that.

The final line is used to make arguments appear at the top of the stack, this can useful again in crafting if you want to replace an item at the top of the list, as it makes it so that the rest of the item's orders don't shift.

Let's apply to a real example

Ok, so now we know what it means and what the code is trying to do in patch files, so how about we see how one of these patch files go shall we?

 [
   {
   "op":"add",
   "path":"/defaultBlueprints/tier1/-",
   "value":
     {"item":"l9m2_superlocker"}
   },
   {
   "op":"add",
   "path":"/defaultBlueprints/tier1/-",
   "value":
     {"item":"l9m2_superfridge"}
   }
 ]

Here we have a file that modifies the "player.config" file and it adds two items from a mod that the Author of this tutorial made. What we see is that the two items named "l9m2_superlocker" and "l9m2_superfridge" and those two items are added at the end of the Tier 1 blueprints, which are blueprints unlocked by default. When another mod that adds items is added, they get harmlessly added after these ones and both will work fine together.

Applying to specific locations

An example!

Now we know how to add whole arguments and how to modify arguments, but what if we want to modify a certain spot inside a giant nest of code? Well, here's a bit of code that we can work with:

(Note: not all ores are listed here)

 "surfaceOres" : [
   [0.5, [ [ "coal", 1.40], [ "uranium", 0.00], [ "plutonium", 0.00], [ "diamond", 0.20], [ "iron", 0.20] ] ],
   [1.5, [ [ "coal", 1.40], [ "uranium", 0.00], [ "plutonium", 0.00], [ "diamond", 0.20], [ "iron", 0.20] ] ],
   [2.5, [ [ "coal", 1.40], [ "uranium", 0.00], [ "plutonium", 0.00], [ "diamond", 0.20], [ "titanium", 0.20] ] ],
   [3.5, [ [ "coal", 1.40], [ "uranium", 0.50], [ "plutonium", 0.00], [ "diamond", 0.20], [ "titanium", 0.20] ] ],
   [4.5, [ [ "coal", 1.40], [ "uranium", 0.00], [ "plutonium", 0.00], [ "rubium", 0.20],  [ "violium", 0.20 ] ] ],
   [5.5, [ [ "coal", 1.40], [ "uranium", 0.00], [ "plutonium", 0.00], [ "rubium", 0.20],  [ "violium", 0.20 ] ] ] ]

Here we want to modify the uranium ore amount that is third from the top of the list (the one in italics)so it's more common on earlier worlds.

Here we would want modify the value so a "replace" operation will need to be used in order change it proper.

The uranium we would want to modify is one the third line, so we must use the sublocation of 2 as the first line is 0, the second line is 1, and the third line is 2.

Now the ore is inside another set of brackets that lists all the ores in order here, but the type of planet (which here is 2.5) is the first item in the group then the ores. Think of it like this: [2.5,[ores]]. So the "ores" group will be 1.

Then we list the ore that we now replace, inside the "ores" group, uranium is listed second, so the location number is 1.

How will the code look?

Inside the file that the ores reside in, the config file to replace uranium with a new value will look like this:


 [
 {"op":"replace",
 "path":"/surfaceOres/2/1/1",
 "value":  [ "uranium", 11.00]}
 ]

Add an item to an array that doesn't exist (Or any other property)

As noted above, Starbound will create the array on its own, but what if you wanted to have more control over this? Well, here comes the Test command to the rescue, it allows for quite a bit more flexibility than the basic commands on their own. In the current Starbound (v1.3.1 as of this writing) the format below is accepted (But not in the average json patch compiler, it is unique to Starbound)

[
 [
   { "op": "test", "path": "/learnBlueprintsOnPickup", "inverse" : true },
   { "op": "add", "path": "/learnBlueprintsOnPickup", "value": [] }
 ],
 [
   {
     "op" : "add",
     "path" : "/learnBlueprintsOnPickup/-",
     "value" : "exampleBlueprint"
   }
 ]
]

The code above will add learnBlueprintsOnPickup if it doesn't exist (The test, and add) and it will, whether it exists or not, add "exampleBlueprint" to the array (Denoted as the second add) Keep in mind, this can be chained, so you can have multiple "test" calls and the rest of the file will still be patched properly

[
 [
   { "op": "test", "path": "/learnBlueprintsOnPickup", "inverse" : true },
   { "op": "add", "path": "/learnBlueprintsOnPickup", "value": [] }
 ],
 [
   { "op": "test", "path": "/someOtherArray", "inverse" : true },
   { "op": "add", "path": "/someOtherArray", "value": [] }
 ],
 [
   { "op": "test", "path": "/someStringValue", "inverse" : true },
   { "op": "add", "path": "/someStringValue", "value": "" }
 ],
 [
   {
     "op" : "add",
     "path" : "/learnBlueprintsOnPickup/-",
     "value" : "exampleBlueprint"
   },
   {
     "op" : "add",
     "path" : "/someOtherArray/-",
     "value" : "I did it!"
   },
   {
     "op" : "replace",
     "path" : "/someStringValue",
     "value" : "I'm a string value"
   }
 ]
]

LUA Scripting

Quick Navigation