HSP : HSP3Dish / onion software 2014(c)

タイトル

hsp3dish.js (WebGL/JavaScript版)プログラミングガイド

  1. hsp3dish.js概要
  2. hsp3dish.jsの仕組み
  3. HSP3Dish Helperによる変換
  4. ブラウザ上での実行
  5. 表示サイズのスケーリング
  6. メディアファイルの再生
  7. 制限事項・既知の問題点
  8. 今後の予定
  9. ライセンス・謝辞

hsp3dish.js概要

hsp3dish.jsは、WebGLをサポートしたWEBブラウザ上で動作するHSP3Dishのランタイムです。 Windows版 HSP3Dishがサポートする機能をWEBブラウザ上で再現することが可能です。 これにより、WindowsだけでなくMacOSやLinuxなど様々なOS上での動作が可能になり、インストールの手間なく手軽に、HSPのアプリケーションを実行させることができるようになります。
このマニュアルでは、hsp3dish.js版の利用方法、注意点などを説明していきます。

動作には、WebGL対応のブラウザが必要です。以下の環境での動作を確認しています。


HSP3Dishスクリプトの変換を支援するための、HSP3Dish Helperツールが同梱されています。 これにより、比較的スムーズにhsp3dish.js向けに変換を行なうことが可能になります。 (尚、動作を確認するためには、自分がアップロード可能なホームページか、ローカルで動作するWEBサーバーが必要となります。)

hsp3dish.jsの仕組み

hsp3dish.jsは、 llvmコンパイラ、及びEMscriptenを使用して、 HSP3ランタイムをJavaScript向けに変換したものです。 HSP3のオリジナルソースを元にしているため、動作の互換性が高く、アップデートも容易なシステムになっています。
iOS版、android版のHSP3Dishは、HSPのスクリプトをネイティブコードに変換した上で実行していますが、 hsp3dish.jsは、HSPのスクリプトを中間コードに出力したもの(.axオブジェクトファイル)をもとにして、インタプリタ(逐次実行)として動作します。これは、Windows版のHSP3Dishと同様です。
スクリプトの実行速度は、ブラウザを実行しているマシンのCPU速度、VMの速度に依存しますが、最近のPCであれば実用的な範囲で動作するはずです。

HSP3Dish Helperによる変換

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


下に並んでいる「hsp3dish.js」のボタンを押して、hsp3dish.js変換のモードにしてください。上のような表示になるはずです。
このダイアログ内に必要な情報を設定し、「変換」ボタンを押すことで、webブラウザ上の動作に必要なファイルがすべて作成されます。ダイアログで設定する項目は、以下の通りです。

設定ができたら、「変換」ボタンを押してください。スクリプトやデータファイルがhsp3dish.js向けに生成されます。
生成されるファイルは、以下の通りです。

元のソーススクリプトがあるフォルダに、これらのファイルが生成されているはずです。 (たとえば、block3.hspを変換した場合は、block3.htmlとblock3.dataが生成されます。)
ここで生成されたファイルを、WEB上にアップロードするだけで、WEBブラウザ上での実行が可能です。
.htmlファイルは、WEBブラウザ上から開くためのHTMLファイルとなります。 たとえば、「www.onionsoft.net/hsp/hsp3js/」という場所にアップロードを行なった場合は、 「http://www.onionsoft.net/hsp/hsp3js/block3.html」が実行のためのURLとなります。
.dataファイルは、HTMLファイル内のJavaScriptから読み込まれるデータファイルで、実行に必要なデータがすべて含まれています。
「hsp3dish.js」ファイルは、HSPランタイムの核となる部分で、WEB上でHSP3Dishを実行させる場合に必ず必要となります。 これは、すべてのスクリプトで同一となるため、同じフォルダに複数の.htmlと.dataを置いた場合でも、共用することが可能です。

ブラウザ上での実行

HSP3Dish Helperから生成された、.htmlファイル、.dataファイル、及びhsp3dish.jsファイルをWEB上にアップロードすることにより、ブラウザ上で実行させることができます。 ローカルファイルの.htmlファイルを開いても起動されません。必ず、WEBサーバー上にファイルを設置するようにしてください。
こちらのページから、実際にblock3.hspスクリプトの動作を確認することができます。
デフォルトで生成されたhtmlファイルでは、「Resize Cavas(表示領域のリサイズ指定)」「Lock/hide mouse pointer(マウスポインタを隠す)」チェックボックス、「Fullscreen(フルスクリーン表示)」のボタンが付加されます。
また実行画面の下部には、hsp3dish.jsのコンソール(システムメッセージ表示エリア)が配置されます。
htmlファイルは、ユーザーが自由に改変して頂いて構いません。レイアウト、配置等は任意で調整を行なってください。


表示サイズのスケーリング

htmlファイルを編集することで、表示サイズ及びスケーリングの設定を行なうことができます。 生成された、.htmlファイルをテキストエディタで開き、以下の場所を編集してください。

「ENV.HSP_WX」「ENV.HSP_WY」で指定されている数値が、スクリプトの動作解像度サイズ(X,Y)となります。 これは、スクリプトの変換時にhsp3dish.iniファイルから取得された値が設定されています。
「ENV.HSP_SX」「ENV.HSP_SY」で指定されている数値が、実際にWEBブラウザ上で表示される解像度サイズ(X,Y)となります。 スクリプトの動作解像度と表示解像度が異なる場合に、スケーリング(拡大縮小)を行なうための設定が「ENV.HSP_AUTOSCALE」項目になります。デフォルトで「0」が指定されていますが、以下の値を設定することが可能です。

メディアファイルの再生

現在のバージョンでは、メディアファイル再生に関して試験的な対応となっています。

メディアファイルはリソースとして膨大なサイズになる場合があるため、起動時にすべてメモリに読み込む現在のリソース管理では、大量の楽曲を流す処理には向いていません。 今後のバージョンでは改良していきたいと考えています。

制限事項・既知の問題点

現在のバージョンでは、以下の制限事項があります。 それ以外の機能については、基本的にHSP3Dishと同等となります。

また、既知の問題として以下が報告されています。

その他、WEBブラウザ上で動作していることから、異なる動作、表示が行われる可能性があります。 現在は、データファイルをまとめて読み込んでいるため、大規模なアプリケーション(画像を大量に使用するなど)は、 重くなったり、処理ができないことがありますので注意ください。

今後の予定

hsp3dish.jsは、WEB上で手軽にHSPの実行を行なう環境として、今後も機能を拡充していく予定です。 以下は、今後のバージョンアップで検討している機能です。 将来のバージョンでは、より高い互換性と機能の向上を目指していきたいと考えています。

ライセンス・謝辞

ユーザーは、HSP3Dishと同様のライセンス(BSDライセンス)で、hsp3dish.jsを利用することができます。 以下のライセンス表記が、hsp3dish.jsファイルに含まれていますので、hsp3dish.jsファイルを改変せずにそのままホームページにアップロードしてご使用ください。 それ以外の場所に、ライセンス及び著作者に関する情報を表示する義務はありません。また、利用にあたっては商用、非商用を問わずライセンス料は必要ありません。

hsp3dish.jsは、zakkiさんによって実装されたEmscripten版HSP3Dishをパッケージに同梱したものです。 素晴らしいシステムを実装したzakkiさん、ご意見をお寄せいただいた多くの方々に感謝致します。
Emscripten版HSP3Dishは、OpenHSPの派生物となっています。ソースコードは、OpenHSPリポジトリから取得することができます。

ONION software