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
fontStyle	String	style of font. Options: 'normal', 'italic', 'oblique'. (default: 'normal')
fontWeight	String	weight of font. Options: 'normal', 'bold', 'bolder', 'lighter'. (default: 'normal')
fontSize	Number	size of font, in pixels. (default: 16)
fontFamily	String	name of font. (default: 'Arial')
lineHeight	Number	vertical height of font. (default: fontSize)
fill	String/Hex	fill color of font. Can be a web font name or hex value. (default: 'black')
align	String	horizontal alignment of font. Options: 'left', 'center', 'right'. (default: 'left')
stroke	String/Hex	stroke color of font. Can be a web font name or hex value. (default: 'black')
strokeThickness	Number	stroke thickness of font. (default: 0)
wordWrap	Boolean	if set to TRUE, text will wrap within bounds. (default: TRUE)
wordWrapWidth	Number	width of font bounds. (default: GAME.width)
dropShadow	Boolean	if set to TRUE, will display a shadow. (default: FALSE)
dropShadowColor	String/Hex	drop shadow color of font. (default: '#000000')
dropShadowAngle	String	drop 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)
dropShadowDistance	Number	drop shadow distance of font, in pixels. (default: 2)
gradient	Object	see Gradient Properties table.

Gradient Properties

Name	Type	Description
* gradient.colors	Object	an 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.x0	Number	starting x coordinate, with 0 being top left and 1 being top right. (default: 0)
gradient.coords.y0	Number	starting y coordinate, with 0 being top left and 1 being top right. (default: 0)
gradient.coords.x1	Number	ending x coordinate, with 0 being top left and 1 being top right. (default: 1)
gradient.coords.y1	Number	ending y coordinate, with 0 being top left and 1 being top right. (default: 1)

Methods (static)

Name	Parameter	Type	Description
asset	initializes 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.name	String	name of asset.
	options.isBitmapFont	Boolean	if set to TRUE, bitmap text rendering is used.
create	creates an entity object to be used for instantiating in Rooms.
	* assetName	String	existing asset name.
	options.name	String	name of new entity. This is optional; if none provided, defaults to assetName.
	options.style	Object	see Style Properties table.
	options.???	Mixed	see Core > Entity : Properties for available properties.
createChild	creates a child entity object to be used for instantiating in Rooms.
	* entityName	String	name of an existing entity to clone.
	options.style	Object	see Style Properties table.
	options.???	Mixed	see Core > Entity : Properties for available properties.
add	instantiates an entity object into the current Room.
	* entityName	String	name of existing entity reference to instantiate.
	* options.x	Number	x coordinate to place in game.
	* options.y	Number	y coordinate to place in game.
	options.style	Object	see Style Properties table.
	options.???	Mixed	see Core > Entity : Properties for available properties.

Properties (object)

See Core > Entity : Properties for available properties.

Methods (object)

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

Events (object)

See Core > Entity : Events for available events.