Escaping characters

When you manage your AGS Strings, you might want to pay special attention to these characters:

• " (double quote)
• \ (backslash)
• [ (opening square bracket, also known as left brace)
• % (percent symbol)

For easy solutions, simply read String_formatting#Displaying_special_characters. For thourough explanations, read below.

How to read this walkthrough There are 3 stages in managing your strings : How you type them into the Editor How they will actually be stored into the engine's memory, at runtime How they will be rendered into the display: in a Label, in a Listbox, or in a Display command.

1) In the AGS script editor :

(all the statements below tested in AGS 3.2.1)

Let's say you want to declare a string containing a backslash (\) and or a double quote ("), in the following fashion :

String s = "this is a string, and soon it will contain a backslash or a double quote";

In the script editor, the backslash acts as an escape character, which means it has no value in itself, but depends on what comes immediately behind.

Situation	What you type into the script editor	What you get in memory	Explanations
One backslash followed by a double quote: \"	String s = "aaa\"bbb";	97 97 97 34 98 98 98	As you can see the backslash acts as an escape character and gets swallowed up so that the double quote doesn't get confused with the ending double quote. By the way, this is not correct syntaxically, as there is no ending double quote: String s = "aaa\";
One backslash followed by another backslash: \\	String s = "aaa\\bbb";	97 97 97 92 98 98 98	As you can see the backslash acts as an escape character and gets swallowed up so that the second backslash actually makes it to the String in memory.
One backslash followed by an opening brace: \[	String s = "aaa\[bbb";	97 97 97 92 91 98 98 98	As you can see the backslash acts as an escape character but DOES NOT get swallowed up. Both backslash and opening brace make it to memory. This becomes useful at rendering time, to display a [ in a Label or a Display.
One backslash followed by anything else: \a, \b, etc.	String s = "aaa\bbb";	97 97 97 98 98 98	The backslash gets deleted. It does not act as an escape character (the "a" immediately after it still makes it to memory) BUT still gets swallowed up, and doesn't appear in the in-memory string.
Any number of backslashes followed by something else	String s = "aaa\\\[\bbb";	97 97 97 92 92 91 98 98 98	All the above applies. Count your number of backslashes carefully! The first two backslashes become just "\", "\[" stays "\[", "\b" becomes just "b". Tricky, isn't it?
Any number of percent symbols	String s = "aaa%bbb"; or String s="aaa%%bbb";	97 97 97 37 98 98 98 or 97 97 97 37 37 98 98 98	The string will be stored in memory exactly as you typed it in. Trouble may arise only if you decide to use that particular String as the first parameter of the String.Format or Display function.

Pro-tip : To avoid human mistakes, manipulate escape characters separately, using only their keyCode.

Example :

What you type in the script editor	What you get in memory at run-time
String s=String.Format("%s%c%c%s", "aaa", eKeyBackSlash, eKeyOpenBracket, "bbb");	97 97 97 92 91 98 98 98 (aaa\[bbb)

2) In the GUI Editor

• What you type in the "Text" property of the Label control is exactly what will be in memory. No escape characters apply.
• What will appear in the Label preview (in the GUI Editor, on the left) is rendered following the rules described in this page for Labels (read further).

What you type in the Text property	What appears in the Label preview	Explanation
aaa[bbb	aaa bbb	See Label rendering rules.
aaa\[bbb	aaa[bbb	See Label rendering rules.
aaa\\\\[bbb	aaa[bbb	See Label rendering rules. All the backslashes get swallowed up at once!
aaa\bbb	aaa\bbb	(identical) See Label rendering rules.
aaa\\\\bbb	aaa\\\\bbb	(identical) See Label rendering rules.
aaa%bbb	aaa%bbb	The percent symbol is rendered identically when displayed in a Label.Text. Remember, though, that it has a special effect only when used as the first parameter of the String.Format or Display function (read the next section).

2) At runtime, in a Label or a Display()

The string as stored in memory	How it will be rendered in a Label or Display	Explanation
aaa[bbb	aaa bbb	The opening brace is a special character that creates a new line.
aaa\[bbb	aaa[bbb	The brace's special behaviour is disabled if it's preceded by one or more backslashes. The backslashes are not rendered.
aaa\\\\[bbb	aaa[bbb	Please note that all the backslashes before a '[' don't get rendered. Not only do they not get rendered, but they get deleted from the String (in-memory) if you make use of any of the following functions: Append, AppendChar, Replace, etc. Also when you do a string -> String conversion (Reminder: string is the old-style AGS string, while String is the new-style AGS string since 3.x). It doesn't seem to happen when you use String.Chars[i]
aaa\bbb	aaa\bbb	The string gets rendered exactly as in memory, as the backslashes are not followed by [.
aaa\\\\bbb	aaa\\\\bbb	The string gets rendered exactly as in memory, as the backslashes are not followed by [.
aaa%ddd	In Label.Text: aaa%ddd In Display: aaa%?dd (where ? could be any character)	% is a special character meant for formatting Strings, as in String s = String.Format("The value of i is %d", i);. In Labels, it will have no effect. However the Display function works the same way as String.Format, so you must avoid having a single percent symbol. Use double percents instead.
aaa%%ddd	In Label.Text: aaa%%ddd In Display: aaa%ddd	% is a special character meant for formatting Strings, as in String s = String.Format("The value of i is %d", i);. In Labels, it will have no effect. However the Display function works the same way as String.Format, so if you want to display one percent symbol, you must have two in your string.
aaa%%bbb	aaa%bbb	A double percent in memory is rendered as a single percent on-screen

3) At runtime, in a Listbox

The string is rendered exactly as it is stored in memory. the Listbox doesn't handle line breaks, so a [ or a \[ in memory will appear as-is in the Listbox.

But remember this :

• If your string contains one percent symbol, it can cause issues if at some stage before rendering it's used in a String.Format function (see previous section for recommendations about the double-percents)
• If your string contains several \ followed by one [, then all the \ will be deleted from memory if your string gets manipulated by any String-manipulation function (Append, AppendChar, etc.). See previous section to know more.