GS2-Quest SDK for Game Engine API リファレンス
モデル
EzContents
EzConsumeAction
| 型 | 必須 | デフォルト | 値の制限 | 説明 |
---|
action | enum [] | ✓ | | ~ 128文字 | スタンプタスクで実行するアクションの種類 |
request | string | ✓ | | ~ 1048576文字 | 入手リクエストのJSON |
EzAcquireAction
| 型 | 必須 | デフォルト | 値の制限 | 説明 |
---|
action | enum [] | ✓ | | ~ 128文字 | スタンプシートを使用して実行するアクションの種類 |
request | string | ✓ | | ~ 1048576文字 | リクエストのJSON |
EzReward
| 型 | 必須 | デフォルト | 値の制限 | 説明 |
---|
action | enum [] | ✓ | | ~ 128文字 | スタンプシートを使用して実行するアクションの種類 |
request | string | ✓ | | ~ 5242880文字 | リクエストモデル |
itemId | string | ✓ | | ~ 1024文字 | 入手するリソースGRN |
value | int | ✓ | | ~ 2147483646 | 入手する数量 |
EzConfig
| 型 | 必須 | デフォルト | 値の制限 | 説明 |
---|
key | string | | | ~ 64文字 | 名前 |
value | string | | | ~ 51200文字 | 値 |
EzProgress
クエスト進行状況
クエストの開始時に作成され、終了時に削除されます。
インゲームの途中でアプリを終了した際にはこのデータが残った状態となり
エンティティが保持する進行中のクエスト情報からゲームをリジュームすることが可能です。
| 型 | 必須 | デフォルト | 値の制限 | 説明 |
---|
progressId | string | ✓ | | ~ 1024文字 | クエスト進行状況GRN |
transactionId | string | ✓ | UUID | ~ 36文字 | トランザクションID |
questModelId | string | ✓ | | ~ 1024文字 | 進行中のクエストモデルGRN |
randomSeed | long | ✓ | | ~ 9223372036854775806 | 乱数シード |
rewards | List<EzReward> | | [] | | クエストで得られる報酬の上限 |
EzCompletedQuestList
クリア済みのクエストリスト
| 型 | 必須 | デフォルト | 値の制限 | 説明 |
---|
questGroupName | string | ✓ | | ~ 128文字 | クエストグループ名 |
completeQuestNames | List<string> | | | | 攻略済みのクエスト名一覧のリスト |
EzQuestGroupModel
クエストグループモデル
クエストグループは複数のクエストをグルーピングするためのエンティティで、クエストの進行はグループ内で同時に1つしか実行できません。
つまり、並列でクエストを進行できるようにする必要がある場合はグループを分ける必要があります。
| 型 | 必須 | デフォルト | 値の制限 | 説明 |
---|
name | string | ✓ | | ~ 128文字 | クエストグループ名 |
metadata | string | | | ~ 1024文字 | メタデータ |
quests | List<EzQuestModel> | | | | グループに属するクエスト |
challengePeriodEventId | string | | | ~ 1024文字 | クエストに挑戦可能な期間を設定した GS2-Schedule イベントGRN |
EzQuestModel
クエストモデル
クエストはインゲームの開始に必要な対価とクリアしたときに得られる報酬を保持するエンティティです。
クリアしたときに得られる報酬は複数のバリエーションを用意でき、クエスト開始時に抽選することができます。
例えば、クエストのクリアフラグ管理は同じコンテンツだが、レアモンスターの出現有無で2種類のコンテンツを用意することができます。
| 型 | 必須 | デフォルト | 値の制限 | 説明 |
---|
questModelId | string | ✓ | | ~ 1024文字 | クエストモデルGRN |
name | string | ✓ | | ~ 128文字 | クエストモデル名 |
metadata | string | | | ~ 1024文字 | メタデータ |
contents | List<EzContents> | ✓ | | | クエストの内容 |
challengePeriodEventId | string | | | ~ 1024文字 | クエストに挑戦可能な期間を設定した GS2-Schedule イベントGRN |
firstCompleteAcquireActions | List<EzAcquireAction> | | [] | | 初回クリア報酬アクションリスト |
consumeActions | List<EzConsumeAction> | | [] | | クエストの参加料 |
failedAcquireActions | List<EzAcquireAction> | | [] | | クエスト失敗時の報酬 |
premiseQuestNames | List<string> | | [] | | クエストに挑戦するためにクリアしておく必要のあるクエスト名 |
メソッド
deleteProgress
クエストの進行情報を削除。
クエストの開始時に force
オプションを使うのではなく、明示的に進行情報を削除したい場合に使用してください。
Request
| 型 | 必須 | デフォルト | 値の制限 | 説明 |
---|
namespaceName | string | ✓ | | ~ 32文字 | ネームスペース名 |
accessToken | string | ✓ | | ~ 128文字 | ユーザーID |
Result
実装例
var domain = gs2.Quest.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
);
var result = await domain.DeleteProgressAsync(
);
var domain = gs2.Quest.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
);
var future = domain.DeleteProgress(
);
yield return future;
if (future.Error != null)
{
onError.Invoke(future.Error, null);
yield break;
}
const auto Domain = Gs2->Quest->Namespace(
"namespace-0001" // namespaceName
)->Me(
AccessToken
);
const auto Future = Domain->DeleteProgress(
);
Future->StartSynchronousTask();
if (Future->GetTask().IsError())
{
return false;
}
end
クエストの完了を報告
クエストが完了したことを報告します。その際に isComplete
にクエストに成功したか、失敗したかを渡します。
クエストに成功した場合は rewards
にクエスト内で入手した報酬を報告する必要があります。
rewards
で報告された内容は評価され、開始時に渡した数量以上や入手できないリソースを入手したと報告してきた場合はエラーとなります。
Request
| 型 | 必須 | デフォルト | 値の制限 | 説明 |
---|
namespaceName | string | ✓ | | ~ 32文字 | ネームスペース名 |
accessToken | string | ✓ | | ~ 128文字 | ユーザーID |
rewards | List<EzReward> | | [] | | クエストで実際に得た報酬 |
transactionId | string | ✓ | UUID | ~ 36文字 | トランザクションID |
isComplete | bool | ✓ | | | クエストをクリアしたか |
config | List<EzConfig> | | [] | | スタンプシートの変数に適用する設定値 |
Result
| 型 | 説明 |
---|
item | EzProgress | クエスト進行状況 |
transactionId | string | 発行されたスタンプシートのトランザクションID |
stampSheet | string | 報酬付与処理の実行に使用するスタンプシート |
stampSheetEncryptionKeyId | string | スタンプシートの署名計算に使用した暗号鍵GRN |
autoRunStampSheet | bool | スタンプシートの自動実行が有効か |
実装例
var domain = gs2.Quest.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
).Progress(
);
var result = await domain.EndAsync(
isComplete: true,
rewards: new Gs2.Unity.Gs2Quest.Model.EzReward[] {
new Gs2.Unity.Gs2Quest.Model.EzReward
{},
},
config: null
);
// New Experience ではスタンプシートはSDKレベルで自動的に実行されます。
// エラーが発生すると TransactionException がスローされます。
// TransactionException::Retry() でリトライが可能です。
// In New Experience, stamp sheets are automatically executed at the SDK level.
// If an error occurs, a TransactionException is thrown.
// you can retry with TransactionException::Retry().
var domain = gs2.Quest.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
).Progress(
);
var future = domain.End(
isComplete: true,
rewards: new Gs2.Unity.Gs2Quest.Model.EzReward[] {
new Gs2.Unity.Gs2Quest.Model.EzReward
{},
},
config: null
);
yield return future;
if (future.Error != null)
{
onError.Invoke(future.Error, null);
yield break;
}
// New Experience ではスタンプシートはSDKレベルで自動的に実行されます。
// エラーが発生すると TransactionException がスローされます。
// TransactionException::Retry() でリトライが可能です。
// In New Experience, stamp sheets are automatically executed at the SDK level.
// If an error occurs, a TransactionException is thrown.
// you can retry with TransactionException::Retry().
const auto Domain = Gs2->Quest->Namespace(
"namespace-0001" // namespaceName
)->Me(
AccessToken
)->Progress(
);
const auto Future = Domain->End(
true,
[]
{
const auto v = MakeShared<TArray<TSharedPtr<Gs2::Quest::Model::FReward>>>();
v->Add({});
return v;
}(), // rewards
nullptr // config
);
Future->StartSynchronousTask();
if (Future->GetTask().IsError())
{
return false;
}
getProgress
クエストの進行情報を取得。
Request
| 型 | 必須 | デフォルト | 値の制限 | 説明 |
---|
namespaceName | string | ✓ | | ~ 32文字 | ネームスペース名 |
accessToken | string | ✓ | | ~ 128文字 | ユーザーID |
Result
実装例
var domain = gs2.Quest.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
).Progress(
);
var item = await domain.ModelAsync();
var domain = gs2.Quest.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
).Progress(
);
var future = domain.Model();
yield return future;
var item = future.Result;
const auto Domain = Gs2->Quest->Namespace(
"namespace-0001" // namespaceName
)->Me(
AccessToken
)->Progress(
);
const auto item = Domain.Model();
start
クエストの開始を宣言
すでに同一ゲームプレイヤーで開始済みのクエストがある場合は失敗します。
それでも強制的に開始したい場合は force
オプションに true を指定してください。
クエストの開始が完了すると、そのクエストで得られる最大報酬に関する情報が応答されます。
その内容をクエスト内の演出で排出してください。
その際に、応答に含まれる乱数シードを使用してゲームプレイに再現性があるように設計しておくと、アプリで乱数起因の不具合が発生したときに調査しやすくなります。
進行中のクエストを一意に特定するためのIDとして クエストトランザクションID
が応答されます。
クエストの完了を報告する際には クエストトランザクションID
を指定することで、どのクエストに対する完了報告かを識別します。
Request
| 型 | 必須 | デフォルト | 値の制限 | 説明 |
---|
namespaceName | string | ✓ | | ~ 32文字 | ネームスペース名 |
questGroupName | string | ✓ | | ~ 128文字 | クエストグループ名 |
questName | string | ✓ | | ~ 128文字 | クエストモデル名 |
accessToken | string | ✓ | | ~ 128文字 | ユーザーID |
force | bool | ✓ | false | | すでに開始しているクエストがある場合にそれを破棄して開始するか |
config | List<EzConfig> | | [] | | スタンプシートの変数に適用する設定値 |
Result
| 型 | 説明 |
---|
transactionId | string | 発行されたスタンプシートのトランザクションID |
stampSheet | string | クエストの開始処理の実行に使用するスタンプシート |
stampSheetEncryptionKeyId | string | スタンプシートの署名計算に使用した暗号鍵GRN |
autoRunStampSheet | bool | スタンプシートの自動実行が有効か |
Error
このAPIには特別な例外が定義されています。
GS2-SDK for GameEngine ではゲーム内でハンドリングが必要そうなエラーは一般的な例外から派生した特殊化した例外を用意することでハンドリングしやすくしています。
一般的なエラーの種類や、ハンドリング方法は こちら のドキュメントを参考にしてください。
型 | 基底クラス | 説明 |
---|
InProgressException | BadRequestException | クエストはすでに進行中です |
実装例
try {
var domain = gs2.Quest.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
);
var result = await domain.StartAsync(
questGroupName: "group-0001",
questName: "quest-0001",
force: null,
config: null
);
} catch(Gs2.Gs2Quest.Exception.InProgress e) {
// Quest is already underway.
}
// New Experience ではスタンプシートはSDKレベルで自動的に実行されます。
// エラーが発生すると TransactionException がスローされます。
// TransactionException::Retry() でリトライが可能です。
// In New Experience, stamp sheets are automatically executed at the SDK level.
// If an error occurs, a TransactionException is thrown.
// you can retry with TransactionException::Retry().
var domain = gs2.Quest.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
);
var future = domain.Start(
questGroupName: "group-0001",
questName: "quest-0001",
force: null,
config: null
);
yield return future;
if (future.Error != null)
{
if (future.Error is Gs2.Gs2Quest.Exception.InProgressException)
{
// Quest is already underway.
}
onError.Invoke(future.Error, null);
yield break;
}
// New Experience ではスタンプシートはSDKレベルで自動的に実行されます。
// エラーが発生すると TransactionException がスローされます。
// TransactionException::Retry() でリトライが可能です。
// In New Experience, stamp sheets are automatically executed at the SDK level.
// If an error occurs, a TransactionException is thrown.
// you can retry with TransactionException::Retry().
const auto Domain = Gs2->Quest->Namespace(
"namespace-0001" // namespaceName
)->Me(
AccessToken
);
const auto Future = Domain->Start(
"group-0001",
"quest-0001",
nullptr, // force
nullptr // config
);
Future->StartSynchronousTask();
if (Future->GetTask().IsError())
{
if (Gs2::Quest::Error::FInProgressError::TypeString == Task->GetTask().Error()->Type())
{
// Quest is already underway.
}
return false;
}
describeCompletedQuestLists
クエスト進行情報の一覧を取得
クエストグループごとに1つの クエスト進行情報
として登録されており、
クエスト進行情報
にはクエストグループ内でクリア済みのクエスト名の一覧が記録されています。
Request
| 型 | 必須 | デフォルト | 値の制限 | 説明 |
---|
namespaceName | string | ✓ | | ~ 32文字 | ネームスペース名 |
accessToken | string | ✓ | | ~ 128文字 | ユーザーID |
pageToken | string | | | ~ 1024文字 | データの取得を開始する位置を指定するトークン |
limit | int | ✓ | 30 | 1 ~ 1000 | データの取得件数 |
Result
実装例
var domain = gs2.Quest.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
);
var items = await domain.CompletedQuestListsAsync(
).ToListAsync();
var domain = gs2.Quest.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
);
var it = domain.CompletedQuestLists(
);
List<EzCompletedQuestList> items = new List<EzCompletedQuestList>();
while (it.HasNext())
{
yield return it.Next();
if (it.Error != null)
{
onError.Invoke(it.Error, null);
break;
}
if (it.Current != null)
{
items.Add(it.Current);
}
else
{
break;
}
}
const auto Domain = Gs2->Quest->Namespace(
"namespace-0001" // namespaceName
)->Me(
AccessToken
);
const auto It = Domain->CompletedQuestLists(
);
for (auto Item : *It)
{
}
getCompletedQuestList
クエスト進行情報を取得
Request
| 型 | 必須 | デフォルト | 値の制限 | 説明 |
---|
namespaceName | string | ✓ | | ~ 32文字 | ネームスペース名 |
questGroupName | string | ✓ | | ~ 128文字 | クエストグループ名 |
accessToken | string | ✓ | | ~ 128文字 | ユーザーID |
Result
実装例
var domain = gs2.Quest.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
).CompletedQuestList(
questGroupName: "main"
);
var item = await domain.ModelAsync();
var domain = gs2.Quest.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
).CompletedQuestList(
questGroupName: "main"
);
var future = domain.Model();
yield return future;
var item = future.Result;
const auto Domain = Gs2->Quest->Namespace(
"namespace-0001" // namespaceName
)->Me(
AccessToken
)->CompletedQuestList(
"main" // questGroupName
);
const auto item = Domain.Model();
getQuestGroup
クエストグループの一覧を取得
Request
| 型 | 必須 | デフォルト | 値の制限 | 説明 |
---|
namespaceName | string | ✓ | | ~ 32文字 | ネームスペース名 |
questGroupName | string | ✓ | | ~ 128文字 | クエストグループ名 |
Result
実装例
var domain = gs2.Quest.Namespace(
namespaceName: "namespace-0001"
).QuestGroupModel(
questGroupName: "quest-group-0001"
);
var item = await domain.ModelAsync();
var domain = gs2.Quest.Namespace(
namespaceName: "namespace-0001"
).QuestGroupModel(
questGroupName: "quest-group-0001"
);
var future = domain.Model();
yield return future;
var item = future.Result;
const auto Domain = Gs2->Quest->Namespace(
"namespace-0001" // namespaceName
)->QuestGroupModel(
"quest-group-0001" // questGroupName
);
const auto item = Domain.Model();
listQuestGroups
クエストグループの一覧を取得
Request
| 型 | 必須 | デフォルト | 値の制限 | 説明 |
---|
namespaceName | string | ✓ | | ~ 32文字 | ネームスペース名 |
Result
実装例
var domain = gs2.Quest.Namespace(
namespaceName: "namespace-0001"
);
var items = await domain.QuestGroupModelsAsync(
).ToListAsync();
var domain = gs2.Quest.Namespace(
namespaceName: "namespace-0001"
);
var it = domain.QuestGroupModels(
);
List<EzQuestGroupModel> items = new List<EzQuestGroupModel>();
while (it.HasNext())
{
yield return it.Next();
if (it.Error != null)
{
onError.Invoke(it.Error, null);
break;
}
if (it.Current != null)
{
items.Add(it.Current);
}
else
{
break;
}
}
const auto Domain = Gs2->Quest->Namespace(
"namespace-0001" // namespaceName
);
const auto It = Domain->QuestGroupModels(
);
for (auto Item : *It)
{
}
getQuest
クエストモデルを取得
Request
| 型 | 必須 | デフォルト | 値の制限 | 説明 |
---|
namespaceName | string | ✓ | | ~ 32文字 | ネームスペース名 |
questGroupName | string | ✓ | | ~ 128文字 | クエストグループ名 |
questName | string | ✓ | | ~ 128文字 | クエストモデル名 |
Result
実装例
var domain = gs2.Quest.Namespace(
namespaceName: "namespace-0001"
).QuestGroupModel(
questGroupName: "quest-group-0001"
).QuestModel(
questName: "quest-0001"
);
var item = await domain.ModelAsync();
var domain = gs2.Quest.Namespace(
namespaceName: "namespace-0001"
).QuestGroupModel(
questGroupName: "quest-group-0001"
).QuestModel(
questName: "quest-0001"
);
var future = domain.Model();
yield return future;
var item = future.Result;
const auto Domain = Gs2->Quest->Namespace(
"namespace-0001" // namespaceName
)->QuestGroupModel(
"quest-group-0001" // questGroupName
)->QuestModel(
"quest-0001" // questName
);
const auto item = Domain.Model();
listQuests
クエストモデルの一覧を取得
Request
| 型 | 必須 | デフォルト | 値の制限 | 説明 |
---|
namespaceName | string | ✓ | | ~ 32文字 | ネームスペース名 |
questGroupName | string | ✓ | | ~ 128文字 | クエストグループ名 |
Result
実装例
var domain = gs2.Quest.Namespace(
namespaceName: "namespace-0001"
).QuestGroupModel(
questGroupName: "quest-group-0001"
);
var items = await domain.QuestModelsAsync(
).ToListAsync();
var domain = gs2.Quest.Namespace(
namespaceName: "namespace-0001"
).QuestGroupModel(
questGroupName: "quest-group-0001"
);
var it = domain.QuestModels(
);
List<EzQuestModel> items = new List<EzQuestModel>();
while (it.HasNext())
{
yield return it.Next();
if (it.Error != null)
{
onError.Invoke(it.Error, null);
break;
}
if (it.Current != null)
{
items.Add(it.Current);
}
else
{
break;
}
}
const auto Domain = Gs2->Quest->Namespace(
"namespace-0001" // namespaceName
)->QuestGroupModel(
"quest-group-0001" // questGroupName
);
const auto It = Domain->QuestModels(
);
for (auto Item : *It)
{
}