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」が指定されていますが、以下の値を設定することが可能です。

その他のオプションも、以下の通り設定することができます。
「HSP_FPS」で固定のフレームレートを指定します。30の場合は30FPS(30/1000秒)で更新を行ないます。0(デフォルト)の場合は、フレーム数をブラウザに任せます(requestAnimationFrame)。
「HSP_LIMIT_STEP」は、強制的にブラウザに処理を返すまでの実行ステップ数を指定します。デフォルトで「5000」が指定されています。あまり大きいとスクリプトや処理系に問題が有った時にブラウザが固まってしまうので注意してください。

メディアファイルの再生

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

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

制限事項・既知の問題点

現在のバージョンでは、以下の制限事項があります。 それ以外の機能については、基本的に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