ExGame

This document explains how to setup ExGame.

Information on how to use Post ExGame, please see the attached document inside the download file.

What is ExGame

ExGame is a tool that converts feature phone's SWF contents to a smart phone content.
The tool will convert the SWF file which was created with Flash Lite 1.1 into a Javascript runnable code. It will automatically optimize the content for Android or iOS devices.
For games that were originally created for feature phone version of Mobage games, the tool will provide less time and cost for migrating the content to a smart phone WEB version.

ExGame Requirements

  • Compatible Android versions are 2.2 or above.
  • Not compatible for first generation iPod touch and iPhone 3G.
  • Compatible iOS versions are iOS4 and iOS5. Recommended to use latest updated version.

How to initialize ExGame

You will need two files to initialize ExGame.
 

  • ExGame (Java script library)
  • An SWF file to run
    Inserting the following HTML code will allow ExGame to run the SWF.

Cross domain communications

You can have different domains for displaying the HTML and the location of swf file when using Akamai.
Since ExGame uses XHR (XMLHttpRequest) to retrieve the swf file, having different domains will restrict access when retrieving the file.
 
In this case you will need to add the following information to the HTTP-Header on the server which is distributing the swf file.

Access-Control-Allow-Origin: *
Notice that DeNA will only validate with iPhone 3GS/iPhone 4 (iOS4) devices.

 

About using cache

The core file of ExGame which is "jj.js", is a static file and we strongly recommend to cache this to the browser.
 
Caching the file to the client browser will remove the communication when loading ExGame.
The ExGame core file itself is 115KB which will take time to download when loading.
If you are caching ExGame, adding the following script tag will allow to automatically re-cache incase the ExGame version changes.

About setting up config

You can configure the settings per player in ExGame. The configuration is setup by adding code to javascript as following.
 

 

Configurable settings on config

 

  • Rendering related
    • disableFrameSkip
    • fps
    • onpreload
    • scale
    • displayScale
    • fullScreen
  • Touch related
    • flick
    • touch
    • disableTouch
    • lightning
    • useLessCanvas

disableFrameSkip

When ExGame is unable to provide the needed frame rate when rendering a frame, it will automatically skip the rendering frame (Frame Skip Function).
This will not affect any internal calculation or key events on the action script.
 
You can disable this function by setting "true", incase you want to avoid skipping any rendering frame even though the frame rate will lower.

Default is false
Notice that by disabling the the function the browser can crash which is not recommended to be disabled on production. (Only for debugging or testing)

 

fps

You can manually override the Frame Rate when the swf's original Frame Rate is too fast and causing performance issue or too slow causing the animation end up quickly.
 
If the animation is showing performance issues we recommend to set the Frame Rate to around 8 fps.
The normal range of fps will be from 8 to 12 fps. We recommend to have "disableFrameSkip" false when changing this value.

Above is example on forcing the Frame Rate to 8 fps.

 

onpreload

By setting up "onpreload" callback , you can show the user the current loading percentage. Though using this function will slightly increase the load compared when not using the "onpreload" function.
We don't recommend to use this function if the swf file has a fast loading speed. You can also setup your own preloading page.
 

Default "null" (None)
Since it can cause performance issues we dont recommend usage on production

 
The source code of the default progress bar is as below.

 

scale

Internal rendering magnification ratio.
 
Since SWF uses vector graphics, magnifying the display will still keep the image quality (Except for raster graphics). You can customize from the orignal scale (240x240), though increasing the magnification ratio will cause more rendering and result slower performance. The aspect ratio is locked as default.
The best practice magnification ratio is 1.5 (which is default), although we recommend modifying the "displayScale" and leave the "scale" as default value. Increasing the "scale" (as default 1.5) and making the "displayScale" smaller will solve the image quality issue when using viewport for smart phone devices.

Default value is 1.5 (360x360)
Above example of scale 1 is 240x240 ratio

 

displayScale

Browser display magnification ratio.
 
If you lock the browser display width with 240px on a smart phone device and try to magnify the 240px image, the image will become unclearer as you magnify.
You can avoid this by configuring the "displayScale". This works by using the CSS3 to show high resolution images in a smaller size which will allow to provide better image quality when magnifying.
On iOS devices the rendering is done by the GPU and wont see much impact to the performances when magnifying the image. Although using a higher resolution image will cause more loading due to the size.
 

Default value is 1
The above example will display the size in two thirds which will be 240x240

 

fullScreen

Will show on full screen mode.
 
Same as Flash Lite the full screen is supported in ExGame. 
Following are tips for creating a smart phone compatible settings. 
 

  • Trace rotation of phone.
  • Absorb the differences of iOS and Android.
  • Restrict the usage of scroll, pinch in and pinch out.
     
    Default value is false
    This function was introduced from ExGame ver.1.0.4 or later
     

    flick

    Will replace flick events to corresponding character.
     
    The feature phone keys can be replaced with flick events. You can assign a key responding to a flick angle events and touch event.
    flicking up will be equivalent to 0. You can specify one key event for touch. There are 13 key events that can be specified which are "ENTER", "*", "#", "0 - 9". 
     flick: {
        "touch": "ENTER",
        "-45:45": "2",
        "45:135": "6",
        "135:225": "8",
        "225:315": "4"
}
    The settings above show :
  • touch event is equivalent to "ENTER".
  • From "-45" degrees to "45" degrees flick event corresponds to key "2".
  • From "45" degrees to "135" degrees flick event corresponds to key "6".
  • From "135" degrees to "225" degrees flick event corresponds to key "8".
  • From "235" degrees to "315" degrees flick event corresponds to key "4".
    By default the flick has not corresponding key assigned
    If the angle overlaps, the event will be converted to either one of the key assigned
    The key event can be duplicated
     

    touch

  • touch.clickableObject
    Will convert touching an object to a corresponding key event.
    Using touch.clickableObject will allow you to assign a key event to a clickable touch object. There are 13 key events that can be specified which are "ENTER", "*", "#", "0 - 9".
    Following are the three ways to setup your touch.clickableObject.
     
    Setup by object-id.
    Setup by instance name.
    Setup by slash syntax.
    You can use the private player to confirm the and retrieve information about object-id ...etc
    The above sample shows how the touch location is converted into the following :
  • If the touch location is object-id "13" then it will raise key event 8.
  • If the touch location contains instance name "mc-name" then it will raise key event 6.
  • If the touch location contains slash syntax "/root/mc1/mc2" then it will raise key event 4.
     
    touch.ontouch:function(x,y){}
    By using touch.ontouch, you can specify your own touch event handler. You can use internal engine state as a key event by using this event handler. You can call the engine's API to retrieve engine's internal information from inside the event handler.
     
    if you return true inside this function the engine will not proceed default process. Instead if you return false (or undefined, null) the engine will proceed default process.
     

    disableTouch

    Will disable all touch functions.
     
    If you want to prevent any unneeded touch events you set this to true which will disable all touch functions.
     
    Default value is false (Can do touch events)
     

    lightning

    Will respond to a key event when touched and ignores flick input.
     
    lightning input is useful when you have a game that decides by the timing that the user has touched. Once the screen is touched it will enter the key input that has been setup. Notice that by setting up this parameter flick input will be disabled.
    Default value is false(Dont use lightning)
    The above example shows that ENTER key event will be sent once the screen is touched
     

    useLessCanvas

    There is an issue on Android 4.1.1 that HTMLCanvasElement is not released from memory causing memory leak when you try to play SWF in ExGame.
    You can avoid this issue by enabling useLessCanvas. Although you will need to be careful that there will be the following limitation when enabling.
  • The performance will lower (play speed)
  • The touch event will become less responsive (in some cases the ontouched event wont be called)
  • The rendering will disrupt in case it is enabled other than Android 4.1.1
    To activate the useLessCanvas on default browser on Android 4.1.1 you can follow the following example.

About API function

The API function is an engine with several functions that can be called by ontouch event.
Can easily convert touch inputs without any cost. By using the API, you can convert the touch input into a key event based on the engine and virtual machine status.
 
You can use the API by passing the api object as below.

API function

  • isExistMC(name)
  • isExistObject(id)
  • getObjectFromPosition(x, y)
  • getFrameCount()
  • getProperty(name, value)
  • getWidth()/getHeight()
  • sendKeyDown(key)
  • sendTouchXY

isExistMC(name)

Will check if there is a movie clip which corresponds to the name instance in the current time line. If exists it will return true if not it will return false.
 
It will search the root if the name starts with "/", else it will search under any MC and return true if the name exists.

isExistObject(id)

Will return true if there is an object corresponding to the id value which exists in the time line, else it will return false. Only "Shape" and "Text" is valuable Object. It wil not search the MC id, instead it will search the elements inside the MC.

getObjectFromPosition(x, y)

Will provide Object list from the specified position (x, y). The list contains PlaceObject ID and the MC names which construct that location. The x, y value is the value after "scale" was set and before "displayScale" is set.

getFrameCount()

Will provide current frame count. The FrameRate increases every second.

getProperty(name, value)

Will retrieve the property of the value which exists on name of the MovieClip. If either name and value doesn't exist it will return undefined . The value does not only have to be property (_x, _y,), but can also be a variable of an MC.

getWidth() / getHeight()

Will return the screen Width and Height. The following code will correspond to the Width (W) and Height (H) of the original swf.

sendKeyDown(key)

Will send key information to the engine if the key has been pushed. The key value can be the following.
 
ENTER
-
#
0～9

sendTouchXY

Will send touch location (x, y) to the engine when it is touched.
 
Please avoid causing a loop. The x, y value is the value after "scale" was set and before "displayScale" is set.

List of Limitations

  • FSCommand is not supported.
  • LoadMovie is not supported.
  • Playing sound is not supported.
  • Up and Down key is not supported.
  • The hit test of a button only supports a square.
  • Vertical Text Object are not supported.
  • Transparent PNG and JPEG are not supported on Android.
  • Android 2.0 and 2.1 are not supported.
  • iPod touch (first and second generation) and iPhone 3G is not supported.
  • Will not work outside of Mobage Opent Platform's Sandbox and Production environment.

ExGame Tips

The swf doesn't run on ExGame

  • Using functions that dont support Flash Lite 1.1 can cause issues on ExGame.
    • Some how it will run on Adobe Player.
    • Test on ExGame as soon as possible to avoid such issues.
    • Be aware of the ActionScript.
  • The Object wont show because of depth overlap.
    • It mostly occurs when server side composes the swf.
    • It can run on Adobe Player.
  • Corrupted text occurs on loadVariables
    • Send multi byte letters in UTF-8 (Mostly it is send as SJIS)

Cant scroll down since ExGame took control of touch

When using in fullScreen mode there makes a strange space

Rendering is heavy

The rendering will become heavier by how much pixels it needs to process.
Especially when using alpha colors or have many color changes which will make the rendering heavier.
 

  • Heavy Example:
    • Have a full screen that has flashing effect.
    • Have a animation that that light moves around on large screen.
  • Light Example:
    • Have a character move around on the middle on the screen. (Only needs to render partially)

Want to make the rendering lighter

If you want make redering lighter you can think about using enableLowQualityCache.
 

  • How to: Enable config.enableLowQualityCache
  • Once cache is created it will reuse the same data.
  • The scale is set when rendering the first time, causing the animation to become unclear when magnifying.
  • You can avoid the issues above by creating the Flash to work as above limitations.

How to use ExGame Developer Support Tool

The tool and sample files are bundled inside ExGame Version 1.0.13 ExGame-Player.zip.
 

How to user ExGame Developer Support Tool with your title

The development flow will be as below.
 

  • Optimize SWF for Android.
    • Place a transparent button and have it compatible with touch operation.
    • Replace feature phone keys like Enter and 5 .
    • Make image data compatible to smart phone resolution with out making it too heavy.
    • Confirm the swf created for Android on ExGame Player.
  • Use ExGame to provide iOS version
    • Have the Server side to implement ExGame Loader in to the HTML so it will be easier to confirm the function after composing.

ExGame Player

Quick Start

  • Place ExGame as "./jj.js".
  • Access player/frame.html and click the sample link.
     

    Limitation

  • Safari browser is recommended. (Since it access local file "file://")
    • Some browsers prevent access to local files which you wont be able run the HTML file.
    • By running a HTTP server locally you can access http://localhost/ from any browser.
  • When trying to run on a device you will need to upload to the Sandbox or on a Domain that can be accessible.
     

    single.html

    HTML to confirm on device.
    You can set ExGame parameters as query string and can scale or displayScale values on the device.
     

    frame.html

    HTML to confirm on browser.
    By displaying both Flash Player and ExGame you can compare between them.
     

    ExGame Player Tips

  • If you are modifying the displayScale, set also fullScreen=0 .
  • scale highest value are as below calculation. (Its the most optimal value and setting it any higher wont have any differences)
    • If you are experiencing frame skip you should lower the scale. We recommend to keep balance between quality and frame rate.
       
  • scale setting calculation
    • Base scale: ExGame view size / SWF width
    • Image enhancement scale: proportion to window.devicePixelRatio
    • Example: ExGame view width 320px, SWF width 240px
      • iPhone 4, 4S → 320/240 - 2.0
      • iPhone 3GS → 320/240 - 1.0

 

  • You can confirm easily on device by using single.html with links or bookmarks.
  • You can emulate SWF operation when running ExGame by implementing the following JavaScript.

ExGame Loader

Description

A tool to confirm the composed SWF.
 

  • Implementing this JavaScript will convert objects inside the page to ExGame to view.
    • Will check the UserAgent and if it confirmes it is iOS it will search the objects.
  • This tool purposed for development since It will slow the initialization of ExGame.
     
    Bellow is setting is assuming that your using default setting which is to have Flash banner and embedded image. 
    scale: 1.5,
displayScale: 2/3
    You can setup each option on data property on object element like data-exg-disable-touch.
     

    Usage

    You can run the tool by referencing exg_loader.js and setting options by JavaScript.
    For more details please see exg_loader.html .
     

    JJUtil

    Description

    A tool that will overcome the ExGame fullScreen mode issue.
     
  • Fixed issues related to view location and rotation.
  • Hide location bar.
     

    Usage

  • Please see jjutil/sample.html .
    • You will need to specify the div element on css to show in the middle of the screen.
    • The following sample is Sandbox application running jjutil.
       

 

Revision History

  • 2013/06/11
    • Initial release

PREVIOUS

Pexについて

NEXT

Screener

Mobage Developers