------------------------------------------------------------------------------
OBAQ for HSP ver3.4 REFERENCE MANUAL                HSP : Hot Soup Processor  
ＨＳＰ拡張拡張DLLリファレンス    Copyright 2014 (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命令は、３角形・４角形など任意の多角形を生成することが
	できます。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つの値を１つのオブジェクトに保存することが可能です。
	何に使用するかは、ユーザーが自由に決めることができます。

	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を追加することはできません。


・更新履歴

	2014/04/24 ver3.4β4

		qspeed命令のoptionパラメーター値に2を追加しました。
		いままで、optionパラメーターに1を指定していた場合に、
		指定した値の２倍が設定されていました。
		このため、互換性を考慮して、option値で2を指定した場合に、
		指定した値が正しく設定される仕様を追加しました。

	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 
-------------------------------------------------------------------------------
