HSP : HSP3Dish / onion software 2022(c)

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

1. android版 HSP3Dish概要
2. 環境の準備
3. Platform APIインストール
4. HSP3Dish Helperの設定
5. 新規プロジェクトの作成
6. プロジェクトのビルド
7. サンプルプロジェクト
8. androidエミュレータ
9. 実機への転送と実行
10. HSP3Dish P Helperについて（New!）
11. アイコンの作成について（New!）
12. データファイルの準備（New!）
13. システム情報の取得
14. タスク(アクティビティ)呼び出し
15. hsp3dish.ini設定ファイルについて
16. マニュアル設定項目について
17. ネットワーク通信について
18. リリースビルド
19. HGIMG4プロジェクトについて
20. デバイスコントロールについて
21. AdMobによる広告配信
22. mes,print命令について
23. android版の注意事項、制限
24. 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向けにビルドを行なうことが可能になります。

※HSP3.6までのHSP3Dish HelperとはSDK、プロジェクトフォルダともに互換性がありません、HSP3.7使用時は新しく環境の構築を行ってください。

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

- android開発環境(SDK) → [ダウンロードサイト]

  Download Options(ダウンロードオプション)から、コマンドライン ツールのみ(Command line tools only)を入手する必要があります。 最新のWindowsバージョンをダウンロードできますので、まずそちらを用意してください。(Command line tools only、Platform Windows版のcommandlinetools-win-???????_latest.zip ファイル)
  次に、zipアーカイブの内容を任意のフォルダにインストールしてください。推奨フォルダは、「c:\and-sdk」です。
  ※英文字のみ、スペースを含まないフォルダ名を使用してください
  (commandlinetools-winからは「cmdline-tools」フォルダが取り出せるはずです。「c:\and-sdk\cmdline-tools」のような形になるようにしてください)

- JDK(Java Development Kit) → [ダウンロードサイト]

  JDK (Java Development Kit)をインストールしてください。JavaSE 16、またはJavaSE 17を推奨します。

  ※できる限り、64bit環境で64bit版をご使用ください。32bit環境での検証は行っていません。

## HSP3Dish Helperの設定

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

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

推奨するフォルダにインストールされた場合、上のような設定になります。
「Javaフォルダ」には、インストールされたJavaが存在している場所を指定してください。
「SDK Gradle」は、android SDKインストール対象のフォルダ、「プロジェクト」フォルダ設定は、android用にアプリをビルドする際に作成されるプロジェクトフォルダの起点になる位置を示します。推奨フォルダは、「c:\and_project」です。

※HSP3.6までのHSP3Dish HelperとはSDKやプロジェクトの構成が異なるため、アップデートした際には別なフォルダを指定してください

## SDKセットアップ

最初に、ビルドに必要なツール類、Platform APIのインストールを行う必要があります。 HSP3Dish Helper(hsp3dh.exe)を起動して、「オプション」タブの「SDKセットアップ」ボタンを押してください。

このセットアップにより、必要なファイルをインストールすることができます。ダウンロードを行うので、ネットに接続されている必要があります。(回線の速度により時間がかかる場合がありますので、しばらくお待ちください)
何らかの理由でネット接続ができない環境で使用する場合は、一時的にネット接続可能な場所で インストールを行なった後、android開発環境(SDK)フォルダそのものを用意すれば、ビルドには問題ありません。

## 新規プロジェクトの作成

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

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

- プロジェクト名

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

- パッケージ名

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

- AdMobを使用する

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

- x86をビルドしない

チェックを入れることでx86向けプロセッサのコードの生成を無効にします。 チェックを入れた状態(x86ビルド無効)で使用することで、ビルド時間を短縮することが可能です。

- HGIMG4を使用する

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

- センサーを使用する

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

## プロジェクトのビルド

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

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

- ソーススクリプト

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

- Assetフォルダ

スクリプトから参照されるデータが格納されるAssetsフォルダにファイルを準備してください。
「Assetフォルダを開く」ボタンを押すことで、対象のフォルダを表示させることができます。 詳しくは、データファイルの準備を参照してください。

- プロジェクト名

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

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

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

## サンプルプロジェクト

sample/hsp3dishフォルダには、HSP3Dishを使うためのサンプルスクリプトが含まれています。 ブロック崩しのHSP3Dishサンプル(block3.hsp)と設定ファイル(hsp3dish.ini)をプロジェクトのhspフォルダにコピーして、ビルドを実行することができます。
他のサンプルも同様にビルドすることが可能です。画像やサウンドのデータを使用するサンプルの場合は、Assetsフォルダにコピーするのを忘れないでください。

## androidエミュレータ

SDKが正しくセットアップされていれば、AVD(Android仮想デバイス)を作成してエミュレータを起動することが可能です。 「オプション」タブの「AVDマネージャー」ボタンを押してAVDマネージャーのモードに入ります。

最初に、AVD(Android仮想デバイス)を作成する必要があります。左上の選択リストから必要なデバイスを選択してください。標準的なスマホであれば、Pixel2～4などを選択します。
次にNameの部分にAVDの名称を入力してください。「MyAVD」など英文字のわかりやすい名前を指定します。その後、「AVD作成」ボタンを押すとデバイスが作成されます。
以降は、「起動」ボタンを押すことで指定された名前の仮想デバイスを起動することができます。仮想デバイス上でAdMobを含むアプリの実行テストを行うことが可能です。

## 実機への転送と実行

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

- 「開発者向けオプション」をオンにする [@IT]

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

## HSP3Dish P Helperについて

HSP3.7β2から、しまくろねこさん作成によるDish P Helperをパッケージに同梱しています。
androidプロジェクトを選択した状態で、「Dish P Helper」ボタンを押すことでツールが起動されます。
(HSPインストールフォルダから「dish_p_helper.exe」を直接起動することも可能です)
Dish P Helperでは、以下の項目をGUIにより設定することが可能です。詳しくは、ツールの説明書を参照してください。

    	    ・バージョンコード(versionCode)
    	    ・バージョンネーム(versionName)
    	    ・最小要求API(minSdk)
    	    ・ターゲットAPI(targetSdk)
    	    ・パッケージ名(package/applicationId)
    	    ・画面の向き(screenOrientation)
    	    ・画面サイズ(hgio_view)　横/縦
    	    ・画面表示倍率(hgio_scale)　横/縦
    	    ・自動拡大縮小(hgio_autoscale)
    	    ・アプリ名(英語)
    	    ・アプリ名(日本語)

## アイコンの作成について

HSP3.7β2から、しまくろねこさん作成によるAndroid/iOSアイコン作成ツールをパッケージに同梱しています。
「オプション」タブを選択した状態で、「Android/iOSアイコン作成ツール」ボタンを押すことでツールが起動されます。
詳しい使用方法は、ツールの説明書を参照してください。

## データファイルの準備

スクリプトから参照されるデータファイルは、プロジェクトディレクトリ内のassetsフォルダに入れてください。
「Assetフォルダを開く」ボタンを押すことで、プロジェクト内のassetsフォルダを表示させることができます。 assetsフォルダには、画像ファイルを始めとして読み込みに使用するファイルをすべて入れておくことができます。
ただし、Windowsとは異なりファイル名の大文字・小文字が区別されますので正しくファイル名を記述する必要がありますのでご注意ください。
HGIMG4プロジェクトを作成している場合は、「res」フォルダをそのままassetsフォルダにコピーしてご使用ください。

HSP3.7β2以降では、複数のファイルをパックしたdpmファイルを使用することが可能です。 Windows上で作成した「data.dpm」ファイルを、他のファイルと同様にプロジェクトディレクトリ内のassetsフォルダに入れてください。 「data.dpm」ファイルは起動時に自動的に読み込まれてパックされたファイルを読み込むことができるようになります。 (ただし、.mp3や.oggファイルなどシステム側で読み込むファイルをパックすることはできませんのでご注意ください)
また、暗号化されたdpmファイルにも対応しているほか、chdpm命令によりdpmファイルを追加することが可能です。
詳しい使用方法は、HSPプログラミング・マニュアルのファイルのパックと暗号化を参照してください。

## システム情報の取得

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

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

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

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

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

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

    		exec "URI文字列", 16

たとえば、URIに「https://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」ファイルを使用せずに、マニュアルで設定を行なう場合は、「マニュアル設定項目について」の項目をお読み下さい。

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

HSP3Dishに関する各種設定は、HSP3Dish P Helperで行うことが可能です。 ここでは、手動で設定する方法について解説していますが、通常はHSP3Dish P Helperをご使用ください。
jniフォルダ内のmain.cppソースを編集することで、HSP3Dishに関する各種設定を行ないます。
「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になります。

## ネットワーク通信について

android上で、httpload、httpinfo等の命令を使ってネットワーク通信を行うことが可能です。 ただし、android8.0以降ではOSの仕様により、httpsアクセス(暗号化された通信)のみを許可し、 httpアクセスは基本的に禁止されています。
たとえば、「http://www.onionsoft.net」にアクセスする場合は、「https://www.onionsoft.net」に 変更することで、通信が可能になります。 (不特定のhttpサーバーへのアクセスは、基本的にはできないと考えてください)
サーバー側の仕様によってはhttpsでのアクセスが できないことがあります。その場合は、「network_security_config.xml」ファイルを追加して 特定のURL(ドメイン)のみhttpアクセスを許可するという方法で、通信を行うことが可能です。
それぞれのプロジェクトごとに、http通信先のドメインを登録することができます。 まず、「network_security_config.xml」ファイルを新規に作成して、プロジェクトフォルダ以下の res/xmlに配置します。ここで、以下の内容を記述してください。

「network_security_config.xml」の内容

    	<?xml version="1.0" encoding="utf-8"?>
    	<network-security-config>
    	    <domain-config cleartextTrafficPermitted="true">
            	<domain includeSubdomains="true">www.onionsoft.net</domain>
    	    </domain-config>
    	</network-security-config>

上の例では、「www.onionsoft.net」をアクセス可能なドメインに指定しています。 ここに必要なドメインを記述します。必要であれば、複数のドメインを設定することができます。
次に、プロジェクトフォルダにある「AndroidManifest.xml」を編集して、「<application～」の行を 以下のように書き換えてください。

    	<application android:label="@string/app_name" android:icon="@drawable/ic_launcher"

    	 android:networkSecurityConfig="@xml/network_security_config">

以上で、登録されたドメインのみhttpアクセスが可能になります。
あくまでも補助的な方法ですので、できる限りhttpsアクセスをすることが望ましいということを 覚えておいてください。

## リリースビルド

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

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

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

- Googleに開発者登録を行なう

    	https://developer.android.com/

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

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

まず、HSP3Dish Helperを起動し、androidタブの既存プロジェクトページを開きます。 次に、「リリース」ボタンを押します。すると、リリースマネージャの画面に変わります。

ここで、「KeyFile」で示されているのが現在選択されている証明書(keystore)になります。 最初は空欄になっているはずですので、「KEY作成」ボタンを押して証明書を作成します。
最初に、ファイルを保存する場所を聞かれるので、任意の名前で保存してください。
次にコマンドプロンプトの画面が開き、以下の項目について情報を求めてくるのでキーボードから入力してください。すべて半角英文字で入力することを推奨します。

    	・キーストアのパスワード
    	・キーストアのパスワード再入力
    	・姓名
    	・組織単位名(部門・部署名) (個人の場合は「Personal」で)
    	・組織名(会社・団体名)
    	・都市名または地域名(市区町村名) (例:「Setagaya-Ku」)
    	・州名または地方名(都道府県名) (例:「Tokyo」)
    	・2文字の国コード(日本の場合は「JP」を入力)
    	・よろしいですか?(「y」を入力)

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

※既に作成済みのキーストアファイルがある場合は、「KEY参照」ボタンを押して選択してください。

- リリースビルドを行なう

リリースビルドを行う場合は、「Password」の項目にキーストアのパスワードをあらかじめ入力しておいてください。 また、「versionCode」「versionName」に入力された値がビルドに反映されます。(最初のビルドは、「versionCode=1」「versionName=1.0」で問題ありませんが、ストアにアップデート版を登録する際にはバージョンを変更する必要が出てきます。)
次に「aab作成」ボタンを押してください。アプリのリリースビルドを実行し、署名を行ないます。 以上で、プロジェクトの「app/release/」フォルダ内に「.aab」のファイルが生成されます。

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

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

## HGIMG4プロジェクトについて

基本的には、Windows版と同様の仕様でHGIMG4スクリプトを使用できます。

暮井 慧（プロ生ちゃん） (C) Pronama LLC

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

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

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

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

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

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

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

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

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

たとえば、

    		devcontrol "vibrate",400

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

また、devinfo命令によりシステム情報を取得することが可能です。

    		devinfo 変数名, "情報名"

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

    	情報名      内容
    	-------------------------------------------
    	name        端末の種別名( 端末名はsysinfo(2)で取得できます )
    	locale      ロケール(地域)の情報

たとえば、

    		devinfo a,"locale"

は、変数aにロリールの情報を代入します。

## AdMobによる広告配信

- 広告配信のための準備

HSP3DishではAdMobを使った広告配信モデルのアプリを作成することが可能です。 適切に設定を行なうことで、HSP3Dishのアプリから広告を配信し、収益を得ることができるようになります。 AdMobはGoogleが提供するモバイル広告配信の仕組みです。これをアプリに組み込むことで、無料アプリであっても広告料を得ることができます。
AdMobを組み込むためには、以下の手順で準備を行なっておく必要があります。
1. AdMobアカウントの作成
アカウントを登録し、支払い情報などの必要事項を記入します。
https://admob.google.com/
2. ユニットIDの取得
AdMobのwebページにログインし、「新しいアプリの登録」を行ないます。 (アプリがまだGoogle Playで公開されていない段階でも可能です)
必要事項を記入することで、ユニットIDを取得することができます。
3. AdMobを使用するプロジェクトの作成
新規プロジェクトを作成します。その際に、必ず「AdMobを使用する」のチェックボックスをONにしておいてください。 それ以外の設定は、通常の新規プロジェクト作成と変わりありません。
4. ユニットIDの登録
プロジェクトのフォルダ以下の「app/src/main/java/tv/hspHspActivity.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"の文字列は大小文字を正確に識別します)

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

を記述した場合は、インタースティシャル広告を表示します。
インタースティシャル広告は表示のリクエストを行なうたびに、１回表示されます。 通常のバナー広告と併用することも可能なので、より幅広い活用が可能になります。
WindowsやiOSでは、devcontrolの記述は無視されますが、複数機種実行時にAndroid上でのみ実行したい場合は、以下のように記述することができます。

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

「devcontrol "AdMob"」は、最初の実行時にAdMob表示を開始し、それ以降は実行しても 無視されますので、タイトル画面表示時などに何度でも実行されても問題ありません。 デフォルトでは、画面下にバナーとして広告が表示されます。 (この時、デバイスがネット接続可能な状態であることを確認しておいてください)
以上の準備でAdMobを使用したアプリをビルドすることが可能になります。
AdMobの表示を抑制する場合は、-1を指定することで無効（非表示）にすることができます。

    		devcontrol "AdMob",-1 // AdMobを無効（非表示）にする

- AdMobプロジェクトのビルド

プロジェクトの更新が完了したら、後は通常のHSP3Dishと同様に、HSP3Dish helperから プロジェクトのビルドを行なうことができます。
ビルド時にエラーが発生した場合は、エラーメッセージなどを参考にしながら、 プロジェクトの設定に問題がないか確認をしてください。
ビルドが成功したら、デバイスに転送して実行を確認することができます。
実行の確認を何度も行なう場合には、テスト用端末の登録を行なっておいてください。 テスト用端末の登録は、src/tv/hsp/HspActivity.javaファイルのソースで指定します。
以下の行があることを確認してください。 また、Googleでは、テスト用の広告ユニットIDを使用することを推奨しています。
https://developers.google.com/admob/android/test-ads?hl=ja

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

デバイス上の動作チェックでは、"****～"の部分に、デバイスIDを記入する必要があります。(端末のデバイスIDは、独自に調べる必要があります、エミュレータの場合は特に登録の必要はありません。)

というメッセージが流れますので、そこで確認することができます。

- アプリのリリース

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

         		.addTestDevice(TestDeviceID)

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

         		//.addTestDevice(TestDeviceID)

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

## mes,print命令について

HSP3Dishでは、内蔵フォントによるmes及びprint命令の文字列描画に対応しています。
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)版のみの制約事項です。将来のバージョンでは、対応を行なっていく予定です。

- 画像サイズについて

縦・横のサイズが2^nのサイズ、つまり1,2,4,8,16,32,64,128,256,512,1024…でない画像を読み込む時には、内部で変換を行なうため多少のオーバーヘッドが発生します。 (通常はそれほど気にする必要はありません。大量の画像を読み込む場合にCPUリソースが余計に必要となります)
画像ファイルはプロジェクトディレクトリ内のassetsフォルダに入れることができます。

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

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!にて行なわれますので、随時ご確認ください。