HSP : HSP3Dish / onion software 2017(c)

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

android版 HSP3Dish概要
環境の準備
Platform APIインストール
HSP3Dish Helperの設定
新規プロジェクトの作成
ライブラリフォルダについて
プロジェクトのビルド
サンプルプロジェクト
実機への転送と実行
データファイルの準備
システム情報の取得
タスク(アクティビティ)呼び出し
hsp3dish.ini設定ファイルについて
マニュアル設定項目について
リリースビルド
HGIMG4プロジェクトについて
デバイスコントロールについて
AdMobによる広告配信
mes,print命令について
android版の注意事項、制限
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の実機上で動作させるためには、以下が必要となります。

android開発環境(SDK) → [ダウンロードサイト]
JDK(Java Development Kit) → [ダウンロードサイト]
Android NDK（Native Development Kit）開発環境 → [ダウンロードサイト]
Apache Ant(開発補助ツール) → [ダウンロードサイト]

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

HSP3Dish Helperの設定

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

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

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

Platform APIインストール

最初に、ビルドに必要なPlatform APIのインストールを行ってください。 HSP3Dish Helper(hsp3dh.exe)を起動して、「オプション」タブの「SDKマネージャー」ボタンから起動することができます。

このツールにより、必要なAPIをインストールすることができます。(ネットに接続されている必要があります)
「Android 4.4.2 (API 19)」のような形で、それぞれのバージョンに対応したAPIのチェックボックスが表示されます。この中で、「Android SDK Tools」「Android SDK Platform-tools」「Android SDK Build-tools」(最新のRev.)「Android 5.0.1 (API 21)」はチェックを入れて必ずインストールするようにしてください。 (「Android 5.0.1 (API 21)」はプログラムで使用できるAPIのレベルを示すもので、インストールする端末のバージョンとは関係ありません。通常は、「Android 5.0.1 (API 21)」をインストールすればすべての端末で動作させることができます。)
「Install packages...」のボタンを押すことで、ダウンロードとインストールが行なわれます。インストールされた項目は、「Installed」の表示が付加されます。

(何らかの理由でネット接続ができない環境で使用する場合は、一時的にネット接続可能な場所でインストールを行なった後、android開発環境(SDK)フォルダそのものを用意すれば、ビルドには問題ありません。)

新規プロジェクトの作成

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

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

プロジェクト名

プロジェクトのタイトル名となります。スペースを含まない英文字のみで指定してください。

ビルドのターゲットIDを設定します。ターゲットIDは、SDKのAPIバージョンを指定するための番号になります。デフォルトで「"android-21"」(5.0.1)が指定されています。通常は、変更する必要はありません。特に理由がない限りは、デフォルトのまま使用してください。
他のターゲットIDが必要な場合は、「ID...」ボタンを含めず押して表示される一欄の中からIDを選んで入力してください。

パッケージ名

アプリを識別するための情報となります。パッケージ名には、他のパッケージ名と重複しない名称が求められます。通常は、ドメインをトップレベルドメインから逆方法に並べたものを使うことが推奨されています。たとえば、「net.onionsoft.testapp」のように階層的に指定します。名称には、スペースを含まない英文字のみで指定してください。Javaのパッケージ命名規約なども参考にしてみてください。
パッケージ名を省略した場合は、日付とプロジェクト名から自動的に生成される文字列が適用されます。

AdMobを使用する

AdMobによる広告配信アプリを作成する場合にチェックを入れてください。 Google Play Services及びAndroid Support Libraryが必要となります。詳しくは、「AdMobによる広告配信」を参照してください。

ARM7最適化を無効

チェックを入れることでARM7に最適化されたコードの生成を無効にします。通常は、チェックを入れない状態(ARMv7コードに最適化)で使用してください。最適化を行なうことで、実行速度が向上します。 ARMv7を持たない古いAndroid端末で実行させる場合には、チェックを入れることで古いARMでも実行できるコードが生成されます。

HGIMG4を使用する

HGIMG4向けに作られたスクリプトを使用する場合にチェックを入れてください。 HGIMG4のプロジェクト作成については、「HGIMG4プロジェクトについて」の項目を参照してください。

センサーを使用する

デバイスの加速度、ジャイロセンサーの読み取りを有効にします。センサーを使用しない場合は、チェックを外しておくことでバッテリーの消費などを抑えることができます。

ライブラリフォルダについて

新規プロジェクト作成時に、ビルドに必要となるライブラリフォルダが作成されます。ライブラリフォルダは、オプションに設定されたプロジェクトの基本(ルート)フォルダ内に作成されます。
ライブラリフォルダとして作成されるものは、以下の通りです。

hsplib35～フォルダ

HSP3Dishのビルドに必要なランタイムのソースが含まれています。古いライブラリとの競合を防ぐため、「hsplib35b3」のようにHSPのバージョンごとに異なるフォルダ名が使用されます。

gameplayフォルダ

HGIMG4のビルドに必要なgameplayランタイムのソースが含まれています。

extlibフォルダ

HGIMG4のビルドに必要な各種ライブラリのソースが含まれています。

HSP3Dish Helper(hsp3dh.exe)を起動して、「オプション」タブの「ライブラリ更新」ボタンを押すことで、プロジェクトフォルダの内容が最新に上書きされます。HSPのアップデートや差し替えを行なった場合に行なっておいてください。

hsplib35～フォルダ内のソースには、各プロジェクトから共有されるHSP3Dishランタイムのソースが含まれます。ユーザーが独自にソースを変更することもできますが、HSP3Dish helperのアップデート等でソースが上書き更新されてしまうことがありますので、注意してください。

プロジェクトのビルド

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

上のようなプロジェクトビルドのダイアログが表示されます。(ビルドになっていない場合は、「既存プロジェクト」のボタンを押して下さい)
プロジェクトのビルドを行なうことで、指定されたHSPスクリプト及びデータファイルをandroidで実行できる形式(apkファイル)として出力されます。 android用アプリの開発では、実行のためのプログラムとデータをすべてまとめたapkファイルが最終的な出力結果となります。
ダイアログで設定する項目は、以下の通りです。

ソーススクリプト

通常は、この項目は空欄のままで、プロジェクトが使用するHSPスクリプト(.hsp)は、プロジェクトフォルダ以下の「hsp」フォルダ内に配置してください。 (HSPスクリプトが複数ある場合は、「main.hsp」という名前のファイルが優先されます。) 「hsp」フォルダを使わずに、直接スクリプトファイルを指定する場合は、ソーススクリプト項目の「参照」ボタンを押して、ファイルを選択することができます。
いずれの場合も、HSPスクリプト(.hsp)は、必ずHSP3Dish用に記述されたスクリプトでなければなりません。対象となるスクリプトが存在しない場合は、ソーススクリプトの変換は行なわれません。
フォルダに「hsp3dish.ini」ファイルが存在する場合は、画面サイズやスケーリングなどの設定が反映されます。詳しくは、「hsp3dish.ini設定ファイルについて」の項を参照してください。

データファイル(dpm)

スクリプトから参照されるデータが格納されているdpmファイルを指定します。dpmファイルは、HSPで使用している形式で、複数のファイルが1つのdpmファイルにパックされています。(「作成...」ボタンを押すことで、指定したフォルダ内にあるすべてのファイルをdata.dpmというファイルにパックして、そのファイルを指定することができます。) データファイルの指定が空欄の場合は、dpmファイルの参照はされません。詳しくは、データファイルの準備を参照してください。

プロジェクト名

ビルドの対象となるプロジェクトを選択します。プロジェクトのフォルダが作成されて、ビルドの準備が整っているものの中から、1つを選択することができます。 (「更新」ボタンを押すことで、プロジェクトのフォルダが再検索されます。)

プロジェクト名などの項目を指定した後、「ビルド」ボタンを押すことでビルドが開始されます。HSPのソーススクリプトの変換及びNDKのコンパイルからパッケージの生成までをすべて自動で行ないます。
ビルドの結果は、consoleウィンドウに表示されます。

正常に終了すると、「終了しました」のメッセージが表示され、プロジェクトフォルダ以下のbinに、apkファイルが生成されています。
「クリーン」ボタンを押すことで、ビルドされたデータを破棄してプロジェクトフォルダを初期化することができます。全体を再度ビルドする場合には、一度「クリーン」によりデータを破棄しておいてください。

サンプルプロジェクト

sample/hsp3dishフォルダには、HSP3Dishを使うためのサンプルスクリプトが含まれています。ブロック崩しのHSP3Dishサンプル(block3.hsp)を、ソーススクリプトに指定して、データファイル(dpm)は空欄のまま、ビルドを実行することができます。

実機への転送と実行

プロジェクトのビルドが完了したら、androidの実機またはシミュレータに転送して確認することが可能です。 (シミュレータ上での実行する場合は、HSP3Dish helperの「オプション」タブから「AVDマネージャー」を起動して、シミュレータを設定・起動してご使用ください)
androidの実機をUSBで接続し、OSから認識されている状態で「転送」ボタンを押すことで、ビルド済みのapkファイルを転送(インストール)します。後はアプリケーション一覧から、転送したアプリの実行を行なってください。
android実機の接続設定については、デバイスの機種ごとに異なります。以下のサイトなどを参考にしてみてください。

実機への転送ができない場合でも、ビルドで生成されたapkファイルをネットやUSBメモリを経由して転送してインストールを行ない実行の確認をすることも可能です。
「Logcat」ボタンを押して実行ログを表示させることが可能です。実機に転送して実行した際の、HSPからのエラーや初期化メッセージを確認することができます。

データファイルの準備

スクリプトから参照されるデータファイルは2通りの方法で用意することができます。 1つは、プロジェクトディレクトリ内のassetsフォルダにファイルをコピーするというものです。基本的には、こちらの方法を使用してください。 assetsフォルダには、画像ファイルを始めとして読み込みに使用するファイルをすべて入れておくことができます。
もう1つの方法は、「データファイル(dpm)」の項目で設定されているデータフォルダ(data.dpmを生成します)にファイルをコピーして使用する方法です。人に見られたくないデータや暗号化を使用したい人は、data.dpmのデータフォルダを使用するようにしてください。ただし、サウンドファイル(wav,mp3など)は認識されないので注意してください。また、data.dpmによるファイルパックからの読み出しには、HSPのpackfile仕様と同様の制限(ファイル名の長さ12文字以内)がありますので注意してください。サウンドのファイルは必ず、assetsフォルダに入れるようにしてください。

システム情報の取得

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

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

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

		exec "パッケージ名", 0, "クラス名"

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

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

		exec "URI文字列", 16

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

hsp3dish.ini設定ファイルについて

プロジェクトフォルダ内にある「hsp」フォルダ(HSPスクリプトを設置するフォルダ)に設定ファイル「hsp3dish.ini」がある場合は、その設定がビルド時に反映されます。
「hsp3dish.ini」は、Windows上で実行する際に画面サイズなどの設定を参照するためのファイルです。詳しくは、HSP3Dishプログラミングマニュアルを参照してください。「パラメーター名=設定値」のように記述することで、androidのビルド時に設定が反映されます。

		パラメーター名          設定内容
		----------------------------------------
		wx			画面のX(横)サイズ
		wy			画面のY(縦)サイズ
		autoscale		自動スケーリング値

画面のスケーリングを自動的に調整したい場合は、「autoscale=0」のように、自動スケーリング値を設定してください。描画した画面サイズを適切に拡大縮小し、現在のスクリーンに表示させることができます。
自動スケーリング値の詳細は以下の通りです。

		0 : 画面全体に収まる最適な大きさ(縦横比は維持)
		1 : X方向のサイズを基準に拡大縮小(縦横比は維持)
		2 : Y方向のサイズを基準に拡大縮小(縦横比は維持)
		3 : 縦横比は無視して画面全体に表示

指定された画面サイズによって、portrait(縦画面)、landscape(横画面)の向きが自動的に設定されます。
「hsp3dish.ini」が存在しない場合や、設定が書かれていない場合は、特に変更は行なわれません。「hsp3dish.ini」ファイルを使用せずに、マニュアルで設定を行なう場合は、「マニュアル設定項目について」の項目をお読み下さい。

マニュアル設定項目について

jniフォルダ内のmain.cソースを編集することで、HSP3Dishに関する各種設定を行ないます。
通常は、「hsp」フォルダに設定ファイル「hsp3dish.ini」を用意して設定を行なってください。ここでは、ソースコードを修正して、マニュアルで設定する方法について説明しています。
「static void engine_handle_cmd」で始まるソースコード(160行付近)にある以下の行を修正します。

		//hgio_view( 480, 320 );
		//hgio_scale( 1.0f, 1.0f );
		//hgio_autoscale( 0 );

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

		hgio_view( 480, 320 );

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

		hgio_scale( 2.0f, 2.0f );

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

		hgio_autoscale( 0 );

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

		0 : 画面全体に収まる最適な大きさ(縦横比は維持)
		1 : X方向のサイズを基準に拡大縮小(縦横比は維持)
		2 : Y方向のサイズを基準に拡大縮小(縦横比は維持)
		3 : 縦横比は無視して画面全体に表示

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

		hgio_uvfix( 1 );

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

リリースビルド

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

Googleに開発者登録を行なう(アプリを配布するためには、有償($25)の登録が必要になります)
署名のための証明書(keystore)を作成する
HSP3Dish Helperでリリースビルドを行なう
Android Developer Consoleからアップロードする

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

Googleに開発者登録を行なう

	http://developer.android.com/

androidのデベロッパーページを開き、「公開」(publish)の詳細ページを選択します。 Googleアカウントでサインインを行ない、開発者情報を適切に入力して登録を行ないます。
(電話番号の入力は、国番号を含めて行ないます。日本の場合は先頭に「81」を付け、市外局番の先頭「0」を省くのが決まりです。「03-1234-5678」の場合は、「+81-3-1234-5678」となります。)
次に、Google Checkoutを利用して登録の決済を行ないます。クレジットカード等を使って支払いを行なうことができます。
すべて終了すると、Android Developer Consoleのページにアクセスできるようになります。有料アプリを登録する場合は、さらに銀行の口座などのアカウント情報を設定する必要があります。

署名のための証明書(keystore)を作成する

まず、HSP3Dish Helperを起動し、androidタブの新規プロジェクトページを開きます。次に、「KEY作成」ボタンを押します。(キー名は、「hspapp」のままで問題ありません)
コマンドプロンプトの画面が開き、以下の項目について情報を求めてくるのでキーボードから入力してください。すべて半角英文字で入力することを推奨します。

	・パスワード
	・パスワード再入力
	・姓名
	・組織単位名(部門・部署名)
	・組織名(会社・団体名)
	・都市名または地域名(市町村名)
	・州名または地方名(都道府県名)
	・国番号(日本の場合は81を入力)
	・よろしいですか?(「y」を入力)
	・鍵パスワード(Enterを入力)

以上で、「hspapp.keystore」ファイルがプロジェクトフォルダのルートに作成されます。このファイルは、アプリ署名のために必要なので、削除しないで大切に保管しておいてください。

HSP3Dish Helperでリリースビルドを行なう

HSP3Dish Helperの、androidタブで既存プロジェクトページを開きます。ビルドしたいプロジェクトを選択し、通常のビルドを行なって正常に動作することを確認してください。
次に「リリース」ボタンを押してください。アプリのリリースビルドを実行し、署名を行ないます。この時、コマンドプロンプトの画面が開き、パスワードを求められるので「hspapp.keystore」を作成した時に入力したパスワードを入力してください。
以上で、プロジェクトのbinフォルダに「プロジェクト名.apk」のファイルが生成されます。

Android Developer Consoleからアップロードする

Android Developer Consoleのページで、新規のアプリを追加し、生成された「プロジェクト名.apk」のファイルをアップロードしてください。 (プロジェクト名-debug.apkや、プロジェクト名-release.apkのファイルは署名されていませんので、無効になります)
Google Playに登録を行なう場合は、紹介文やスクリーンショット、サポート情報などを設定する必要があります。
アップロードしたapkファイルをactivate(有効化)し、publish(公開)ボタンを押すことで、アプリを一般に公開します。(実際に公開されるまで、数時間の遅延があります)
公開されている情報は、Android Developer Consoleから、いつでも修正を行なうことができます。ファイルを更新する場合は、再度リリースビルドを行なって、apkファイルを差し替えた後にactivate(有効化)してください。ただし、更新を行なうためには、バージョン番号を上げる必要があります。プロジェクトが使用している「AndroidManifest.xml」ファイルの、android:versionCode、android:versionName項目の数値を更新してから、リリースビルドを行なうようにしてください。

※androidの新しいSDKでは、署名に使用されるzipalignツールが異なるフォルダに収録されています。「リリース」ボタンを押した際に「zipalignツールがありません。」というエラーが出る場合は、SDKフォルダのbuild-tools以下にある最新の「zipalign.exe」ファイルを、SDKフォルダのtools以下にコピーしてください。

HGIMG4プロジェクトについて

HSP3.5β3からHGIMG4スクリプトのビルドに対応しています。基本的には、Windows版と同様の仕様で使用できます。
HGIMG4プロジェクトは、初回のビルドに非常に時間がかかります。また、OpenGL/ES2の機能を使用するためandroid端末の環境や機種によっては、動作しなかったり、遅くなることがあります。
HGIMG4では、起動時に必ずresフォルダ及びシェーダー等のファイルが必要になります。 HSPの「sample/hgimg4」フォルダにある「resフォルダ」からandroid用のHGIMG4プロジェクトフォルダの「assets」以下にコピーしてください。(「assets/res/…」というフォルダ構成になります)
最低限必要なファイルは以下になります。

		res/font.gpb
		res/shaders フォルダ内のシェーダーファイル

以下の機能については、未対応なので注意してください。将来のバージョンで対応する予定です。

画面のサイズ指定、スケーリングに対応していません(hgio_view/hgio_scale等のマニュアル設定項目も機能しません)

AdMobの表示に非対応です

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

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

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

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

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

たとえば、

		devcontrol "vibrate",400

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

AdMobによる広告配信

従来のAdMobからの更新について

※HSP3Dish 3.4版までは、従来の(古い)AdMobライブラリを使用していましたが、 Googleの更新により、2014/8/1以降は、古いAdMobライブラリを使用したアプリの更新、及び新規追加はできなくなっています。(既に登録されているアプリに影響はありません。)
HSP3Dish 3.5版では、Google Firebaseを使用した新しいAdMobライブラリに切り替えているので、この制限はありません。古いAdMobライブラリを使用するプロジェクトを更新する場合は、新規でプロジェクトを作成し直してください。

広告配信のための準備

HSP3DishではAdMobを使った広告配信モデルのアプリを作成することが可能です。適切に設定を行なうことで、HSP3Dishのアプリから広告を配信し、収益を得ることができるようになります。 AdMobはGoogleが提供するモバイル広告配信の仕組みです。これをアプリに組み込むことで、無料アプリであっても広告料を得ることができます。
AdMobを組み込むためには、以下の手順で準備を行なっておく必要があります。

1. AdMobアカウントの作成

アカウントを登録し、支払い情報などの必要事項を記入します。
https://www.google.co.jp/admob/

2. ユニットIDの取得

AdMobのwebページにログインし、「新しいアプリの登録」を行ないます。 (アプリがまだGoogle Playで公開されていない段階でも可能です)
必要事項を記入することで、ユニットIDを取得することができます。

3. AdMobを使用するプロジェクトの作成

新規プロジェクトを作成します。その際に、必ず「AdMobを使用する」のチェックボックスをONにしておいてください。それ以外の設定は、通常の新規プロジェクト作成と変わりありません。

4. ユニットIDの登録

プロジェクトのフォルダ以下の「src/tv/hsp/HspActivity.java」ファイルを編集します。

		static final String APP_ID = "ca-app-pub-???????????????????????????";

の行を探してください。このAPP_IDの部分を、AdMobのwebページで取得したアプリID文字列に置き換えてください。このアプリIDにより、広告の配信者が特定されます。

		static final String BANNER_AD_UNIT_ID = "ca-app-pub-???????????????????????????";
		static final String INTERSTITIAL_AD_UNIT_ID = "ca-app-pub-???????????????????????????";

の行を探してください。BANNER_AD_UNIT_IDとINTERSTITIAL_AD_UNIT_IDには、広告ユニットIDを指定します。 BANNER_AD_UNIT_IDは、バナー広告で使用される広告ユニットIDを指定します。 INTERSTITIAL_AD_UNIT_IDは、インタースティシャル広告で使用される広告ユニットIDを指定します。これらのIDは本番のアプリで使用します。

5. AdMob表示スクリプトの追加

スクリプト実行時の適切なタイミングでAdMobを有効にするようにしてください。タイトル画面や、ゲームメニューなど画像や音声のリソース読み込みが落ち着いた後に有効にすることを推奨します。 (CPU負荷が高い時には、AdMobのタスクが遅延することがあります)
AdMobを有効にする場合は、

		devcontrol "AdMob",0		; AdMobを有効にする

をスクリプトに記述してください。("AdMob"の文字列は大小文字を正確に識別します) WindowsやiOSでは、この記述は無視されますが、複数機種実行時にAndroid上でのみ実行したい場合は、以下のように記述することができます。

		getreq v_platform,SYSREQ_PLATFORM
		if ( v_platform = PLATFORM_ANDROID ) {
			devcontrol "AdMob",0		; AdMobを有効にする
		}

「devcontrol "AdMob"」は、最初の実行時にAdMob表示を開始し、それ以降は実行しても無視されますので、タイトル画面表示時などに何度でも実行されても問題ありません。デフォルトでは、画面下にバナーとして広告が表示されます。 (この時、デバイスがネット接続可能な状態であることを確認しておいてください)

以上の準備でAdMobを使用したアプリをビルドすることが可能になります。

AdMobプロジェクトのビルド

プロジェクトの更新が完了したら、後は通常のHSP3Dishと同様に、HSP3Dish helperからプロジェクトのビルドを行なうことができます。
ビルド時にエラーが発生した場合は、エラーメッセージなどを参考にしながら、プロジェクトの設定に問題がないか確認をしてください。

ビルドが成功したら、デバイスに転送して実行を確認することができます。

実行の確認を何度も行なう場合には、テスト用端末の登録を行なっておいてください。テスト用端末の登録は、src/tv/hsp/HspActivity.javaファイルのソースで指定します。
以下の行があることを確認してください。また、Googleでは、テスト用の広告ユニットIDを使用することを推奨しています。
https://firebase.google.com/docs/admob/android/quick-start?hl=ja

		static final String TestDeviceID = "********************************";

デバイス上の動作チェックでは、"****～"の部分に、デバイスIDを記入する必要があります。 (エミュレーターの場合は、"****～"の代わりにAdRequest.DEVICE_ID_EMULATORを指定してください。)
端末のデバイスIDは、AdMob表示時にデバイスモニタ内のログに、

	「 To get test ads on this device, call adRequest.addTestDevice("********************************");」

というメッセージが流れますので、そこで確認することができます。デバイスモニタは、HSP3Dish Helperの、「オプション」タブの「Deviceモニター」ボタンを押して起動させることができます。 LogCatよりも詳細なログが表示されます。 (広告の表示エラーや、問題に関するメッセージも表示されます)

インタースティシャル広告について

全画面を使用したインタースティシャル広告を表示させることができます。

		devcontrol "AdMob",16		; インタースティシャル広告を表示する

インタースティシャル広告は表示のリクエストを行なうたびに、１回表示されます。通常のバナー広告と併用することも可能なので、より幅広い活用が可能になります。

アプリのリリース

AdMobの表示をサポートしたアプリは、通常のHSP3Dishアプリと同様の方法でビルドし、Google Playから配信することが可能です。リリース時には、テスト用端末の登録コードを削除するのを忘れないようにしてください。

     		.addTestDevice(TestDeviceID)

この行は、テスト用端末を登録するためのものです。 src/tv/hsp/HspActivity.javaファイルのソース内で２か所記述されています。
テストが終了して、本番のアプリとしてリリースする場合には、

     		//.addTestDevice(TestDeviceID)

のように先頭に「//」を入れて登録を無効にするコードに修正することを忘れないでください。

mes,print命令について

HSP3Dishでは、内蔵フォントによるmes及びprint命令の文字列描画に対応しています。(HGIMG4はフォントデータによる描画を行うため該当しません)
font命令で指定する、font名は無視され、フォントサイズは反映されます。また、フォントスタイルは標準(0)と太文字(1)にのみ対応しています。
android上のフォントを取得する処理は、システムの負担が大きいため一度描画した内容(テクスチャ)はHSP3Dish側でキャッシュすることで高速化する仕組みになっています。通常は、この仕組みについて意識することなく使用することができるはずです。
キャッシュ機能のコントロールを行ないたい場合は、setreq命令により設定を記述してください。(Windows,iOS版には影響ありません)

		setreq SYSREQ_MESCACHE_MAX, 64	; キャッシュの最大登録数を指定する

キャッシュの内部動作としては、一度表示したメッセージとまったく同じ内容の文字列があった場合に、以前のデータを再利用して表示することになります。ただし、８フレームの間表示されなかったキャッシュは破棄されます。
保持されるキャッシュの最大登録数は、デフォルトで64になっています。キャッシュの設定範囲は、0～128が目安で、数値が大きくても高速化されるとは限りません。あくまでも、顕著な速度低下を抑制することが目的で、もともとメッセージ表示はコストの高い処理であることをご理解の上使用してください。
キャッシュの最大登録数を0に設定した場合は、キャッシュによる高速化は行なわれません。

android版の注意事項、制限

入力可能な情報

タップした座標がmousex,mouseyに反映されるほか、stick命令により、クリック(タップ)のON/OFFを取得可能です。また、mtlist、mtinfo命令により高度なタッチ情報(マルチタッチなど)を取得することができます。複数ポイントのタッチ情報(マルチタッチ)は、デバイスがサポートしている場合のみ取得可能です。 Androidデバイスによっては、ハードウェアがマルチタッチをサポートしていない場合がありますので、注意してください。

画像フォーマットについて

celload、picload命令などで読み込まれる画像は、以下のフォーマットが使用できます。アルファチャンネルを使用する場合は、PNG形式が推奨されます。

JPEG baseline (プログレッシブJPEGは非サポート)
PNG (1bit、2bit、4bit、8bit、24bit、24bit+アルファチャンネル形式に対応)
TGA (サブセット)
BMP (白黒、RLE圧縮は非サポート)
PSD (RGB24bitのみ読み出し)
GIF
HDR (radiance rgbE format)
PIC (Softimage PIC)

gmodeの制約について

現在のバージョンでは、gmode 6(色減算)はサポートされていません。これは、android(NDK)版のみの制約事項です。将来のバージョンでは、対応を行なっていく予定です。

画像サイズについて

celload、picload命令などで読み込まれる画像の縦・横サイズが、2048を越えるものについては、正しく扱えない機種もあるので、推奨されません。縦・横のサイズが2^nのサイズ、つまり1,2,4,8,16,32,64,128,256,512,1024でない画像を読み込む時には、内部で変換を行なうため多少のオーバーヘッドが発生します。 (通常はそれほど気にする必要はありません。大量の画像を読み込む場合にCPUリソースが余計に必要となります)
画像ファイルはプロジェクトディレクトリ内のassetsフォルダに入れることができます。ただし、古い端末などではリソースのサイズ・個数に制限がある場合があります。 1つのファイルが4MBを越えるような大きなファイルを多数使用する場合は、data.dpmに含めて使用することを推奨します。

再生可能なサウンドファイルについて

mmload命令で同時に読み込むバッファの数が30を超えた場合、正しく再生されない報告を頂いています。
これは、android上のOpenSL/ES上の制約によるもので、この問題は修正していく予定です。とり急ぎは、mmloadで使用するバッファの数を必要に応じて切り替えるなどして30以下に抑えるようお願い致します。 (特に音楽の再生などは、同時に行なう必要がないので1つのバッファIDを共有するようにした方がいいです)
尚、android上だけの制限なので、WindowsやiOS上では問題ありません。

サウンドは、拡張子が「.wav」「.mp3」「.ogg」「.aac」のファイルに対応しています。 .aacや.oggについては、すべてのフォーマットをサポートしていないので注意してください。「.wav」「.mp3」については、Windows版を含めすべてのhsp3dishで幅広くサポートされている形式です。
サウンドのファイルは必ずプロジェクトディレクトリ内のassetsフォルダに入れるようにしてください。data.dpmに含めるとOSのシステム側から読み取ることができません。

画面の回転について

現在のバージョンでは、実行中の画面自動回転には対応していません。必ず、縦・横画面を固定して動作する仕様で作成してください。
hsp3dish.ini設定ファイルにより、画面サイズが指定されている場合は、自動的に縦画面・横画面の設定が行なわれます。
マニュアルで、画面の向き(回転)を設定したい場合は、AndroidManifest.xmlを書き換えて制御することが可能です。

        <activity android:name="android.app.NativeActivity"
	          android:screenOrientation="portrait"
                  android:label="@string/app_name">

「android:screenOrientation=」の行で指定されているパラメーターが、"portrait"の場合は縦画面。"landscape"の場合は、横画面にそれぞれ固定されます。

データの保存について

bsave、bload命令によってアプリケーション固有のフォルダにデータファイルの読み書きが可能です。「/」を含めずファイル名(半角英文字)のみ指定された場合は、アプリケーション固有のフォルダ (「/data/data/<自分のパッケージ名>/files」で示される場所)がアクセス対象となります。このフォルダは通常は、自分以外のアプリケーションからはアクセスできない設定になっています。 (ファイル名が「/」で始まった場合は、フルパス指定となります。)

android版の更新予定

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

各種システム情報取得
カメラ、ブラウザの呼び出しサポート

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