HSP : HSP3Dish / onion software 2024(c)

title

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

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

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つのプロジェクトファイルを作成する必要があります。プロジェクトのフォルダは、設定メニューで設定されている場所を起点に作成されます。

プロジェクトのビルド

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


上のようなプロジェクトビルドのダイアログが表示されます。(ビルドになっていない場合は、「既存プロジェクト」のボタンを押して下さい)
プロジェクトのビルドを行なうことで、指定されたHSPスクリプト及びデータファイルをandroidで実行できる形式(apkファイル)として出力されます。 android用アプリの開発では、実行のためのプログラムとデータをすべてまとめた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実機の接続設定については、デバイスの機種ごとに異なります。以下のサイトなどを参考にしてみてください。

実機への転送ができない場合でも、ビルドで生成された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により設定することが可能です。詳しくは、ツールの説明書を参照してください。

アイコンの作成について

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命令により、他のタスク(アクティビティ)を呼び出すことが可能です。

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

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

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

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

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

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

指定された画面サイズによって、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の行を有効にします。hgio_viewにより、もともとの画面サイズ(スクリプトが動作する解像度)を設定してください。上の例では、横サイズが480、縦サイズが320であることを示しています。

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

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

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

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

上の例では、「www.onionsoft.net」をアクセス可能なドメインに指定しています。 ここに必要なドメインを記述します。必要であれば、複数のドメインを設定することができます。

次に、プロジェクトフォルダにある「AndroidManifest.xml」を編集して、「<application～」の行を 以下のように書き換えてください。

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

リリースビルド

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

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

HGIMG4プロジェクトについて

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


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

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

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

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

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による広告配信