Classes

Text

Games require all sorts of text to display things like menus, dialogs, score, lives, etc.. JackyJS supports three kinds of text: system fonts, web fonts, and bitmap fonts.

System Fonts

If using this type of font in your games, be sure to check the following list first to make sure your text appear correctly for everyone: Common Fonts for Windows and Mac. This type of font is good for things like scores, counters, lists, and other simple elements that don't necessarily require a lot of flare.

Web Fonts

This type of font has become more popular in the web design world because of their ease of use and universality. No licenses, free-to-use, simple javascript include. JackyJS makes using this type of font super simple; ie, there is nothing extra you need to do besides adding the necessary Google javascript in the <head>. Check out Google's Web Fonts. The following example shows you how to add Google Web Fonts to your game:


	<head>
		<script>
			WebFontConfig = {
				google: {
					families: [ 'Press Start 2P', 'Varela Round' ]
				}
			};
			(function() {
				var wf = document.createElement('script');
				wf.src = ('https:' === document.location.protocol ? 'https' : 'http') +
					'://ajax.googleapis.com/ajax/libs/webfont/1/webfont.js';
				wf.type = 'text/javascript';
				wf.async = 'true';
				var s = document.getElementsByTagName('script')[0];
				s.parentNode.insertBefore(wf, s);
			  })();
		</script>
	</head>		

Bitmap Fonts

This type of font is great for when you need more control over the details of your text. For example, you can't always rely on consistent rendering of borders and shadows across different computers and devices. Using a bitmap font creator like bmGlyph (Mac), for instance, ensures that your font design looks the same for every user because the application generates a graphic of the glyphs, which, in turn, is used by an auto-generated XML file to render the glyphs to screen.

TIP: when publishing a font using bmGlyph for Mac, please ensure that the export Format dropdown is set to 'Sparrow/Starling'. This setting generates JackyJS compatible XML code in the .fnt file.

Graphic Fonts

If your game needs some elaborate text with very fancy details and you want to ensure it looks exactly the same everywhere, then your only option is to create a graphic and load it as a Sprite asset.

In order to instantiate Text entities in your game, you first have to preload the relevant files, create the assets, and create the entity objects. The following example shows you how:


	GAME.initPreload(function(){
		GAME.Preloader.fonts.push('jackyjs/assets/fonts/myBitmapFont.xml');
	});
	
	GAME.initAssets(function(){
		// system font
		GAME.Text.asset({
			name:'title',
			style: {
				fill: 'black',
				fontFamily: 'Arial',
				fontSize: 30
			}
		});
		
		// web font
		GAME.Text.asset({
			name:'start',
			style: {
				fill: '#ffff00',
				fontFamily:'Varela Round',
				fontSize: 20
			}
		});

		// bitmap font
		GAME.Text.asset({
			name: 'paragraph',
			style: {
				fontName: 'yourBitmapFontName',
				fontSize: 16
			}
			isBitmapFont: true
		});
	});
	
	GAME.initInterface(function(){
		var title = GAME.Text.create('title', {name: 'title', content: 'Welcome to jackyJS!'});
		var start = GAME.Text.create('start', {name: 'start', content: 'PRESS\nSTART'});
		var paragraph = GAME.Text.create('paragraph', {name: 'start', content: 'lorem ipsum dolor sit amet...'});
	});
	
	GAME.initRooms(function(){
		var Intro = GAME.Room.create({name:'Intro'});
		
		Intro.onCreate(function(obj){
			obj.addText('title', {x:GAME.width/2, y:GAME.height/2});
		});
	});

The best thing about Text entities in JackyJS is that they are first class objects! This means they can rotate, fade, scale, collide, respond to input, become draggable, etc... pretty much everything a Sprite can do. Text entities also support the inheritance model, where child text objects can inherit properties, events, and behaviours from their parents. See the Core > Entity section for more information.

Style Properties

Name Type Description
fontStyleStringstyle of font. Options: 'normal', 'italic', 'oblique'. (default: 'normal')
fontWeightStringweight of font. Options: 'normal', 'bold', 'bolder', 'lighter'. (default: 'normal')
fontSizeNumbersize of font, in pixels. (default: 16)
fontFamilyStringname of font. (default: 'Arial')
lineHeightNumbervertical height of font. (default: fontSize)
fillString/Hexfill color of font. Can be a web font name or hex value. (default: 'black')
alignStringhorizontal alignment of font. Options: 'left', 'center', 'right'. (default: 'left')
strokeString/Hexstroke color of font. Can be a web font name or hex value. (default: 'black')
strokeThicknessNumberstroke thickness of font. (default: 0)
wordWrapBooleanif set to TRUE, text will wrap within bounds. (default: TRUE)
wordWrapWidthNumberwidth of font bounds. (default: GAME.width)
dropShadowBooleanif set to TRUE, will display a shadow. (default: FALSE)
dropShadowColorString/Hexdrop shadow color of font. (default: '#000000')
dropShadowAngleStringdrop shadow angle of font. Angle is between 0 and 360, with 0 being right, 90 being up, 180 being left, and 270 being down. (default: 270)
dropShadowDistanceNumberdrop shadow distance of font, in pixels. (default: 2)
gradientObjectsee Gradient Properties table.

Gradient Properties

Name Type Description
* gradient.colorsObjectan array of color objects, with two properties:
- color: '#ff0000'
- stop: 0
Stop 0 means at the top, while stop 1 means at the bottom.
gradient.coords.x0Numberstarting x coordinate, with 0 being top left and 1 being top right. (default: 0)
gradient.coords.y0Numberstarting y coordinate, with 0 being top left and 1 being top right. (default: 0)
gradient.coords.x1Numberending x coordinate, with 0 being top left and 1 being top right. (default: 1)
gradient.coords.y1Numberending y coordinate, with 0 being top left and 1 being top right. (default: 1)

Methods (static)

Name Parameter Type Description
assetinitializes a resource asset to be used as a reference in the creation of entities. Its only parameter is an options object literal with the following required properties. When using bitmap fonts (isBitmapFont = TRUE), style options like shadow, stroke, and fill have no effect.
* options.nameStringname of asset.
options.isBitmapFontBooleanif set to TRUE, bitmap text rendering is used.
createcreates an entity object to be used for instantiating in Rooms.
* assetNameStringexisting asset name.
options.nameStringname of new entity. This is optional; if none provided, defaults to assetName.
options.styleObjectsee Style Properties table.
options.???Mixedsee Core > Entity : Properties for available properties.
createChildcreates a child entity object to be used for instantiating in Rooms.
* entityNameStringname of an existing entity to clone.
options.styleObjectsee Style Properties table.
options.???Mixedsee Core > Entity : Properties for available properties.
addinstantiates an entity object into the current Room.
* entityNameStringname of existing entity reference to instantiate.
* options.xNumberx coordinate to place in game.
* options.yNumbery coordinate to place in game.
options.styleObjectsee Style Properties table.
options.???Mixedsee Core > Entity : Properties for available properties.

Properties (object)

See Core > Entity : Properties for available properties.

Methods (object)

Name Parameter Type Description
setTextsets the text content and/or style to something else.
* contentStringnew content to update. NOTE: you can use "\n" for new lines.
styleObjectnew style to update. See the Style Properties table.

Events (object)

See Core > Entity : Events for available events.