Modding:JSON
JSON is an acronym that stands for "JavaScript Object Notation."
According to the JSON home page,
JSON is a lightweight data-interchange format. It is easy for humans to read and write. It is easy for machines to parse and generate. It is based on a subset of the JavaScript Programming Language, Standard ECMA-262 3rd Edition - December 1999. JSON is a text format that is completely language independent but uses conventions that are familiar to programmers of the C-family of languages, including C, C++, C#, Java, JavaScript, Perl, Python, and many others. These properties make JSON an ideal data-interchange language.
Starbound uses JSON to store hierarchical information pertaining to just about every aspect of the game. The splash screen, the menu graphics, the character creator, all of the in-game graphics and sounds, etc. are all defined through JSON configuration files.
Many parts of Starbound can be customized, however the functionality behind a great many things is still hard-coded in the engine. That means that, at least at the time of the writing of this article, a great portion of the functionality of (for example) races and ships are at best tricky to change. Some things are impossible to change, or can cause unpredictable behavior in the game.
JSON Example
1 {
2
3 "frameGrid" : {
4 "size" : [32, 44],
5 "dimensions" : [8, 1], // This is a comment.
6 "names" : [
7 [ "default.0", "default.1", "default.2", "default.3", "default.4", "default.5", "default.6", "default.7" ]
8
9 ]
10
11 },
12 "aliases" : {
13 "default.default" : "default.0"
14 }
15 }
This is a .frame file, very typical of a simple animated object.
- The frameGrid section (lines 3-11) defines the size of each sprite.
- "size" (line 4) defines the size of one sprite (32 pixels wide by 44 pixels high.
- "dimensions" (line 5) defines the overall sprite file (8 sprites wide by 1 sprite high).
- "names" (line 6-9) define names for each individual frame so they can be referenced for animation.
- "aliases" (lines 12-14) define secondary names for frames, for convenience in remapping, sprites that pull double-duty, etc.
If you do the math, you can figure that the .png file referenced here is probably 256 pixels wide by 44 pixels high. If the configuration of this file does not match your graphic, you will have problems, including Mapping errors.
The Starbound game engine supports comments in JSON files. This is outside of the JSON standard and may cause problems with editors that attempt to debug ("lint") your JSON file. If you can specify a language for your JSON files, use Javascript; it will accommodate the comments and still give you proper JSON syntax highlighting.
JSON Reference
Variables
All entities include pre-scripted variables that the game utilizes for special functions. These variables are stored in the item's JSON code but can also be accessed by Lua.
| Objects | Monsters | Weapons | Projectiles | Armor | Tech | Panes |
Troubleshooting
Troubleshooting Starbound JSON config files consists of a few major points.
- Check the error in the log file.
- Make sure your braces ({, }) are matched.
- Make sure your brackets ([, ]) are matched.
- Make sure your quotation marks (") are matched.
- Make sure your commas are in the right place. An extra comma is often the culprit.
- Use a "lint" program or website to check your syntax if you can't find the problem. JSONLint.com is one such site. Many text editors have a JSLint plugin as well.
- Did you exit completely out of the game client, not just exit to the menu and go back in?
- Is starbound.exe still running in the background? (Check your task manager.)
See these other troubleshooting tips.
Please exhaust all of these possibilities before asking another modder to at your code. When all else fails, visit our IRC channel and ask someone for help.
