------------------------------------------------------------------------------
HSPSW ver3.6 REFERENCE MANUAL                       HSP : Hot Soup Processor  
ＨＳＰ拡張拡張DLLリファレンス         copyright 2005-2020 (c) onion software  
------------------------------------------------------------------------------

・はじめに

	このDLLは、Hot Soup Processor ver3以降とともに使用することで、
	STEAMWORKS SDKが持つSteam連携機能を利用可能にします。
	HSPSWを使用することにより、以下の機能がサポートされます。

		STEAM実績の取得・解除・再設定
		STEAMステータス値の取得・設定


・使い方の概要

	HSPSWを使用する場合は、スクリプトの先頭に必ず「#include "hspsw.as"」
	という行を追加してください。以上で、HSPの機能が拡張され、このリファレンスで
	説明をしている命令を使用することができるようになります。

	HSPSW.DLLは、必ずSTEAMがインストールされている環境で使用してください。
	実行時には、HSPSW.DLLと同じフォルダに、以下のファイルを配置する
	必要があります。

		steam_api.dll			STEAMWORKS API DLL
		sdkencryptedappticket.dll	STEAMWORKS SDK 付属DLL

	これらのファイルは、STEAMWORKS SDKのファイルに含まれています。
	steamworksのページ( https://partner.steamgames.com/ )からダウンロード
	することができるSDKパッケージ(steamworks_sdk_???.zip)内からファイルを
	コピーして使用してください。
	DLLは、アーカイブ内の以下のフォルダに含まれています。

	/sdk/public/steam/lib/win32/sdkencryptedappticket.dll
	/sdk/redistributable_bin/steam_api.dll


・事前の準備

	このプラグインは、STEAMWORKS SDKの機能を呼び出します。
	最初に、STEAM及びSTEAMWORKS SDKについてのドキュメントを参照し、
	仕組みについて理解をしておいてください。

	自身のアプリで使用する際には、アプリIDと実績・ステータス等を
	あらかじめSTEAM側で設定しておく必要があります。

	このプラグインサンプルでは、STEAMのサンプルゲーム「Spacewar」
	(APPID 480)を使用してテストを行っています。
	アプリIDは、「steam_appid.txt」ファイルで指定されています。
	自身のアプリでテストする場合は、テキストエディタ等で、
	「steam_appid.txt」の内容を修正してください。
	「steam_appid.txt」は、必ずHSPSW.DLLと同じフォルダに配置して
	おいてください。


・実績テーブル

	STEAMの実績を実装する場合は、以下の手順が必要になります。

	1. Steamworksアプリ管理の実績の設定ページで実績を設定する
	2. HSPSW.DLLプラグイン上で実績テーブルを作成する
	3. 実績テーブルの最新情報をリクエストする
	4. 実績の取得・解除を行う

	HSPSW.DLLプラグイン上で作成するコードは、2〜4になります。

	1つの実績が持つデータは、以下になります

	API Name : 呼び出し用文字列(英文字列)、AchievementIDとも呼ばれます。
	Display Name : 表示される実績の名前(UTF-8文字列)
	Description : 表示される実績の説明(UTF-8文字列)

	あらかじめ、Steamworksアプリ管理のページで設定を行ってください。
	最も重要なのは、API Nameで「ACH_WIN_ONE_GAME」などの文字列で
	管理します。必ず実績ごとに異なる文字列を指定する必要があります。

	実績テーブルは、HSPSW.DLL内で実績の情報を蓄積するための
	メモリエリアです。実績の情報取得を行う際にあらかじめ作成しておく
	必要があります。

	実績テーブルは、自動作成と手動作成の２通りの方法で作成できます。
	自動作成は、ゲームに設定された実績のリストをすべて登録します。
	これは、steamset_achievement命令によって行うことが可能です。
	通常は、実績テーブルを自動作成しておいて問題ありません。
	手動作成する場合は、steamset_max命令でテーブルの最大数を指定した
	後に、steamreg_achievement命令でAPIKEYを登録していきます。

	実績テーブルが作成できたら、steamreq_status命令により最新の情報を
	取得してください。steamreq_status命令は、単純にサーバーに取得の
	リクエストを行うだけなので、実際にデータを受け取るまで待つ必要が
	あります。

	フレームごとに、steamupdate命令を呼び出して、常にSTEAM APIの
	状態監視と更新を行っておいてください。
	リクエスト中は、steamupdate命令で取得されるflag値が、通信中の
	ステータス(STEAM_GETSTAT)になっています。
	これが、準備完了のステータス(STEAM_READY)になれば、正しく
	実績テーブル及びステータスが更新されたことを示します。

	実績テーブルを取得後、以下の操作が可能です。

	steamget_achievement命令により実績の状態を取得できます。
	steamget_achievementstr命令により、実績の文字列データを取得できます。

	steamunlock_achievement , steamunlock_achievementkey命令に
	より、実績を解除することができます。
	steamclear_achievement , steamclear_achievementkey命令により
	実績をクリア(解除前に戻す)することができます。
	実績のクリアは、テスト段階でのみ利用可能です。
	実際のアプリ上ではサポートされないのでご注意ください。

	実績の解除は、必ずアプリケーション上で実装する必要があります。
	また、実績解除を行った場合は、直後にサーバーへの通信が行われます。
	steamupdate命令で取得されるflag値が、通信中のステータス(STEAM_GETSTAT)から
	準備完了のステータス(STEAM_READY)になることを確認するようにしてください。


・ステータス値(STEAMゲームデータ)

	STEAMのゲームデータ読み書きを実装する場合は、以下の手順が必要になります。

	1. Steamworksアプリ管理の設定ページでゲームデータを設定する
	2. 最新情報をリクエストする
	3. ステータス値の取得・設定を行う

	ステータス値は、Steamworksアプリ管理の設定ページで設定されるゲームデータのことです。
	整数値(int値)、または実数(float値)をサーバーに保持しておき、アプリケーションから
	数値の更新を行うことが可能です。
	ゲームデータは実績と結びついていて、ゲームデータ値をもとに実績を解除したり
	実績の達成度を、ゲームデータをもとに算出するなどで使われます。
	これらの定義は、すべてアプリ管理の設定ページで行います。

	ステータス値は、実績テーブルとセットで管理されています。
	steamreq_status命令により、サーバーから最新のデータを取得した際に
	ステータス値も更新されます。

	ステータス値の取得は、steamget_status、steamget_statusf命令を
	使用します。(float値の場合は、「f」の付いた命令を使用します)

	ステータス値の設定は、steamset_status、steamset_statusf命令を
	使用します。(float値の場合は、「f」の付いた命令を使用します)
	ステータス値を設定した場合は、直後にサーバーへの通信が行われます。
	steamupdate命令で取得されるflag値が、通信中のステータス(STEAM_GETSTAT)から
	準備完了のステータス(STEAM_READY)になることを確認するようにしてください。
	まとめてステータス値を設定する場合は、1回ごとに通信を待つ必要は
	ありません。

		例:
			steamset_status "NumGames",99
			steamset_statusf "MaxFeetTraveled",1.1
			repeat
				steamupdate flag
				if flag=STEAM_READY : break
				if flag=STEAM_ERROR : break
			loop


・ランキング(Steamランキング)

	ランキング(Steamランキング)は将来のバージョンで提供される予定です。


・命令一覧

	steaminit                                       STEAM APIの初期化
	steambye                                        STEAM APIの終了
	steamupdate                                     STEAM APIの更新
	steamset_max                                    実績テーブルの初期化
	steamreq_status                                 ステータス取得リクエスト

	steamset_achievement                            実績テーブル自動設定
	steamreg_achievement                            実績テーブル設定
	steamget_achievement                            実績テーブル値取得
	steamget_achievementstr                         実績テーブル文字列取得
	steamunlock_achievement                         実績の解除
	steamunlock_achievementkey                      実績の解除
	steamclear_achievement                          実績のクリア
	steamclear_achievementkey                       実績のクリア

	steamset_status                                 ステータス値の設定
	steamset_statusf                                ステータス値の設定
	steamget_status                                 ステータス値の取得
	steamget_statusf                                ステータス値の取得


・命令の詳細

	steaminit                                       STEAM APIの初期化

		STEAM APIの初期化を行います。
		最初に１回だけ実行してください。
		実行後に結果がシステム変数statに格納されます。
		0ならば正常終了、それ以外はエラーが発生したことを示しています。
		ネットワークの接続ができない場合や、STEAMが起動されていない
		場合はエラーになります。


	steambye                                        STEAM APIの終了

		STEAM APIの終了処理を行います。
		プログラム終了時に自動的に呼び出されるので、
		通常は実行する必要はありません。


	steamupdate var                                 STEAM APIの更新

		var : flag値が代入される変数

		STEAM APIの更新処理を行います。
		ここで、STEAMからの情報取得や、通信の処理を行います。
		一定時間ごとに呼び出す必要があります。
		通常は、メインの描画フレームループ内などに入れてご使用ください。
		実行後にflag値が指定された変数に格納されます。
		flag値の内容は、以下の通りです。

		ラベル             | 値    状態
		------------------------------------------------------
		STEAM_NONE         |  0    未初期化の状態
		STEAM_ERROR        |  1    エラー状態
		STEAM_READY        |  2    待機状態
		STEAM_GETSTAT      |  3    リクエスト送信中

		リクエスト通信などを行っている最中は、flag値がSTEAM_GETSTATに
		なっています。必ず、STEAM_READYに戻ることを確認してください。
		何らかのエラーが発生した場合は、STEAM_ERRORとなります。
		その場合は、再度リクエストを行うなど適切な復帰処理を
		実装してください。


	steamset_achievement                            実績テーブル自動設定

		実績テーブルを自動設定します。
		実績テーブルは、あらかじめ必要な実績の情報を蓄積するための
		内部エリアです。
		この命令により、ゲームに設定された実績のリストを自動的に
		実績テーブルに登録します。
		手動で実績テーブルを設定する場合は、steamset_max及び
		steamreg_achievement命令を使用してください。

		実行後に自動設定された実績の数がシステム変数statに格納されます。
		システム変数statが0の場合は、設定されなかったことを示します。


	steamset_max p1                                 実績テーブルの初期化

		p1 (0)       : 実績テーブルで管理される実績の数

		実績テーブルを手動設定するために初期化を行います。
		p1で実績テーブルで管理される実績の数を指定します。
		以降は、steamreg_achievementで任意の実績テーブルを設定する
		ことができます。


	steamreg_achievement index,"APINAME"            実績テーブル設定

		index (0) : 設定する実績のインデックス(0〜)
		"APINAME" : 設定する実績のAPI Name

		実績テーブルを手動で設定します。
		indexで0から始まる実績のindex値を指定します。
		"APINAME"で、あらかじめ設定されているAPI Nameを指定します。
		実行後に結果がシステム変数statに格納されます。
		0ならば正常終了、それ以外はエラーが発生したことを示しています。


	steamreq_status                                 ステータス取得リクエスト
		STEAMサーバーから実績・ステータス値の最新情報を取得する
		リクエストを行います。
		この命令実行後は、サーバーへの通信が行われます。
		steamupdate命令で取得されるflag値が、通信中(STEAM_GETSTAT)から
		準備完了(STEAM_READY)になることを確認するようにしてください。

		例:
			steamreq_status
			repeat
				steamupdate flag
				if flag=STEAM_READY : break
				if flag=STEAM_ERROR : break
			loop


	steamget_achievement var, index                 実績テーブル値取得

		var   : 結果が代入される変数
		index (0) : 取得する実績のインデックス(0〜)

		実績テーブルに設定された実績解除の情報を取得します。
		varで指定された変数に整数型で結果が代入されます。
		実績解除の情報は、以下の値になります。

			-1 : 実績解除されている
			0  : 実績解除されていない

		実行後に結果がシステム変数statに格納されます。
		0ならば正常終了、それ以外はエラーが発生したことを示しています。


	steamget_achievementstr var, index,type        実績テーブル文字列取得

		var   : 結果が代入される変数
		index (0) : 取得する実績のインデックス(0〜)
		type (0)  : 取得する値のタイプ

		実績テーブルに設定された情報を取得します。
		varで指定された変数に文字列型で結果が代入されます。
		取得する値のタイプ値は、以下の値になります。

			0  : API Name
			1  : Display Name : 表示される実績の名前(UTF-8文字列)
			2  : Description : 表示される実績の説明(UTF-8文字列)

		実行後に結果がシステム変数statに格納されます。
		0ならば正常終了、それ以外はエラーが発生したことを示しています。


	steamunlock_achievement index                   実績の解除

		index (0) : 実績テーブルのインデックス(0〜)

		指定された実績を解除します。
		この命令実行後は、サーバーへの通信が行われますので、
		正しく更新が行われることを確認してください。


	steamunlock_achievementkey "API Name"           実績の解除

		"API Name" : 実績のAPI Name

		指定された実績を解除します。
		この命令実行後は、サーバーへの通信が行われますので、
		正しく更新が行われることを確認してください。


	steamclear_achievement index                    実績のクリア

		index (0) : 実績テーブルのインデックス(0〜)

		指定された実績をリセット(解除前の状態に戻す)します。
		実績のクリアは、テスト段階でのみ利用可能です。
		実際のアプリ上ではサポートされないのでご注意ください。
		この命令実行後は、サーバーへの通信が行われますので、
		正しく更新が行われることを確認してください。


	steamclear_achievementkey "API Name"            実績のクリア

		"API Name" : 実績のAPI Name

		指定された実績をリセット(解除前の状態に戻す)します。
		実績のクリアは、テスト段階でのみ利用可能です。
		実際のアプリ上ではサポートされないのでご注意ください。
		この命令実行後は、サーバーへの通信が行われますので、
		正しく更新が行われることを確認してください。


	steamset_status "API Name", p1                  ステータス値の設定

		"API Name" : ステータス値のAPI Name
		p1(0)      : 設定するステータス値

		指定されたステータス値を整数で設定します。
		実行後に結果がシステム変数statに格納されます。
		0ならば正常終了、それ以外はエラーが発生したことを示しています。
		この命令実行後は、サーバーへの通信が行われますので、
		正しく更新が行われることを確認してください。


	steamset_statusf "API Name", p1                 ステータス値の設定

		"API Name" : ステータス値のAPI Name
		p1(0)      : 設定するステータス値(実数)

		指定されたステータス値を実数で設定します。
		実行後に結果がシステム変数statに格納されます。
		0ならば正常終了、それ以外はエラーが発生したことを示しています。
		この命令実行後は、サーバーへの通信が行われますので、
		正しく更新が行われることを確認してください。


	steamget_status var, "API Name"                 ステータス値の取得

		var   : 結果が代入される変数
		"API Name" : ステータス値のAPI Name

		指定されたステータス値を取得します。
		結果は、varで指定された変数に整数型で代入されます。
		実行後に結果がシステム変数statに格納されます。
		0ならば正常終了、それ以外はエラーが発生したことを示しています。


	steamget_statusf var, "API Name"                ステータス値の取得

		var   : 結果が代入される変数
		"API Name" : ステータス値のAPI Name

		指定されたステータス値を取得します。
		結果は、varで指定された変数に実数型で代入されます。
		実行後に結果がシステム変数statに格納されます。
		0ならば正常終了、それ以外はエラーが発生したことを示しています。


・更新履歴

	2018/09/30

		最初のバージョン。


・注意点

	HSPSW.DLLは、HSP3.EXEと同時に使用されるプラグインファイルです。
	使用するHSPは、ver3.0以上をお使い下さい。ver2.61やそれ以前のHSPには
	対応していませんのでご注意下さい。
	EXEファイルを作成した場合でも、HSPSW.DLLをEXEファイルと同じディレクトリ
	に置かないと動作しません。また、packfileにDLLを追加することはできません。


・ライセンスおよび連絡先

	ユーザーがHSPを使って作成したオリジナルのソフトウェア(実行ファイル)の
	権利は、それを作成したユーザーに属します。
	ライセンスはHSPと同様にBSDライセンスになります。
	有償・無償を問わずHSPSW.DLLを自由に配布することができます。

	ユーザーが作成したオリジナルのソフトウェアに対してonion softwareが著作権を
	主張することはありません。
	onion softwareは本プログラムによって生じた、いかなる損害についても
	保証いたしません。自己の責任の範囲で使用してください。
	HSPSW.DLLは、Microsoft Visual Studio 2017でコンパイルされて います。 


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