Textblox.lua

This page is still under construction!

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

Installation

textblox comes packaged with cinematX v0.8+ and can be downloaded from the cinematX github repo. Textblox is installed as part of the cinematX suite; to install it manually, download the textblox.lua, graphX.lua, inputs.lua and rng.lua files and the textblox folder from the repository into your LuaScriptsLib folder.

Setup

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

local textblox = loadAPI("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 = loadAPI("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})

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 = loadAPI("textblox");

-- 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
textblox.printExt ("Heyoooooooooooo", {x=-200000,y=-200100, bind=textblox.BIND_LEVEL, halign=textblox.HALIGN_MID, valign=textblox.VALIGN_MID})

Text Blocks

Text Blocks are, as their name suggests, objects that store blocks of text. Unlike the print functions, Text Blocks gradually reveal their text through a typewriter effect.

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

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.

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.

Name	Description
<br>	Inserts a line break.
<lt>	Inserts a less than (<) character.
<gt>	Inserts a greater than (>) character.
<butt>	Inserts "rockythechao".
<tremble>text</tremble>	Makes the enclosed text shake.
<wave>text</wave>	Makes the enclosed text wave.

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.