TextMarkup

Markup - only half the story

With TxtAdv I try to give developers the freedom to choose for themselves how to use the framework. That is why TxtAdv does not actually force you to use the markup written in the .txt files.

The styles are parsed and you can access them via C++ code, but you can choose to ignore them. The text and styles are completely separate. For that exact reason, you will have to handle the styles yourself when rendering your text. TxtAdv only provides you with the necessary data for you to act on.

Without further ado, let's dive in and look at how you should write your markup.

Emphasis

The emphasis markup used in TxtAdv is very similar to that of Markdown. However, there are a few modifications and additions so pay attention!

There are 4 styles that you can combine and mix.

• Bold. Text between * symbols are marked as bold
• Italic. Text between _ symbols are marked as italic
• Underline. Text between __ symbols are marked as underlined
• Strikethrough. Text between ~ symbols are marked as crossed out

Note! The difference here to Markdown, is that the * character is used to denote bold, instead of the double **. Also strikethrough does not exist in Markdown (the original), but does exist in Github Flavoured Markdown as ~~.

Example:

// produces 'foobar' which is bold, italic and crossed out
*_~foobar~_*

The styles do not need to be nested properly, so *_~foobar*~_ produces the exact same result as in the example.

CAUTION!
Do not use ** for bold, since in TxtAdv ** means a bold emphasis style with the length of 0, and it will just be ignored.

Metadata

On top of emphasis style, you can also specify other attributes that I have chosen to call metadata. These other text attributes are:

• Size
• Fill color
• Outline color
• Background color

Size

In Markdown you have header sizes from 1-6, corresponding to the HTML tags <h1> through <h6>. In TxtAdv, I opted to use sizes 1-5, but not limit them to be used as headers.

These sizes are arbitrary sizes, not bound to any font size. You are in charge of handling these sizes yourself. Like all markup, they are optional so you may decide to ignore them.

To use different sizes in your text, specify the size with !x, where x is a number from 1 to 5. If x is something else, it is considered normal story text. Size 1 is the default size that the story uses, so unless otherwise specified, size 1 is used.

Example:

I am in size 1,!2 I am in size 2 all the way.

Fill color

This is the color that should be used to render your text. The color is in the RGBA-format and the default color is white (#ffffffff). Only the fill color can be set directly using the markup text, and to be honest, it looks ugly.

That is why style tags exist (see next section).

Example:

I am in white,#ff0000ff I am in red color.

Outline color

This color should be used to specify the outline color of the text. By default, it is white, but remember, you don't even need to use this color.

Background color

This color is seldom used, but it specifies the color in the background, behind the letters and characters. It can provide extra emphasis to a word for example.

Tags

Tags are mainly used to define text styles. These style tags can then be reused throughout the text. They have the same benefit as variables in code, you only need to change the value(s) in one place. Furthermore, style tags can be much cleaner to use than to use hex strings and multiple emphasis markup symbols. I find that readability is very important which is why style tags were created.

For example, compare

Greetings, I am #dd0000ff*__Arthur Pendragon__*#ffffffff, and you are?.

to this

Greetings, I am <name>Arthur Pendragon</name>, and you are?

The second style is much nicer, wouldn't you agree?

Of course, these style tags need to be defined somewhere. And as you might remember, that happens in a .style file.

Variables & Expressions

In addition to the static markup, TxtAdv also support a powerful dynamic variable markup system. To understand what this is, let's look at an example.

So you are the legendary {s_name} that I have heard so much about. Rumor has it
that you killed {i_orcs_killed} of those gnarly Orcs.

I mentioned in the earlier section that readability is important, which is why the variable markup is very easy to read. You have probably already figured out the syntax of a variable, but what are the s_ and i_ prefixes?

A variable has the following format:

{<type>_<name>}

where <type> is the variable type and <name> is the actual name of the variable. TxtAdv supports four types of variables:

• Integer
• Floating-point number (decimal)
• String
• Expression

As you might have already guessed, the type prefix for an integer variable is i. Floating-point numbers or floats for short use the prefix f and string variables s. All of them are quite intuitive and easy to remember, but what is the last variable type, "expression"?

Expressions are used for situations where there is need for some amount of computation. So the value cannot easily be represented by a variable or a series of variables. Again, to illustrate what I mean, let's see an example.

Today the price for bread is {f_price_bread}. You have enough for {x_bread_afford_count} loaves of bread.

Here the number of bread loaves you can afford is determined by today's price for bread and the amount of money you have (not visible here).

Expression variables are very powerful, but for now, you will have to define these expression in C++ code. In the future, I will add Lua support so that you can define these expressions via a Lua function.

How do I modify the variables?

The variables that you saw in the previous section, are stored in a C++ object. But you can access that variable storage from Lua in your matcher and action functions. This means that you can change them at your will and later in the story the variables will have changed.