HSP : Hot Soup Processor ver3.2 / onion software 1997-2009(c)

# HSP3.21 アップデートガイド

1. イントロダクション
2. HSP3.21の変更点について
3. HSP3.1との違いについて
4. HSP2との違いについて
5. HSP3の概要
   1. 動作環境
   2. 命令の追加
   3. 関数のサポート
   4. 実数のサポート
   5. プラグイン
   6. モジュール
   7. ラベル型変数のサポート
   8. HSPLet
   9. DLL呼び出し
   10. COM呼び出し
   11. スクリプトエディタ
   12. peasエディタ
   13. HSPTVブラウザ
6. ver2.xからのスクリプト移行
   1. 計算順序の変更
   2. 命令の関数化
   3. 命令及びシステム変数の変更
   4. モジュール機能の仕様変更
   5. プラグイン仕様の変更
   6. 配列についての変更
   7. メモリバッファについての変更
   8. peek命令の変更
   9. HSP3は難しい？（HSP2との互換マクロについて）

## イントロダクション

HSP3.2は、HSP3.1に替わる新しいバージョンです。 しかしながら、HSP2からHSP3にあったような大幅な仕様の変更はなく、 あくまでも上位互換として動作する形で、各種機能が追加されています。

ここでは、HSP3.2とHSP3.1及びHSP3.21の違いについて。 そして、HSP2.61とHSP3全般の違いについて解説していきます。

## HSP3.21の変更点について

HSP3.21は、HSP3.2のマイナーアップデートバージョンです。 HSP3.21では64bit版Windowsへの対応などいくつかの点で不具合を修正していますが、仕様的に大きな変更はありません。 HSP3.2をすでに使っているユーザーは、特に意識することなくHSP3.21をお使いいただけるはずです。

HSP3の詳細な更新履歴については、こちら(history.txt)を参照してください。

HSP3.21でHSP3.2から追加変更された主要な項目は以下の通りです。

- Windows Vista及びWindows 7の64bit(x64)版でウィンドウが閉じなくなる不具合を修正しました
- HGIMG3でメモリのリークがある不具合を修正しました
- HGIMG3上でOBAQプラグインのオブジェクト描画に対応しました
- HGIMG3でエミッターなどいくつかの機能追加を行ないました
- OBAQプラグイン用の簡易モデル作成ツールを追加しました
- hspinetプラグインにRC4/BASE64サポートを追加しました
- hspinetプラグインサンプルにメール送信スクリプトを追加しました
- sprocketさん製作のArtlet2D,SQLeleモジュールを標準で同梱しました

## HSP3.1との違いについて

HSP3.1をすでに使っているユーザーは、特に意識することなくHSP3.2をお使いいただけるはずです。 HSP3.2では、それまでの機能を継承しながら、新たな要素を多数追加しています。

HSP3の詳細な更新履歴については、こちら(history.txt)を参照してください。

HSP3.1で動作していたスクリプトは、ほとんどの場合、修正することなくHSP3.2で動作させることができます。 HSP3.2で修正が必要な項目は以下の通りです。

新規追加キーワードの衝突

  HSP3.2では、新たに以下のキーワードが標準で定義されるようになりました。

  - ldim
  - newlab
  - resume
  - yield
  - split
  - strtrim
  - gradf
  - objimage
  - objskip
  - objenable
  - celload
  - celdiv
  - celput
  - m_pi
  - rad2deg
  - deg2rad
  - powf

  これらの名称を変数名、命令定義、関数定義などで使用している場合、 エラーとなる場合があります。 新しいキーワードと衝突して、過去のスクリプトが動作しない場合は、 衝突しているキーワードを変更するか、#undef命令によりシステム定義を 一時的に無効とすることで動作させることができます。

ラベル型変数の仕様変更

  ラベル型変数の動作が3.1と異なっています。 HSP3.1では、dimtypeによりラベル型変数を初期化した時に、何も代入を行なわない 場合でもgoto、gosub等で指定可能でした。(初期値はプログラム先頭として処理) HSP3.2では、初期化時(何も代入を行なわない時)のラベル型変数は、goto、gosub等で 指定するとエラーとなります。 また、varuse関数によりラベルが代入されているか(有効なラベルが代入されているか) を取得可能になっています。 ラベル型をより安全に使用するための変更となります。 既存のスクリプトがこの仕様変更により、動作しなくなる可能性は低いと思われます。

これ以外の項目で、バージョンアップにあたりスクリプトを修正する必要はありません。

HSP3.1で追加変更された主要な項目は以下の通りです。

- ヘルプ表示をHDLに切り替え、すべてのサンプル・ドキュメントを横断検索可能になりました
- HSPアシスタント機能を追加しました(かんたん入力、サンプルビューアーを内包しています)
- 呼び出し位置より後ろで定義されている関数・命令を呼び出せるようになりました
- 新規プラグインとして2D物理エンジン、obaq.dllを追加しました
- ゲーム系のサンプルスクリプトを大幅に追加しました
- 2Dイベントエディタelm2dツールとサンプルを追加しました
- ラベル型変数を扱うためのnewlab、ldim命令が標準で追加されました
- 文字列操作のためのstrtrim関数、split命令が標準で追加されました
- ボタンに画像を利用するためのobjimage命令が標準で追加されました
- グラデーションの描画を行なうgradf命令が標準で追加されました
- 配置オブジェクトの設定を行なうobjskip、objenable命令が標準で追加されました
- 画像データを扱うためのcelload、celput、celdiv命令が標準で追加されました
- M_PI,rad2deg,deg2rad,powfが標準マクロとして追加されました
- プリプロセッサ命令、modcfuncを追加しました
- strf関数で可変長複数パラメーターの指定が可能になりました
- 外部プラグイン、DLLの初期化・解放プロセスを厳格にしました
- 内部メモリ管理アルゴリズムを修正、若干の高速化を行ないました
- マルチスレッド版ランタイム(hsp3mt)を同梱しました
- HSPSDKをフルセットに同梱しました
- プラグインhgimg3、hspinet、hspext、hspda、hspcvの修正・機能追加をしました
- 新規モジュールllmod3、mod_picfont、mod_stbar、encode等を追加しました

## HSP2との違いについて

HSP3は、HSP2までの仕様とプログラムを大幅に見直し、再構築したHSP3の最新バージョンです。 ver2.61までに培われた親しみやすさ、習得のしやすさ、シンプルさといった資産を継承しながら、 より幅広い応用と汎用性を持たせた環境を提供すべく開発されています。

以前のバージョンからの移行も含めて入門者から上級者まで幅広く使っていけるスクリプト言語となる ことを願っています。

HSP3は、まったく新しく設計されたコアシステムを中心に構成されています。 このコアシステムは、プラットフォームに依存しないスクリプトエンジンと、自由に機能拡張を可能とする アーキテクチャを持っています。 シンプルで強力なコアシステムのもとで、各種プラットフォームに対応した拡張コンポーネントを 用意し、安定した可搬性と生産性を実現するシステムを目指しています。

いままでの書式やルールの特長は継承し、不要な仕様を見直すことで豊富な資料や過去の資産を有効に 活用することができ、次期バージョンへ移行するための敷居も低くなっています。

HSP3は、ver2.61までの書式やルールを継承していますが、完全な互換性はありません。
HSP3を新規にインストールした場合でも、HSP2.xは削除されず独立した形で使用することができます。

ver2.61までのソーススクリプトをver3.0に移行させるためには、注意点を参照した上で 互換性のない部分を変更するようにしてください。

また、ver3.0が正式にリリースされた後も、ver2.xの配布及びメンテナンスはしばらくの間継続される予定です。 既存のすべてのユーザーに、無理なくver3.0への移行ができるよう努力をしていきたいと考えています。

## HSP3の概要

HSP2を利用してきたユーザー向けに、HSP3.2の概要を紹介します。

### 動作環境

HSP3のコアシステムは、WIN32上で動作します。 HSP2.xはWindows95以降のバージョンをサポートしていましたが、HSP3ではWindows98以降を動作環境としています。 (ただし、Windows95+InternetExplorer4以降の環境では動作可能です。)

### 命令の追加

HSP2.xではプラグイン命令だった画像関連の命令が標準で装備されています。 画像の拡大や回転を行なうgrotate、grect、gsquare命令や、 円を描画するcircle命令、HSVによる色指定を行なうhsvcolor命令など 多くの機能がサポートされています。

### 関数のサポート

式の中に関数を含めることができるようになっています。 これにより、一部の命令やシステム変数が関数に置き換えられています。

### 実数のサポート

64bit浮動小数による実数計算をサポートしています。 三角関数や平方根などの数学関数を装備しており、 精度の高い計算を行なうことができます。

### プラグイン

拡張プラグインについては、3.0から大きく仕様が拡張されています。 3.0専用にプラグインを作成することにより、型の拡張や描画システム、 イベントの管理など、大幅なシステムの拡張を可能にします。

HSP2.61までのプラグインは、互換機能によりほぼすべてをそのまま使用することができます。 また、HSP2.61で標準添付されていた拡張プラグインはすべて同名のものを同梱しています。

HSP3.0では、これに加えてHTTPやFTPのネットワークアクセスに特化したHSPINETや、 高度な3D処理をサポートするHGIMG3を同梱しています。 HSP3.2では、さらに高度な画像処理に特化したプラグインHSPCVや、3Dゲーム作成で 評価の高いEasy3Dが同梱されています。

### モジュール

モジュール機能はスクリプトの名前空間や、変数の領域を独立させることで、 スクリプトの再利用性とメンテナンス性を高めることができます。 ユーザー定義命令の作成やモジュール変数の作成、 ローカル変数の定義などにも結び付いた高度な仕組みです。 詳しくは「モジュール機能ガイド」をご覧ください。

### ラベル型変数のサポート

ラベル型変数は、スクリプトの任意の位置情報を変数に格納するための仕組みです。 ラベル情報を変数に格納することにより、スクリプトの可能性がさらに広がります。

### HSPLet

HSPLetは、HSPの実行をJavaランタイム上で行なうためのシステムで、 これによりWebブラウザでの実行及び、Windows以外のシステムで HSP3のスクリプトを 動作させることが可能になります。 詳しくはHSPLetの説明書および マニュアルをご覧ください。

### DLL呼び出し

WIN32APIなど外部DLLを手軽に定義して呼び出すことが可能です。 HSP2.61のloadlib関連命令及びllmodに含まれる命令は、HSP3でサポートされません。

### COM呼び出し

WindowsのCOMコンポーネント呼び出しをサポートしています。 COMオートメーション、COMイベントなどの高度な技術を手軽に利用することができます。 これにより、IEコンポーネント、XMLパーサー、正規表現による検索や置き換え、RSSの取得などの 最新テクノロジーをスクリプトから簡単に呼び出せます。

### スクリプトエディタ

新規のスクリプトエディタを同梱しています。 編集サイズ制限の撤廃と、キーワードの色付け、タブの採用などにより 高機能なものとなっています。(以前のバージョンもHSED3LE.EXEとして同梱されています。) スクリプトエディタから呼び出される周辺ツール(ヘルプブラウザ等)も、 バージョンアップしたものを同梱しています。

### peasエディタ

peasエディタは、テンプレート(ひな型)のパーツと、パラメーターやオプションを決めるだけで、 自動的にスクリプトを生成する簡易プログラミング環境を提供します。 ユーザーは、今まで通りにエディタでスクリプトを書くことはもちろん、マウス操作だけで プログラムを作成することが可能になります。

### HSPTVブラウザ

HSPTVブラウザが標準で同梱されています。 これは、ネットワークを介してアップデートされるコンテンツビューアーです。 オンライン上のHSP情報、最新ソフトウェアを手軽にダウンロードして楽しむことができます。

## ver2.xからのスクリプト移行

ここでは、既にver2.xを使用していた方、スクリプトを移行したい方に向けての 変更点および注意点をお知らせします。

### 計算順序の変更

HSP3では、計算式で演算子ごとの優先順位が付けられています。 多くの言語と同様に、「+」「-」よりも「*」「/」の方が先に計算されるようになっています。 これにより、ver2.xまでの計算式(左から処理)と結果が変わってくる場合があります。 優先順位の詳細については、「言語仕様ガイド」を参照してください。

### 命令の関数化

一部の命令が関数として実装されています。 このため、ver2.xで使用していた命令の一部がそのままでは使用できなくなっています。 関数化された主な命令は、以下の通りです。

- int
- str
- rnd
- strlen
- peek
- wpeek
- instr
- strmid
- getpath
- ginfo
- sysinfo

例えば`rnd a, 10`は`a = rnd(10)`という書式になります。

### 命令及びシステム変数の変更

HSP 2.xに存在した以下のキーワードは3.0で変更されています。 ほとんどは代替の命令により同等の動作が可能になります。 また、2.xと互換で動作するマクロ(hsp261cmp.as)を利用することで ある程度の互換を持たせることができるようになります。

変更された命令
命令名 | 変更点
--- | ---
rnd | rnd()という書式の関数になりました
gettime | gettime()という書式の関数になりました
peek | peek()という書式の関数になりました
wpeek | wpeek()という書式の関数になりました
notemax | notemaxというシステム変数(マクロ)になりました
strlen | strlen()という書式の関数になりました
sysinfo | sysinfo()という書式の関数になりました
getpath | getpath()という書式の関数になりました
strmid | strmid()という書式の関数になりました
instr | instr()という書式の関数になりました
ginfo | ginfo()という書式の関数になりました
sndload | mmload命令という名称に変更されました
snd | mmplay命令という名称に変更されました
sndoff | mmstop命令という名称に変更されました
skiperr | onerror命令による割り込みをお使いください
objsend | 代替としてsendmsg命令が用意されています
palfade | 代替命令は用意されていません
palcopy | 代替命令は用意されていません
getpal | palcolorと同機能になります
text | "hsp3util.as"モジュールにてtext,emes命令を提供しています

変更されたシステム変数
システム変数名 | 変更点
--- | ---
csrx | ginfo_cxマクロに名称変更
csry | ginfo_cyマクロに名称変更
paluse | ginfo_paluseマクロに名称変更
dispx | ginfo_dispxマクロに名称変更
dispy | ginfo_dispyマクロに名称変更
rval | ginfo_rマクロに名称変更
gval | ginfo_gマクロに名称変更
bval | ginfo_bマクロに名称変更
winx | ginfo_winxマクロに名称変更
winy | ginfo_winyマクロに名称変更
cmdline | dir_cmdlineマクロに名称変更
windir | dir_winマクロに名称変更
curdir | dir_curマクロに名称変更
exedir | dir_exeマクロに名称変更
sysdir | dir_sysマクロに名称変更
prmx | ginfo命令の仕様変更により必要なくなりました
prmy | ginfo命令の仕様変更により必要なくなりました

loadlib関連命令は、#uselib・#funcを利用したDLL呼び出しか、 またはcallfunc関数による外部呼び出しに引き継がれます。 以下の命令は、HSP3ではサポートされていません。 (ll_poke、ll_peek等は、「dupptr命令+poke命令/peek関数」で代替が可能です。)

- ll_ret
- ll_retset
- ll_getptr
- ll_peek
- ll_peek1
- ll_peek2
- ll_peek4
- ll_poke
- ll_callfunc
- ll_n
- ll_poke1
- ll_poke2
- ll_poke4
- ll_libfree
- ll_callfnv
- ll_call
- ll_free
- ll_s
- ll_p
- ll_str
- ll_dll
- ll_func
- ll_type
- ll_z
- ll_libload
- ll_getproc
- ll_bin

ただし、HSP3.2以降ではllmodに含まれる命令、マクロ等を継承したllmod3が同梱されています。 詳しくは、common/llmod3ディレクトリにあるソースを参照してください。

### モジュール機能の仕様変更

モジュール機能の仕様が変更されています。 数値以外のパラメーターをユーザー定義命令に渡す場合には、スクリプトを変更する必要があります。 また、mref命令についても一部機能変更がありますので注意してください。 詳細については、「言語仕様ガイド」を参照してください。

### プラグイン仕様の変更

HSP2.5以降のすぺてのプラグイン規約に対応していますが、 HSP3の内部仕様変更による制限がいくつかあるので、注意が必要です。

- BMSCR構造体は、flagからcolorまでのフィールドのみ参照できます。
- PVal構造体のflagフィールド(型タイプ値)やlenフィールド(配列情報)を DLL側で書き換えることはできません。
- PVal構造体から文字列型の配列変数にアクセスすることはできません。

これ以外の点においては、HSP ver2.61と同等の情報が受け渡されます。 HSP2.61互換のプラグインでは、以下のような制限が発生しますので注意してください。 また、プラグインの互換機能はすべてのHSP2.xプラグインの動作を保障するものではありません。

プラグインから変数に値を代入する場合、バッファの自動拡張は行なわれません。 バッファオーバーフローが発生しないように注意してください。

フルセットのアーカイブには、ver2.61同梱プラグインのうち、hspda、hspdb、hspdx、 hspext、hspsock、hgimg(x)及びヘッダファイルが含まれています。 これらのプラグインは、ver2.61に同梱されているものとまったく同一のDLL ファイルで、3.0のプラグイン互換機能により動作しています。 (HSP同梱でないユーザー作成プラグインの互換性については、それぞれの仕様により異なります。)

hspdx.dllについては、HSP3.0のpicload仕様変更によりパレットモード時に 読み込んだ画像のパレットが反映されません。このため、画像ファイルから パレットデータを取り出すためのbmppalette命令を定義したモジュール集、 「hsp3util.as」を提供しています。 使用例については、hspdxのサンプルスクリプトを参照してください。

### 配列についての変更

ver3.0からは配列変数の扱いが大きく変更されています。 ver2.xではdimまたはsdim命令によって、配列の最大数を確保してから使用する形になっていましたが、 ver3.0では配列の確保をすることなく配列変数に代入することが可能になっています。 (ただし、代入されていない配列の内容を参照するとエラーになります)

ver2.xではデフォルトで0〜15までの配列(数値型変数の場合)を利用可能でしたが、 ver3.0ではデフォルトの確保はありません(0のみ)。 この違いによって一部のスクリプトが配列の参照中にエラーとなる場合があります。

### メモリバッファについての変更

HSP3から文字列型の変数は、自動拡張により自由なサイズのデータが扱われることになります。 このため、文字列型の配列変数を作成した場合には可変長の変数バッファが複数作成されることになり、 ver2.xまでのような連続したメモリ空間での管理ではなくなります。 これにより、文字列型の配列変数に対してbsave、bloadなどを始めとした直接メモリを操作する命令を実行した場合、 ver2.xではすべての次元にアクセスできましたが、 ver3.0からは特定の配列要素単位でのアクセスとなります。

実際にそのような操作を行なっているスクリプトは多くないと思われますが、 文字列型の配列変数に対するメモリ操作には注意が必要です。

### peek命令の変更

peek命令はpeek関数になりましたが、同時にver2.xでサポートしていた文字列読み出しの機能は廃止されています。 同等の処理を行なう場合は、getstr命令で区切りキャラクターコードを0としてお使いください。

### HSP3は難しい？

いままでHSP2を利用してきたユーザーの中には、HSP3になって新しい要素が大幅に 導入されたため、難しくなったと考えている方も多いと思います。

HSP3は、HSP2を使ってきたユーザーすべてに移行して使ってもらえるよう、設計されています。 HSP3で、大きく変わった点として関数の導入がありますが、これはいままで命令だったものを 計算式の中に記述できるようにしたもので、機能が変更されているわけではありません。 それ以外に追加された多くの機能は、HSPを拡張するための仕組みで、モジュール機能や 外部API呼び出し(loadlib関連命令にあたるもの)など、一般ユーザーが手軽に新しい機能を 使うことができるようにしたものです。

HSP3では、より柔軟な書き方ができるようになりましたが、人それぞれのスタイルが あるものなので、HSP2と同じ書き方でも構いませんし、必要のない機能は使う必要はありません。 もしHSP2に慣れている場合は、スクリプトの先頭に次のような1行を追加してください。 主要な命令のほとんどがHSP2と同じ書き方で実行できるようになります。

    #include "hsp261cmp.as"		;ver2.61互換を有効にする

これは、commonフォルダに存在する「hsp261cmp.as」で定義されている ver2.61互換マクロにより、3.0以降で動作するよう適切な命令に変換するものです。 ただし、現状のver2.61互換マクロは、β版でありすべての記述をサポートして いるわけではありません。また、計算式の優先順位変更も行なわれません。 完全ではないものの、ある程度までのスクリプトであれば、そのまま3.0で 動作させることが可能です。

ver2.61互換マクロの設定以降には、ver3.x専用の命令及び定義ファイルなどを 置かないように注意してください。