Modding Basics

A bunch of resources and tutorials about modding the game. Very useful for both modding beginners and veterans alike. Is getting constant revisions and updates, if you suggest something that is important I can add it to the list too. Hope this helps yall.

Unpacking the Assets and Mods

We should probably start here...
It is a very simple process, depending on the OS.

Please remember:
This works on unpacking mods too! just specify the correct location or move the mods packed file to the directory for easier access.

For Windows:

To find mod .paks:

• Go to the steam directory then go to /workshop
  
• In steam go to the mod page, go to the far right of the url (may need to turn it on in settings or copy the pages url) and take the numbers at the end
  
• Back in the workshop directory go to /211820/MODNUMBERS, MODNUMBERS being the numbers from the url in the previous step
  
• Inside will be the mod, usually in a .pak file if uploaded using the uploader tool

To unpack assets:

• Go to the Starbound local directory, usually in /steamapps/common/Starbound
  
• Open powershell in the current directory by either pressing alt + f and clicking on powershell or clicking on the file directory and typing "powershell" and pressing enter
  
• Paste the following line of code into powershell:

  ./win32/asset_unpacker.exe ./assets/packed.pak ./assets/_unpacked

• WAIT Do NOT close the window! This will take some time! You can go to the directory in /assets/_unpacked/ and see it fill up
  
• Enjoy your unpacked assets!

For unpacking mods, replace the /assets/packed.pak to your new directory for the mod pak, it doesnt matter where this is, and you can delete it after, and the /assets/_unpacked to /assets/_unpackedmods/MODNAME for ease of navigation.

Resources and Tools

You should consider using these if you want to make life easier on yourself and other people.

Text Editor:

You should use a text editor that is not provided by basic operating systems. I personally use Notepad++ which can be found below. Additionally you can re automatically recognising Starbound files as JSON.
https://notepad-plus-plus.org/downloads/
To automatically highlight text as JSON and make it easier to read in this editor, follow these steps:

1. Make sure Notepad++ is closed
   
2. Download this https://github.com/Nebulox/ModdingResources/blob/main/langs.xml file
   
3. Navigate to

   /Users/YOURUSER/AppData/Roaming/Notepad++/langs.xml

4. Replace this file with the one uploaded
   
5. Please note this will overwrite any changes you have made to this file in the past, if you would like to manually replace the files, I suggest comparing the files or finding the JSON segment and replacing it manually.

Alternatively you can use Atom with the "Startbound Suite" plugin or other code editors of your choice. I believe there is a plugin for VS Code, but I am not certain.

Art Program:

This can be anything that supports pixel art and transparency. Personally I use paint dot net but some people use Aseprite which is also available on steam.
https://www.getpaint.net/
https://www.aseprite.org/

I recommend against GIMP as it suffers from being unintuitive, overcomplicated, has bad usability, is harder to learn, and going into the huge amount of plugins required to make it easier for beginners (or familiar to its competition - photoshop) is just not worth it compared to a simple install and use package like paint dot net or others. The GUI is plain awful, though plugins can fix that. It is also very very bad for pixel art and often requires huge changes to settings or plugins to be good for pixel art, and swapping back and forward between settings is a little annoying. Its a years long reputation GIMP has, and it has definitely gotten worse in terms of interface since I first used it, people tell me it only gets worse over time. If you like GIMP though, you're fine for that since learning a new program can ♥♥♥♥♥♥♥ suck, I just don't recommend it for Starbound, or in general since there are plainly better alternatives. GIMP rant over (comment suggested I put this info here)

Paint dot Net
Plugins:

Animation Helper - by recursor
Official Link: https://forums.getpaint.net/topic/17516-sprite-animation-helper-v-10096-updated-june-192018/
Allows you to preview an animation by highlighting it and setting some parameters!

To Install and Use:

1. Make sure Paint.Net is closed
   
2. Put the AnimationEffect.dll in C:/Program Files/paint.net/Effects
   
3. Open Paint.Net
   
4. Go to the Effects tab located at the top left of the window

Pastebin:
When people ask you for your log file, paste it here and toss them the link to save time for everyone. Be sure to disable public listing.
You can find your log file at the local files, /Starbound/storage/starbound.log (no numbers)
https://pastebin.com/

Tiled:
To modify or create modern dungeons in Starbound, you need Tiled.
https://www.mapeditor.org/

See the Tiled section for more details.

Agent Ransack:
This is a very powerful search tool used to browse the starbound assets folder. While most people simply use the folder search their operating system provides to find files of interest, programs like AgentRansack take it one step further and treat any file that contains text as a "directory" and searches for keywords within that file. Modders often use programs like Agent ransack to find all files that contain specific lua functions or JSON variables by using them as a "search term". It is also worlds faster.
https://download.mythicsoft.com/ar/867/AgentRansack_867.exe

Kawa's Starbound JSON Lab:
A useful multipurpose online tool for JSON editing and producing a code for patching. It also has a built-in json linter that supports Starbounds json (and comments) to verify your code. It has links to patch file generators and other ways of verifying your patches!
http://helmet.kafuka.org/sbmods/json/

Patching Tool:
An online tool used to produce JSON code for a .patch file.
https://chbrown.github.io/rfc6902/

ShareX:
A simple tool used to record desktop footage to create mp4 files, gifs and other files. Is also available on steam. Be sure to go to your settings and install the correct devices for ShareX! Without them audio may not be synced or function correctly.
https://getsharex.com/
OR
OBS:
A tool used in growing popularity to record videos. Be sure to install your drivers for it correctly!
https://obsproject.com/

Libraries

The lua Docs
Located in your Starbound folder, these contain everything the wiki says and more.
In here: /Steam/steamapps/common/Starbound/doc/lua/...

The Wiki
Most of the things relating to modding is listed here, however it is a bit out of date.
https://starbounder.org/Modding:Portal

JSON Library:
Contains basic information on the Json scripting language. Click on a category to find variables of that type.
https://starbounder.org/Modding:JSON

Documented Directives:
Directives are useful in quick real-time modifications to images without needing to adjust a png or make animated frames. They refer to things like ?hueshift=50 at the end of a .png.
https://starbounder.org/Modding:Image_Processing_Directives

Lua Library:
Contains lua functions used by starbounds .lua scripts. Click on a category below when you are on the page to show some lua functions associated with that category. If you want a more populated list with all functions, check your own docs in your local starbound docs.
https://starbounder.org/Modding:Lua/Tables

Documented Datatypes:
This is especially useful for lua functions that use datatypes you may not recognise. If you see something like "ItemDescriptor" in the lua docs, and want to know what it specifically means, check here.
https://starbounder.org/Modding:Lua/Starbound_Datatypes

Vector Library:
You will often find lua variables on the page refer to the use of vectors. This page will hopefully attempt to assist you in making sense of them. The file for this is in the vanilla assets under /scripts/vec2.lua, while you're there check out util.lua, which also very useful.
https://starbounder.org/Modding:Lua/Tables/Vector2

Tiled

The main program used to create dungeons and map files for Starbound.
Download:
https://thorbjorn.itch.io/tiled

Tiled Tips:
- When starting a new dungeon, I suggest copying an existing one and editing it from there, that way you can avoid any spontaneous errors
- Make backups of existing files, and restart Tiled when making changes to tilesets used in your dungeon
- You likely wont be able to open other peoples dungeons unless your files are in the exact same paths as the person who made theirs, this also includes your own if you move files around. Be considerate of your changes

Setup Tutorial:
When downloading Tiled, get the latest version.

Before you start, go to edit>preferences>plugins and disable json.dll and enable json1.dll

How to add a new Tileset:
Step 1:
New tileset, collection of images.


Step 2:
Click this button:

Step 3:
Choose an icon image of your object or tile. They are the same thing in tiled.

Step 4:
For a tile, choose add property and set it up like this.

Objects are similar but with different properties.

Use the image position from the object itself.

Step 5:
SAVE AND RESTART TILED. Not doing so can cause exception errors when trying to make a dungeon and permanently causing you to be unable to add objects to your tileset again.

Step 6:
Back on your map, do this to embed the tileset in your map.


Courtesy of Travelling Merchant for the original setup tutorial! Thanks a ton man!

Useful Things to Know

Commands
/help
Shows every command
/admin
Toggles the player admin mode where they are in a state of semi invulnerability where they cannot take damage through normal means. Also enables access to admin commands such as the spawn commands, warp commands and variable setting among many others.
/debug
Toggles debug hitboxes, damage boxes, sensory boxes among other useful debug information.
/boxes
Only works while debug, shows object and tile boxes, showing what tiles they occupy and what tiles are occupied in general
/warp
This can warp you to instanceworlds and such.
Example: /warp instanceworld:outpost

/reload
This will reload the game, things related to json, and general json changes require the item not being active, so weapons need to not be held, you can drop them or unequip them, objects need to be unloaded off screen or broken, etc. Techs and statuses need to be removed. Lua changes are affected without the need to drop the item, and image changes as well. This reloads less assets than the reload keybind, which you need to set manually in starbound.config.

Patching and lua Hooking

Patching Tutorial:
Patching is very important. It ensures compatibility with other mods and it is a standard practice most modders use.
https://community.playstarbound.com/threads/basic-patching-now-with-path-guide-v1-9.84496/
This page can generate a patch file for you, if you paste the original file on the left, and then the file with your changes on the right, without Starbounds comments (//thesethings):
http://chbrown.github.io/rfc6902/

Hooking/lua Patching Tutorial:
Normally having 2 scripts will have the second script's functions overwrite the first. To avoid this use lua hooking. Hooking is effectively patching more lua into an existing lua script. You do this by adding your script as a new lua file to the "scripts" table with a patch or natively in your mod;

"scripts" : ["originalscript.lua", "yourhook.lua"]

The examples can be used in the same hook script at the same script. Typically you should prefix these as well to avoid any possible conflicts with other hooks added to this script, just in case.
If you want to modify any init() function:

local YOURPREFIX_oldInit = init or function() end --create a new function based on the function from the other script, and then run it, if it doesn't exist just give an empty function
init = function() 
  YOURPREFIX_oldInit()

  --Then run your new code after
  sb.logInfo("New stuff!")
end

If you want to modify the fire() function in gunfire.lua:

local YOURPREFIX_oldFire = fire or function() end
fire = function(args) 
  YOURPREFIX_oldFire(args)  -- you can put this at the start, to run it before your code additions, or at the end, to run it after, it may depend where if you want to modify the args before the code is run!

  --Your new function body
  sb.logInfo("Gun fired!")
end

Basically, what is happening is you save the function of the other script, in a value, then running it if it exists, before running your code. Basically its like adding more information to a paragraph.

Other Guides

https://steamcommunity.com/sharedfiles/filedetails/?id=2655311116
https://steamcommunity.com/sharedfiles/filedetails/?id=3389634436
https://steamcommunity.com/sharedfiles/filedetails/?id=1380289410

Discord Servers and Help

If you are ever needing help you can contact me or other modders usually. I prefer discord, and you can find me and many other capable individuals in the following discords.

The Official Starbound Server[discord.gg]
The Starforge[discord.gg]
The Great Void, my server[discord.gg]
Arcana[discord.gg]

[Neb]

True, might add it now

[Wonky]

Thanks for explaining so thoroughly, much appreciated. Just had to ask, since you didn't provide any real reasons on the guide itself, and I believe the actual valid reasons beyond "I didn't like it" need to be mentioned when telling people to avoid something.

[Neb]

If you're dead set on that kind of program, Krita is far better, there's also Affinity Photo among other similar stuff to avoid Photoshop that provide far far smoother UX than GIMP. Inkscape is good but I don't know the jist of its pixel art capabilities if any, I use it for vector art.

Its a years long reputation GIMP has, and it has definitely gotten worse in terms of interface since I first used it, people tell me it only gets worse over time. If you like GIMP though, you're fine for that since learning a new program can fucking suck, I just don't recommend it for Starbound, or in general since there are plainly better alternatives.

[Neb]

My personal experience learning it was uncomfortable, where in Krita or Photoshop I could get familiar a lot faster than in GIMP, and programs like Aseprite and paint dot net don't even require learning to get started. It also spits out roughly 30 errors every launch, on multiple different systems, so not sure if its a me thing or not. I experienced this, but so did others; file operations are significantly slower than most applications.

[Neb]

The main takeaways are inefficiency with pixel art and in general versus competition and bad design making it harder and unintuitive to use, paint dot net is far more lightweight and easy to use, and Aseprite is designed around pixel art and offers very nice animation tools - iirc you can get it from the github.

For the long of it; GIMP suffers from being unintuitive, overcomplicated, has bad usability, is harder to learn, and going into the huge amount of plugins required to make it easier for beginners (or familiar to its competition - photoshop) is just not worth it compared to a simple install and use package like paint dot net or others. The GUI is plain awful, though plugins can fix that. It is also very very bad for pixel art and often requires huge changes to settings or plugins to be good for pixel art, and swapping back and forward between settings is a little annoying.

[Wonky]

What's up with GIMP?

[Neb]

I suggest using the web page instead of the GitHub in the future.

[FUS]

Well then fyi the 1.1.6 build from GitHub didn't had the .dll included in case someone else wants to take a shot at dungeon making

[Neb]

Nope, I believe its not tied to the application version.

However, newer versions of Tiled now work so you do not need to get the older versions anymore.

[FUS]

Wasn't json1.dll Tiled plugin added only in 1.2.2? It was missing in 1.1.6 and looking it up the internet pointed me at the former's patchnotes.