Logo 3.5Cats_AndHalfAFish



January 08, 2020 Shade, Godot : JSON vs CSV data
Importing spreadsheet data into Godot.

Note : Godot 3.2 beta 4.

I have been tinkering a bit with the GUI for my inventory system. And it suddenly dawned on me : how am I going to get all item data into the game ?

Placeholder inventory in 'Shade'.
Placeholder inventory in 'Shade'.

In my previous point&click game (Finding Fifi) I had a limited number of items that could be picked up (about 20, I think).

Screenshot from 'Finding Fifi' showing inventory.
Inventory in 'Finding Fifi'.

I used a general 'PickUp' class, and manually initialized objects at the start of the game by setting their location, name, and visibility.
When such an object was later clicked on, I went through a long 'if / else if ' list to find the appropriate function to call (remove picked up object from game screen, show icon in inventory, ...)

I similarly had a general 'HotSpot' class. Instances were again manually initialized at the start of the game, by setting their name and size, and whether the hotspot area was active or not.
Clicking a hotspot with an inventory item selected, would trigger another 'if / else if ' list to determine if hotspot and icon matched (and then trigger some action).

This system worked well for me. But as I said, Finding Fifi was a smallish game.
So, what am I to do with 'Shade' (the game I'm currently working on) ? There will most likely be a larger number of items to interact with ...

Looking around on Youtube, I quickly found out that many people use spreadsheets to define the properties of items (pickups) in their games. To get that data into their game engine, they convert the spreadsheets to JSON.

Spreadsheet data.
Spreadsheet data.

Personally, I'm not a big fan of JSON, because ... well, all those curly braces !
As an alternative to JSON, I could use CSV (comma-separated values) data. This would mean : -no- curly braces + a smaller file size.

I decided to take a look at both options.


Creating a CSV-file from a LibreOffice Calc doc couldn't be easier : file > save as > csv.

CSV data.
CSV data opened in Notepad++.

Importing this file into Godot is a bit annoying : you need to copy the CSV file into the "res://" folder using the Windows Explorer (or something similar). You can't drag the file into the editor like you can do with, for instance, images.
If that went well, you'll see the CSV file sporting an icon with a big red cross.
Looks like Godot isn't happy about something ...

Importing CSV data into Godot. Importing CSV data into Godot.
Importing CSV data into Godot.

The solution is easy : select the CSV file, click the 'import' tab next to the 'scene' tab, and select 'import as CSV' (the default is 'CSV Translation', which is used for ... translations !). And here comes the annoying part : Godot wants to restart after the import !

Reading and using the CSV-file is really easy :

Code for using CSV data in Godot.
Code for using CSV data in Godot.


Creating a JSON-file from a LibreOffice Calc doc is a bit more involved.
First, you need to export the document to CSV, and then use an online JSON-creator tool to convert CSV into JSON.

I don't really like that : 1) there are 2 steps, 2) what if the online tool 'goes away' ???

My solution : create a small (simplistic !) Java program that reads the .ODS Calc document and converts it into JSON.
Fortunately, this is easy to do with the help of 2 libraries : org.jopendocument and org.json. I'm sure you can guess what they are used for. =)
The jars can be downloaded from Maven Central.

Here is some of the JSON data (formatted in the JSON Formatter online tool for readability) :

JSON data.
JSON data.

Importing a .JSON file into Godot is a bit weird. You also need to do this through the Windows Explorer, but the file doesn't show up -at all- in the Godot resource folder !
A bit strange, if you ask me (but then : what do I know about engine design ?! =) ) ...

Reading and using the file is again very simple :

Code for using JSON data in Godot.
Code for using JSON data in Godot.


  • CSV is a simple format that's easy to edit (if necessary).
  • It can be created in most/all spreadsheet software.
  • CSV files are smaller than JSON files (less repetition).
  • They are easy to import into Godot, and also easy to use (read).
  • However, to use the data inside your game, you will have to create some kind of structure to link 'keys' with 'values'. You will also need to manually convert string values into, for instance, floats or arrays.

  • JSON is an annoying format to write/edit in something like Notepad++. Too many nested curly braces. Too easy to mess up.
  • You probably need some online tool to create/edit/validate your data.
  • JSON files have data repetition (keys are repeated for all 'records').
  • They're not visible in the Godot resource folder.
  • However, the data is immediately usable inside your game (all data consists of key-value pairs in the correct data type).

Since I now have a little Java program to convert my spreadsheets directly into JSON, I think I'll go with JSON for now. We'll see how that works out ... =)