22 February 2010

Last time, I talked about sinusoidal motion, a way to make certain movements and animations look more natural. I mentioned that it could be used to make an opening animation for text boxes. This time we'll be looking at text boxes themselves.

We've all seen text boxes. They're the windows full of dialogue that appear when you talk to people in video games.

It's easy enough to slap a single box of text onto the screen in Game Maker. But most text boxes consist of several pages of dialogue, and the player advances through them by pressing a button.

You could achieve this with an array of strings, like this:

Create Event (TextBox object):

//define the pages of text//(# is the newline character in GML)
Page[0] = "Hello there, traveller!";
Page[1] = "This is a bomb shop! I stock all#sorts of different explosives.";
Page[2] = "No smoking, please!";//set the page index
PageIndex = 0;

Draw Event (TextBox object):

//draw the string on the screendraw_string(TextX,TextY,Page[PageIndex]);

Step Event (TextBox object):

//check for a press of the A buttonifJoyButtonPressed(A);
{//increase the page index
PageIndex += 1;
}

This is an okay method, but it has an annoying problem: You have to manually cut the dialogue into pages yourself, as well as place the newline characters.

Imagine you have a game where you want the text box to be resizable. Or, not all text boxes are the same size (as in Final Fantasy VII). Or, you've already written all the dialogue for your RPG, and then decide to change the size of the font or the text box. The method above would suck in these cases - you'd be stuck reworking all your strings every time something changed.

There really needs to be a way to just write the dialogue all in one piece, and let the game take care of the rest: deciding when to break lines, and cutting it into individual pages.

Well, let's see what we can do...

Making Pages

This time we'll give the TextBox object only a single string of dialogue. This will be the source text that the pages are made out of. Also, in order to make the pages contain the right amount of text, the TextBox object will need to know about its size.

Create Event (TextBox object):

//define the source text//(which can be from the calling object, or loaded from a text file, whatever)
DialogString = "...";//set dialog offset to 1. This is the position in the source text to start reading from.
DialogOffset = 1;//set dialog length to the length of the source text. This is the position in the source text to stop at.
DialogLength = string_length(DialogString);

Step Event (TextBox object):

//check for a press of the A buttonifJoyButtonPressed(A);
{//make the next page of text to showMakePage();
}

We call the MakePage() script every time the player presses the button, to construct the page of text that they'll see next. We also call it once in the create event, so that there's an initial page showing.

MakePage() basically bites off a chunk of the DialogString source text and puts it into a new string, CurrentPageString, which is the string that will be drawn.

script: MakePage()

//set up some temp variablesvar numLines,line,letter,word;
line = 0; word = "";//set the font to the current font so that the font measuring scripts work rightdraw_set_font(TextBoxFont);//empty the CurrentPageString, so we can refill it with text from DialogString
CurrentPageString = "";

//get the number of lines that fit in the box, based on line spacing and height of box
numLines = textheight div linespacing;//show error message if no lines fit in boxif numLines = 0
{show_error("No lines fit in the text box!",1);
}

//main loopdo
{//read a letter from the source text
letter = string_char_at(DialogString,DialogOffset);//increase the offset by one since you read one letter
DialogOffset += 1;//is the letter the escape char?if letter=="^"
{//change letter to return
letter = "#";//increase the line count to full
line = numLines;
}//add the letter to word
word += letter;//if the letter was a space, hyphen, or return (or the end of the source text was reached), the word is completeif letter==" "||letter=="#"||letter=="-"||DialogOffset>DialogLength
{//check to see if word alone exceeds the textbox widthifstring_width(word)>textwidth
{show_error("Single word is too long for the textbox!",1);
}//check to see if word added to current pages's text is too wideifstring_width(CurrentPageString+word)>textwidth
{//add a return to go to the next line, and increase the line count
CurrentPageString += "#";
line += 1;//if this was the last line...if line = numLines
{//return the offset to the beginning of the word in order for the next page to start at the right point
DialogOffset -= string_length(word);//blank out the word so it won't be added.
word = "";
}
}//only add the word if it hasn't been blanked outif word != ""
{//add the word to the current page's text
CurrentPageString += word;//if letter was a return, increase the line countif letter="#" line += 1;//and reset word to blank
word = "";
}
}
}until (line >= numLines or DialogOffset > DialogLength)//stop the loop when reach the last line or the end of the source text

With the comments, MakePage() should be pretty much self-explanatory, but there are two points I want to go into more detail on.

The first is the "escape character", ^. What is it for? Well, it's sort of like a page break. Sometimes you want the sentence of dialogue to end, and not start the next sentence until the player advances to the next page, even if there's enough space to fit the next few words. It all depends on the flow of the dialogue.

I used the caret because it's sufficiently obscure, but of course the escape character can be anything you want to define it as. If your RPG townsfolk are going to use emoticons like ^_^ then you might want to pick something else.

The second point is this: Why is the MakePage() script so complicated? Anyone familiar with GML will know that you can use a function called draw_text_ext(), which will automatically word wrap to any width that you specify. Why do I go through so much trouble to manually run through the string and add newline characters to cause it to wrap?

It becomes clear as we move on to the next aspect of text boxes. They have to type out.

Typing Out

In order to make them type out, we shouldn't draw CurrentPageString in the draw event. Instead, we should make a new string, ResultString, and draw it. ResultString will be built up from CurrentPageString in the step event of the TextBox object.

Draw Event (TextBox object):

Step Event (TextBox object):

//if the text box is typing out the textif printing
{//increase CharIndex
CharIndex += 1;//if CharIndex is the size of the page of textif CharIndex >= CurrentPageLength
{//fill the ResultString with the entire current page and stop typing out
CharIndex = CurrentPageLength;
ResultString = CurrentPageString;
printing = false;
}else
{//otherwise, make the ResultString as much of the current page as CharIndex is large
ResultString = string_copy(CurrentPageString,1,CharIndex);
}
}

We need the new variables, 'printing' so that we know when it's typing out and when it's done, 'CharIndex' to increase each step so we can keep taking more and more of CurrentPageString, and 'CurrentPageLength' so that we know when we've finished going through CurrentPageString. These three will need to be set up at the end of MakePage() now.

script: MakePage()

Now it'll print out. It's because of this that MakePage() needs to be so complex. If we relied on draw_text_ext() for word wrap, we'd get ugly results. Because we're actually drawing ResultString to the screen, and ResultString builds up letter by letter, the computer wouldn't know if a word was going to run off the side of the text box until after it had printed fully out. This would result in seeing words print out of bounds, and then skip on to the next line. MakePage() comes to the rescue here, determining where the lines should break before ever being printed, so that the words "know" to be on the next line before they even finish printing out.

Well, now that we've got our dialogue typing out, you'll notice a new problem. When the user presses the button, it'll skip to the next page. We don't want to do that, if the current page hasn't finished printing out. Instead, we want to instantly finish typing out the current page. Only if the user presses the button again should it advance one page.

This will require modifying the step event.

Step Event (TextBox object):

//if the text box is typing out the textif printing
{//increase CharIndex
CharIndex += 1;//if CharIndex is the size of the page of text OR the user presses the buttonif CharIndex >= CurrentPageLength orJoyButtonPressed(A)
{//fill the ResultString with the entire current page and stop typing out
CharIndex = CurrentPageLength;
ResultString = CurrentPageString;
printing = false;
}else
{//otherwise, make the ResultString as much of the current page as CharIndex is large
ResultString = string_copy(CurrentPageString,1,CharIndex);
}
}else
{//if it's not typing out, pressing the button should advance one pageifJoyButtonPressed(A)
{//but if we're on the last page, we should close the text boxif DialogOffset >= DialogLength
{instance_destroy();exit;
}//otherwise, determine the next page of text to type outMakePage();
}
}

What we've done is check for a press of the button while 'printing' is true, and made it do the same thing as reaching the end of the page: ResultString becomes CurrentPageString in total, and 'printing' is set to false. Also, we've made the standard check for the button only happen when 'printing' is not true.

I've also added a check at that point if it's the last page or not. If the player presses the button on the last page, there's no new page to advance to, so the text box should close instead of calling MakePage() again.

Now that it's all working, we should add some visual cue so that the player knows that the button does something different at different times. While the text is typing out, the button skips to the end. While it's not, the button advances one page. On the last page, the button closes the text box.

Most games don't bother with a different icon for each possible state. They just show a triangle or something once the text is done typing out, so that you know there's more. If it's the last page, the triangle simply doesn't appear when the text finishes appearing.

It's easy enough to check for all three states, though, so this is how you can do it - add this to the draw event:

Draw Event (TextBox object):

Variable Text Speed

That's pretty much it for text boxes. But there's some nice finishing touches we can add - variable text speed, for one. In the code blocks above, the text types out at 1 character per step. This speed should be under the player's control, because everybody reads at a different rate.

All that needs to be done is replace the line that says

Code:

CharIndex += 1;

and replace it with

Code:

CharIndex += textspeed;

The text speed can be set to 1 at the game start, and then the player can change it from an option menu. Or - and this is pretty cool - since the left and right buttons usually do nothing while a text box is open, you could let the player alter the text speed any time a box is open.

You can make the upper and lower limits anything that seems reasonable to you. However, the difference between settings isn't enough when they're linear. They need to be logarithmic. So, instead of adding to and subtracting from textspeed, I suggest you multiply and divide it (or bit shift it).

There should be lights or pips or something worked into the design of the text box, so that the player has a visual clue to the setting that the text speed is at.

Canceling

Finally, you can add this to the step event.

Step Event (TextBox object):

ifJoyButtonPressed(B)
{//close the text boxinstance_destroy();exit;
}

This lets the player hit a cancel button to close the text box whether the dialogue is finished or not. It's really annoying to accidentally re-talk to a character and be forced to page through their entire diatribe when you've already read it. You might want to add a check so that the player can only leave like this if they've talked to the person before, but I think the player ought to be able to cancel even if it's new dialogue. There might still be certain important story driven dialogue that they can't cancel, though.

Example GMK

If you use my code or scripts in your game or engine,
no credit is necessary. But I'd love to hear about your project if you
do! Just drop me a comment below, or e-mail me at
us.mercurysilver@gmail.com

The log2() function was just a quick and dirty way to convert the text speed limits I was using from 0.25 through 8 to 1 through 6, in order to display the little indicator arrows in the text box. You can remove those lines and set the indicator arrows in another way if you need.

However, my guess is that the error you are asking about is caused by the "textspeed" variable somehow becoming either 0 or a negative number. The log2() function will throw an error in those cases.

Have you edited any other events or scripts? The global "textspeed" variable is set to 1 in the Background object's Create Event. It has to be greater than 0 or the text will have no speed and not print out.

With those 15 lines commented out, pressing left should have no effect whatsoever because the program is not checking for it.

The code is really very straightforward. I don't know how to say this without it sounding rude, but if you are editing it knowledgeably there should not be this many errors. But perhaps you are using a newer version of Game Maker that is behaving unpredictably.