HSP : HSP3Dish / onion software 2012(c)
android版 HSP3Dishは、android OS搭載機種(スマートフォン、タブレット等)上で動作するHSP3Dishのランタイムです。
Windows版 HSP3Dishがサポートする機能をandroid OS上で再現することが可能です。
(android版 HSP3Dishは、Windows版のスクリプトを実行させることを目的としており、HSP3開発システムそのものをiOS上で再現するものではありません。)
このマニュアルでは、android版の利用方法、注意点などを説明していきます。
現状ではandroid上で実行できるファイルをビルドするためには、開発のための環境設定を行なう必要があります。開発環境の構築に費用はかかりません。すべて無料で準備することができます。
これらは、Windows上で動作し、接続されているandroidデバイス上で動作の確認を行なうことができます。
HSP3Dishでのビルドを支援するための、HSP3Dish Helperツールが同梱されています。
これにより、比較的スムーズにandroid向けにビルドを行なうことが可能になります。
(尚、統合開発環境Eclipse上でお使い頂くことも可能ですが、
手順が多いためHSP3Dish Helperの利用を推奨しています。)
androidの実機上で動作させるためには、以下が必要となります。
最新版のWindows版(インストーラーではない)zipアーカイブを任意のフォルダに解凍してください。推奨フォルダは、「c:\android\android-sdk〜」です。
最新版のJDK (Java Development Kit)をインストールしてください。x86版、x64版どちらでも構いません。
最新版のWindows版zipアーカイブを任意のフォルダに解凍してください。推奨フォルダは、「c:\android\android-ndk〜」です。
最新版のzipアーカイブを任意のフォルダに解凍してください。推奨フォルダは、「c:\android\apache-ant〜」です。
推奨するフォルダにアーカイブを解凍した場合、上のような状態になります。(英文字のみ、スペースを含まないフォルダ名を使用してください)
ビルドに必要なPlatform APIのインストールを行ないます。 android開発環境(SDK)フォルダ内にある、「SDK Manager.exe」を実行してください。
このツールにより、必要なAPIをインストールすることができます。(ネットに接続されている必要があります)
「Android 4.0.3 (API 15)」のような形で、それぞれのバージョンに対応したAPIのチェックボックスが表示されます。
この中で、「Tools」「Android 2.3.3 (API 10)」はチェックを入れて必ずインストールするようにしてください。
それ以外のバージョンは必要に応じてインストールして頂いて構いません。
「Install packages...」のボタンを押すことで、ダウンロードとインストールが行なわれます。
インストールされた項目は、「Installed」の表示が付加されます。
HSPインストールフォルダ(最新版のHSP3Dish開発セットによりアップデートされている必要があります)にあるHSP3Dish Helper(hsp3dh.exe)を起動してください。
「オプション」ボタンを押して表示される画面で、android開発環境(SDK)などのインストール行なったフォルダの場所を設定してください。
推奨するフォルダにインストールされた場合、上のような設定になります。
最後の「プロジェクト」フォルダ設定は、android用にアプリをビルドする際に作成されるプロジェクトフォルダの起点になる位置を示します。推奨フォルダは、「c:\android」です。
HSP3Dish Helper(hsp3dh.exe)を起動して、中央下にある「android」ボタンを押して、androidビルドのモードにします。
上のようなプロジェクト新規作成のダイアログが表示されます。(新規作成になっていない場合は、「新規プロジェクト」のボタンを押して下さい)
以下の項目を設定して「新規作成」ボタンを押すことで、指定したプロジェクトのフォルダが作成され、android用のビルド準備が整います。
android用アプリの開発では、1つのアプリにつき必ず1つのプロジェクトファイルを作成する必要があります。プロジェクトのフォルダは、設定メニューで設定されている場所を起点に作成されます。
プロジェクトのタイトル名となります。スペースを含まない英文字のみで指定してください。
ビルドのターゲットIDを設定します。ターゲットIDは、SDKのAPIバージョンを指定するための番号になります。このIDは、「ID一覧...」ボタンを押すことで一覧を表示させることができます。
HSP3Dishでは、Android 2.3.3(API Level10)以上が必要になります。 ターゲットとなる環境に合わせてIDを指定して下さい。上の例では、ID2がAndroid 2.3.3となります。
アプリを識別するための情報となります。パッケージ名には、他のパッケージ名と重複しない名称が求められます。
通常は、ドメインをトップレベルドメインから逆方法に並べたものを使うことが推奨されています。たとえば、「net.onionsoft.testapp」のように階層的に指定します。
名称には、スペースを含まない英文字のみで指定してください。Javaのパッケージ命名規約なども参考にしてみてください。
パッケージ名を省略した場合は、日付とプロジェクト名から自動的に生成される文字列が適用されます。
HSP3Dish Helper(hsp3dh.exe)を起動して、中央下にある「android」ボタンを押して、androidビルドのモードにします。
上のようなプロジェクトビルドのダイアログが表示されます。(ビルドになっていない場合は、「既存プロジェクト」のボタンを押して下さい)
プロジェクトのビルドを行なうことで、指定されたHSPスクリプト及びデータファイルをandroidで実行できる形式(apkファイル)として出力されます。
android用アプリの開発では、実行のためのプログラムとデータをすべてまとめたapkファイルが最終的な出力結果となります。
ダイアログで設定する項目は、以下の通りです。
実行するためのHSPスクリプト(.hsp)を指定します。必ずHSP3Dish用に記述されたスクリプトでなければなりません。「参照」ボタンを押すことで、ファイル選択ダイアログを開くことができます。
スクリプトから参照されるデータが格納されているdpmファイルを指定します。dpmファイルは、HSPで使用している形式で、複数のファイルが1つのdpmファイルにパックされています。「作成...」ボタンを押すことで、指定したフォルダ内にあるすべてのファイルをdata.dpmというファイルにパックして、そのファイルを指定することができます。 データファイルの指定が空欄の場合は、データのないスクリプトとして処理されます。
ビルドの対象となるプロジェクトを選択します。プロジェクトのフォルダが作成されて、ビルドの準備が整っているものの中から、1つを選択することができます。 (「更新」ボタンを押すことで、プロジェクトのフォルダが再検索されます。)
プロジェクト名などの項目を指定した後、「ビルド」ボタンを押すことでビルドが開始されます。HSPのソーススクリプトの変換及びNDKのコンパイルからパッケージの生成までをすべて自動で行ないます。
ビルドの結果は、consoleウィンドウに表示されます。
正常に終了すると、「終了しました」のメッセージが表示され、プロジェクトフォルダ以下のbinに、apkファイルが生成されています。
「クリーン」ボタンを押すことで、ビルドされたデータを破棄してプロジェクトフォルダを初期化することができます。全体を再度ビルドする場合には、一度「クリーン」によりデータを破棄しておいてください。
sample/hsp3dishフォルダには、HSP3Dishを使うためのサンプルスクリプトが含まれています。
ブロック崩しのHSP3Dishサンプル(block3.hsp)を、ソーススクリプトに指定して、
データファイル(dpm)は空欄のまま、ビルドを実行することができます。
プロジェクトのビルドが完了したら、androidの実機に転送して確認することが可能です。
(エミュレータ上での実行は現在まだサポートされていません)
androidの実機をUSBで接続し、OSから認識されている状態で「転送」ボタンを押すことで、ビルド済みのapkファイルを転送(インストール)します。
後はアプリケーション一覧から、転送したアプリの実行を行なってください。
android実機の接続設定については、デバイスの機種ごとに異なります。以下のサイトなどを参考にしてみてください。
実機への転送ができない場合でも、ビルドで生成されたapkファイルをネットやUSBメモリを経由して転送してインストールを行ない実行の確認をすることも可能です。
「Logcat」ボタンを押して実行ログを表示させることが可能です。実機に転送して実行した際の、HSPからのエラーや初期化メッセージを確認することができます。
スクリプトから参照されるデータファイルは2通りの方法で用意することができます。
1つは、「データファイル(dpm)」の項目で設定されているデータフォルダ(data.dpmを生成します)にファイルをコピーして使用する方法。基本的には、こちらの方法を使用してください。
ただし、サウンドファイル(wav,mp3など)は認識されないので注意してください。
もう1つの方法は、プロジェクトディレクトリ内のassetsフォルダにファイルをコピーするというものです。サウンドのファイルは必ず、assetsフォルダに入れるようにしてください。
assetsフォルダには、画像ファイルを入れることも可能ですが、assetsフォルダのリソースのサイズ・個数に制限があるため、1MBを越える大きなファイルを多数使用する場合は、data.dpmのデータフォルダを使用してください。
また、テキストファイルなどその他のデータファイルは必ず、data.dpmのデータフォルダを使用するようにしてください。
sysinfo関数によりOSバージョン及び、デバイス名を取得することが可能になりました。
sysinfo(0)で、「android 2.3.3」のような文字列を取得することができます。これにより、ソース中で現在動作しているOSやバージョンを判別可能です。
また、sysinfo(2)で、デバイス名を取得することができます。現在、sysinfo関数の他の項目はサポートされていません。
exec命令により、他のタスク(アクティビティ)を呼び出すことが可能です。
exec "パッケージ名", 0, "クラス名"
2番目のパラメーター(実行モード)が0の場合は、「パッケージ名」「クラス名」により、
実行するタスクを指定します。
セキュリティの解除が必要な場合は、「AndroidManifest.xml」の
より手軽に実行する手段として、URIを指定してアプリを呼び出す方法があります。
exec "URI文字列", 16
たとえば、URIに「http://hsp.tv」を指定した場合は、規定のwebブラウザを開きURLとして表示します。 「tel:123456789」によりダイアラーを起動します。他にもOSがサポートする様々な呼び出し方法が存在します。
タップした座標がmousex,mouseyに反映されます。 またstick命令により、クリック(タップ)のON/OFFを取得可能です。
celload、picload命令などで読み込まれる画像は、以下のフォーマットが使用できます。 アルファチャンネルを使用する場合は、PNG形式が推奨されます。
celload、picload命令などで読み込まれる画像の縦・横サイズが、2048を越えるものについては、正しく扱えない機種もあるので、推奨されません。
縦・横のサイズが2^nのサイズ、つまり1,2,4,8,16,32,64,128,256,512,1024でない画像を
読み込む時には、内部で変換を行なうため多少のオーバーヘッドが発生します。
(通常はそれほど気にする必要はありません。大量の画像を読み込む場合にCPUリソースが余計に必要となります)
画像ファイルはプロジェクトディレクトリ内のassetsフォルダに入れることができます。
ただし、リソースのサイズ・個数に制限があるため、1MBを越える大きなファイルを多数使用する場合は、data.dpmに含めて使用してください。
現在のバージョンでは、mes及びprint命令で表示可能な文字列は半角英文字・記号のみになっています。デフォルトで16x16ドットの固定フォントが用意されています。
拡張子が「.wav」「.mp3」「.ogg」「.aac」のファイルに対応しています。
.aacや.oggについては、すべてのフォーマットをサポートしていないので注意してください。
「.wav」「.mp3」については、Windows版を含めすべてのhsp3dishで幅広くサポートされている形式です。
サウンドのファイルは必ずプロジェクトディレクトリ内のassetsフォルダに入れるようにしてください。data.dpmに含めるとOSのシステム側から読み取ることができません。
画面の回転については、AndroidManifest.xmlを書き換えて抑制することが可能です。
<activity android:name="android.app.NativeActivity" android:screenOrientation="portrait" android:label="@string/app_name">
上で示した位置に、「android:screenOrientation=」の行を追加してください。
以下の機能は今後、上から順に高い優先度で追加される予定です。
バージョンアップの告知は、HSPオフィシャルサイトHSPTV!にて行なわれますので、随時ご確認ください。