Core

Game

The global GAME object is essentially the guts of JackyJS. It is responsible for handling the game loop, checking for events, and rendering output. It's also host to a bunch of constants, variables, events, and useful functions to make developing web games much easier.

TIP: Pay special attention to the Inits table, as that's where all your awesome code goes. :-)

Global Constants

The following are global constants accessed through GAME.cons, which cannot (should not) be changed:


	cons: {
		BLEND: {
			NORMAL: PIXI.blendModes.NORMAL,
			ADD: PIXI.blendModes.ADD,
			MULTIPLY: PIXI.blendModes.MULTIPLY,
			SCREEN: PIXI.blendModes.SCREEN,
			OVERLAY: PIXI.blendModes.OVERLAY,
			DARKEN: PIXI.blendModes.DARKEN,
			LIGHTEN: PIXI.blendModes.LIGHTEN,
			COLOR_DODGE: PIXI.blendModes.COLOR_DODGE,
			COLOR_BURN: PIXI.blendModes.COLOR_BURN,
			HARD_LIGHT: PIXI.blendModes.HARD_LIGHT,
			SOFT_LIGHT: PIXI.blendModes.SOFT_LIGHT,
			DIFFERENCE: PIXI.blendModes.DIFFERENCE,
			EXCLUSION: PIXI.blendModes.EXCLUSION,
			HUE: PIXI.blendModes.HUE,
			SATURATION: PIXI.blendModes.SATURATION,
			COLOR: PIXI.blendModes.COLOR,
			LUMINOSITY: PIXI.blendModes.LUMINOSITY
		},

		DIRECTION: {
			RIGHT: 0,
			UP: 90,
			LEFT: 180,
			DOWN: 270
		}
	}

Global Variables

The following are global variables accessed through GAME.vars, which can be changed at any time:


	vars: {
		SCREEN_X: 0,
		SCREEN_Y: 0,
		GRAVITY: 0.5,
		GRAVITY_DIRECTION: 270,
		SPEED_MAX: 12,
		FRICTION: 0.15,
		PARTICLE_LIMIT: 100
	}

Global Custom

The following is where your custom global constants, variables, and functions should be placed. It is accessed through GAME.custom and initialized in the GAME.initCustom() function. Placing constants, variables, and functions here allows you to access them from anywhere in your game code, without worrying about polluting the global window object scope.


	custom {
		cons: {},
		vars: {},
		funcs: {}
	}

For example:


	GAME.initCustom(function(){
		GAME.custom.cons.ENEMIES_MAX = 10;
		GAME.custom.cons.BULLETS_MAX = 100;
		
		GAME.custom.vars.ENEMY_COUNT = 0;
		GAME.custom.vars.BULLET_COUNT = 0;
		
		GAME.custom.funcs.checkEnemies = function(){
			if (GAME.custom.vars.BULLET_COUNT > GAME.custom.cons.BULLETS_MAX){
				GAME.find({instanceOf:'bullet'}).each(function(obj){
					obj.destroy();
				});
			}
		};
	});

Global Instances

There is a special global variable called GAME.Instances. It stores instantiated entities for quick access; that is, instead of having to use GAME.find all the time. Basically, whatever unique name you provided for an entity during creation, is what gets registered in this global variable. It is for this reason, even though not mandatory, to always provide a name for your entities.

Global instances are available the moment the first room has started. They can be used at any time and in any entity event thereafter. What this means is that any entity can access any other entity's properties, methods, and events! A useful feature for sure. ;-)

NOTE: unless a particular entity is set as persistent, it will no longer be available in GAME.Instances after a Room transition; ie, it doesn't exist anymore.

The naming convention is as follows:

  1. uses name if provided, else, asset name.
  2. removes underscores and hyphens.
  3. captializes all characters.

Consider the following example:


	GAME.initRooms(function(){
		var level1 = GAME.Room.create({name:'level1'});
		
		level1.onCreate(function(obj){
			obj.addSprite('carrot', {x:0, y:0});
			obj.addSprite('carrot', {name:'carrot-2', x:16, y:16});
			obj.addSprite('carrot', {x:32, y:32});
		});
		
		level1.onStart(function(obj){
			// spins all carrots
			GAME.find({instanceOf:'carrot'}).each(function(obj){
				obj.spin();
			});
			
			// blinks only the third carrot
			// global instance name overridden since unique name not provided
			GAME.Instances.CARROT.blink();
			
			// destroys only the second carrot
			GAME.Instances.CARROT2.destroy();
		});
	});

TIP: in cases where you may want multiple instances without unique names, you'll have to use the GAME.find function to precisely target and iterate over these kinds of objects.

Properties (read-only)

Name Type Description
widthNumberthe actual pixel width of the game, before scaling.
heightNumberthe actual pixel height of the game, before scaling.
orientationStringthe device orientation ('portrait' OR 'landscape').
scaleBooleanwhether the game can scale proportionately. (default: FALSE)
mouseXNumberthe current mouse screen X value (top left is 0, 0).
mouseYNumberthe current mouse screen Y value (top left is 0, 0).
scrollXNumberthe horizontal page scroll amount.
scrollYNumberthe vertical page scroll amount.
hasAdBlockBooleanis TRUE if an ad blocker is detected.
hasStorageBooleanis TRUE if localStorage is present (See the Classes > Data for more info).
hasFocusBooleanis TRUE if game has focus.
isFullScreenBooleanis TRUE if game is in full screen.
isMobileBooleanis TRUE if game is running on a mobile device (iphone, ipad, ipod, android, windows phone).

Methods

Name Parameter Type Description
pausepauses the game (and all pausable entities).
resumeresumes the game (and all pausable entities).
togglePauseif paused, resumes the game, and vice versa.
freezestateBooleanfreezes the game when TRUE, unfreezes when FALSE. (freezing the game means absolutely no events are firing. This happens automatically when the user navigates away from the game)
abortcompletely aborts the engine, with no recovery.
shaketimeNumberhow many milliseconds to shake the screen. (default: 500)
amountNumberdistance in pixels to shake. (default: 4)
callbackFunctionthe function to execute when done shaking.
fullscreentoggles full screen mode. NOTE: game is always scalable in full screen mode.
findtargetObjectsearches active entities for a matching target. Target is an object literal with property/value pairs you want matched. If one of the properties to be matched is class, then separate classes with a comma (no spaces).

	GAME.find({name:'ball', hasGravity:true, class:'green,fast'});

When matches are found, an object is returned with the following properties:

- items: an array of matched elements (even when only ONE is found).
- length: a number representing the matched items array length.
- first: a function to execute on the first matched element.
- last: a function to execute on the last matched element.
- eq: a function to execute on specific element. (Has a non-zero based index parameter)
- each: a function for iterating over the matched entities.

If you want to store the first matched element in a variable:

	var ball = GAME.find({name:'ball'}).items[0];

To iterate over all items:

	GAME.find({class:'ball'}).each(function(obj){
		obj.fadeOut();
	});

To iterate over specific item:

	GAME.find({class:'ball'}).eq(3, function(obj){
		// fades out third element
		obj.fadeOut();
	});

To iterate over last item:

	GAME.find({class:'ball'}).last(function(obj){
		obj.fadeOut();
	});

logtypeString'ERROR', 'NOTICE', 'USAGE', 'TEST'
* messageStringthe message in the console log will be color-coded depending on the type of parameter (red for ERROR, blue for NOTICE, and yellow for USAGE). If type is set to TEST (or only one parameter is entered), then basic console output is assumed.
referenceStringan object reference to append to the message. For example, indicating object context can help to troubleshoot an error:

	GAME.log('ERROR', 'missing parameter', obj.name);

executethis is the entry point for the engine. You place this function call into a <div> with an id of jjs-container. Here is an example:

	<body>
		<div id="jjs-container">
			<script>
				GAME.execute({
					name: 'MyNewGame',
					width: 320,
					height: 240, 
					scale: true,
					bgColor: '#006699',
					orientationLock: 'landscape'
				});
			</script>
		</div>
	</body>

* options.nameStringname of your game. Used with localStorage to save game Data; ie, unique game names prevent overwriting one game's save data with another, especially if on same domain.
* options.widthNumberactual pixel width of game, before scaling. (default: 320)
* options.heightNumberactual pixel height of game, before scaling. (default: 480)
options.bgColorStringhex value of background color: (default: '#000000')
options.loadingTextStringtext to show in loading progress bar. (default: 'Loading...')
options.orientationLockStringif set, will display a rotate graphic when device orientation does not match. Values: 'portrait', 'landscape'. (default: NULL)
options.progressClassStringthe class of the progress bar wrapper element. Values: 'middle'. (default: '')
options.scaleBooleanif set to TRUE, will scale the game, proportionately. (default: true)
options.scrollLockBooleanif set to TRUE, browser scrolling is disabled when focus is on game. (default: TRUE)
options.splashBooleanif set to FALSE, no splash image will be shown while loading. (default: TRUE)
options.transparentBooleanif set to TRUE, background is see-through. This means you can see the web page beneath the canvas.
options.volumeSoundNumberglobal sound volume. Values: 1-100. (default: 50)
options.volumeMusicNumberglobal music volume. Values: 1-100. (default: 50)
options.mutedSoundBooleanglobal sound muting. (default: FALSE)
options.mutedMusicBooleanglobal music muting. (default: FALSE)

Events

When a JackyJS event occurs a corresponding global function is executed, that is, if custom code exists for it. Most of the following event functions simply require an anonymous function as its only parameter. Further, these global event functions are typically assigned in the GAME.initGlobal() function.

Name Parameter Type Description
onInitcallbackFunctionafter all initialization code is done.
onExecutecallbackFunctionafter the execute function is run, after adblock is checked, but before preload.
onStartcallbackFunctionafter the first room is started and all corresponding instances are instantiated.
onUpdatecallbackFunctionafter every step of the game loop, after all entities updated.
onOrientationChangecallbackFunctionafter device orientation changed.
onFocuscallbackFunctionwhen user clicks on game.
onBlurcallbackFunctionwhen user clicks somewhere else on page.
onFreezecallbackFunctionwhen user navigates away from page.
onUnFreezecallbackFunctionwhen user navigates back to page, if previously frozen.
onMousePressbuttonStringwhich button was pressed and released. ('LEFT' is the only available choice for now)
callbackFunctionfunction to execute when mouse button is pressed and released.
onMouseDownbuttonStringwhich button was held down. ('LEFT' is the only available choice for now)
callbackFunctionfunction to execute while mouse button is held down.
onMouseUpbuttonStringwhich button was released. ('LEFT' is the only available choice for now)
callbackFunctionfunction to execute when mouse button is released.
onKeyPresskeyStringwhich key was pressed and released. (see Input class for key codes)
callbackFunctionfunction to execute when key was pressed and released.
onKeyDownkeyStringwhich key was held down. (see Input class for key codes)
callbackFunctionfunction to execute while key is held down.

Inits

This is where all your custom code goes. Basically, you are passing an anonymous function as the only parameter to all of these functions. All of this code should reside in your own Javascript file, which is to be included after the JackyJS min file.

Name Parameter Type Description
initGlobalcallbackFunctionwhere all your global event functions go.
initCustomcallbackFunctionwhere all your global custom constants, variables, and functions are defined.
* initPreloadcallbackFunctionwhere all your assets are placed for preloading.
* initAssetscallbackFunctionwhere all your assets are initialized for later use in entities.
* initEntitiescallbackFunctionwhere all your entities (Sprite, Background, Text, etc) are initialized and events assigned (onCreate, onUpdate, onCollision, etc).
initEntitiesChildrencallbackFunctionwhere all your entity children are initialized and events assigned. JackyJS supports inheritance of entity properties and events, as well as overriding parent behaviors.
initInterfacecallbackFunctionwhere all your button, Dialog, and Text objects can go. This is entirely optional and is available only as an organizational construct; ie, you can place this code in the GAME.initEntities() function if you like, especially if your game has minimal code.
initParticlescallbackFunctionwhere all your Particle parts, emitters, and systems should go.
initPathscallbackFunctionwhere all your Paths are initialized and events assigned.
* initRoomscallbackFunctionwhere all your Rooms are initialized and events assigned.
initTimelinescallbackFunctionwhere all your Timelines are initialized and events assigned.
initTransitionscallbackFunctionwhere all your Room Transitions are initialized and events assigned.