Braces, Brackets and Commas, Oh My. A JSON Primer

A lot of your time creating mods will be spent editing and creating JSON objects that will either alter existing items, or create new objects entirely. Below is an introduction to objects in JSON and tips to help make your life easier when reading and altering these files.

JSON, for the uninitiated, stands for Javascript Object Notation and is actually a very simple concept. It is a way to store objects as a list of attributes using key : value pairs. If that doesn't sound simple to you, read on.

I highly recommend using an online JSON parser to double check your work. You can copy and paste your objects into the parser and it will let you know if you've made any boo boos. A decent one is here, otherwise you can always google around.

JSON = JavaScript Object Notation
JSON Parsers are your friends.

The Example - Distress Beacon

Let's say we have a certain object that we want to modify and we'll take that one step further and say it's the Distress Beacon. Let's take a look at what is actually in the file and see if we can make some sense out of it.

From /assets/objects/boss/ironbeacon.object Modified for readability.

{
"objectName" : "ironbeacon",
"rarity" : "Common",
"objectType" : "wire",
"description" : "A distress beacon. It might help you. Or it might not.",
"shortdescription": "Distress Beacon",
"race" : "generic",
"category" : "tools",
"printable" : false,
"inventoryIcon" : "ironbeaconicon.png",
"orientations" : [

{
"dualImage" : "ironbeacon.png:<color>.<frame>",
"imagePosition" : [-16, 0],
"frames" : 12,
"animationCycle" : 2,
"spaceScan" : 0.1,
"anchors" : [ "bottom" ]
}
],​

"animation" : "/objects/wired/ironbeacon/ironbeacon.animation",
"animationParts" : {

"beacon" : "ironbeacon.png"
},​

"animationPosition" : [-16, 0],

"scripts" : [ "/objects/wired/ironbeacon/ironbeacon.lua" ],
"scriptDelta" : 5
}

Commas And Lists - The Age Old Problem (not really)

Before we dissect the JSON object that represents our distress beacon, let's have a brief chat about lists. You know, like a grocery list.

I don't know about you, but when I make a list, I usually don't get all hung up on where to put commas. JSON has a couple of different types of lists, but the rules are the same for each and they are the same as the rules you were taught in 2nd grade about where to put commas in lists.

Comma Placement in Grocery Lists (Also applies to lists in JSON)

• One item lists - let's not get hung up on the philosophy of when a list is a list here, just don't use a comma.
  CORRECT Eggs
  INCORRECT ,Eggs,,,,, , , (also incorrect would be any other variation involving a comma)
  
  
• Two item lists - we want to add Milk to our list, but where to put it? You decide, here are our options:
  Milk, Eggs
  Eggs, Milk
  
• Three to N item lists - a snobbish way to say three or more. Here we always have 3 options:
  • Add an item to the beginning of the list
    Bread, Milk, Eggs
  • Add an item to the end of the list
    Bread, Milk, Eggs, Butter
  • Slip it in somewhere in the middle so it doesn't stand out as much
    Bread, Milk, Condoms, Eggs, Butter
• To sum it up: For any list containing more than one item you place a comma between each item.
  • Never a comma at the end,
  • ,Never a comma at the begging
  • just , put , commas , between, things

Objects

Objects are represented by comma separated lists of KEY : VALUE pairs contained within a pair of braces { }. The KEY : VALUE pairs are the object's attributes -- they are what describe the object.

• An Empty Object -- an object with no attributes.
  { }
  
  
• An Object With 1 attribute
  {
  "attributeName" : "attributeValue" }
  
  
• An object with 2 attributes, separated by a single comma, because it's a list and that's what you do.
  {
  "attributeName1" : "attributeValue1" ,
  "attributeName2" : "attributeValue2"
  }

Objects are simply a list of attributes.
Make your list and check it twice. (see Commas And Lists)

KEY : VALUE pairs (Attributes)

A KEY: VALUE pair is precisely that - a pair consisting of one KEY and one VALUE. The key is the name of the object's attribute and the value is, well, the value of that attribute.

• The KEY is written inside a pair of double-quotes, and is separated from the VALUE by a colon.
• The value can have several different types which are discussed in the next section.

"objectName" : "ironbeacon"

This tells us our Distress Beacon has an attribute called objectName and the value of objectName is set to "ironbeacon".

Attributes are simply KEY : VALUE pairs.

Values & Types

The value of each attribute can be a single value, a list of values, a single object, or a list of objects.

A single value can be a string of text, a number, a Boolean value (true or false), or even an object.

• Quoted Values - Strings of Text
  • Always enclosed in a pair of double-quotes.
    "shortdescription" : "Distress Beacon"
    
    
  • A file path is a string of text
    "animation" : "/objects/wired/ironbeacon/ironbeacon.animation"
    
    
  • Strings can also have external meaning, like Category. tools is one of the predefined categories but changing this value to "BossSummoningItems" would not work unless "BossSummoningItems" was a pre-defined category.
    "category" : "tools"
• Unquoted Values - Numbers & Booleans
  • Numbers can be integers or decimals and are never put in quotes.
    "spaceScan" : 0.1
    "scriptDelta" : 5
    
    
  • Boolean values should not be quoted and should be written as either true or false
    "printable" : false

Strings are always put in "double quotes"
Numbers should never be quoted, neither should true or false.
Numbers should only be in quotes when they are meant to be part of a string of text, as in "Apex and 99 Bananas don't mix."

Objects As Values

Values can also be entire objects. The value is then placed inside a new pair of braces { } and it is then just like any other object. When you see pairs of braces { } within another pair of braces, you have a nested object -- one object is nested within another.

The animationParts attribute of the distress beacon has an object for its value. The object has one attribute named beacon.
"animationParts" : {

"beacon" : "ironbeacon.png"
}​

Lists As Values

When more than one value is needed to make up an attribute, the value can be represented as a list of values (an array).

• Lists of values are always contained in a pair of square brackets [ ]
• Each item in the list should be the same type.
  A list of objects, a list of strings, a list of numbers, etc.

For example, the player position can be represented by an X and a Y coordinate which could be stored in a list of numbers :
"playerPosition" : [100,50]

The most complex value of our distress beacon is the orientation attribute. However, now that we understand what all these braces, brackets, and commas are there for, it actually becomes quite simple.

"orientations" : [ //Square bracket, so we're in a list.

{ //Ok, this is an object so we have a list of objects. Neat.
"dualImage" : "ironbeacon.png:<color>.<frame>",
"imagePosition" : [-16, 0], //Another list, look at me go!
"frames" : 12,
"animationCycle" : 2,
"spaceScan" : 0.1,
"anchors" : [ "bottom" ] //A lonely list, he needs friends.
}
] ​

Anyone have any wild guesses of what a comment might be?

So that's it. Simple. Now go make stuff!