ExGameについて
このドキュメントではExGameの設定方法について説明します。
ExGame動作環境
- Androidについて、Android2.2以上に対応しています。
- iOS 系デバイスについて、iPod touch初代・iPhone 3Gには対応しておりません。
- iOS バージョンについて、iOS4、iOS5 に対応しております。また系統ごとに最新版を推奨致します。
ExGameの起動方法
ExGameを起動するには、2つのファイルが必要です。
ExGame(java scriptライブラリ)
動作させるswfファイル
最低限、次のHTMLを記述するだけで、ExGame上でswfが動作します。
<html><head><title>ExGame sample</title>
<script type="text/javascript" src="jj.js"></script>//ダウンロードされた最新のjj.jsをご指定ください。
<script type="text/javascript">
window.onunload = function() {}; // ブラウザのBack Forward Cacheの無効化
window.onload = function() {
var container = document.getElementById("container");
var jj = new JumpinJack("example.swf", container);//example.swf部分に動作させる(変換したい)swfファイルをご指定ください。
};
</script></head><body><div id="container"></div></body></html>
localhost以外でExGameを起動する場合
localhost以外のSandbox環境などでExGameを起動させる場合はファイルパスを下記のように設定する必要があります。
- 相対パス指定
- var jj = new JumpinJack("?url=http://sample.com/example.swf", container);
- 絶対パス指定
- var jj = new JumpinJack("
http://g12001234.sb.sp.pf.mbga.jp/?url=[http://sample.com/example.swf](http://sample.com/example.swf)", container);
ドメインを超えて通信する場合
Akamaiなどを利用する場合、HTMLを表示するドメインとswfの設置ドメインとが異なることがあります。
ExGameエンジンはXHR(XMLHttpRequest)を使用してswfを取得するので、取得先のドメインが違う場合はブラウザのセキュリティ制限で通信が出来ません。
その場合、取得するswfを配信するサーバにて、HTTP-Headerに次の設定を加えることで通信が出来るようになります。
Access-Control-Allow-Origin: *
上記の動作確認は、弊社ではiPhone 3GS/iPhone 4(iOS4)のみで行っております
キャッシュの利用について
ExGameのコアであるjj.jsは静的なファイルであり、運用上ブラウザのキャッシュに乗せる設定にされることを強く薦めます。
クライアントのキャッシュに乗ることにより、ExGameを毎回読みに来る通信が発生しなくなります。
ExGameは現在115kbほどあり、毎回読みこむとページを表示するたびにExGameを読み込む時間がかかります。
ExGameをキャッシュに乗せる場合は、以下のようにscriptタグにクエリー文字列を付与することで、バージョンが変わった際の再キャッシュが手軽に出来ます。
<script type="text/javascript" src="jj.js?version=3"></script>
Config設定について
ExGameでは、それぞれのプレイヤーに対し、挙動を細かく設定することが出来ます。 以下のように、JavaScriptを通じて設定項目を設定します。
設定しない場合はデフォルトの設定となります。
window.onload = function() {
var container = document.getElementById("container");
var jj = new JumpinJack("example.swf", container, config);
};
var config = {
disableFrameSkip: true,
fps: 12,
flick: {
"touch": "5",
"-45:45": "2",
"45:135": "6",
"135:225": "8",
"225:315": "4"
}
};
Config設定項目
-
描画関連設定
-
disableFrameSkip
-
fps
-
onpreload
-
scale
-
displayScale
-
fullScreen
-
タッチ入力関連設定
-
flick
-
touch
-
disableTouch
-
lightning
-
useLessCanvas
disableFrameSkip
ExGameでは、重いフレームを描画する場合など本来のFrameRateが再現出来なくなった際に、描画するフレームを間引くことによりFrameRateを実現しようとします(フレームスキップ機能)。
間引くのは描画だけであり、ActionScriptの実行などの内部計算やキー入力は影響を受けません。
1フレーム1フレームが重要な意味を持っており、多少重くなっても描画を間引かれると重大な問題が起こりうる場合には、このオプションをtrueにすることによってフレームスキップ機能を停止することが出来ます。
見栄えと動作速度のトレードオフを調整できます。
var config = {
disableFrameSkip: true,
};
デフォルトの設定はfalse
ブラウザクラッシュの原因となる可能性がございますので本番での利用は非推奨となります。(本設定は主にデバッグ用となります)
fps
swfに元々設定されているFrameRateでは速すぎて動作が全体的に重くなってしまう場合、もしくは遅すぎてあっという間にアニメーションが終わってしまう場合などに、強制的にFrameRateを設定することが可能です。
もしアニメーションの動作が重いように感じられた場合、このオプションで8fps程度を指定してみてください。
大体の目安は8fpsから12fpsです。この設定を変更される際には、disableFrameSkipをfalse(デフォルト)にした状態で調整をされることをお勧めします。
var config = {
fps: 8,
};
上記は8fpsを強制的に設定している例
onpreload
onpreloadコールバック関数を設定することで、ユーザーに現在の読み込み%を通知することが可能です。 コールバック関数を呼び出す負荷が増えるので、onpreloadを設定した場合の起動時間は設定しなかった場合に比べて若干長くなります。ロード時間が短いswfの場合、設定をされない方が良いです。 ゲームに応じて、自前のローディング画面を用意することも可能です。
var preloadCallback = function(current, total) { // current: 読み込み番号 total: 全体数
document.getElementById("status").innerHTML =
"現在" + Math.ceil(current / total * 100) + "%読み込み中";
};
var config = {
onpreload: preloadCallback,
};
デフォルトはnull(設定なし)
起動速度を落とす原因となる可能性がございますので、本番での利用は非推奨となります。
デフォルトで配布している、プログレスバーを表示するonpreloadのソースコードは以下です。
(function() {
var element = null;
var container = null;
var text;
var bar;
config.onpreload = function(current, total) {
if(!element) {
container = document.getElementById("container");
element = document.createElement("div");
element.style.position = "absolute";
element.style.top = "0";
element.style.left = "0";
element.style.width = container.offsetWidth + "px";
text = document.createElement("div");
text.style.textAlign = "center";
text.style.position = "relative";
element.appendChild(text);
bar = document.createElement("div");
bar.style.position = "relative";
bar.innerHTML = " ";
bar.style.backgroundColor = "#ccf";
bar.style.overflow = "none";
element.appendChild(bar);
container.style.position = "relative";
container.appendChild(element);
element.style.top = Math.floor((container.offsetHeight - element.offsetHeight) / 2) + "px";
}
if(current == total) {
container.removeChild(element);
element = null;
} else {
text.innerHTML = "loading: " + Math.floor(current / total * 100) + "%";
bar.style.width = Math.floor(container.offsetWidth * current / total) + "px";
}
};
})();
scale
内部描画の描画倍率を変更します。
swfはベクターグラフィックですので、拡大しても綺麗に表示することが出来ます(ラスター画像除く)。scaleを指定することにより、本来のswfのサイズ(大抵は240x240)を変更することが出来ます。 描画領域が広くなればなるほど描画のコストがあがり、結果として速度が遅くなりますのでご注意ください。 縦横比率固定となっております。 デフォルトの1.5倍は経験上良い値ですので、この設定値はあまり変更せず、表示サイズ変更(displayScale)を用いられることをお勧めします。 scaleで大きく描画し、displayScaleで縮小表示することで、スマートフォン特有の「viewportを小さく設定すると画像が粗く表示される」問題を回避することが出来ます。その場合の最適scaleは、大抵1.5(デフォルト)となります。
var config = {
scale: 1,
};
デフォルトは1.5倍(常に拡大、大抵は360x360)
上記の設定は、それを1倍(240x240)の例
displayScale
ブラウザでの表示倍率を変更します。
スマートフォンは、ブラウザの横幅を小さいピクセル(240pxなど)で固定した場合、その240pxをブラウザ端末の画面サイズに拡大する影響で、そこに表示される画像が粗く表示されてしまう問題があります。displayScaleを指定することにより、この問題を回避することが出来ます。 原理としては、CSS3を利用して大きい画像を縮小表示しておくことで、その画像が拡大されても綺麗に表示することが可能です。 この設定による拡大縮小は、iPhoneではおそらくGPUを用いて実行している関係で、実際の重さにほとんど影響を与えません。ただ、元画像で大きい画像を用意する際に、本来のサイズよりも大きい分処理が重くなります。
var config = {
displayScale: 2 / 3,
};
デフォルトは1倍(変更せず)
上記は、元サイズの2/3の大きさにする例 scaleの設定をデフォルト(1.5)にした場合には、この設定によって本来のサイズ(大抵240x240)に戻ります
fullScreen
フルスクリーンでの表示を行います
Flash Liteのよくある使用方法のうち、フルスクリーン表示をサポートします。ExGame以外の他の要素が無いことを前提とし、スマートフォンの中心に描画されるように各種設定します。
横に回転した場合なども、可能な限り追随します。
Android/iPhoneの差異を吸収します。
スクロール・ピンチイン・ピンチアウトを可能な限り禁止します。
var config = {
fullScreen: true,
};
デフォルトの設定はfalse(フルスクリーンしない)
ExGame ver.1.0.4 以上で提供される機能です。
flick
フリックの方向に応じて、対応する入力に変換します。
フィーチャーフォンでの各キー入力を、フリックの方向等に応じて、対応するキー入力に変換します。フリック方向(角度)に対するキーの割り当てと、タッチ操作に対するキーの割り当てが可能です。 フリック方向(角度)は、上を0度として指定します。 タッチ操作は、対応するキーを一つだけ設定します。 設定可能なキーは「ENTER」「*」「#」「0」~「9」の13種類です。
flick: {
"touch": "ENTER",
"-45:45": "2",
"45:135": "6",
"135:225": "8",
"225:315": "4"
}
上記は、以下の状態を示します
-
タッチ操作を「ENTER」に変換
-
-45度から45度方向へのフリックを2キーに変換
-
45度から135度方向へのフリックを6キーに変換
-
135度から225度方向へのフリックを8キーに変換
-
225度から315度方向へのフリックを4キーに変換
信息
デフォルトの設定は、フリックの挙動は無し :::
角度が重なっている場合は、そのどちらかに変換されます
キーは重複しても問題ありません
touch
- touch.clickableObject
タッチ入力を、状況に応じたキー入力に変更します。
touch.clickableObjectを使用する事で、タッチ入力にて、特定の要素がタッチされた時に、設定されたキー入力への変更が可能です。変換可能なキーは「ENTER」「*」「#」「0」~「9」の13種類です。 指定方法には以下の3種類があります。
object-idによる指定
インスタンス名による指定
スラッシュシンタックスによる指定
これらのobject-id等の情報は専用プレイヤーにて確認・取得が可能です。
touch: {
clickableObject: {
13: "8",
"mc-name": "6",
"/root/mc1/mc2": "4"
}
},
上の例では、タッチした位置によって、以下の変換がおこなわれます。
- タッチ位置に、object-id「13」が存在していればキー入力8とする。
- タッチ位置に、インスタンス名「mc-name」が存在していればキー入力6とする。
- タッチ位置がスラッシュシンタックスの「/root/mc1/mc2」であった場合、キー入力4とする。
touch.ontouch:function(x, y) {}
touch.ontouchによって、タッチ入力に反応する独自のイベントハンドラを登録できます。このイベントハンドラを用いる事で、エンジンの内部状況を利用したキー入力変換も可能となります。 イベントハンドラの中では、エンジンのAPI機能を呼び出すことによって、エンジンの内部情報を所得して利用することが出来ます。
この関数内でtrueを返すと、エンジンではデフォルトの処理をしません。逆にこの関数内でfalse(もしくはundefinedやnull等)を返すと、エンジンはデフォルトの処理をします。
disableTouch
タッチ機能を全てオフにします。
不要なタッチ操作などを発生させたくないときにtrueを設定すことで、全てのタッチ操作をオフにすることが出来ます。
デフォルトはfalse(タッチ操作可能)です。
lightning
フリック入力を無視し、タッチした瞬間に入力を受け付けます。
電撃入力。タッチしたタイミングでキー入力の判定を行うようなゲームなどに有効です。画面をタッチしたタイミングで、設定したキーが即座に入力されます。このパラメーターを設定すると、フリック入力が無効となりますので、ご注意ください。
var config = {
lightning: “ENTER”,
};
デフォルトではfalse(電撃入力しない)です。
上記例では、タッチした瞬間にENTERが送られます。
useLessCanvas
Android 4.1.1 では HTMLCanvasElement のメモリが解放されない問題があり、ExGame で SWF を再生することでメモリリークが発生します。
本事象は useLessCanvas オプションを有効にすることで緩和することができます。ただし、次のような副作用があるので検証を十分に行った上で有効にしてください。
-
多くの場合パフォーマンス(再生速度)が下がる
-
多くの場合タッチの反応が悪くなる(ontouchend イベントが呼ばれないことがある)
-
Android 4.1.1 以外で有効にすると描画が乱れる場合がある
Android 4.1.1 の標準ブラウザの場合に useLessCanvas を有効にするには例えば次のように起動オプションを指定します。var ua = navigator.userAgent.toLowerCase();var config = {useLessCanvas: (ua.indexOf("android 4.1.1") >= 0 && ua.indexOf("chrome") == -1)};
API機能とは
API機能とは、主にontouchで呼び出すことの出来るエンジン提供の関数群です。
既存のFlash Liteを、コストをかけずに手軽にタッチ入力に変換するための機能です。 APIを使うことによって、エンジンやバーチャルマシンの内部の状態を参考にしながら、タッチ入力を適切なキー入力に変換することが出来ます。
利用するには、以下のようにapiオブジェクトを通して参照します。
var config = {};
var jj = new JumpinJack('example/swf',
document.getElementById('container'), config);
jj.api.(各APIメソッド)
API機能
- isExistMC(name)
- isExistObject(id)
- getObjectFromPosition(x, y)
- getFrameCount()
- getProperty(name, value)
- getWidth()/getHeight()
- sendKeyDown(key)
- sendTouchXY
isExistMC(name)
現在のタイムラインにて、nameというインスタンス名のムービークリップが存在すればtrueを返す。存在しなければfalseを返す
nameが「/」から始まっている場合は、ルートからの探索で探します。そうでない場合は、どこかのMC下にnameが存在すればtrueを返します
isExistObject(id)
idの値を持つObjectがタイムライン上に存在すればtrueを返します。存在しなければfalseを返します idの値を持つObjectは、ShapeやTextに限られます。MCのidは探索せず、そのMCの要素を構成するidの中から探索します。
getObjectFromPosition(x, y)
x, yの位置にあるobjectの一覧を取得します。 リストで返ってきます。リストの中身は、まずはPlaceObjectのIDが入っていて、次にその位置を構成するMC名の一覧が入っています。 x, yの値は「scale」が適用された後の値であり、「displayScale」は適用される前の値です。
getFrameCount()
現在のフレームカウントを取得します。 基本的に1秒間にFrameRate増加します。
getProperty(name, value)
nameという名前のMovieClipより、valueという名前のプロパティを取得します。 nameが無い場合はundefinedが返ります nameの中にvalueが無い場合はundefinedが返ります valueは、プロパティ(_xや_y、_framecount等)だけではなく、そのMCに設定された変数も取得可能です。
getWidth() / getHeight()
実際の画面の幅と高さを返します。 オリジナルswfの幅をW、高さをHとすると以下が成り立ちます。
getWidth() == W * config.scale
getHeihgt() == H * config.scale
sendKeyDown(key)
keyキーが押されたという情報をエンジンに送ります。 keyに指定できるのは以下の通りです。
ENTER
0~9
sendTouchXY
x, yの地点が押されたことをエンジンに通知します。
無限ループにならないように気を付けてください。 x, yの値は「scale」が適用された後の値であり、「displayScale」は適用される前の値です。
制限事項
- FSCommandには対応しておりません
- LoadMovieには対応しておりません
- 音楽の再生には対応しておりません
- 上下キーには対応しておりません
- ボタンのHitテストは四角形以外対応しておりません
- 縦書きテキストのオブジェクトには対応しておりません
- Androidにおける、透過PNG/透過JPEGの描画には対応しておりません
- Android2.0/2.1系列には対応しておりません
- iPod touchの第1世代および第2世代、iPhone 3Gには対応しておりません
- MobageオープンプラットフォームのSandbox環境・本番環境以外では動作しません
ExGameのTips
ExGame上でswfが動作しない
- Flash Lite 1.1 でサポートされていない機能を利用すると ExGame において問題となる場合がある
- Adobe 製 Player では何となく動いてしまう
- 対策として、ExGame にて早期の動作確認を行っておく
- 特に ActionScript 注意する
- depth 重複によりオブジェクトが表示されない
- サーバ側で SWF を合成利用する際に発生しやすい
- Adobe 製 Player では動いてしまう
- loadVariables にて文字化けが発生する
- マルチバイト文字は UTF-8 で渡す(SJIS のままである事が多い)
タップ操作が ExGame にとられてしまい、スクロールダウン出来ない
fullScreen モード利用時に変なスペースが出来る
- JJUtil.js にて動作を確認する
描画が重くなってしまう
処理すべきピクセル数に比例して描画が重くなります。
特にアルファを利用した着色や、頻繁に色が変わる着色は重くなります。
- 重い例:
- 画面全体を発光させるエフェクト
- 画面大の後光が回るアニメ
- 軽い例
- 画面中央でキャラクタが激しく動く(部分的な書き換えに収まる)
描画を軽量化したい
描画を軽量化したい場合は enableLowQualityCache オプションの利用をご検討ください。
-
方法: config.enableLowQualityCache を有効にする
var config = {enableLowQualityCache: true,}; -
キャッシュ生成方法が都度から一度作成したものを使いまわす挙動に変更されます。
-
初回描画時のスケールが適用されるため、拡大を行うアニメーションを付けると画質が荒くなります。
-
上記は Flash を挙動に合わせ作りなおす事で回避することが可能です。
ExGame開発サポートツールの使い方
本ツール群とサンプルファイルはExGameバージョン1.0.13のExGame-Player.zip にて同梱されています。
弊社タイトルでのExGame開発サポートツールの利用法
本ツール群を用いた開発フローを下記の通りです。
- Android 向けに SWF の最適化を行います。
- 透過ボタンを置き、タッチ対応に適した操作へと変更します。
- Enter や [5] といった フィーチャーフォン用の表記を置き換えます。
- 画像データは全体容量が重すぎないよう配慮しつつ スマートフォン用解像度のものに置き換えます。
- Android 対応の済んだ SWF を ExGame Player にて動作確認します。
- ExGame を用いて iOS 用に提供します。
- サーバ側にて HTML に ExGame Loader を埋め込んでおくと合成後の動作確認が容易になります。
ExGame Player
Quick Start
- ExGame を ./jj.js として配置してください。
- player/frame.html にアクセスし Sample にあるリンクをクリックしてください。
使い方
- player 以下の single.html, frame.html が本体になります。
- query strings (URL の ?.. に続くパラメータ) により ExGame を設定、操作します。
- Sample のリンクを押して URL のパラメータが変わり、同時に ExGame の挙動が変わる事をご確認ください。
制限
- ブラウザは Safari の利用を推奨致します。 (ローカルアクセス(file://) が行える為)
- 一部ブラウザでは XHR によるローカルファイルの読み取りが禁止されており、直接 HTML ファイルを開いても動作致しません。
- HTTP サーバを立て、http://localhost/ でアクセスする事により各種ブラウザで動作致します。
- 実機にて利用される際は Sandboxにアップロードするなど、利用可能なドメイン上にてご利用ください。
single.html
実機確認用の HTML です。
query strings により ExGame のパラメータを指定可能であり、実機にて scale や displayScale といった値を調整し試すことが可能です。
frame.html
ブラウザ確認用 HTML です。
Flash Player と ExGame の動作画面を並べることで動作の違いを確認出来ます。
ExGame Player Tips
-
displayScale を操作する場合は fullScreen=0 を同時指定してください。
-
scale の理論上限は下記計算式の通りです(最も美麗に見え、かつそれ以上の値を指定しても効果をもたらさない)
- フレームスキップが目立つ場合は scale を下げ、品質とフレーム数のバランスを取る対応をお勧め致します。
-
scale 設定の計算式
- 基本となる倍率: ExGame 表示幅 / SWF 横幅
- 画質向上のための倍率: window.devicePixelRatio に比例
- 例: ExGame 表示幅 320px, SWF 横幅 240px
- iPhone 4, 4S → 320/240 - 2.0
- iPhone 3GS → 320/240 - 1.0
// iOS5 or later のみ高解像度表示を許容
var ratio = window.navigator.userAgent.indexOf('OS 4_') > 0 ? 1.0 : window.devicePixelRatio;
// 計算式参照のこと
var scale = 320/240 * ratio;
var config = {
scale: scale,
displayScale: 1/scale
};
- ブックマーク、またはリンク集を作成すると single.html を用いた実機確認が容易になります。
- 次のような JavaScript を仕込む事により、ExGame 再生中 SWF の操作エミュレートが可能です。
var automate = {
20: function(jj, fr) {
jj.api.sendTouchXY(160,160);
}
};
true && setTimeout(function() {
var jj = window.jj;
var fr = jj.api.getFrameCount();
for (var keyf in automate) {
if (fr >= keyf) {
automate[keyf](jj, fr);
console.log("triggered",keyf,fr);
delete automate[keyf];
}
}
if (Object.keys(automate).length > 0) {
setTimeout(arguments.callee, 20);
}
}, 400);
ExGame Loader
概要
合成後 SWF を確認するためのツールです。
- 本 JavaScript を埋め込んでおくとページ内に object 要素がある場合、ExGame に置き換えて表示します。
- UserAgent 確認を行い、iOS であると判断した場合に object 要素を検索する挙動です。
- ExGame の起動速度が遅くなるため、あくまで開発補助ツールとしての利用を想定しております。
初期設定は Flash バナーなど画面内埋め込み利用を想定し、下記のように指定されています。
scale: 1.5,
displayScale: 2/3
object 要素の data 属性にて data-exg-disable-touch のように各種オプションを指定可能です。
利用方法
exg_loader.js を参照し、JavaScript によりオプション指定、実行します。
詳しくは exg_loader.html の記述を参考に御覧ください。
JJUtil
概要
ExGame fullScreen モードの問題点を修正したツールです。
- 表示位置、ローテーションにまつわる不備の解消
- ロケーションバーを隠す
利用方法
- jjutil/sample.html を御覧ください。
- 画面中央に表示するにはdiv要素に対してcssでの指定が必要です。
- 下記Sandbox環境アプリにてjjutilを動作させた場合のサンプルとなります。
<!DOCTYPE html><html lang="ja"><head><meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0, minimum-scale=1.0, maximum-scale=1.0, user-scalable=no" />
<meta name="format-detection" content="telephone=no"><title>exgame jjutil</title>
<!-- 画面中央に表示するためにはdiv要素に対してcssでの指定が必要です -->
<style type="text/css">
body { margin: 0; }
#container { text-align: center; }
.swf { margin: 0; }
</style>
</head>
<body><div class="swf"></div><div id="container"></div>
<script src="?url=http%3a%2f%2fexsample%2ecom%2fjj%2ejs"></script>
<!-- 必ずjj.jsとセットで使用する必要があります -->
<script src="?url=http%3a%2f%2fexsample%2ecom%2fjjutil%2ejs"></script>
<script>
window.addEventListener('DOMContentLoaded', function() {
var swf = '?url=http%3a%2f%2fexgame%2ecom%2ftutorial2%2eswf';
var container = document.getElementById("container");
var width = 320; //1倍で表示させたい幅をpx指定
var height = 460; //1倍で表示させたい高さをpx指定
//既存config設定と同様になりますがfullScreen:trueの指定は不要となります。
jjutil.setFullScreen(swf, container, width, height, {
disableFrameSkip: true,
});
}, false);
</script></body></html>
更新履歴
- 2013/04/10
- Sandbox環境でExGameを起動する場合の記述を追加
- 2013/02/28
- useLessCanvasに関する記述を追加
- 2012/05/15
- TipsとExGame開発サポートツールに関する記述を追加
- 2012/01/16
- 動作環境に関する記述を追加
- 2012/04/02
- Tipsと開発サポートツールに関する記述を追加