XData File Creation

In order to get custom text for readables into your map, you will have to define the texts somewhere. This happens in the files within the xdata/ folder.

I will describe a basic single-page readable here. Hopefully I will be able to add more information on creating books and other multi-page readables. See also xdata file format for detailed information.

Create the .xd File

Create a new .xd file named after your map file. If your map file is called "readable_tutorial.map", create the file xdata/readable_tutorial.xd. (note: the xd file can be any name but it makes sense to use map name when published for identification and to avoid conflict etc. For example darkmanor.xd will work fine with darkmanor448.map and darkmanor449.map etc. or even just 449.map during development.)

To save time-consuming syntax typing, I suggest copying the content of another .xd file right into yours. There is are already the file readable_test.xd in the xdata/ folder. Open it and copy all of its content into yours.

A basic readable text can be defined by these two blocks (it's the same text that is used in the Readables Tutorial):

The Main Block

readables/readable_tutorial/sample
{
   precache
   "gui_page1"   : "guis/readables/page_test.gui"
   import {
       "title" -> "page1_title"
       "body"  -> "page1_body"
   } from "readables/readable_tutorial/page1"
}

This block is some kind of "Table of Contents" of your readable. It defines which gui templates each page of your readable is using and which texts are to be displayed. The important part is the first line

readables/readable_tutorial/sample

which is the name used to access this text in the editor. This value corresponds to the xdata_contents key of your readable entity.

Secondly, there is the import { ... } from command, which tells the readable where to look for the actual text to be display on Page 1. It refers to the data block defined below.

The Data Block

readables/readable_tutorial/page1
{
   "title" : "W00t!"
   "body"  : "This is a damn fine readable. Read it at your own risk. Absolutely frobable. Totally 
customizable. Choose your own background, your own font, your own text size! Heck, even custom 
texts are possible..."
}

Again, the name of the block is important, as it is referred to in the master block. The syntax is quite straight forward. Anything inside the quotes will appear as an uninterrupted block of text (word wrapping will happen automatically). Use two empty quotes ("") to leave an empty line.

If you want to type separate lines, putting a slash "/" after them will make them join up in the readable (this may be useful if you are using an editor without word-wrap).

{
   "title" : "W00t!"
   "body"  : "This is a damn fine readable. Read it at your own risk. Absolutely frobable. Totally 
customizable. Choose"  /
"your own background, your own font, your own text size! Heck, even custom texts are possible..."
}

Note: There can be no hard returns inside a pair of quotes, or the readable will not work!

Custom Fonts and Stuff

You can use custom fonts, font sizes and backgrounds in your readables. These are defined in the .gui file which is referred to in the master block:

"gui_page1"   : "guis/readables/page_test.gui"

Each page can use its own gui (for example if you plan to display page 1 as the book's cover and the rest as ordinary book pages). The tutorial is still to be written: GUI Definitions

Notes, Troubleshooting, etc.

If your readable will not display in-game and you get a 'num_pages not defined' error when you know you have - or you only have one page, then check to see if you accidentally put a \ character after the last quote marks. The function is expecting more and there isn't any. With an inventory readable this will also lock up the inventory and all frobbing so is pretty fatal to continuing the game.

If your text is too long for the page it won't crash it just will get truncated at the most it can display in the defined rectangle.

You can use reloadXData in the console to reload changed xdata definitions in-game.

More troubleshooting tips at Readables#Test_your_Readable.21