Flash Library Integration

From J2Play

Jump to: navigation, search

Contents

Introduction

Calling J2Play APIs requires a connection to a the J2Play servers. The following instructions walk you through the complete process, from connecting to the J2Play platform to successfully calling its APIs.

Preparation

First you need to copy some necessary files over to the folder where your .swf is generated. To do so:

  • Find the J2Play library that matches your Flash and ActionScript version. We provide three different versions of J2Play library in our flash-toolkit package
    • AS3 -- for Flash9 with ActionScript 3
    • AS2 -- for Flash7, Flash8 and Flash9 with ActionScript 2
    • Flash6 -- for Flash6 with ActionScript 2

Copy following files from the directory j2play-flash-toolkit/[version]/swf/ to your game's output directory (this is found in the publish settings for the .swf file your game.fla file produces):

  • game.properties
  • j2play.properties
  • j2playlib.swf

Configuration

Change Settings in game.properties

Each game is identified with a unique Game_ID. For local testing you need to provide login information to the platform. The following steps explain how to obtain a Game_ID and how to setup your local testing environment.

  1. Open the copied game.properties file in a text editor (open from your game's output directory)
  2. Set up the debug information for launching test movie in your local Flash IDE.

The first field value you need to set in the game.properties file is game_id. You can obtain this by going to the J2Play Management Console. Copy the 5 digit number under the "ID" column for your game and replace "your_game_id" with this value. For example, replace this: 

DEBUG.GAME_ID=your_game_id

with this: 

DEBUG.GAME_ID=80503

Add J2Play Developer App

If you have not already done so add the J2Play Developer App on Facebook (http://apps.facebook.com/j_devapp/). This will give you easy access to a set of user credentials you can use to debug your flash game integration in the next step.

Setup Game for Local Testing

Notice: The following settings are only for local testing from the Flash IDE. When the game is launched from J2Play community on web, these settings will be ignored.

Copy and paste the information a from the J2Play Developer Application (in the previous step), as outlined below: 

DEBUG.NETWORK_ID=networkid
DEBUG.SCREENNAME=screenname
DEBUG.USER_ID=userid
DEBUG.PASSWORD=password

Example: 

DEBUG.NETWORK_ID=facebook
DEBUG.SCREENNAME=joe
DEBUG.USER_ID=11111111111
DEBUG.PASSWORD=passkey
  • Save the properties file and close it

Include the J2Play Flash interface to your game

  • Open your game .fla file
  • In the Flash publish settings, add the Flash interface directory into your game class path (Publish Settings -> Flash -> ActionScript Settings). On Windows use ..\j2play-flash-toolkit\[flash version]\interface (or the appropriate relative path); on Unix use ../j2play-flash-toolkit/[flash version]/interface (or the appropriate relative path).

Action Script

If you are not using the flash IDE and do not use the flash timeline i.e. a pure actionscript approach, please skip to the document class section below.

  • Insert a keyframe (empty, except for the background layer graphics) at the very beginning of your Flash movie for all layers.
  • Insert a extra layer to your Flash game named j2playlib. This layer should be the same length (in frames) as your longest layer. And it must only contains one keyframe.

NOTE: if you are using Scenes make sure this layer is added to the same Scene that the API is to be called from

  • Add the following code to the j2playlib layer in frame 1:

Actionscript 2 

import ca.j2x.flash.J2PlayLoader;
import ca.j2x.flash.IController;
import flash.external.ExternalInterface;

stop();

if (!ExternalInterface.addCallback("unload", this, j2play_unload))
{
	trace("*****WARNING*****\nCannot build the external callback function!\n");
}

var loader= new J2PlayLoader;
loader.load(this, loadCallback);

function loadCallback(success : Boolean)
{
	if (success)
	{
		trace("J2Play Library initialized successfully!");
		// play the actual game movie
		play();
	}
}

function j2play_unload()
{
	var j2play:IController = _global.controller;
	if (j2play && j2play.isConnected())
	{
		j2play.destroy();
	}
}

Actionscript 3

To use the same flash movie timeline approach as in actionscript 2, use the following: 

import ca.j2x.flash.J2PlayLoader;
import ca.j2x.flash.IController;
import ca.j2x.flash.lang.Global;
import flash.external.ExternalInterface;

stop();

ExternalInterface.addCallback("unload", j2play_unload);

var loader= new J2PlayLoader;
loader.load(this, onGameLoad);

function onGameLoad(success : Boolean)
{
	if (success)
	{
		trace("J2Play Library initialized successfully!");
		// play the actual game movie
		play();
	}
}

function j2play_unload()
{
	var j2play:IController = Global.vars.controller;
	if (j2play && j2play.isConnected())
	{
		j2play.destroy();
	}
}

Document Class

If your application uses a document class (under Publish Settings when using ActionScript 3.0), you may not be using any frames at all in the flash movie timeline (pure actionscript with no timeline). In these cases, it is necessary to move your constructor code and/or initialization code to a class method in the document class, and call it when the J2Play library has finished inititalizing. This is only to ensure the J2Play library is ready for use, when your game tries to use it.

Here is a document class example which you can model into your own: 

package {
	import flash.display.MovieClip;

	import ca.j2x.flash.J2PlayLoader;
	import ca.j2x.flash.IController;
	import ca.j2x.flash.lang.Global;
	import flash.external.ExternalInterface;	

	public class MainClass extends MovieClip {

		public function MainClass() {
			trace ('Constructing MainClass...');
			ExternalInterface.addCallback("unload", onJ2PlayUnload);
			var loader= new J2PlayLoader;
			loader.load(this, onJ2PlayLoad);
		}

		function onJ2PlayLoad(success : Boolean) {
			if (success) {
				trace("J2Play Library initialized successfully!");
				// Now that the J2Play toolkit is loaded and initialized, continue the game
				// bootstrap as it normally would (i.e. play() or old contructor code
				// ...
				// call your original constructor code here 
				originalContructor();
				// ...
			}
		}
		
		function onJ2PlayUnload() {
			var j2play:IController = Global.vars.controller;
			if (j2play && j2play.isConnected()) {
				j2play.destroy();
				trace("J2Play Library destroyed");
			}
		}
		
		function originalConstructor() {
			// Your original construction code
			// ...
		}
	}	
}

ExternalInterface callback

The "ExternalInterface" is used to register a callback function that our community uses to notify your game that system is closing so that the flash game can preform any cleanup. When you are debugging your flash game locally, there is no community, so this warning can be ignored.

Background

If you want to show the background (or even loading movie) when j2play library is initializing, you can add it to a empty layer in first frame.


Result

  • Your modified game layer and frame layout will now look like: 
a-----------------------------------    j2playlib layer
o@############################       Your old game layers      
o###################################    
  ....                  ...
o#####                   
B###################################    Your old game layers

a: j2playlib layer, keyframe 1, contains aforementioned ActionScript code
-: empty frame added
o: empty keyframe added
B: empty keyframe added (as 'o'), where you may put the background in
#: old frames contains your original game
@: old frames (as '#'), where you can add the calling to 'j2play_continue()' if a document class is used.

Test and Finish

  • Publish your Flash game and test it. (From the menu -> Control -> Test Movie).
  • Make sure you got the "J2Play Library initialized successfully!" message in the Output window of the Flash IDE.

You should now see your Flash game running as it normally would. However, the J2Play Flash Toolkit is integrated and its features are now available to players.

Common Problems

  • If you get "Cannot initialize controller with (something)" in the trace output, please make sure you have filled the game.properties file correctly.
  • If you keep getting "J2Play Loader: File j2playlib.swf is loaded." in the trace output, please make sure the 'j2playlib' layer is long enough to cover your whole game timeline and it only contains one keyframe.

Links

Retrieved from "http://developer.j2play.net/wiki/index.php/Flash_Library_Integration"
Personal tools