One of the most striking characteristics of classic JRPGS is the use of text boxes for conversations, where the characters appear one by one and the player can advance to the next page when the current one is finished.

The best RPG ever!

In this post we’ll implement a generic text box component based on the CCLayerColor class, which you can then further customize as needed. It only supports bitmap fonts (CCLabelBMFont) for now, so each character can be manipulated individually. The component supports touching it to display the whole page at once, as well as to advance pages. You can also implement the TextBoxDelegate protocol to receive notifications when the page changes or the text reaches the end. I’ll assume the reader is familiar with the cocos2d framework and the Objective-C language. If you want to get the sample project and code right away, skip to the end of the post.

The TextBoxLayer class

First, we’ll define the interface of the TextBoxLayer class as follows:

#define TEXT_SPEED 60
#define TEXT_FONT_FILE @"arial16.fnt"

@class TextBoxLayer;

@protocol TextBoxDelegate
- (void)textBox:(TextBoxLayer *)tbox
	didFinishAllTextWithPageCount:(int)pc;
@optional
- (void)textBox:(TextBoxLayer *)tbox didMoveToPage:(int)p;
@end

@interface TextBoxLayer : CCLayerColor {
	CCLabelBMFont *textLabel;
	NSString *text;
	NSMutableArray *lines;
	float progress;
	int linesPerPage;
	int currentPageIndex;
	NSMutableString *currentPage;
	int currentPageCharCount;
	int totalPages;
	id delegate;
	BOOL ended;
}
@property (readwrite,retain) id delegate;
- (id) initWithColor:(ccColor4B)color
			   width:(GLfloat)w
			  height:(GLfloat)h
			 padding:(GLfloat)padding
				text:(NSString *)txt;
- (void)update:(float)dt;
- (NSString *)nextPage;
- (int)calculateStringSize:(NSString *)txt;
@end

We create a TextBoxDelegate protocol, so your code can be notified when the page changes or the text reaches the end. You can then respond by hiding the text box or doing any other custom action specific to your game. The constants TEXT_SPEED and TEXT_FONT_FILE define the speed of text advance and the default font file. The initWithColor... method is pretty straight-forward, as it takes a color, the dimensions of the box, internal padding (which will also be added to the dimensions of the box) and the full text to display (without line-breaks). The update method should be called every frame, and will update the text according to the time elapsed since the last frame. The nextPage and calculateStringSize are used internally and will be detailed later.

Calculating the line breaks

In order to wrap the text correctly, we’ll need to insert line-breaks when the current line no longer fits horizontally in the box. To make this easier, we’ll create the calculateStringSize helper method, which takes a NSString as an argument and returns the string width based on the default font.

- (int)calculateStringSize:(NSString *)txt {
	CCBMFontConfiguration *conf = FNTConfigLoadFile(TEXT_FONT_FILE);
	int totalSize = 0;
	for (int i = 0; i < [txt length]; i++) {
		int c = [txt characterAtIndex:i];
		ccBMFontDef def = conf->BMFontArray_[c];
		totalSize += def.xAdvance;
	}
	return totalSize;
}

We then use this method during class initialization to implement an algorithm that will split the text into lines and places them into an array. The code also calculates some values we’ll use later such as the number of lines per page and the number of pages needed.

CCBMFontConfiguration *conf = FNTConfigLoadFile(TEXT_FONT_FILE);
linesPerPage = h / conf->commonHeight_;

NSArray *words = [txt componentsSeparatedByString:@" "];
NSMutableString *wrappedText = [NSMutableString string];
lines = [[NSMutableArray alloc] init];

for (NSString *word in words) {
	NSString *eval = [wrappedText stringByAppendingFormat:@" %@", word];
	int size = [self calculateStringSize:eval];

	// See if the text so far plus the new word fits the rect
	if (size > w) {
		// If not, closes this line and starts a new one
		[lines addObject:[NSString stringWithString:wrappedText]];
		[wrappedText setString:word];
	} else {
		[wrappedText appendFormat:@" %@", word];
	}
}
[lines addObject:[NSString stringWithString:wrappedText]];
totalPages = ceil((float)[lines count] / linesPerPage);

Finally, we obtain the first page of text and assign it to the CCLabelBMFont object. We then iterate through all its children (each character in the string is represented by a CCSprite) and hide each of them by setting its opacity to 0.

textLabel = [CCLabelBMFont labelWithString:[self nextPage] fntFile:TEXT_FONT_FILE];
textLabel.anchorPoint = ccp(0,1);
textLabel.position = ccp(padding, h + padding);

// Hides all characters in the label
for (CCNode *node in textLabel.children) {
	CCSprite *charSpr = (CCSprite *)node;
	charSpr.opacity = 0;
}

The code above uses the nextPage method to take the lines and assemble them into a page.

- (NSString *)nextPage {
	progress = 0;

	[currentPage release];
	currentPage = [[NSMutableString string] retain];

	currentPageCharCount = 0;

	int line = currentPageIndex * linesPerPage;

	int i = 0;
	while (i < linesPerPage && line < [lines count]) {
		[currentPage appendFormat:@"%@\n", [lines objectAtIndex:line]];
		currentPageCharCount += [[lines objectAtIndex:line] length];
		i++;
		line++;
	}
	currentPageIndex++;

	return currentPage;
}

Updating the text

The rest of the magic happens in the update method. It will calculate which characters should be displayed and set their opacity to 255.

- (void)update:(float)dt {

	progress += (dt * TEXT_SPEED);

	int visible = progress;

	if (visible > currentPageCharCount) {
		progress = visible = currentPageCharCount;
	}

	// Each character sprite is assigned a tag corresponding to its index in the string,
	// and even though line-breaks are skipped, they are still counted for tag purposes.
	// Therefore, we use an offset so that the tag is correct.
	int offset = 0;

	for (int i = 0; i < visible; i++) {

		if ([currentPage characterAtIndex:i + offset] == '\n') {
			offset++;
		}

		CCSprite *charSpr = (CCSprite *) [textLabel getChildByTag:i + offset];
		charSpr.opacity = 255;
	}
}

We'll also need a way for the player to skip the text animation as well as advance to the next pages. We do that using the ccTouchesEnded event, which will also call the delegate methods as appropriate. Please note that in our game the text box is modal, therefore a tap anywhere on the screen will be considered. It should be easy to restrict this to taps within the text box by checking if the touch is contained in the text box rectangle.

-(void) ccTouchesEnded:(NSSet *)touches withEvent:(UIEvent *)event {

	if (progress < currentPageCharCount) {

		for (CCNode *node in textLabel.children) {
			CCSprite *charSpr = (CCSprite *)node;
			charSpr.opacity = 255;
		}
		progress = currentPageCharCount;

	} else {

		if (currentPageIndex < totalPages) {
			[textLabel setString:[self nextPage]];

			for (CCNode *node in textLabel.children) {
				CCSprite *charSpr = (CCSprite *)node;
				charSpr.opacity = 0;
			}

			if ([delegate respondsToSelector:@selector(textBox:didMoveToPage:)]) {
				[delegate textBox:self didMoveToPage:currentPageIndex];
			}

		} else {

			if (!ended) {
				ended = YES;

				if ([delegate respondsToSelector:@selector(textBox:didFinishAllTextWithPageCount:)]) {
					[delegate textBox:self didFinishAllTextWithPageCount:totalPages];
				}
			}
		}
	}
}

That's it!

EDIT: the code is now available on GitHub

And our text box is done! To download the sample project containing the full source code, click here.