doclib\hspsw.txt » Plain Format
------------------------------------------------------------------------------
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
-------------------------------------------------------------------------------