TGB Resource: Bitmap Fonts

Bitmap Font for Torque Game Builder

This resource is yet another goofy one, and many may find it 'useless' with the addition of the t2dTextObject in the latest 1.1.3 release of TGB. I created this resource because someone said they'd love to have this functionality, due to some limitations in the t2dTextObject (not sure what they were referring too).

This resource sounded like a fun thing to do, so I did it, and I'm giving it to the community to play around with, extend and use in there projects.

So, onto the resource, eh?

This resource takes a bitmap file, any image format supported by the engine, which contains a series of tiles (256 to be exact) of any set size -- the only requirement is that the image be 16x16 tiles --

Here's an example image:


This image, as you can see, contains a limited subset of characters (all your standard printable characters -- no extended ascii)

You'll also notice, this image contains TWO (2) fonts. Each font is different, the first font, for example is not case-sensitive so the letters 'A' and 'a' are both drawn as an 'A' -- this is a limitation of the font itself, not the resource.

The second font, is case-sensitive, and draws 'A' and 'a' appropriately.


These bitmap files were generated using a tool called 'Bitmap Font Builder v1.9.9' -- it's free for non-commercial use (has a nag screen too, but for quick one-off's is great). For commercial registration, they simply ask for a donation of some sort.

The application has a "Character Set" menu, and the image above used the "NeHe Two-Font Texture (32-159 x2)" option.

I saved the bitmap as a BMP file, using 255,0,255 as my background color, then opened it in Photoshop and used the Wand tool to select the Cyan background, told it to select all other pixels with similiar color and then removed them to make the image transparent. I then saved the image as a PNG and imported it into TGB as "Untitled2ImageMap".

The use of this resource is quite simple, you load the bitmapFont.cs in your project somewhere, preferably in a location that will be loaded when the project loads (in your game.cs -- outside of a function call?) so that the BitmapFontDataBlock datablock is accessible in the Level Builder.

Create a new TileLayer, assign it the "BitmapFontDataBlock" datablock, set your defaults, such as Tile Size, Location, etc.

If you want to have a general idea as to how much space will be consumed by your strings, you can set the Tile Count X/Y values and position the Tile Layer in your Level so that it draws in the appropriate location -- you can even fill the TileLayer with tiles to help with visualizing the level layout.

Once you've placed the object, jump into your favorite code editor, I prefer Torsion, and add your logic to fill the Tile Layer with "words".

The resource supports multi-line text, and so you can populate the tilelayer's character grid from a text file or user input from a multi-line textbox as well. The only requirement is that multi-line text contain "\n" as the line seperator (does not support passing in arrays/sim[sets/groups] of strings, yet).

Here's some example code;

function updateScore(%score)
{
	scoreObject.setText(%score);
}

Sorry, was that too simple? Here's something more complex:

function updateScoreAndPlayerInfo(%player, %score)
{
	scoreObject.setFont(0); // big fancy font for large numbers
	scoreObject.setText(%score);

	playerObject.setFont(1); // fancier script-like font
	playerObject.setText(%player.Name);

	echo("PLAYER NAME : " @ playerObject.getText());
	echo("PLAYER SCORE: " @ scoreObject.getText());
}

Ok, so I lied, it's not really more complex, just more repetitive.

That's it, there's a few functions exposed by the bitmapFont class, and all your default t2dTileLayer functions are also available.

The functions exposed by the bitmapFont class are as follows:

[b]Datablock[/b]
BitmapFontDataBlock -- Datablock that assigns Defaults

[b]Functions/Methods[/b]
setImageMap(%this, %imageMap);
getImageMap(%this);
setText(%this, %text, %font);
getText(%this);
setFont(%this, %font);
getFont(%this);
%save(%this, %file); // wrapper to saveTileLayer
sizeObjectToLayer(%this); // internal
getCharacterFrame(%this, %char, %offset); // internal

Here are some additional screenshots:


And last, but not least, here's the code for the bitmapFont class, and the BitmapFontDataBlock:

/*

ONE QUICK NOTE: It appears that there is a small bug, and I don't think it is in the script

Description:

When you call 'setText('Aa')' with a Case-Sensitive font selected, it performs the strcmp()'s
properly and you see 'Aa' drawn on the screen

If you then call 'setText('aA')', after calling 'setText('Aa')' you will see 'Aa' drawn to the 
screen -- this appears to be a logical flaw in the way the engine handles strings -- 

I have not dug around too much, but it appears as though the engine uses a String Table, and 
does not use case-sensitive matching to determine if a string is already in the table or not.

Unfortuneately, this is an issue I can not resolve through TorqueScript -- or at least, I do
not know how -- Hopefully either GG or someone else in the community can supply a Patch for this.

*/

// bitmapFont.cs
new t2dSceneObjectDatablock(BitmapFontDataBlock)
{
   // this defines the 'text' property
   text = "";
   // defines the class, so you can call "setText" and "getText"
   class="bitmapFont";
   characterMap = " !\"#$%&''()*+,-./0123456789:;<=>?@ABCDEFGHIJKLMNOPQRSTUVWXYZ[\]^_'abcdefghijklmnopqrstuvwxyz{|}~";
   font = 0;
   fontImageMap = Untitled2ImageMap;
};

function bitmapFont::setImageMap(%this, %imageMap)
{
   %this.fontImageMap = %imageMap;
}

function bitmapFont::getImageMap(%this)
{
   return %this.fontImageMap;
}

function bitmapFont::setText(%this, %text, %font) // %font is 0 or 1
{
   %this.text = %text;
   if(%font $= "") { %font = 0; } // default to first font
   else { %this.font = %font; }
   if(%this.isMemberOfClass("t2dTileLayer"))
   {
      //echo("Displaying Text");
      //echo("Layer File: " @ %this.layerFile);
      %this.clearLayer(); // clear all tiles
      
      if(strpos(%text, "\n") >= 0) %multiLine = true;
      else %multiLine = false;
     
      if(%multiLine)
      {
         %lines = new SimSet() { }; // holds all of our "lines"
         %prev = 0;
         %next = strpos(%text, "\n", %prev);
         while(%next >= 0)
         {
            //echo("Position: " @ %next);
            %line = new ScriptObject() { text = getSubStr(%text, %prev, %next - %prev); };
            %lines.add(%line);
            %prev = %next + 1;
            %next = strpos(%text, "\n", %next + 1);
         }
         if(strlen(%text) > %prev)
         {
            %line = new ScriptObject() { text = getSubStr(%text, %prev, strlen(%text) - %prev); };
            %lines.add(%line);
         }
         
         %this.setTileCountY(%lines.getCount());
         %lastx = 0;
         %y = 0;
         while(%lines.getCount() > 0)
         {
            %line = %lines.getObject(0);
            %linex = strlen(%line.text);
            if(%linex > %lastx) { %this.setTileCountX(%linex); %lastx = %linex; }
            
            for(%x = 0; %x < %linex; %x++)
            {
               // go char by char and place on tilelayer
               %frame = %this.getCharacterFrame(getSubStr(%line.text, %x, 1));
               if(%frame < 0) %frame = 0;
               %this.setStaticTile(%x, %y, %this.fontImageMap, %frame);
            }
            
            %lines.remove(%line);
            %line.delete();
            %y++;
         }
         %this.sizeObjectToLayer();
      }
      else
      {
         // handle a single line of text
         %chars = strlen(%text);
      
         %this.resizeLayer(%chars, 1); // set tile count
         %this.sizeObjectToLayer(); // fit object to tiles
         for(%x = 0; %x < %chars; %x++)
         {
            // go char by char and place on tilelayer
            %frame = %this.getCharacterFrame(getSubStr(%text, %x, 1));
            if(%frame < 0) %frame = 0;
            %this.setStaticTile(%x, 0, %this.fontImageMap, %frame);
         }
      }
   }
   else
   {
      error("The object is not a member of the t2dTileLayer Class");
      error("-- bitmapFont only works with t2dTileLayers");
   }
}

function bitmapFont::setFont(%this, %font)
{
   if(%font $= "") return;
   if(%font > 1 || %font < 0) { error("bitmapFont only accepts 0 and 1 for 'font'"); return; }
   %this.font = %font;
}

function bitmapFont::getFont(%this)
{
   return %this.font;
}

function bitmapFont::getText(%this)
{
   return %this.text;
}

function bitmapFont::save(%this, %file)
{
   if(%this.isMemberOfClass("t2dTileLayer"))
   {
      %this.saveTileLayer(%file);
   }
}

function bitmapFont::sizeObjectToLayer(%this)
{
   if(!%this.isMemberOfClass("t2dTileLayer")) return;
   // this was snagged from the TileLayerEditor code
   %xSize = %this.getTileCountX() * %this.getTileSizeX();
   %ySize = %this.getTileCountY() * %this.getTileSizeY();
   
   %upperLeft = %this.getAreaMin();
   %lowerRight = t2dVectorAdd( %upperLeft, %xSize SPC %ySize );
   
   %this.setArea( %upperLeft, %lowerRight );
   %this.setPosition( %this.getPosition() );
}

function bitmapFont::getCharacterFrame(%this, %char, %offset)
{
   // character frames map directly to the charactermap string
   //error("CHAR: " @ %char @ " --- OFFSET: " @ %offset);
   if(%offset $= "") %offset = 0;
   %frame = strpos(%this.characterMap, %char, %offset);
   %chr = getSubStr(%this.characterMap, %frame, 1);
   if(strcmp(%chr, %char) != 0)
   {
      // we grabbed the wrong case
      return %this.getCharacterFrame(%char, %frame+1);
   }
   if(%frame < 0)
   {
      error("FRAME  : " @ %frame);
      error("CHAR   : " @ %char);
      error("OFFSET : " @ %offset);
   }
   return (%frame - 1) + (%this.font * 128);
}

Simply copy the code, and save it as bitmapFont.cs somewhere in your project directory, and exec() it from whereever seems most appropriate to you.

Please note the 'disclaimer' in the code header about the case-sensitivity matching when passing strings you've used in the past with different case's --