Modding Basics p1 - Editing Vanilla Files v1.4

Discussion in 'Starbound Modding' started by The | Suit, Dec 12, 2014.

Thread Status:
Not open for further replies.
  1. The | Suit

    The | Suit Agent S. Forum Moderator




    I Recommend Reading my Modding Ebook Instead, this tutorial is slightly out of date.
    http://community.playstarbound.com/resources/unofficial-modding-ebook.2930/



    Modding Basics p1 - Editing Vanilla Files
    Tutorial Version Updated to: 'Beta v. Upbeat Giraffe
    This guide is not compatible with - Enraged Koala or Earlier versions of Starbound.

    Modding in Starbound is extremely easy, it only takes a little common sense and some trial and error and you are on your way. In this first tutorial we are going to be looking at how to edit the base vanilla files of the game.

    INDEX

    Starting Off
    The Tools Required
    Understanding Directory Structure
    Setting up the Mod
    Patching

    STARTING OFF
    The first thing we need to understand before we begin starbound modding is where starbound is installed.
    Open up steam --> Games Library --> right click on starbound --> properties --> local files (tab) --> Browse local files

    [​IMG]

    This will open up your starbound directory.

    Noteable Files

    Mods Folder - the mods folder is where you place your mods. There are 3 types of mods you should be aware of.
    *Note Mods folder is in 2 separate locations based on the branch you are in. For more information go here:
    http://community.playstarbound.com/index.php?threads/guide-to-installing-mods-v-1-2.89072/

    Nonpacked Mods - An nonpacked mod is a folder with files inside. What you need tobe aware of is the modinfo file should only be 1 level higher in the directory tree than the mods folder. What does that mean? Say we downloaded mod example, when we unzipped \ unrared it there was a folder with files.

    THINGS YOU SHOULD NOT DO
    If you copied the files and placed it directly into you would get an error. This would place the mod in the root folder - which would result in an error.
    Code:
    starbound/mods/example.modinfo 
    If you unzipped it and unrared it with an extra folder the mod will not be read
    Code:
    starbound/mods/example/example/example.modinfo
    WHAT YOU SHOULD DO
    If you unzipped it with the files within a single folder 1 level below root.
    Code:
    starbound/mods/example/example.modinfo 
    You have installed the mod correctly.

    Pak Files - As same as the example stated above. Pak files require also to be 1 level below the root directory

    Modpak Files - Modpak files are the only files placed in the starbound/mods root directory.

    Win32 Folder - This folder contains the asset unpacker and packer. Though it maybe an exe, it is actually a command line tool, hence there is no GUI. If you double click on it nothing will happen. To get it to work you have to create a .bat file [ batch file ] for windows. Use terminal for mac and Command Line for linux. If you are not sure what to do, there are multitude of tools available in starbound mods section which will help you pack and unpack mods.

    The Bat file must follow the exact syntax, no extra spaces or returns allowed. The format is;
    For sake of Windows - these code samples are placed into a *.bat [ batch ] file.

    For Unpacking
    "Unpacker.exe location" "pak or modpak file location" "location to unpack"

    An example of the code used [ different for everyone based on install location]
    Code:
    "C:\Program Files (x86)\Steam\steamapps\common\Starbound\win32\asset_unpacker.exe" "C:\Program Files (x86)\Steam\steamapps\common\Starbound\assets\packed.pak" "C:\Program Files (x86)\Steam\steamapps\common\Starbound\unpacked"
    For windows place the single line of code in notepad, do file --> save as and save it as unpack.bat. Then double click on it to run the bat file. A new window will open sometimes showing nothing, Do not close it, it will do so by it self when its done. This process may take a few minutes to unpack.

    For packing the file
    "asset_packer.exe location" "location of folder to pack" "where to place the packed file, also if its a packed file or modpak file"

    An example would be
    Code:
    "C:\Program Files (x86)\Steam\steamapps\common\Starbound\win32\asset_packer.exe" "mod name" "C:\Program Files (x86)\Steam\steamapps\common\Starbound\moddev\testmod\" "C:\Program Files (x86)\Steam\steamapps\common\Starbound\mods\example.modpak"
    "mod name" will be the name you see on the menu screen of starbound.

    For more information go here;
    http://community.playstarbound.com/...successfully-pack-and-unpack-pak-files.66649/

    Starbound.log - is single-handedly the most important file when it comes to modding. Anytime you have issues with your mod open the starbound.log in notepad.
    You can read more about starbound.log in my other guide here;
    http://community.playstarbound.com/...d-errors-fixing-most-problems-yourself.69198/

    TOOLS REQUIRED

    UTF-8 Character Set Text Editor - Not Word Document Processor
    You will want to avoid word document processors such as MS Word. These use different character sets which can throw errors in the game. Programs such as Windows Notepad are fine though using something like Notepad++ which will autoformat text for you.
    Some good options are listed here;
    http://starbounder.org/Modding:Text_Editors


    Pixel Editing Tool
    Any pixel editor which exports PNG files and supports transparencies is fine. Personally speaking, all my tutorials will be based around Photoshop, but I will list some free alternatives as well.

    GIMP
    A great free alternative to photoshop.

    http://http://www.gimp.org/

    JSON
    Starbound uses JSON to setup its configuration files for vast majority of its moddable files. Because of their choice modding in starbound is fundamentally much easier. An you can learn all the rules fairly quickly.

    RULES
    • All files must begin and end with curly brackets.
    • Brackets must be closed in reverse sequential order. So the newest bracket must be closed first before brackets made earlier.
    • Every set of data in the array must end with a comma, except the last line.
    • Capitalization when referencing a file or item is extremely important. Item Bob is not the same as item bob.
    • All strings ( letters of text ) should be in quotes
    • Numbers and True and False statements should not be in quotes
    • Make sure you close quotes.
    • Standard format is "variable" : "value assigned"
    • You cannot mix and match variables of different file types (example you can't add durability variable of miningtools to item files)

    TEST
    Identify the mistakes and do the necessary corrections
    Q1:
    Code:
    "name" : "bob"
    Q2:
    Code:
    "name : bob"
    Q3:
    Code:
    { "name" : "bob"
    "age" : "50"
    }

    A1: No curly brackets
    Code:
    { "name" : "bob" }
    A2: No curly brackets, and quotes are not started or closed properly.
    Code:
    { "name" : "bob" }
    A3: No comma after "bob" 50 should not be in quotes.
    Code:
    { "name" : "bob",
    "age" : 50
    }


    SET UP
    Now that you understand the basics and have the tools you required let's first start by unpacking the assets. Which was covered earlier.
    Now that your assets are unpacked we need to setup our mods folder. Go to
    Code:
    starbound/mods
    Create a new folder call it example
    Now open up your text editor and write
    Code:
    {
    "name" : "nameofmod",
    "requires" : [],
    "includes" : []
    }
    Go to file --> save as. Save it in starbound/mods/example
    With the file name pak.modinfo
    name the file with the extension of modpak for example packed.modinfo
    Please make 100% sure you didn't inadvertently name the file packed.modinfo.txt - which will not be read by the game.

    Name
    The name of the mod - and the name used in the require and include function.

    Requires -
    Forces that mod to be required before the mod will work

    Includes
    If the mod exists it loads the mod after the following mod.
    For example say Mod "A" overwrites player.config
    Mod "B" adds items to player.config. The Mod "B" Author knows about this incompatibility. He or She can use the "Includes" tag. So anytime this mod is present in the users mod repertoire it will load after that mod and if it is not there, it will load normally.

    Now we have finally setup our mod, at this point any files we place in the example folder will make changes to the game. But before we start modding there is one final thing we need to cover. Directory Structure.

    DIRECTORY STRUCTURE
    What we need to understand that is our mod folder is an exact parallel to the assets folder. The location of our modinfo file is essentially telling the game this is the root assets location (unless you change the path directory - which you shouldn't do - unless you are an advanced user )

    Lets go to our unpacked assets folder. You will notice files such as player.config - liquid.config - universe.config are all found in the root of the unpacked assets. If we make any changes to them, we need to place them in the exact parallel folder directory. Or in our case the root of the example folder where our modinfo file is.

    Let us look at another example coalore.item
    This file is located in
    Code:
    [root]\items\generic\crafting\coalore.item
    So if we make any changes to this file. We need to place our modified file in
    Code:
    starbound\mods\example\items\generic\crafting\coalore.item
    Where the example folder as mentioned above is our root - or parallel to our assets folder.

    PATCHING VANILLA
    Now since we are at coalore, let us make our first mod. Open coalore.item in our text editor, it should look something like this;

    Code:
    {
      "itemName" : "coalore", --item reference name. Used when referencing this item in json
      "rarity" : "Common", -- rarity level
      "inventoryIcon" : "coalore.png", --image used
      "description" : "It's coal. A decent source of fuel.", -- description of item
      "shortdescription" : "Coal", --name of item shown in game.
    
      "learnBlueprintsOnPickup" : [ "gunpowder" ] -- this line lets you learn a blueprint when you first pick up the item. It is an optional line.
    }
    There are 2 types of edits we can do. One edit is called a dirty edit. These edits generally involve simply changing a value and placing it in our mods folder in the parallel location. These edits are highly incompatible with other mods. And only should be used in personal mods that are never distributed.

    The proper way to make changes though is through "Patching"
    I will not go into much detail about patching here as you can find a much more indepth tutorial here.
    http://community.playstarbound.com/index.php?threads/basic-patching.84496/

    But first lets first copy our coalore.item to our parallel directory in example folder.
    Now rename the file coalore.item.patch


    You might remember that JSON requires you to start with curly brackets. In the case of patches it is square.
    Go this website
    http://json-schema-validator.herokuapp.com/jsonpatch.jsp

    Copy the original code of the file to the bottom box and the code given below into the top.

    Code:
    [
    {
            "op": "replace",
            "path": "/shortdescription",
            "value": "Super Coal"
    }
    ]
    Hit patch. This is a good place to test patches to make sure they give the proper outcome.
    As you can see in the output the short description now has changed to super coal. Now delete the code inside the coalore.item.patch and copy and paste the code example given above instead. Now that we are sure the patch file does as we intended it to do.

    Save the file and load starbound. if everything is done correctly all your coal should now be renamed to super coal.
    Congratulations you just made your first starbound mod.

    PACKING AND REDISTRIBUTION
    Now that we confirmed our mod works, we need to package it.
    As started in the beginning of the tutorial we need to use the asset_packer.exe

    Pack the file as given in the instructions above. Now make sure you remove your unpacked file from the mods folder or you will get an error about a duplicate mod.

    This way starbound will not consider the folder and i'ts contents a mod. Make sure you package it as modpak file and place it in the root starbound mods directory. Confirm again the mod works before redistributing it on your mod distributor of choice.


    Honorable Mentions
    People who helped contribute to the guide.
    @teihoo , @Kawa , @JellyBlade
     
    Last edited: Nov 15, 2015
    G.Xyon, Roubo, zimtZer0 and 9 others like this.
  2. MysticMalevolence

    MysticMalevolence Oxygen Tank

    Nice guide, but actually, notepad doesn't work. At least for me, it refuses to save .modinfo and .patch files, instead forcing them to save as .txt or .object files... making the mod useless.
     
  3. The | Suit

    The | Suit Agent S. Forum Moderator

    Well if you are adamant of using notepad - you should
    use save as
    change type to all files.

    [​IMG]

    Otherwise use Notepad++
     
    Savvon and lezvamp like this.
  4. MysticMalevolence

    MysticMalevolence Oxygen Tank

    I did. It saved as .modinfo.txt.
    I already used notepad++ yesterday to fix it, just thought I'd let you know that notepad doesn't always work.
     
  5. AstralGhost

    AstralGhost Pangalactic Porcupine

    Just an FYI,
    I went to download Adobe Photoshop CS2 yesterday and noticed that there is a disclaimer that states the download is intended only for people that already had a CS2 license and NOT technically available to everyone 'for free'.

    While they no longer have any means of enforcing this (since that's the entire point of taking the servers down), and obviously knew the repercussions - I will point out that using the software is technically not really legal and creating anything from it that you might sell or take donations for (including a mod) would be illegal.
    This is one of those pieces of software that moved on to become 'abandonware'. A software that's not technically free or legal, but the developers do nothing to enforce their copyrights simply because they don't care about it anymore.

    Just thought I'd make a note of that. :)
    The rest of the tutorial looks great, though.
     
  6. The | Suit

    The | Suit Agent S. Forum Moderator

    Sure technically that is there.
     
  7. Oddbrother

    Oddbrother Cosmic Narwhal

    Another great alternative to Photoshop for Windows is Paint.NET.
     
    Last edited: Jan 6, 2015
    LastDay and The | Suit like this.
  8. Crystan

    Crystan Maverick Hunter

    Also great, especially for pixelart, is the free program RealWorld Paint. Unlike paint.net, you can create animations with it and export them as sheets.
     
    LastDay, Oddbrother and The | Suit like this.
  9. Wise Nyt

    Wise Nyt Subatomic Cosmonaut

    I need help with this guide, although I'm sure I've made some sort of noob mistake, I just can't seem to work out what I've done wrong...
    I unpacked the assets folder properly and created the example folder. Its when I actually had to do the modinfo file and patch file is where I failed, I did it in all the ways I could think of and even checked others mods to see how they wrote it just to see I'm doing anything wrong but I still couldn't work it out.
    This is the last thing I tried before I gave up, which is to just copy what you wrote.
    coalore.item.patch
    Code:
    [
    {
            "op": "replace",
            "path": "/shortdescription",
            "value": "Super Coal"
    }
    ]
    before that I wrote for the coalore.item.patch :
    Code:
    {
      "itemName" : "coalore",
      "rarity" : "Common",
      "inventoryIcon" : "coalore.png",
      "description" : "It's coal. A decent source of fuel.",
      "shortdescription" : "Super Coal",
      "fuelAmount" : 2
    }
    example.modinfo
    Code:
    {
    "name" : "nameofmod",
    -- The lines below are optional.
    "path" : ".", - this sets the root asset directory
    "dependencies" : [] -this allows the mod to access resources of another mod. It also loads the mod after that mod, hence overwriting any changes if the mod it is dependent on. The exact name of the mod as per modinfo needs to go in quotes inside the square brackets.
    }
    Before this I wrote the example.modinfo code as:
    Code:
    {
    "name" : "nameofmod",
    "path" : ".",
    "dependencies" : []
    }
    and before that I wrote :
    Code:
    {
    "name" : "nameofmod",
    }
    I did all of this in a number of different ways but I still couldn't get it to work, sometimes it'd just give me and an error and other times it would load but I wouldn't see the coal as "Supercoal" but just normal "coal".
    Help please!
     
  10. The | Suit

    The | Suit Agent S. Forum Moderator

    By looking at your file - I am guessing you are using enraged koala instead of upbeat giraffe?
    As in you are not using nightly or unstable version?
     
  11. Wise Nyt

    Wise Nyt Subatomic Cosmonaut

  12. The | Suit

    The | Suit Agent S. Forum Moderator

    This tutorial is only for unstable \ nightly.
    No point in learning to mod for enraged - the enraged system uses __merge not patch.
    Which is now no longer used.
    Also the reason you are getting errors.
     
  13. Wise Nyt

    Wise Nyt Subatomic Cosmonaut

    I failed on the second sentence of this page...
    Thanks, I could of been stuck on this for quite some time. General question though, whats the difference between unstable and nightly? I mean, which one would I go on if that's even an option.
     
  14. The | Suit

    The | Suit Agent S. Forum Moderator

    Stable = The least bug free version. But hasn't been updated in around 7 months.
    Unstable = Buggy version of stable, requires some bug fixing before moving out. Updated Dec 19 2014 last.
    Nightly = Updated daily [ except weekends ] - has all the cutting edge new features and tons of bugs- or minor changes. Not recommended for people with limited bandwidth.

    If you want to learn modding stick with unstable - and then move to stable when the new stable comes out.
    Till then stick with unstable.
     
  15. Wise Nyt

    Wise Nyt Subatomic Cosmonaut

    Thanks man, much appreciated.
     
    The | Suit likes this.
  16. The | Suit

    The | Suit Agent S. Forum Moderator

    No problem - don't take it too hard. Unless you were modding from the start you would not have known about the switch from merge to patch system.
    So it would be more my fault for not having a disclaimer not compatible with older starbound versions - will remedy that now.
     
  17. Wise Nyt

    Wise Nyt Subatomic Cosmonaut

    Cool, its nice to know some good came out of this.:)
     
  18. DarthTrethon

    DarthTrethon Spaceman Spiff

    I don't understand a lot of it yet but I was looking at the changes from the old _merge style to the patching system and it seems rather drastic. But are they going to change the modding system again or is this how it's going to remain all the way through release and onward? I seem to remember they said they were going to do certain things to make modding easier but I don't recall them mentioning exactly what.....I wonder if they're going to change the whole system again or not.
     
  19. The | Suit

    The | Suit Agent S. Forum Moderator

    No the patch system is finalized. It removes the limitations of the old merge system when it comes to nested arrays.

    It is extremely versatile in many aspects - though there are some parts which require extra effort on your part - such as individually adding items one by one in a already existing list, as opposed to the old merge where you could add them all in one go.
     
    DarthTrethon likes this.
  20. Korvic

    Korvic Void-Bound Voyager

    Hey there, following your guides, however it seems in this one when explaining unpacking, the directory for where to put the files messes with it, not allowing you to unpack it (at least for me, running 64-bit Win 7).

    Code:
    "C:\Program Files (x86)\Steam\steamapps\common\Starbound\win32\asset_unpacker.exe" "C:\Program Files (x86)\Steam\steamapps\common\Starbound\assets\packed.pak" "C:\Program Files (x86)\Steam\steamapps\common\Starbound\unpacked\"
    
    Needed to be changed to the following in order to run properly, otherwise it'd just close as soon as it's opened.
    
    "C:\Program Files (x86)\Steam\steamapps\common\Starbound\win32\asset_unpacker.exe" "C:\Program Files (x86)\Steam\steamapps\common\Starbound\assets\packed.pak" "C:\Program Files (x86)\Steam\steamapps\common\Starbound\unpacked"
    
    (Removed the \ at the end of "unpacked" for the folder to unpack things to)
    
     
Thread Status:
Not open for further replies.

Share This Page