------------------------------------------------------------------------------ OBAQ for HSP ver3.3 REFERENCE MANUAL HSP : Hot Soup Processor HSP拡張拡張DLLリファレンス Copyright 2011 (c) Zener Works/kuni/onitama ------------------------------------------------------------------------------ ・はじめに このDLLは、Hot Soup Processor ver3.2以降とともに使用することで、 物理エンジン(OBAQ)が持つ機能を手軽に利用することができるプラグインです。 OBAQは、DLL内にすべての機能を内包しており、HSPが実行可能な環境であれば 追加のモジュールやDLLをインストールする必要はありません。 ・OBAQの機能概要 OBAQを使用することにより、2Dベースによる剛体の衝突、重力シミューレーション を扱うことができます。 OBAQは誰にでも手軽に、物理演算による自然な動きを実現することが できるよう、2Dに特化し、設定や命令もシンプルにまとめられています。 精度の高い技術計算というよりも、ゲームやデモンストレーション等を サポートするためのお手軽なシステムと考えてください。 OBAQには、スプライトマネージャーを内蔵しており、標準機能のみを使用した スプライト描画を手軽に行なうことができます。また、表示座標をユーザーが 管理することにより、DirectX等を使った表示システムにも対応可能です。 ・使用のための準備 OBAQ.DLLは、最新のHSP3フルセットに同梱されています。 DLLが動作しない場合は、実行に使われているHSP3.EXEと同じディレクトリに、 OBAQ.DLLがあるかどうかを確認してください。 OBAQを使用する場合は、スクリプトの先頭に必ず「#include "obaq.as"」 という行を追加してください。以上で、HSPの機能が拡張され、この リファレンスで説明をしている命令を使用することができるようになります。 まず最初に、試しにサンプルスクリプト(sample/obaqフォルダ内)を実行 してみてください。 拡張された機能の簡単な使用例を見ることができるはずです。 ・使い方の概要 OBAQは、シンプルな表示物の管理と、描画機能を内蔵しています。 管理される最小の単位を、オブジェクトと呼んでいます。 オブジェクトには、四角形、三角形を始めとして任意の形状を割り当てる ことができます。また、描画機能によりオブジェクトを画面上に表示したり、 画像を割り当てることが可能です。 OBAQでは、オブジェクトに割り当てられた形状をもとに画面内を1つの空間と 見なして、すべての衝突と重力を考慮して配置、移動が行なわれます。 つまり、画面内にあるすべてのオブジェクトは、現実と同様に重さを持ち、 材質(摩擦や反発力など)のパラメーターを持っています。 これらを適切に設定することで、リアルな物理挙動を手軽に再現することが できるようになります。 OBAQを使用する際には、最初に初期化を行なう必要があります。 qreset OBAQ初期化 qreset命令により、すべての情報が初期化され何もない状態になります。 この時、HSPの描画対象として設定されていたウィンドウが、OBAQでも 描画の対象となります。 qreset命令により初期化を行なうと、画面全体を囲む壁(枠)が自動的に 設定されます。これは、何も壁のない状態で画面内にオブジェクトを配置 した際に、画面外まで落下するのを防ぐためのものです。 壁のサイズや位置を変更したい場合は、qborder命令により再設定を 行なってください。 オブジェクトは、それぞれ表示するための位置(座標)が設定されています。 OBAQでは、内部で独自を座標系を持っており、画面左上を(0,0)として、 右下に向かうほど値が増えていきます。(Xの正方向が右、Yの正方向が下) OBAQに内蔵された描画機能を使用する場合は、初期設定の段階では 内部座標を4倍したものが、表示の座標(画面上のドット数換算)となっています。 この座標変換は、qview命令によりユーザーが任意に設定することが できるようになっていますので、ズームや縮小、位置などを調整することが できます。 OBAQの初期化が終了したら、表示のためのメインループを作成してください。 以下は、一般的なループの例です。 qreset ; OBAQの初期化 *main ; メインループ ; redraw 0 ; 画面の更新を開始 color 0,0,0:boxf ; 画面をクリア qexec ; OBAQによるオブジェクトの更新 ; ここにユーザーの処理を入れてください qdraw ; オブジェクトの描画 redraw 1 ; 画面の更新を終了 await 12 ; 一定時間待つ goto *main メインループでは、必ずqexec命令によりオブジェクトの移動更新を 行なう必要があります。内部の描画を利用する場合は、qdraw命令による 画面の更新も必要になります。 qdraw命令による描画は、WindowsのシステムAPI(GDI)を利用しています ので、画面クリアと、redraw命令による更新も行なってください。 他のシステムによる描画(DirectX等)を行なう場合は、qexec命令による 更新だけを行なってから、各オブジェクトの表示位置を自前で取得して 描画を行なう必要があります。(表示座標の変換用にqcnvaxis命令や qgetaxis命令が用意されています。) オブジェクトを追加することで、画面上に表示物が現われます。 OBAQでは、それぞれのオブジェクトをID番号で管理しています。 オブジェクトを登録する場合は、以下の命令を使用します。 qaddpoly命令は、3角形・4角形など任意の多角形を生成することが できます。qaddmodel命令では、より自由な形状をあらかじめ 配列変数に座標データとして格納したものを使用してオブジェクトを 生成します。 qaddpoly 多角形オブジェクト追加 qaddmodel 自由設定オブジェクト追加 これらの命令は、任意の場所に指定された形状のオブジェクトを追加します。 追加されたオブジェクトのIDを変数で受け取ることができるので、 パラメーターを変更する際は保存しておいてください。 オブジェクトを削除(破棄)する場合には、以下の命令を使用します。 qdel オブジェクト削除 qdel命令は、個別のオブジェクトを削除します。 qreset命令により、すべてのオブジェクトと設定情報を破棄して、 初期状態に戻すことができます。 オブジェクトが登録されると、後は物理挙動に従って、自動的に動き 始めます。それぞれのオブジェクトには、多くのパラメーターがあり 以下の命令によって設定することができます。 qtype typeパラメーターを設定 qstat statパラメーターを設定 qpos 位置、角度パラメーターを設定 qspeed 加速パラメーターを設定 qgroup グループパラメーターを設定 qweight 重さなどのパラメーターを設定 qdamper 吸振などのパラメーターを設定 qinertia 惰性などのパラメーターを設定 qmat マテリアルパラメーターを設定 qmat2 マテリアル詳細パラメーターを設定 qmat3 マテリアル表示パラメーターを設定 quser ユーザー定義データを設定 quser2 ユーザー定義データを設定2 また、設定できるパラメーターと対になる形で、設定された内容を変数に 読み出すための命令も用意されています。 qgetpos 位置、角度パラメーターを取得 qgetweight 重さなどのパラメーターを取得 qgetdamper 吸振などのパラメーターを取得 qgetinertia 惰性などのパラメーターを取得 qgetspeed 加速パラメーターを取得 qgetgroup グループパラメーターを取得 qgettype typeパラメーターを取得 qgetstat statパラメーターを取得 qgetmat マテリアルパラメーターを取得 qgetmat2 マテリアル詳細パラメーターを取得 qgetmat3 マテリアル表示パラメーターを取得 qgetuser ユーザー定義データを取得 qgetuser2 ユーザー定義データを取得2 オブジェクトの挙動や表示方法は、すべてこれらのパラメーターにより設定 することができます。 オブジェクトの挙動で、基本となる動作を設定するのがtypeとstatの バラメーターです。これらは、qtype、qstat命令で設定することが できます。 typeパラメーターは以下の値を持ちます。 マクロ名 値 内容 --------------------------------------------- stat_reserve 0 未使用オブジェクト stat_sleep 1 出現待ちオブジェクト stat_active 2 出現しているオブジェクト 登録されたオブジェクトは、通常stat_activeが設定されています。 stat_sleepが設定されているオブジェクトは、画面上で点滅表示となり 接触判定などが行なわれません。 statパラメーターは以下の値を持ちます。 マクロ名 値 内容 ----------------------------------------------------------- type_normal 0 通常のオブジェクト type_inner 1 接触判定を反転したオブジェクト type_bindX 0x40 X軸を背景に固定 type_bindY 0x80 Y軸を背景に固定 type_bindR 0x100 回転を固定 type_bind 0x1c0 背景に完全固定(物理挙動なし) type_autowipe 0x100000 ボーダー範囲を越えたら自動的に消去 通常のオブジェクトは、type_normalが設定されており、物理挙動を反映した 動作を行ないます。 qpos命令により、オブジェクトの座標、角度を変更することができます。 ただし、OBAQでは、基本的に物体を動かす場合でも、直接物体の座標を 変更するのではなく動かしたい方向に力を加えたり、qgetspeed命令により 加速度を設定することで実現してください。 qweight、qdamper、qinertia命令はオブジェクトの材質や挙動に関する パラメーターを設定することができます。 これらの値については、ある程度物理法則について理解があると、より予測が つけられると思います。わからない人は、以下の説明を参考に、適切な値を 設定するようにしてください。特にいじる必要のないパラメーターについては、 デフォルトの値を使用しておいて構いません。 qweight num,weight,moment 重さなどのパラメーターを設定 num(0) : オブジェクトID weight(6.0) : 重さ moment(1200.0) : モーメント パラメーターのそれぞれのカッコ内は、初期値(省略時の値)です。 weight(重さ)は、半径rの円に標準的な比重の場合、 (r ^ 2) / 32.0 くらいを目安に設定してください。 moment(モーメント)は、回転のしやすさに関わるパラメーターだと考えて 下さい。 半径rの円盤: weight * (r ^ 2) / 2.0 辺の長さがa, bの長方形 : weight * ((a ^ 2) + (b ^ 2)) / 12.0 のような値を目安に設定してください。 qdamper num,damper,friction 吸振などのパラメーターを設定 num(0) : オブジェクトID damper(0.7) : 吸振 friction(1.0) : 摩擦抵抗値 damper(吸振)は、接触した際のゆれを抑える力を示しています。 0.0から1.0までの値を設定するようにしてください。 (範囲チェックは行なわれません) friction(摩擦)は、物体同士が接触した時に減衰する力の係数になります。 接触する物体のfrictionと乗算した値が参照され計算されます。 0.0から1.0までの値を設定するようにしてください。 (範囲チェックは行なわれません) qinertia num,inertia,gravity 惰性などのパラメーターを設定 num(0) : オブジェクトID inertia(0.999) : 惰性パラメーター値 gravity(1.0) : オブジェクトの重力値 inertia(惰性)は、0.0に近づくほど抵抗が発生してねっとりした動きに なります。0.0から1.0までの値を設定するようにしてください。 (範囲チェックは行なわれません) gravity(オブジェクトの重力)は、空間に設定されている重力に乗算される形で オブジェクトのみに反映されます。 特定のオブジェクトだけに、異なる重力を与える場合に使用します。 現実にはありえない形で、特定のオブジェクトだけに無重力や反重力を与える ため、ゲームなどのキャラクター制御に有効です。 以下の命令は、qdraw命令でオブジェクトの描画を行なう際の表示方法を 設定します。 qmat マテリアルパラメーターを設定 qmat2 マテリアル詳細パラメーターを設定 qmat3 マテリアル表示パラメーターを設定 以下の命令は、オブジェクトそれぞれのユーザーが任意の数値を保存する ためのものです。quser命令では整数値を3つ、quser2命令では 実数値を3つ、合計6つの値を1つのオブジェクトに保存することが可能です。 何に使用するかは、ユーザーが自由に決めることができます。 quser ユーザー定義データを設定 quser2 ユーザー定義データを設定2 以上が、基本的な使い方になります。 ・現バージョンの制限 現在のバージョンでは、使用にあたって以下の制限があります。 これらの値をオーバーした際の動作は保障されませんのでご注意ください。 オブジェクトの最大数 : 最大512個 すべてのオブジェクトが保有する、形状データの頂点数の合計 : 16384まで 1つのオブジェクトに内包できるカスタム形状の数 : 8まで ・表示上の注意点 スプライト表示による画像の回転・拡大・縮小は、高速化のため精度が低い ものとなっています。ワイヤーフレームの輪郭と厳密な一致が起こらない場合が あるのでご了承ください。より高精度な回転などが必要な場合は、DirectX を使用するなどの対応が必要になります。 ワイヤー、スプライトの表示ともに、WindowsのシステムAPI(GDI)を 使用した描画のため、1ドットより小さい単位での動きが切り捨てられて しまいます。これにより、物体がぶれたり、安定しないことがあります。 こういった部分が気になる場合は、必要に応じて、表示側でぶれを吸収する などの対処を行なうようにしてください。 ・OBAQ Model Editorについて OBAQ Model Editorは、qaddmodel命令で使用可能な自由形状を編集するための 簡易的なツールです。 sample/obaqフォルダ内にある、obaqme.hspをスクリプトエディタで 読み込み、実行することができます。 詳しい使用方法は、マニュアル(obaqme.txt)を参照してください。 ・HGIMG3でのサポート HGIMG3のver3.21から、OBAQオブジェクトをDirectXにより表示させるための 機能が搭載されています。ユーザーがOBAQプラグインに対して記述する スクリプトはそのままで、DirectX表示に変更することが可能です。 これにより、大量のオブジェクト表示、高画質なスプライトの回転縮小などに 加えて描画速度の向上も実現することができます。 ・命令一覧 OBAQ.DLLは、HSPに以下の命令を追加して利用可能にします。 それぞれの命令の使用方法は、ヘルプ(F1キーによる命令リファレンス)を参照 してください。 qreset OBAQ初期化 qterm OBAQ終了処理 qexec OBAQフレーム処理 qdraw OBAQ描画処理 qview ビュー設定 qsetreq システムリクエスト設定 qgetreq システムリクエスト取得 qgetptr システムポインタ値取得 qborder 外壁を設定 qgravity 重力を設定 qcnvaxis 内部座標を表示座標に変換 qgetaxis 内部座標を取得 qdel オブジェクト削除 qfind オブジェクト検索 qnext オブジェクト検索結果取得 qcollision コリジョン取得開始 qgetcol コリジョン取得 qgetcol2 コリジョン詳細情報取得 qgetcol3 コリジョン詳細情報取得2 qaddpoly 多角形オブジェクト追加 qaddmodel 自由設定オブジェクト追加 qpos 位置、角度パラメーターを設定 qgetpos 位置、角度パラメーターを取得 qweight 重さなどのパラメーターを設定 qgetweight 重さなどのパラメーターを取得 qspeed 加速パラメーターを設定 qgetspeed 加速パラメーターを取得 qgroup グループパラメーターを設定 qgetgroup グループパラメーターを取得 qtype typeパラメーターを設定 qgettype typeパラメーターを取得 qstat statパラメーターを設定 qgetstat statパラメーターを取得 qmat マテリアルパラメーターを設定 qgetmat マテリアルパラメーターを取得 qmat2 マテリアル詳細パラメーターを設定 qgetmat2 マテリアル詳細パラメーターを取得 qmat3 マテリアル表示パラメーターを設定 qgetmat3 マテリアル表示パラメーターを取得 quser ユーザー定義データを設定 qgetuser ユーザー定義データを取得 quser2 ユーザー定義データを設定2 qgetuser2 ユーザー定義データを取得2 qdamper 吸振などのパラメーターを設定 qgetdamper 吸振などのパラメーターを取得 qinertia 惰性などのパラメーターを設定 qgetinertia 惰性などのパラメーターを取得 qpush 任意の場所に力を与える qblast 任意の場所から放射状に力を与える qgetversion バージョン情報を取得 ・注意点 OBAQ.DLLは、HSP3.EXEと同時に使用されるプラグインファイルです。 使用するHSPは、ver3.3以上をお使い下さい。ver2.61やそれ以前のHSPには 対応していませんのでご注意下さい。 EXEファイルを作成した場合でも、OBAQ.DLLをEXEファイルと同じディレクトリ に置かないと動作しません。また、packfileにDLLを追加することはできません。 ・更新履歴 2010/01/28 ver3.21 obaqme(簡易モデル作成ツール)とサンプルを追加。 タイプ値、type_autowipeを追加。 HGIMG3でのOBAQサポート用にqgetptr命令を追加。 著作権とライセンス文書を一部修正。 2009/10/19 ver3.2a サンプルスクリプトを一部修正。 2009/8/1 ver3.2 サンプルにミニロゴとサムネイルを追加。 2009/7/24 ver3.2rc1 qtypeでtype_innerを正しく設定できなかった不具合を修正。 qaddployでloggroupが反映されていなかった不具合を修正。 qmatで指定する色コードが$RRGGBBになっていなかった不具合を修正。 新規サンプルゲーム、tof2.hspを追加。 2009/7/9 ver3.2beta4 最初のバージョン。 ・クレジット OBAQは、Zener Works, Inc./kuni/onitamaにより共同で開発された物理エンジンです。 物理法則を使ったゲームや、ちょっとした動きに現実感を与える手伝ができれば 嬉しいと思います。 是非とも、OBAQで新しいものを生み出して我々を驚かせてください。 Zener Works, Inc. http://www.zener.co.jp/ kuni http://susami.co.jp/ ONION software http://www.onionsoft.net/ ・著作権とライセンス OBAQ.DLLの著作権はZener Works, Inc/kuni/onitamaにあります。 ユーザーが作成したオリジナルのソフトウェア(実行ファイル)に OBAQ.DLLを添付して配布する場合は、以下の条件に従ってください。 ・無償(フリーソフト)として配布する場合 OBAQ.DLLを自由に添付してお使い頂けます。 使用する際の報告や問い合わせの必要なく、ライセンスされます。 DLLの著作権表示、及びOBAQロゴの明示は、してもしなくても構いません。 ・有償(市販、シェアウエア)として配布する場合 OBAQ.DLLを使用したソフトにより、税務申告が必要な利益が発生する場合には、 有償ライセンスの取得が必要です。 ただし、少数の配布、最低限の必要経費(メディア代金等)のみで配布する 場合は無償と考えますので、有償ライセンスの取得は必要ありません。 有償ライセンスの取得には、必ず費用がかかるわけではありません。 販売数に応じて、定められたライセンス契約を個別に締結させて頂きます。 詳しくは、info@hsp.tvまでメールにてお問い合わせください。 ・無償/有償の共通事項 本プログラムによって生じた、いかなる損害についても保証いたしません。 自己の責任の範囲で使用してください。 また、付属のサンプルスクリプトは自由に改変、公開していただいて構いません。 尚、ライセンス形態に関わりなく、サンプルに付属するOBAQロゴ (obaqlogo.bmp)は自由に組み込んで頂いて結構です。 ------------------------------------------------------------------------------- HSP users manual / end of file -------------------------------------------------------------------------------