Textblox.lua

DEPRECATED: Replaced by Textplus

textblox is a custom text and message box framework for LunaLua.

Installation

The latest version of this API is included in SMBX2.

Setup

To enable the textblox library for a specific level, add this line to lunadll.lua:

local textblox = API.load("textblox");

This will load the textblox API.

Fonts

A core element of textblox is the Font class, which allows users to create custom fonts for use with the library. Font objects can reference either one of SMBX's built-in fonts or a custom monospaced spritefont.

To create your own Font, call textblox.Font (fonttype, properties). The first argument is the font type constant (textblox.FONTTYPE_DEFAULT or textblox.FONTTYPE_SPRITE); if DEFAULT is used for the first argument, the second argument is SMBX font number, but if SPRITE is used for the first argument, the second is a table of named arguments.

Name	Type	Is Optional?	Default Value	Description
image	LuaImageResource	no	nil	The spritefont image used; must be an 16x8 grid of any-size characters.
imagePath	string	yes	nil	The file path of the spritefont image used relative to the level resource folder; this argument can be used in place of image.
charWidth	number	yes	16	The width in pixels of each character in the font.
charHeight	number	yes	16	The height in pixels of each character.
kerning	number	yes	1	The horizontal spacing between fonts in pixels.

Example code:

local textblox = API.load("textblox");

-- SMBX font
local newFont1 = textblox.Font (textblox.FONTTYPE_DEFAULT, 4)

-- Using imagePath to load the image at font creation
local newFont2 = textblox.Font (textblox.FONTTYPE_SPRITE, {imagePath="customFont1.png", charWidth=20,charHeight=8})

-- Pre-loading images and using the "image" argument
local font3Image = Graphics.loadImage ("customFont3.png")
local newFont3 = textblox.Font (textblox.FONTTYPE_SPRITE, {image=font3Image, kerning=-1})

textblox comes with various premade fonts which are stored in textblox.defaultSpritefont[i][k], where i is the font and k is the variation.

Displaying text

Once you've selected or created your font of choice, you can display text using the font via the function textblox.printExt (text, properties). The first argument is the text string, the second is a table of named arguments.

Name	Type	Is Optional?	Default Value	Description
x	number	yes	400	The x coordinate the text is printed at.
y	number	yes	300	The y coordinate the text is printed at.
bind	constant	yes	textblox.BIND_SCREEN	If set to textblox.BIND_SCREEN, the text will be printed to screen coordinates; If set to textblox.BIND_LEVEL, the text will be printed to level coordinates.
halign	constant	yes	textblox.HALIGN_LEFT	The horizontal alignment of the printed text; can be set to textblox.HALIGN_LEFT, textblox.HALIGN_MID or textblox.HALIGN_RIGHT.
valign	constant	yes	textblox.VALIGN_TOP	The vertical alignment of the printed text; can be set to textblox.VALIGN_TOP, textblox.VALIGN_MID or textblox.VALIGN_BOTTOM.
opacity	number	yes	1.00	The alpha transparency of the text; must be a number from 0 (invisible) to 1 (opaque).
font	number	yes	textblox.FONT_DEFAULT	The Font the text is displayed in.
width	number	yes	math.huge	The max width of the line in pixels before it wraps.

Example code:

local textblox = API.load("textblox");

function onTick()
    -- Print "Testing!" at the top of the screen
    textblox.printExt ("Testing!", {x=400,y=150, halign=textblox.HALIGN_MID, valign=textblox.VALIGN_MID})

    -- Print "Heyoooooooooooo" at -200k,-200.1k in the level with the third default font
    textblox.printExt ("Heyoooooooooooo", {x=-200000,y=-200100, font=textblox.defaultSpritefont[3][2], bind=textblox.BIND_LEVEL, halign=textblox.HALIGN_MID, valign=textblox.VALIGN_MID})
end

Results:

Of note, textblox.printExt () returns the following four values: the total width in pixels, total height, number of line breaks and finally a table containing the width of each line. While these can be used to help with positioning in menus, special effects or even custom message boxes, the Text Block class is generally recommended for more complex needs as it contains all the functionality of printed text and more.

Text Blocks

Text Blocks are, as their name suggests, objects that store blocks of text. Unlike the print function, Text Blocks are instantiated once and continue to exist until they are either closed by the user or close themselves (if they're configured to do so). Text Blocks have their own window graphics and gradually reveal their text through a typewriter effect, so they can serve as useful message boxes for dialogue or player notifications.

Text Blocks are created with textblox.Block (x,y, textStr, properties).

Name	Type	Is Optional?	Default Value	Description
font	textblox Font	yes	textblox.FONT_DEFAULT	The font the Text Block uses to display its' text.
pauseGame	boolean	yes	false	If true, the Text Block will freeze the game upon being created and unfreeze it after closing.
visible	boolean	yes	true	The Text Block will not display if this value is false.
z	number	yes	2	The draw depth (v0.3+)
boxType	constant	yes	textblox.BOXTYPE_MENU	Sets the Text Block's default appearance based on several built-in templates (v0.3+).
boxTex	LuaImageResource	yes	n/a	The texture used by the Text Block's background; if not specified, this value will default to the corresponding texture of the box type.
boxColor	number	yes	0x00AA0099	The color of the Text Block's box.
borderTable	property table	yes	{thick=8}, other properties based on the box type	The images and additional properties used for the Text Block's border: ulImage, uImg, urImage, rImage, drImage, dImage and so on set the images for the upper-left corner and the following edges and corners clockwise, thick sets the thickness (default 8) and col sets the color (default 0xFF9900FF). If not specified, this value will default to the corresponding texture table of the box type.
scaleMode	constant	yes	textblox.SCALE_FIXED	The scale mode of the Text Block. If set to textblox.SCALE_FIXED, the block will display at a fixed width and height (defined by the corresponding properties.) If set to textblox.SCALE_AUTO, the size of the block will be calculated based on the text.
width	number	yes	200	The width of the Text Block when scaleMode is set to textblox.SCALE_FIXED.
height	number	yes	200	The height of the Text Block when scaleMode is set to textblox.SCALE_FIXED.
bind	constant	yes	textblox.BIND_LEVEL	If set to textblox.BIND_SCREEN, the Text Block will be displayed at screen coordinates; If set to textblox.BIND_LEVEL, the block will be displayed at level coordinates.
boxAnchorX	constant	yes	textblox.HALIGN_LEFT	The horizontal alignment of the Text Block; can be set to textblox.HALIGN_LEFT, textblox.HALIGN_MID or textblox.HALIGN_RIGHT.
boxAnchorY	constant	yes	textblox.VALIGN_TOP	The vertical alignment of the Text Block; can be set to textblox.VALIGN_TOP, textblox.VALIGN_MID or textblox.VALIGN_BOTTOM.
textAnchorX	constant	yes	textblox.HALIGN_LEFT	The horizontal alignment of the text inside the Text Block; can be set to textblox.HALIGN_LEFT, textblox.HALIGN_MID or textblox.HALIGN_RIGHT.
textAnchorY	constant	yes	textblox.HALIGN_TOP	The vertical alignment of the text inside the Text Block; can be set to textblox.VALIGN_TOP, textblox.VALIGN_MID or textblox.VALIGN_BOTTOM.
marginX	number	yes	4	The horizontal spacing between the text and border.
marginY	number	yes	4	The vertical spacing between the text and border.
textAlpha	number	yes	1	The alpha transparency of the text; must be a number from 0 (invisible) to 1 (opaque).
autoClose	boolean	yes	false	If set to true, the Text Block will close itself after the text is fully revealed.
inputClose	boolean	yes	false	If true, the Text Block can be closed by pressing the jump, run or alt run key. If false, the Block must be closed with the function Block:closeSelf ()
speed	number	yes	0.5	The speed at which the Text Block reveals its' text through the typewriter effect (specifically, the number of letters revealed each frame).
autoTime	boolean	yes	false	If true, the Text Block will automatically add pause commands after punctuation.
endMarkDelay	number	yes	8	The number of frames the Text Block will pause after end-of-sentence punctuation (such as periods, semicolons, question marks and exclamation marks) when autoTime is set to true.
midMarkDelay	number	yes	4	The number of frames the Text Block will pause after mid-sentence punctuation (such as commas) when autoTime is set to true.
finishDelay	number	yes	10	The number of frames the Text Block will pause after revealing all of its' text (and before closing if autoClose is true).
typeSounds	table of string	yes	empty table	If a table of filenames for sound files is specified, the Text Block will shuffle through the sounds and play them as it reveals its' text; the frequency of the sounds is based on the length of the audio (the Text Block will not play a new sound until the current one is finished).
startSound	string	yes	""	If a valid filename for a sound file is specified, the Text Block will play the sound upon being created.
finishSound	string	yes	""	If a valid filename for a sound file is specified, the Text Block will play the sound after it finishes displaying its' text.
closeSound	string	yes	""	If a valid filename for a sound file is specified, the Text Block will play the sound when it closes.

Example code:

local textblox = API.load("textblox");

-- Create a basic Text Block at the center of the screen with all the default properties
local block1 = textblox.Block (400,300, "Hello there.", {})

-- Create an auto-timed, auto-scaled Text Block at -200k,-200.1k in the level...
local block2 = textblox.Block (400,300, "Testing, testing, 1... 2... 3... testing!  I am moving!  I repeat, I am moving!  This is not a drill!  Somebody, anybody, please help me!  I can't find the brakes!", {scaleMode=textblox.SCALE_AUTO, bind=textblox.BIND_LEVEL, autoTime=true, speed=0.75})

-- ...And make it move to the right!
function onLoop ()
    if block2 ~= nil  then
        block2.x = block2.x + 2
    end
end

Additional Functions

The following functions can be used to further control Text Blocks:

textblox Text Block functions
Type	Function/Field	Return values/Value type	Description
function	Block:finish ()	nil	Completes the typewriter effect of the Block and ends effects such as shaking.
function	Block:isFinished ()	boolean	Returns whether the Text Block's typewriter effect is finished or not.
function	Block:closeSelf ()	nil	Closes the Text Block.
function	Block:setText (string textStr)	nil	Changes the Block's text.
function	Block:resetText (string textStr)	nil	Changes the Block's text and restarts the typewriter effect.
function	Block:getCharsPerLine ()	number	Returns the max number of characters per line for the Block's text.
function	Block:getTextWrapped (boolean addSlashN)	string	Returns the Block's text string formatted for wrapping based on the Block's size.
function	Block:getLength ()	string	Returns the length of the Block's text string returned by :getTextWrapped().
function	Block:getLengthFiltered ()	string	Returns the length of the Block's text string after filtering out the commands.
function	Block:playTypeSound ()	nil	Plays one of the type sounds defined by the typeSounds property.

Commands

textblox uses a markup language similar to HTML for special in-text commands. The following commands can be used to insert special characters and control the appearance of text.

IMPORTANT: <gt> and <lt> must be used for displaying the corresponding symbols. Trying to use the symbols themselves will break the command processing for that string.

Name	Description
<br>	Inserts a line break.
<lt>	Inserts a less than (<) character.
<gt>	Inserts a greater than (>) character.
<butt>	Inserts "rockythechao".
<tremble> <tremble #> (v0.4.6+)	Makes text shake; higher numbers give more intense shaking. </tremble> or <tremble 0> to cancel the effect.
<wave> <wave #>	Makes text move in a sine wave; higher numbers give higher waving. </wave> or <wave 0> to cancel the effect.
<color 0xRRGGBBAA> (v0.4.6+) <color presetname> (v0.4.6b)	Tints text the given color. The following presets can be used: white, ltgray, gray, dkgray, black, red, blue, yellow, green, purple, default (resets to the initial color of the text)

These commands are for triggering effects and controlling the timing of Text Blocks:

Name	Description
<pause #>	Pauses the text for # frames; if # is "mid" or "end", uses the number of frames specified in the midMarkDelay and endMarkDelay properties, respectively.
<shake #>	If # is "screen", shakes the screen; if # is "box", shakes the Text Block.
<speed #>	Changes the typewriter speed of the Text Block.
<sound #>	Plays the sound effect from the filename #.
<notiming>text</notiming>	Enclosed text will be ignored for autotiming if the Text Block's autoTime property is true.

Overriding SMBX messages

textblox is capable of overriding the built-in SMBX message box. When textblox.overrideMessageBox is set to true, all SMBX message boxes are replaced with Text Block objects using the table of named arguments stored in textblox.overrideProps. By changing the properties stored in textblox.overrideProps, you can thus customize the SMBX message box.