11.1. PiaFramework 基本機能

基本的な機能の使い方を説明します。

初期化

はじめに PiaFramework の初期化を行います。 Pia 全体のバッファや使用するネットワークの種類などを InitializeFrameworkSetting 構造体に設定し、framework::Initialize() を呼び出すことで初期化します。

const int ROOT_HEAP_SIZE = 10 * 1024 * 1024;
PIA_ATTRIBUTE_ALIGN(8) static uint8_t s_memory[ROOT_HEAP_SIZE];
nn::pia::framework::InitializeFrameworkSetting setting;
setting.piaBuffer = s_memory;
setting.piaBufferSize = ROOT_HEAP_SIZE;
setting.networkType = networkType;
setting.traceFlags = nn::pia::common::TraceFlagFramework
nn::pia::Result result = nn::pia::framework::Initialize(setting);
if (result.IsFailure())
{
    // 失敗時の処理
}

終了処理

PiaFramework の終了処理を行うためには framework::Finalize() を呼び出します。

nn::pia::framework::Finalize();

ディスパッチ処理と接続チェック

Pia や NEX のディスパッチ処理は Framework::Update() で行います。 Framework::Update() は1 ゲームフレームに最低 1 回または 2 回の頻度で呼び出す必要があります。また、Framework::Update() は内部で nn::nex::NgsFacade::IsConnected() や nn::pia::session::Session::CheckConnectionError() を呼び出して接続チェックを行っています。非同期処理中であれば Framework::Update() の返す nn::pia::Result  が失敗時のエラーハンドリングを行う必要はありません。

nn::pia::Result result;

result = nn::pia::framework::Framework::GetInstance()->Update();
if (result.IsFailure())
{
    // 失敗時の処理
}

セッション参加処理状態の遷移

PiaFramework では初期化、セッションの構築・参加、終了処理を状態遷移 API である Framework::ChangeStateAsync を呼び出すことで管理します。 非同期処理の完了には Framework::IsChangeStateCompleted を、非同期処理の結果の確認には Framework::GetChangeStateResult を用います。 各セッティング構造体の isAutoInitialize オプションを有効にすることで自動的に初期化と終了処理が行われます。

同様に、isAutoInitializeNetworkInterface、isAutoInitializeSocket、isAutoInitializeAndLogin オプションを有効(デフォルト無効)にすることで自動的にネットワークインターフェース(AC ライブラリ)、ソケット、NEX ライブラリの初期化と終了処理が行われます。

初期化

初期化、スタートアップ

// 事前に状態遷移に必要な設定の登録を行います
{
    // 登録例
    nn::pia::framework::InitializeSessionSetting setting;
    setting.browsedSessionInfoListNum = MaxBrowsedSessionNum;
    nn::pia::framework::Framework::GetInstance()->RegisterInitializeSessionSetting(setting);
}

nn::pia::Result result;

result = nn::pia::framework::Framework::GetInstance()->ChangeStateAsync(nn::pia::framework::Framework::State_SessionStartedUp);
if (result.IsFailure())
{
    // 失敗時の処理
}

// 非同期処理の開始に成功した場合、Update() を定期的に呼び出して非同期処理の進行を待つ必要があります
while (!nn::pia::framework::Framework::GetInstance()->IsChangeStateCompleted())
{
    nn::pia::framework::Framework::GetInstance()->Update();
}

// 非同期処理の結果を確認
result = nn::pia::framework::Framework::GetInstance()->GetChangeStateResult();
if (result.IsFailure())
{
     // 失敗時の処理
}

終了処理

クリーンアップ、終了処理

nn::pia::Result result;

result = nn::pia::framework::Framework::GetInstance()->ChangeStateAsync(nn::pia::framework::Framework::State_NotInitialized);
if (result.IsFailure())
{
    // 失敗時の処理
}

// 非同期処理の開始に成功した場合、Update() を定期的に呼び出して非同期処理の進行を待つ必要があります
while (!nn::pia::framework::Framework::GetInstance()->IsChangeStateCompleted())
{
    nn::pia::framework::Framework::GetInstance()->Update();
}

// 非同期処理の結果を確認
result = nn::pia::framework::Framework::GetInstance()->GetChangeStateResult();
if (result.IsFailure())
{
     // 失敗時の処理
} 

ブラウズマッチメイク

PiaFramework 使用時は PiaSession ではなく PiaFramework のセッション管理 API を使用します。 ブラウズマッチメイクでは、セッションの作成、検索、参加を行う前に、 ChangeStateAsync() を用いて State_SessionStartedUp まで状態を遷移する必要があります。


ブラウズマッチメイクが可能な状態まで遷移

result = nn::pia::framework::Framework::GetInstance()->ChangeStateAsync(nn::pia::framework::Framework::State_SessionStartedUp);
if (result.IsFailure())
{
    // 失敗時の処理
}

// 非同期処理の開始に成功した場合、Update() を定期的に呼び出して非同期処理の進行を待つ必要があります
while (!nn::pia::framework::Framework::GetInstance()->IsChangeStateCompleted())
{
    nn::pia::framework::Framework::GetInstance()->Update();
}

// 非同期処理の結果を確認
result = nn::pia::framework::Framework::GetInstance()->GetChangeStateResult();
if (result.IsFailure())
{
     // 失敗時の処理
}


セッションの作成

nn::pia::Result result;

result = nn::pia::framework::Framework::GetInstance()->CreateSessionAsync(&createSessionSetting);
if (result.IsFailure())
{
    // 失敗時の処理
}

// 非同期処理の開始に成功した場合、Update() を定期的に呼び出して非同期処理の進行を待つ必要があります
while (!nn::pia::framework::Framework::GetInstance()->IsCreateSessionCompleted())
{
    nn::pia::framework::Framework::GetInstance()->Update();
}

// 非同期処理の結果を確認
result = nn::pia::framework::Framework::GetInstance()->GetCreateSessionResult();
if (result.IsFailure())
{
     // 失敗時の処理
}  


セッションの検索

nn::pia::Result result;

result = nn::pia::framework::Framework::GetInstance()->BrowseSessionAsync(&criteria);
if (result.IsFailure())
{
    // 失敗時の処理
}

// 非同期処理の開始に成功した場合、Update() を定期的に呼び出して非同期処理の進行を待つ必要があります
while (!nn::pia::framework::Framework::GetInstance()->IsBrowseSessionCompleted())
{
    nn::pia::framework::Framework::GetInstance()->Update();
}

// 非同期処理の結果を確認
result = nn::pia::framework::Framework::GetInstance()->GetBrowseSessionResult();
if (result.IsFailure())
{
     // 失敗時の処理
}


セッションの参加

nn::pia::Result result;

result = nn::pia::framework::Framework::GetInstance()->JoinSessionAsync(&joinSessionSetting);
if (result.IsFailure())
{
    // 失敗時の処理
}

// 非同期処理の開始に成功した場合、Update() を定期的に呼び出して非同期処理の進行を待つ必要があります
while (!nn::pia::framework::Framework::GetInstance()->IsJoinSessionCompleted())
{
    nn::pia::framework::Framework::GetInstance()->Update();
}

// 非同期処理の結果を確認
result = nn::pia::framework::Framework::GetInstance()->GetJoinSessionResult();
if (result.IsFailure())
{
     // 失敗時の処理
}  


セッションの離脱

nn::pia::Result result;

result = nn::pia::framework::Framework::GetInstance()->ChangeStateAsync(nn::pia::framework::Framework::State_SessionCleanedUp);

if (result.IsFailure())
{
    // 失敗時の処理
}

// 非同期処理の開始に成功した場合、Update() を定期的に呼び出して非同期処理の進行を待つ必要があります
while (!nn::pia::framework::Framework::GetInstance()->IsChangeStateCompleted())
{
    nn::pia::framework::Framework::GetInstance()->Update();
}

// 非同期処理の結果を確認
result = nn::pia::framework::Framework::GetInstance()->GetChangeStateResult();
if (result.IsFailure())
{
     // 失敗時の処理
}

ランダムマッチメイク

ランダムマッチメイクは状態遷移 API の Framework::ChangeStateAsync を呼び出すだけで自動的に行われます。ブラウズマッチメイクと異なり State_SessionStartedUp まで事前に遷移する必要がないため、必要な設定の登録が完了していれば一度の ChangeStateAsync() の呼び出しでセッションの構築・参加を行うことができます。


ランダムマッチメイクのセッション参加

nn::pia::Result result;

// State_SessionJoined に遷移すると自動でランダムマッチメイクが行われる。
result = nn::pia::framework::Framework::GetInstance()->ChangeStateAsync(nn::pia::framework::Framework::State_SessionJoined);

if (result.IsFailure())
{
    // 失敗時の処理
}

// 非同期処理の開始に成功した場合、Update() を定期的に呼び出して非同期処理の進行を待つ必要があります
while (!nn::pia::framework::Framework::GetInstance()->IsChangeStateCompleted())
{
    nn::pia::framework::Framework::GetInstance()->Update();
}

// 非同期処理の結果を確認
result = nn::pia::framework::Framework::GetInstance()->GetChangeStateResult();
if (result.IsFailure())
{
     // 失敗時の処理
}  


セッションの離脱はブラウズマッチメイクと同様に呼び出します。

アンリライアブル通信

Framework API を呼び出すだけでアンリライアブル通信とリライアブル通信を行うことができます。


アンリライアブル通信の送信

nn::pia::Result result;

result = nn::pia::framework::Framework::GetInstance()->SendToAllUnreliable(sendData, sizeof(sendData));

if (result.IsFailure())
{
    // 失敗時の処理
}


アンリライアブル通信の受信

nn::pia::Result result;

result = nn::pia::framework::Framework::GetInstance()->ReceiveUnreliable(&srcId, buf, &receivedSize, sizeof(buf));

if (result.IsFailure())
{
    // 失敗時の処理
}

入力同期通信

Framework API を呼び出すだけで入力同期通信を行うことができます。

// 1 フレーム進めます
result = nn::pia::framework::Framework::GetInstance()->SyncStep();
if (result.IsFailure())
{
    // 失敗時の処理
}

// 受信処理
nn::pia::StationId* stationIdList = nn::pia::framework::Framework::GetInstance()->GetStationIdList();
for (int i = 0; i < MaxStationNum; ++i)
{
    // 初期化時に SyncProtocol::Setting::dataUnitSize を設定して有効にしたデータ ID について確認します
    for (int j = 0; j < nn::pia::sync::SyncProtocol::DataIdNum; ++j)
    {
        result = nn::pia::framework::Framework::GetInstance()->GetSyncData(stationIdList[i], j, &syncAllData[i][j]);
        if (result.IsFailure())
        {
            syncAllData[i][j] = 0;
        }
    }
}

// 送信処理
// 送信する同期データを用意して SyncProtocol に設定します。
// 初期化時に SyncProtocol::Setting::dataUnitSize を設定して有効にしたデータ ID について確認します
for (int i = 0; i < nn::pia::sync::SyncProtocol::DataIdNum; ++i)
{
    result = nn::pia::framework::Framework::GetInstance()->SetSyncData(i, &syncSendData);
}

// 同期データの送信処理をすぐに行うために、もう一度 nn::pia::framework::Framework::Update() を呼びます。
nn::pia::framework::Framework::GetInstance()->Update();

状態同期通信

状態同期通信については Framework::GetCloneProtocol() により CloneProtocol インスタンスを取得して管理します。

// CloneProtocolインスタンスの取得
nn::pia::clone::CloneProtocol *pCloneProtocol = nn::pia::framework::Framework::GetInstance()->GetCloneProtocol();

クローンの更新処理は Framework::CloneUpdate() を用いて行います。Framework::CloneUpdateResult にはエラーの発生状態や CloneProtocol の動作状態、CloneProtocol が管理する時刻が格納されます。

// クローンの更新処理
nn::pia::framework::Framework::CloneUpdateResult cloneUpdateResult = nn::pia::framework::Framework::GetInstance()->CloneUpdate();

エラー処理

エラー発生時には、pia::Result をエラー処理 API の Framework::HandleErrorAsync() に渡します。これにより、 PiaFramework 内部で自動的に各ライブラリのエラー処理が行われます。

nn::pia::Result result;

// result.IsFailure() が真である result を引数に与えることによって、エラーの種類に応じて自動的にエラー処理が行われます
result = nn::pia::framework::Framework::GetInstance()->HandleErrorAsync(transitionState, result);

if (result.IsFailure())
{
    // 失敗時の処理
}

// 非同期処理の開始に成功した場合、Update() を定期的に呼び出して非同期処理の進行を待つ必要があります
while (!nn::pia::framework::Framework::GetInstance()->IsHandleErrorCompleted())
{
    nn::pia::framework::Framework::GetInstance()->Update();
}

// 非同期処理の結果を確認
result = nn::pia::framework::Framework::GetInstance()->GetHandleErrorResult();
if (result.IsFailure())
{
     // 失敗時の処理
}