Unreal SDK

The Alakazam Portal plugin brings the whole /v1 surface to Unreal — generate and manage worlds, create talk-to characters, mint runtime sessions — plus a drop-in Alakazam Character component. Blueprint-first, with full C++ access. Requires Unreal Engine 5.4+.

Install

Copy the plugin

Drop the AlakazamPortal folder into your project’s Plugins/ directory (YourProject/Plugins/AlakazamPortal).

Enable it

Open the project — Unreal prompts to build the plugin the first time. Confirm it’s on under Edit → Plugins → Alakazam Portal, then restart the editor. Module dependencies (HTTP, Json) are declared by the plugin — nothing to add to your Build.cs.

Setup

Open the Setup Wizard

The Alakazam Setup Wizard opens on first run. You can also configure the plugin any time under Project Settings → Plugins → Alakazam Portal.

Paste your key

Start with an sk_test_… secret key (get one here) — it runs a free, mocked sandbox. Swap to sk_live_… when you ship.

Secret keys are editor/server-only. Your sk_ key can create worlds and mint sessions, so never ship it inside a packaged build. At runtime, a player talks to a world through a short-lived session token minted by your backend — the two-token rule.

Programmable worlds & AI characters (`/v1`)

UAlakazamClient is a singleton wrapper over the /v1 API. Grab it with UAlakazamClient::Get() — in the editor it reads the key from Project Settings; on a server, set the key you loaded from your environment. Because Unreal’s HTTP is asynchronous, every call takes a completion callback. The same calls are exposed as Blueprint nodes (category Alakazam).

#include "AlakazamClient.h"

UAlakazamClient* Client = UAlakazamClient::Get();

// Generate a world from a premise. Each call takes a TFunction completion callback
// (bool bSuccess, const FString& Json, int32 StatusCode) delivered on the GAME THREAD;
// turn the raw JSON into a typed struct with the matching Parse* helper.
Client->CreateWorld(TEXT("a neon rooftop at night"), TEXT(""), TEXT(""), TEXT(""),
    [](bool bSuccess, const FString& Json, int32 StatusCode)
{
    if (!bSuccess) return;
    const FAlakazamWorldResult World = UAlakazamClient::ParseWorldResult(Json);
    UE_LOG(LogTemp, Log, TEXT("world %s · slug %s · mock %d"),
        *World.WorldId, *World.Slug, World.bMock);
});

List, fork, edit, and import compiled worlds the same way — each takes the same completion callback:

Client->ListWorlds(20,        [](bool ok, const FString& Json, int32){ /* { worlds, nextCursor } */ });
Client->ForkWorld(WorldId,    [](bool ok, const FString& Json, int32){ /* { worldId } */ });
Client->EditWorld(WorldId, TEXT("add rain and a flickering sign"), [](bool, const FString&, int32){});
Client->ImportWorld(CompiledWorldJson, TEXT("My Level"), TEXT(""), [](bool, const FString&, int32){});

From Blueprint, use the dynamic-delegate nodes (Create World, Mint Session, Character Say) and the Parse World Result / Parse Say Result pure nodes.

A sk_test_… key returns deterministic mocks — every response carries mock: true, and nothing spends GPU or quota. Build your whole integration for free, then swap to sk_live_…. See Testing.

Drop-in Alakazam Character

UAlakazamCharacter is an Actor Component that wraps the session → say → speak loop. Add it via Add Component → Alakazam Character on any actor, then set its properties in the Details panel (or from Blueprint / C++):

CharacterId and WorldId — from a character you created (they’re the same id).
SessionToken — leave empty in the editor to mint one with your stored key (prototyping); in a packaged build, assign a token minted by your backend (the two-token rule).

Bind the Blueprint events — OnReply, OnError, OnTtsAudio — and call Say:

Character->CharacterId  = TEXT("chr_…");
Character->WorldId      = TEXT("chr_…");
Character->SessionToken = BackendMintedToken;   // production: minted by YOUR server

Character->OnReply.AddDynamic(this, &AMyActor::HandleReply);        // OnReply(FString reply)
Character->OnReplyDetail.AddDynamic(this, &AMyActor::HandleDetail); // OnReplyDetail(FAlakazamSayResult: stance, emotion, affect, action)
Character->OnError.AddDynamic(this, &AMyActor::HandleError);
Character->OnTtsAudio.AddDynamic(this, &AMyActor::HandleTtsBytes);  // OnTtsAudio(TArray<uint8> MP3 bytes)

Character->Say(TEXT("hello"));

Voice is delivered as raw bytes, not auto-played. Unreal has no built-in runtime MP3 decoder, so the component broadcasts the raw audio/mpeg TTS bytes on OnTtsAudio instead of playing them for you. Feed those bytes to a runtime audio importer (e.g. a runtime-audio-importer plugin) to get a USoundWave you can play. This is an honest engine difference: Unity decodes MP3 natively and auto-plays through an AudioSource; Unreal hands you the bytes.

To create the character the component talks to (an editor/server step — needs the secret key) and mint the session token your backend would hand the client, use the same UAlakazamClient::Get() with CreateCharacter, MintSession, and CharacterSay. For a public, token-free share link to a public world, use UAlakazamClient::PublicPlayUrl(Slug).

`UAlakazamClient` reference

The Unreal client mirrors the Unity AlakazamClient and the /v1 contract 1:1 — each method takes a completion callback (and is a Blueprint node under Alakazam).

Method	Auth	Result
`CreateWorld(premise, name?, frameUrl?, pov?)`	secret	`{ worldId, slug, cover, mock }`
`ImportWorld(worldJson, name?, description?)`	secret	`{ worldId, slug, imported }`
`FetchWorld(id)`	secret	world (graph nested under `world`)
`ListWorlds(limit)`	secret	`{ worlds, nextCursor }`
`ForkWorld(id)`	secret	`{ worldId }`
`EditWorld(id, instruction)`	secret	`{ world, diagnostics, reply }`
`LikeWorld(id)`	publishable ok	—
`CreateCharacter(name, premise, authored)`	secret	`{ id, slug, kind, mock }`
`ListCharacters(limit)`	secret	`{ characters, nextCursor }`
`MintSession(worldId, playerIdentity?, origin?)`	secret	`{ token, expiresIn, slug }`
`ConnectSession(sessionToken)`	session	`{ worldId, reactorJwt, world }`
`RefreshSession(sessionToken)`	session	`{ reactorJwt, expiresIn }`
`TrackSession(sessionToken, reactorSessionId)`	session	—
`EndSession(sessionToken)`	session	`{ ok, seconds }`
`CharacterSay(characterId, sessionToken, text)`	session	`{ reply, stance, emotion, action }`
`CharacterTts(characterId, sessionToken, text)`	session	raw `audio/mpeg` (MP3) bytes
`CharacterImage(characterId, sessionToken, prompt)`	session	`{ src, generated }`
`GetUsage()`	secret	`{ day, usage, caps, plan }`
`PublicPlayUrl(slug)`	—	`FString` (static helper)

Optional params at parity with Unity: frame_b64 on CreateWorld / CreateCharacter (seed creation from a base64 image), cursor on ListWorlds / ListCharacters (pagination — pass the prior nextCursor), and ttlSeconds on MintSession (60–3600, sent only when > 0). The Alakazam Character component also fires an OnConnected(bool) event.

Next steps

Unity SDK

The same worlds + AI characters in Unity.

Characters

Stances, memory, voice, and images in depth.

The two-token rule

Mint session tokens server-side; never ship a secret key.

Testing sandbox

Build the whole integration free with a test key.

Get started

Agents & SDKs

Engine SDKs

Guides

Resources

Install

Setup

Programmable worlds & AI characters (`/v1`)

Drop-in Alakazam Character

`UAlakazamClient` reference

Next steps

Unity SDK

Characters

The two-token rule

Testing sandbox

​Install

​Setup

​Programmable worlds & AI characters (/v1)

​Drop-in Alakazam Character

​UAlakazamClient reference

​Next steps

Unity SDK

Characters

The two-token rule

Testing sandbox

Install

Setup

Programmable worlds & AI characters (`/v1`)

Drop-in Alakazam Character

`UAlakazamClient` reference

Next steps