Unity SDK

The Alakazam Portal Unity package (com.alakazam.portal) gives you the whole /v1 surface from C# — generate and manage worlds, create talk-to characters, mint runtime sessions — plus a drop-in AI Character component. Requires Unity 6000.0+.

Install

Add the package from its git URL (Unity Package Manager → + → Add package from git URL…), or declare it in your manifest:

https://github.com/Alakazam-studios/alakazam-unity.git

{
  "dependencies": {
    "com.alakazam.portal": "https://github.com/Alakazam-studios/alakazam-unity.git"
  }
}

Setup

Open the Setup Wizard

The wizard opens automatically on first import, or launch it from the menu bar: Alakazam → Setup Wizard.

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.

Set your data preferences

Accept the terms and choose your telemetry opt-ins. You’re ready.

Secret keys are editor/server-only. Your sk_ key can create worlds and mint sessions, so never ship it inside a 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`)

AlakazamClient is a thin C# wrapper over the /v1 API. Construct it with your secret key (or pass nothing in the editor to reuse the key from the Setup Wizard).

using AlakazamPortal;

var client = new AlakazamClient("sk_test_…");

// Generate a world from a premise
CreateWorldResponse world = await client.CreateWorld("a neon rooftop at night");
Debug.Log($"{world.worldId} · {world.slug} · mock={world.mock}");

List, fork, edit, and import compiled worlds:

string mine    = await client.ListWorlds(limit: 20);              // raw JSON
string forked  = await client.ForkWorld(world.worldId);
string edited  = await client.EditWorld(world.worldId, "add rain and a flickering sign");

// Import a pre-compiled SMWorld graph verbatim (no recompile)
CreateWorldResponse imported = await client.ImportWorld(compiledWorldJson, name: "My Level");

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 AI Character

The Alakazam Character component wraps the session → say → speak loop as an NPC you can drop into any scene.

Add it to your scene

Menu bar: AlakazamPortal → Add AI Character to Scene. This creates an AlakazamCharacter (plus an AudioSource for spoken replies), or add the component to any GameObject via Add Component → Alakazam → Alakazam Character (AI NPC).

Point it at a character

Create a character first (client.CreateCharacter(...), below), then set Character Id and World Id on the component (they’re the same id).

Authorize runtime turns

In the editor, leave Session Token empty — the component mints one with your stored secret key for prototyping. In a shipped build, assign a sessionToken minted by your backend and never ship the secret key.

Wire OnReply and call Say(...). With autoSpeak on (default) and a voice AudioSource assigned, replies play back through TTS automatically:

using AlakazamPortal;
using UnityEngine;

public class Innkeeper : MonoBehaviour
{
    public AlakazamCharacter npc;   // the Alakazam Character component

    void Awake()
    {
        npc.OnReply += r => Debug.Log($"{r.stance}: {r.reply}");
        npc.OnError += Debug.LogError;
    }

    public async void Greet()
    {
        await npc.Say("hello");     // fires OnReply, then auto-speaks via the AudioSource
    }
}

To create the character the component talks to (an editor/server step — needs the secret key), and to mint the session token your backend would hand the client:

var npc      = await client.CreateCharacter("Iris", "a wry rooftop hacker");
SessionToken session = await client.MintSession(npc.id);   // do this on YOUR backend in production
SayResult    turn    = await client.CharacterSay(npc.id, session.token, "who are you?");
Debug.Log($"{turn.stance}: {turn.reply}");

The component also exposes Speak(line) (synthesize + play a line) and ShowImage(prompt) (returns a show_image src). For a public, token-free share link to a public world, use AlakazamClient.PublicPlayUrl(slug).

`AlakazamClient` reference

Every method maps 1:1 to a /v1 endpoint. Typed methods deserialize the response; the rest return the raw JSON string.

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

Optional params: frameB64 on CreateWorld / CreateCharacter (seed creation from a base64 image), cursor on ListWorlds / ListCharacters (pagination — pass the prior nextCursor), and ttlSeconds on MintSession (60–3600, omitted when 0). Empty optionals are omitted from the request body (never sent as ""), so payloads match the Unreal SDK.

Next steps

Unreal SDK

The same worlds + AI characters in Unreal Engine.

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 AI Character

`AlakazamClient` reference

Next steps

Unreal SDK

Characters

The two-token rule

Testing sandbox

​Install

​Setup

​Programmable worlds & AI characters (/v1)

​Drop-in AI Character

​AlakazamClient reference

​Next steps

Unreal SDK

Characters

The two-token rule

Testing sandbox

Install

Setup

Programmable worlds & AI characters (`/v1`)

Drop-in AI Character

`AlakazamClient` reference

Next steps