Skip to content

FileFormats

Jump to bottom
Daniel Riissanen edited this page Jan 8, 2019 · 2 revisions

Files

TxtAdv uses 3 types of files that are used to define the story and how it's controlled.

  • Txt files: This is the core file that you will be working with. You write all of the story text in this file.
  • Ctrl files: Information about how to control the the flow of the story resides in here.
  • Style files: These are optional files that can make styling of common elements a breeze.

Txt files

I know that people love examples so that's why I am going to start with an example .txt file and then explain the format down below.

Sample .txt-file:

Ctrl: Content/intro.ctrl
Style: Content/intro.style

Story: chapter1-part1
    Adeleine was sure she had bought five bottles of wine, but now she could
    only find four. Could she have miscounted and left one of the bottles at
    the store?

    What should she do now?
Story: chapter1-part2
    Had it not been for her fast thinking, the whole dinner party would have
    been ruined.
    ...

In an attempt to make the life of content creators easier, I've kept the file format of txt files simple. There are three parts;

  1. Ctrl file declaration
  2. Style file declaration
  3. Story points declarations

Of those three, the style file declaration is optional and can be left out.

The ctrl file declaration is a single line with the format:

Ctrl: <file path>

where <file path> is the path to the .ctrl-file (see next section).

The style file declaration follows the same format:

Style: <file path>

where <file path> is the path to the .style-file.

After the file declaration follows a single blank line and then various story point declarations. You can think of story points as paragraphs or even whole chapters.

The story point declaration format:

Story: <unique name>
    <text>

where <unique name> is a unique identifier for the story point and <text> is regular story text. The <text> can be stylized and annotated, but that will be discusssed on another page. The <text> needs to be indented by at least 2 spaces. In the example I used four spaces, but two is enough.

Ctrl files

Sample .ctrl file:

chapter1-part1, LUA/intro.lua, m_ch1_pt1, a_ch1_pt1
chapter1-part2, LUA/intro.lua, m_ch1_pt2, a_ch1_pt2
chapter1-part3, LUA/intro.lua, m_ch1_pt3, a_ch1_pt3

Ctrl files have an even simpler format, they're just CSV files in disguise. CSV stands for Comma-Separated Values. Each line consists of a set of values that are separated by a comma.

There are 4 values per line in a .ctrl file and they correspond to the following:

  1. Story point ID: The unique identifier of one of the story points defined in the .txt file (see above).
  2. Lua file: The path to the Lua file handling story branching and flow.
  3. Lua matcher function: The name of the function in the Lua file that handles input matching. Details can be found on another page.
  4. Lua action function: The name of the function in the Lua file that changes the story and decides where to go next. Details can be found on another page.

Note:
In the example above all of the story points use the same Lua file. This allows you to control everything in one part of the story in one file. The Lua matcher function and the Lua action function names may also be identical to that of another story point, but usually you will want separate ones.

Style files

Sample .style file:

subheader
  size: 2
  emphasis: bold underline
name
  emphasis: bold
  fill_color: #ffff00ff
item
  emphasis: italic
  fill_color: #0000ffff

The .style file follows a simple format too! Each style starts with the name of the style and after that, a set of key-value pairs that are indented. As with the .txt file, you only need to indent by 2 spaces, but you can indent with more spaces if you want.

The format:

<style name>
  <attribute name>: <attribute value>
  ...

The <style name> must begin with a alphabetic English letter, meaning that it cannot start with a number or a special character.

There are predefined attributes and they are:

  • size: A number ranging from [1, 5] (inclusive)
  • emphasis: A set of emphasis keywords (see below)
  • outline_color: A RGBA hex string
  • fill_color: A RGBA hex string
  • bg_color: A RGBA hex string

A value outside the range for the size attribute, renders the attribute invalid and it will have the default value of 1.

The emphasis keywords are:

  • bold - For bold text
  • italic - For italicized text
  • underline - For underlined text
  • strikethrough - For crossed over text

The keywords may be combined by separating them with a space, the order does not matter.

The RGBA hex string starts with a #, and is followed by 8 hexadecimal digits ranging from 0-F. The first two digits define the red color, the next two the green color, and so forth. #000000ff is the color black, and #ffffffff is white.

fill_color is the normal text color, outline_color can be used to define a different color to the outline of the text, and bg_color can be used to define a background color. The background color is seldom used, but it might come in handy.

Comments

All of the three files may contain comments. There are two types of comments, single-line comments denoted by // and multi-line comments starting with /* and ending with */.

Example:

// I am a single-line comment
/* I am a
   multi-line comment
*/

Everything after // and between /* and */ are considered a part of the comment.

Clone this wiki locally