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