HSP : HSP3Dish / onion software 2014(c)

タイトル

HSP3Dish android(NDK)版プログラミングガイド

  1. android版 HSP3Dish概要
  2. 環境の準備
  3. Platform APIインストール
  4. HSP3Dish Helperの設定
  5. 新規プロジェクトの作成
  6. プロジェクトのビルド
  7. サンプルプロジェクト
  8. ソースのコンパイル
  9. 実機への転送と実行
  10. データファイルの準備
  11. システム情報の取得
  12. タスク(アクティビティ)呼び出し
  13. 画面サイズのスケーリングについて
  14. リリースビルド
  15. デバイスコントロールについて
  16. AdMobによる広告配信
  17. android版の注意事項、制限
  18. android版の更新予定

android版 HSP3Dish概要

android版 HSP3Dishは、android OS搭載機種(スマートフォン、タブレット等)上で動作するHSP3Dishのランタイムです。 Windows版 HSP3Dishがサポートする機能をandroid OS上で再現することが可能です。 (android版 HSP3Dishは、Windows版のスクリプトを実行させることを目的としており、HSP3開発システムそのものをandroid上で再現するものではありません。)
このマニュアルでは、android版の利用方法、注意点などを説明していきます。

現状ではandroid上で実行できるファイルをビルドするためには、開発のための環境設定を行なう必要があります。開発環境の構築に費用はかかりません。すべて無料で準備することができます。 これらは、Windows上で動作し、接続されているandroidデバイス上で動作の確認を行なうことができます。
HSP3Dishでのビルドを支援するための、HSP3Dish Helperツールが同梱されています。 これにより、比較的スムーズにandroid向けにビルドを行なうことが可能になります。 (尚、統合開発環境Eclipse上でお使い頂くことも可能ですが、 手順が多いためHSP3Dish Helperの利用を推奨しています。)

環境の準備

androidの実機上で動作させるためには、以下が必要となります。


推奨するフォルダにアーカイブを解凍した場合、上のような状態になります。(英文字のみ、スペースを含まないフォルダ名を使用してください)

Platform APIインストール

ビルドに必要なPlatform APIのインストールを行ないます。 android開発環境(SDK)フォルダ内にある、「SDK Manager.exe」を実行してください。


このツールにより、必要なAPIをインストールすることができます。(ネットに接続されている必要があります)
「Android 4.2.2 (API 17)」のような形で、それぞれのバージョンに対応したAPIのチェックボックスが表示されます。 この中で、「Tools」「Android 4.2.2 (API 17)」はチェックを入れて必ずインストールするようにしてください。 それ以外のバージョンは必要に応じてインストールして頂いて構いません。
「Install packages...」のボタンを押すことで、ダウンロードとインストールが行なわれます。 インストールされた項目は、「Installed」の表示が付加されます。

HSP3Dish Helperの設定

HSPインストールフォルダ(最新版のHSP3Dish開発セットによりアップデートされている必要があります)にあるHSP3Dish Helper(hsp3dh.exe)を起動してください。


「オプション」ボタンを押して表示される画面で、android開発環境(SDK)などのインストール行なったフォルダの場所を設定してください。


推奨するフォルダにインストールされた場合、上のような設定になります。
最後の「プロジェクト」フォルダ設定は、android用にアプリをビルドする際に作成されるプロジェクトフォルダの起点になる位置を示します。推奨フォルダは、「c:\android」です。

新規プロジェクトの作成

HSP3Dish Helper(hsp3dh.exe)を起動して、中央下にある「android」ボタンを押して、androidビルドのモードにします。


上のようなプロジェクト新規作成のダイアログが表示されます。(新規作成になっていない場合は、「新規プロジェクト」のボタンを押して下さい)
以下の項目を設定して「新規作成」ボタンを押すことで、指定したプロジェクトのフォルダが作成され、android用のビルド準備が整います。 android用アプリの開発では、1つのアプリにつき必ず1つのプロジェクトファイルを作成する必要があります。プロジェクトのフォルダは、設定メニューで設定されている場所を起点に作成されます。

プロジェクトのビルド

HSP3Dish Helper(hsp3dh.exe)を起動して、中央下にある「android」ボタンを押して、androidビルドのモードにします。


上のようなプロジェクトビルドのダイアログが表示されます。(ビルドになっていない場合は、「既存プロジェクト」のボタンを押して下さい)
プロジェクトのビルドを行なうことで、指定されたHSPスクリプト及びデータファイルをandroidで実行できる形式(apkファイル)として出力されます。 android用アプリの開発では、実行のためのプログラムとデータをすべてまとめた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のデータフォルダを使用するようにしてください。
ただし、data.dpmによるファイルパックからの読み出しには、HSPのpackfile仕様と同様の制限(ファイル名の長さ12文字以内)がありますので注意してください。

システム情報の取得

sysinfo関数によりOSバージョン及び、デバイス名を取得することが可能になりました。 sysinfo(0)で、「android 2.3.3」のような文字列を取得することができます。これにより、ソース中で現在動作しているOSやバージョンを判別可能です。
また、sysinfo(2)で、デバイス名を取得することができます。現在、sysinfo関数の他の項目はサポートされていません。

タスク(アクティビティ)呼び出し

exec命令により、他のタスク(アクティビティ)を呼び出すことが可能です。

２番目のパラメーター(実行モード)が0の場合は、「パッケージ名」「クラス名」により、 実行するタスクを指定します。 セキュリティの解除が必要な場合は、「AndroidManifest.xml」のに起動するクラスを記述してください。

より手軽に実行する手段として、URIを指定してアプリを呼び出す方法があります。

たとえば、URIに「http://hsp.tv」を指定した場合は、規定のwebブラウザを開きURLとして表示します。 「tel:123456789」によりダイアラーを起動します。他にもOSがサポートする様々な呼び出し方法が存在します。

画面サイズのスケーリングについて

最初に作成された解像度と異なるスクリーン上で実行する際に、スケーリング(拡大縮小)を適用することができます。
jniフォルダ内のmain.cソースを編集することで、スケーリングに関する設定を行ないます。
「static void engine_handle_cmd」で始まるソースコード(160行付近)にある以下の行を修正します。

行頭が「//」になっている項目は、コメントアウトされ機能しません。 初期設定では、スケーリングの設定は行なっていませんので、上のようになっているはずです。

まず、「//」を消去して、hgio_viewの行を有効にします。hgio_viewにより、もともとの画面サイズ(スクリプトが動作する解像度)を設定してください。上の例では、横サイズが480、縦サイズが320であることを示しています。

指定した倍率で表示を行ないたい場合は、hgio_scaleの行を有効にします。hgio_scaleにより、もともとの画面サイズに対して、指定した倍率で表示を行ないます。倍率を固定したい場合には、こちらを使用してください。通常は、hgio_autoscaleを使用することを推奨します。

画面のスケーリングを自動的に調整したい場合は、hgio_autoscaleの行を有効にします。hgio_autoscaleにより、描画した画面サイズを適切に拡大縮小し、現在のスクリーンに表示させます。
カッコ内の数値で、スケーリングの方法をいくつか指定することができます。

スケーリングの設定は、起動時に行なわれます。スクリプト実行中に変更することはできません。

テクスチャを拡大した際に、隣のピクセルがブレンドされてしまう現象を補正します。 通常はこのオプションを指定する必要はありませんが、画面のスケーリング等で正しくテクスチャが表示されない場合に試してみてください。
カッコ内の数値が0以外の場合は補正がONになります。0の場合は補正がOFFになります。

デバイスコントロールについて

Androidデバイス固有の機能にdevcontrolなどの命令でアクセスすることが可能です。

		devcontrol "コントロールコマンド",パラメーター1,パラメーター2,パラメーター3

上のような書式で、デバイスコントロールを行ないます。 Androidデバイス上では、文字列として指定するコントロールコマンドは、以下を認識します。 (コントロールコマンドの文字列は、大文字小文字も含めて完全に一致する必要があります。)
認識しないコントロールコマンドを記述した場合もエラーは発生しませんので注意してください。 

	コントロールコマンド    内容
	-------------------------------------------
	vibrate			バイブ(振動)動作(パラメーター1)
	AdMob			AdMobによる広告の表示

たとえば、 

		devcontrol "vibrate",400

は、バイブ(振動)動作を行なうようデバイスに指示を出します。
パラメーターの数値を変えることにより、振動の長さ(ミリ秒単位)を変えることができます。

リリースビルド

HSP3Dish Helperからリリースビルドを行なうと、署名入りのapkファイルを生成することができます。これにより、Google Play(Android マーケット)に作成したアプリを登録することが可能になります。 公開するための、おおまかな手順は以下の通りです。

順を追って説明していきます。

AdMobによる広告配信

android版の注意事項、制限

android版の更新予定

以下の機能は今後、上から順に高い優先度で追加される予定です。

バージョンアップの告知は、HSPオフィシャルサイトHSPTV!にて行なわれますので、随時ご確認ください。

ONION software