------------------------------------------------------------------------------
HSPTV API ver3.3 REFERENCE MANUAL                   HSP : Hot Soup Processor  
ＨＳＰ拡張モジュールリファレンス           copyright 2011 (c) onion software  
------------------------------------------------------------------------------

・はじめに

	ここでは、Hot Soup Processor ver3.3以降でサポートされている、
	HSPTVブラウザに対応したプログラム作成についての解説と、付属の
	モジュールについての説明を行ないます。
	HSPTV APIを使用することにより、HSPTV上で動作するプログラムの
	テストと、ランキング作成などの機能が利用可能です。


・使い方の概要

	HSPTV対応プログラムのテストには、スクリプトの先頭に以下の行を追加
	してください。

		#include "hsptv.as"

	これで、HSPTV上での動作チェックと、ランキング機能が利用できるように
	なります。
	また、スクリプトの実行を行なうと、HSPTVブラウザが起動し動作します。


・標準イメージについて

	HSPTVブラウザで使用するための標準イメージが用意されています。
	標準イメージは、hsptvフォルダ内にhsptv_img.bmpとして格納されています。
	すべての環境で共通して使用できる画像素材としてご利用ください。
	以下のスクリプトで画像を読み込むことが可能です。

		;	HSPTVブラウザ用・標準イメージを読み込む
		celload dir_exe+"\\hsptv\\hsptv_img.bmp",1

	上の例では、画像バッファ1に、標準イメージ(hsptv_img.bmp)を読み込みます。	hsptv_img.bmpファイルは、ユーザーが改変・削除・変更しないようにしてください。
	イメージの内容については、実際に画像ファイルを直接ご確認ください。
	汎用的に使用できる16x16、32x32、64x64ドットの素材が、512x512画像として
	詰められています。アイデア次第で様々な用途や目的に利用することができます。


・ランキング機能について

	HSPTV対応プログラムは、ランキング情報を保持する機能を利用することが
	できます。これは、動作しているソフトに対して「スコア」「ユーザー名」
	「コメント」等の情報を一定量保存しておくもので、ゲームのハイスコア
	情報などを記録するなど様々な用途に使用できます。

	ランキング機能で保存される情報は、以下の通りです。

		■スコア

			32bitの整数値。マイナス値は扱えません。
			スコアの値が大きい順に上位30位が保持されます。

		■ユーザー名 

			スコアに付随するデータです。
			スコアを登録したユーザー名の情報を文字列で保持します。
			ユーザー名は、HSPTVブラウザのオプションで設定された
			名前が自動的に使用されます。(英文字のみ20字まで)

		■コメント

			スコアに付随するデータです。
			スコアを登録したユーザーのコメント(付加情報)を
			文字列で保持します。
			この項目は、登録時のコメントに利用するだけでなく、
			ソフトに関する情報を付加するなどプログラム側で自由に
			利用することが可能です。
			コメントには最大255文字までの文字列を保持できます。

	実際に、HSPTVサーバーにプログラムが登録され、HSPTVブラウザにネットから
	配信された場合には、スコア情報はサーバーに保持され、ユーザーの情報を
	記録するインターネットランキングとして機能します。

	HSPTV対応プログラム作成のためにテストしている状態(スクリプトエディタ
	から実行している時)では、カレントディレクトリにスコア情報を保持する
	ためのローカルファイル(hsptvdat.txt)が作成され、サーバーに登録される
	時と同じ状態をシミュレートします。
	(テストの段階では、HSPTVサーバーに情報は送信されません。)

	ユーザーが作成したプログラムでは、「スコア」「ユーザー名」「コメント」
	の情報を自由に取得、更新することができます。
	ハイスコアの保持に使用することはもちろん可能ですし、他の情報を保持
	するために応用することもできます。
	サーバーでは、スコアの値が大きい順に最大３０件までデータを記録して
	いますが、プログラム側が何件まで表示するか、どの項目を表示するか、
	またスコアの値を決める方法も任されています。

	ランキング機能を利用するプログラムを作成する場合には、このドキュメント
	に記載されている「サーバー送信について」の項目をお読み頂き、同意された
	上で開始してください。


・追加命令について

	「hsptv.as」を利用することで、以下の命令を新規に使用できるように
	なります。

	hsptv_up p1,"comment", p2			HSPTVデータ更新

		p1 : スコア値(32bit整数値)
		"comment" : コメント文字列(256byteまで)
		p2 : オプション機能値

		HSPTVデータを更新します。
		スコア,コメント情報を反映させます。
		スコアがマイナス値の場合は最新データのみ取得します。
		(HSPTV配信プログラムの場合は、この命令によってサーバー
		との通信が発生します。この命令の終了までには、ある程度の
		時間がかかることを想定してプログラムを作成してください。)
		コメントは、設定する文字列の情報を256byte(半角255文字)までの
		内容で指定することができます。
		オプション機能値を省略するか、または0を指定した場合は、
		通常のランキング(スコアが高い順)としてデータを更新します。
		オプション値に、0x1000(4096)を指定した場合にはp1で指定した
		インデックスのスコアをクリア(スコアを0にする)します。
		オプション値に、0x2000(8192)を指定した場合には、
		ユーザー名の反映を行なわず、常に空の文字列が設定されます。
		オプション値は複数の値を加算して指定することが可能です。
		(データの内容をクリアする場合には、オプション値0x1000及び
		0x2000を組み合わせて使用してください。)


	hsptv_getrank var1,var2,var3,rank		HSPTVデータ取得

		var1 : スコア情報が代入される変数名
		var2 : ユーザー名情報が代入される変数名
		var3 : コメント情報が代入される変数名
		rank : 順位のインデックス(0〜29)

		HSPTVデータの内容を変数に読み出します。
		この命令は、hsptv_up命令によって更新されたデータを
		変数に読みだすものです。
		読み出される内容は、最後にhsptv_up命令を実行した
		時点の情報になります。
		rankの値は、は0が1位、29が30位となります。
		var1は数値型、var2,var3は文字列型として初期化されます。
		この命令では、通信は発生しないので、情報の読み出しは
		即時に行なわれます。


・サーバー送信について

	実際にサーバー上から配信された場合は、ランキング情報の登録、取得に
	ネットワーク通信が行なわれます。
	最初に情報を送信する前には、「現在の情報をHSPTVサーバーに反映させて
	いいですか？」というダイアログが表示され、「はい」を選択した時のみ
	送信が行なわれます。
	(テストの段階では、「以上の情報を反映させていいですか？」という
	ダイアログが表示されます。)

	サーバーとの通信は、ネットワークの負荷や環境によって時間がかかる場合が
	あります。ある程度の時間がかかることを想定したプログラムを作成して
	おいてください。リアルタイムにデータを更新するようなプログラムは、
	作成できません。また、サーバーの負荷を抑えるためにも、５秒に１回の
	アクセス以上の頻度にならないように心掛けて下さい。
	必要以上にサーバー負荷がかかるプログラムの登録は、ネットワーク帯域
	確保のため、やむを得ず一時的に休止させて頂く場合もありますので、
	予めご了承下さい。

	サーバーとの通信は、httpプロトコルによって行なわれます。
	PROXYサーバー等の設定は、HSPTVブラウザの設定がそのまま使用されます。

	HSPTVサーバー側に保持されたランキング情報は、基本的に配信される
	ソフトウェアごとに独立して管理され、対応したソフトウェア以外から
	アクセスされることはありません。
	HSPTVサーバーは、可能な限りランキング情報についての保持と管理を
	行ないますが、あくまでも現状をサービスとするもので、内容についての
	保証をするものではありません。
	事故やアップデートなどにより、やむを得ず、すべての情報が破棄される
	可能性がありますので、予めご了承下さい。


・サンプルスクリプトについて

	サンプルディレクトリmiscに「hsptv_test.hsp」として、以下のスクリプトが
	収録されています。
	このスクリプトは、上位10名の情報表示と更新を行なうことができます。

	#include "hsptv.as"

		score=1000
		sdim comm,64
		mes "HSPTVデータの更新登録テスト"
		hsptv_up -1,""				; 最初に情報を更新しておく
		gosub *update				; ランキング情報の表示

		pos 500,32:objsize 120,24
		mes "スコア"
		input score
		mes "コメント"
		input comm
		button "更新",*send
		button "終了",*ok
		stop

	*send
		hsptv_up score, comm
		gosub *update
		stop
	*ok
		end

	*update
		color 255,255,255
		boxf 0,32,500,480			; 背景をクリア
		color 0,0,0
		pos 0,32
		repeat 10				; 上位10位のみ表示
		hsptv_getrank rscore,ruser,rcomm,cnt	; 情報を取得する
		rank=cnt+1
		mes "#"+rank+":"+rscore+"("+ruser+") "
		mes "    コメント:"+rcomm
		loop
		return

	この他、標準イメージを利用するためのサンプル、「hsptv_test2.hsp」
	「hsptv_test3.hsp」も収録されています。


・再受信可能な文字列について

	HSPTVサーバーとの通信は、文字列を別なコードにエンコードした後に
	行なわれます。日本語を含む、ほとんどの文字列は送信可能ですが、
	全角文字や特殊文字の一部で文字化けが発生する可能性があります。
	また、「&」記号は送信の段階で別な文字に変換されるため、
	正常な結果が期待できません。バイナリデータを文字列に変換する場合などは
	特に注意するようにしてください。


・更新履歴

	2011/7/26  ver3.3RC1

		標準イメージの記述を追加。

	2007/7/13  ver3.2β4

		hsptv_upのcomment文字列を最大256byteに拡大。

	2007/7/28  ver3.1

		正式版としてリリース。

	2007/7/20  ver3.1RC1

		最初のバージョン。


・注意点

	hsptv.asは、あくまでもHSPTVブラウザ上で動作するプログラムのテストに
	利用するためのファイルです。hsptv.asを利用した状態で、実行ファイル
	作成を行なうことはできません。

	HSPTV対応プログラムは、セキュリティのため以下の機能を制限しています。

	・ファイルの削除機能(delete命令)
	・マウスカーソルの表示コントロール(mouse -1によるカーソル消去)
	・windowsなどシステムが使用するフォルダへのアクセス

	これらの機能は、HSPTV対応プログラムで使用しないようお願い致します。
	使用した場合は、無効になるか、またはエラーとなります。

	実際にHSPTVブラウザ上で配信されるプログラムは、HSPTVサーバーに
	登録しなければ、他のユーザーに届きません。
	HSPTVサーバーへの登録は、HSPプログラムコンテストなどHSPTVサイト上で
	不定期に行なわれています。詳しくは、HSPTVサイトを参照してください。


・著作権およびライセンス


	HSPTV及びhsptvモジュールは、onion softwareの著作物です。
	onion softwareは本プログラムによって生じた、いかなる損害についても
	保証いたしません。自己の責任の範囲で使用してください。

	hsptvモジュール(hsptv.as)は、BSDライセンスのもと、自由に改編、再配布を
	行なうことができます。


-------------------------------------------------------------------------------
                                                HSP users manual / end of file 
-------------------------------------------------------------------------------
