Unreal

本頁譯自英文。如兩者有出入，以英文頁面為準。閱讀英文頁面

適用於 Unreal Engine 5 的 Lingara 外掛程式是一個遊戲執行個體子系統，建構在玩家核心的 C 介面之上。它在玩家套件支援的五個平台上執行：Windows、macOS、Linux、Android 和 iOS。目前尚不支援遊戲主機。

安裝外掛程式

每次發行都會為每個受支援的引擎版本附上一個外掛程式 zip 檔，命名為 LingaraEmbed-<semver>-UE5.<m>.zip。把與你的引擎對應的那一個解壓縮到專案的 Plugins/ 資料夾中，然後在編輯器中啟用該外掛程式。不需要安裝其他任何東西。

從你的伺服器取得權杖

外掛程式從不持有密鑰。當它需要權杖時，會廣播 OnTokenNeeded。回應方式是向你自己伺服器的權杖路由傳送 POST 要求，伺服器用伺服器套件核發權杖並回傳權杖及其到期時間，然後把兩者交給 ProvideToken。如果你的伺服器無法回應，請呼叫 TokenUnavailable，讓等待權杖的呼叫立即失敗，而不是等到逾時。

繫結你使用的事件

核心在自己的執行緒上執行網路 I/O。子系統在自己的 tick 中清空佇列，每個畫格最多 MaxEventsPerTick 個事件（一項專案設定），並在委派上逐一廣播。在遊戲開始時繫結你的遊戲需要的委派，然後啟動子系統：

OnTokenNeeded：需要權杖時；
OnNpcTurn：串流回覆的每一個片段（見 NPC 對話）；
OnPractice：每一次練習更新（見練習結果）；
OnError：呼叫失敗時。

Unreal C++

// Your own server mints the token: never put a client secret in a game.
void ALingaraEmbedSnippetActor::HandleTokenNeeded(const FLingaraTokenNeeded& Event)
{
	const TSharedRef<IHttpRequest, ESPMode::ThreadSafe> Request = FHttpModule::Get().CreateRequest();
	Request->SetVerb(TEXT("POST"));
	Request->SetURL(TokenUrl);
	Request->SetHeader(TEXT("Content-Type"), TEXT("application/json"));
	Request->SetContentAsString(TEXT("{}"));
	Request->OnProcessRequestComplete().BindUObject(this, &ALingaraEmbedSnippetActor::HandleTokenResponse);
	Request->ProcessRequest();
}

void ALingaraEmbedSnippetActor::HandleTokenResponse(FHttpRequestPtr Request, FHttpResponsePtr Response, bool bConnected)
{
	ELingaraCallResult Result;
	FLingaraEmbedError Error;
	TSharedPtr<FJsonObject> Body;
	FString Token;
	FString ExpiresAt;
	const bool bOk = bConnected && Response.IsValid() && EHttpResponseCodes::IsOk(Response->GetResponseCode())
		&& FJsonSerializer::Deserialize(TJsonReaderFactory<TCHAR>::Create(Response->GetContentAsString()), Body)
		&& Body->TryGetStringField(TEXT("token"), Token) && Body->TryGetStringField(TEXT("expires_at"), ExpiresAt);
	if (bOk)
	{
		Lingara()->ProvideToken(Token, ExpiresAt, Result, Error);
	}
	else
	{
		// Fail the waiting calls now rather than at the core's timeout.
		Lingara()->TokenUnavailable(TEXT("the token endpoint failed"), Result, Error);
	}
}

Unreal C++

// The subsystem drains the core's queue from its own tick (at most
// MaxEventsPerTick a frame, from Project Settings): bind the events you use.
void ALingaraEmbedSnippetActor::BeginPlay()
{
	Super::BeginPlay();
	ULingaraEmbedSubsystem* Subsystem = Lingara();
	Subsystem->OnTokenNeeded.AddDynamic(this, &ALingaraEmbedSnippetActor::HandleTokenNeeded);
	Subsystem->OnNpcTurn.AddDynamic(this, &ALingaraEmbedSnippetActor::HandleNpcTurn);
	Subsystem->OnPractice.AddDynamic(this, &ALingaraEmbedSnippetActor::HandlePractice);
	Subsystem->OnError.AddDynamic(this, &ALingaraEmbedSnippetActor::HandleError);

	FLingaraEmbedConfig Config;
	Config.MaxEventsPerTick = 256;
	ELingaraCallResult Result;
	FLingaraEmbedError Error;
	Subsystem->Start(Config, Result, Error);
}

void ALingaraEmbedSnippetActor::HandleError(const FLingaraEmbedError& Error)
{
	UE_LOG(LogTemp, Warning, TEXT("Lingara %s: %s"), *Error.KindName, *Error.Message);
}