Guide:Making a codex

From Starbounder - Starbound Wiki
Jump to: navigation, search

Welcome to the codex guide.

This guide aims to explain the inner workings of the .codex files and how to make them.

Codex JSON fields

A typical .codex file you'll find in the game assets looks as follows:

  "id" : "glitchhistory1",
  "species" : "glitch",
  "title" : "Built for Purpose? I",
  "description" : "An excerpt from a book investigating the origin of the Glitch.",
  "icon" : "glitchcover1.png",
  "contentPages" : [
    "Are we not a fascinating race? Having long since attained self-awareness, the origin of the Glitch race fascinates me.

The most curious thing is that we were deliberately built with the compulsion to fulfil desires outside of those that are biologically necessary. The need to fulfil carefully crafted base instincts became imperative and shaped the entire oil spattered time-line of Glitch history.",

 "The question is why? Why limit our potential to that of beings governed by emotion so easily replicated?

I have run every analysis, constructed every model and the answer continues to allude. Are we but an experiment? And if so, is instinct the variable or the control? Perhaps only our creator will know."

  "itemConfig" : {
    "rarity" : "common",
    "price" : 25

Let's go over the JSON fields.

This field defines the unique name of the codex used internally by the game. If this value is not unique, the game will likely crash on startup.
This value is also used to define the item that unlocks the codex. The item id looks like <id>-codex, or "glitchhistory1-codex", as is the case with example codex above.
This field determines which tab the codex appears under in the codex UI. As the UI is not dynamic, you are limited to using the pre-existing races or none.
This field is entirely optional. Leaving it out will place the codex in the "?" tab of the codex UI.
The title of the codex, the name that will appear in both the inventory and the codex UI.
A short line describing the codex that will appear in the inventory tooltip.
Leaving this field out will not break the game, but will leave the inventory tooltip rather blank.
A name of or a path to a 16 by 16 pixel image that will represent the codex item in the world, in the inventory and in the codex UI.
This field is optional. Leaving it out will default the icon to a regular book. Codexinhand.png
This is where the magic happens. Content pages contains an array of strings that define the contents of the codex.
Each page in the codex is defined in the following manner :
[ "page1", "page2", "page3" ]
The game does not do any automatic formatting on your part. If the page string is too long, it will overflow on top of the UI, so watch out for that.
This parameter holds within itself the parameters that determine the properties of the codex item :
rarity - determines the colour of the border around the item in the inventory as well as the pickup popup formatting.
price - determines the price of the item. Be mindful that the shops apply a modifier on top of this price.
Note that this field can accept same parameters as any other item, but there probably isn't much point to putting in more than rarity and price.

Remember that all of the names of the fields are case sensitive. Writing "contentPages" as "ContentPages" will give you an error.


There are a few things you shuld know about formatting the codex :

  • The codex file must be in utf8 encoding. Make sure your text editor supports specifying the encoding of a file.
  • The game font does not have any fancy symbols in it outside the ascii. Any fancy apostrophes, quotes, long dashes and such will not display properly.
  • Make sure that there aren't any tab symbols inside of the page strings. While the game will trim other whitespace characters, it will display tab symbols as boxes.
  • Line breaks
    • You can add line breaks by simply inserting them into the page string.
    • The game uses a unix EOL style by default (\n), but it should work with windows style (\r\n). Try switching to unix style if you see unexplained "box" symbols in the game.
  • Colours
    • Colour codes can be used as usual in both title, description and contentPages.
    • Colour codes are used as follows: ^colour;
    • For example, ^blue; will turn all the text after it blue. ^reset; turns all the text after it white. Not resetting the colour will not have any repercussions outsidee of the string.
    • Alternatively, the game accepts hex codes as colours as follows: ^#FFFFFF;

Quick Navigation