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 Requirements
- How to initialize ExGame
- About setting up config
- Configurable settings on config
- About API function
- API function
- List of Limitations
- ExGame Tips
- How to use ExGame Developer Support Tool
ExGame is a tool that converts feature phone's SWF contents to a smart phone content.
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.
- 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.
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.
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.
|Notice that DeNA will only validate with iPhone 3GS/iPhone 4 (iOS4) devices.|
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.
- Rendering related
- Touch related
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)|
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.|
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.
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|
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|
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
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". 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
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.The above sample shows how the touch location is converted into the following :
You can use the private player to confirm the and retrieve information about object-id ...etc
- 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.
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.
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 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
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.
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.
- getObjectFromPosition(x, y)
- getProperty(name, value)
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.
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.
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.
Will provide current frame count. The FrameRate increases every second.
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.
Will return the screen Width and Height. The following code will correspond to the Width (W) and Height (H) of the original swf.
Will send key information to the engine if the key has been pushed. The key value can be the following.
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.
- 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.
- 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)
- Confirm disableTouch disableTouch .
- Confirm JJUtil.js .
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)
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.
The tool and sample files are bundled inside ExGame Version 1.0.13 ExGame-Player.zip.
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.
- Place ExGame as "./jj.js".
- Access player/frame.html and click the sample link.
- 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.
You can set ExGame parameters as query string and can scale or displayScale values on the device.
By displaying both Flash Player and ExGame you can compare between them.
- 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.
- 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.
A tool to confirm the composed SWF.
- 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. You can setup each option on data property on object element like data-exg-disable-touch.
For more details please see exg_loader.html .
- Fixed issues related to view location and rotation.
- Hide location bar.
- 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.
- Initial release