GETTING STARTED

Build an adaptive game

Install PlayState, create a client-safe director, and connect typed recommendations to your authoritative game runtime.

TypeScript strictNode 18+ESM + CommonJSMIT

What PlayState does

playstate-labs transforms validated player and game state into bounded recommendations for pacing, encounters, difficulty, quests, rewards, hints, and live events.

Your game remains authoritative.

The SDK only recommends explicitly allowed actions. Your runtime validates each payload and decides whether to apply it.

Client safe

Local rules and fallbacks require no API keys.

Typed end to end

Zod validation protects every boundary.

Provider resilient

AI failure becomes a usable deterministic result.

Engine neutral

One contract supports every runtime.

Installation and prerequisites

bash

npm i playstate-labs

Requirement	Minimum	Notes
Node.js	18+	Required for trusted-server operations.
TypeScript	5+	Strict mode recommended.
Game runtime	Any	Use JSON adapters outside JavaScript.

Trusted backend environment

dotenv

PLAYSTATE_PROJECT_ID=my-game
PLAYSTATE_BASE_URL=https://api.playstate.dev
PLAYSTATE_API_KEY=
OPENAI_API_KEY=
OPENAI_MODEL=gpt-5-mini

Your first decision

import { PlaystateClient } from "playstate-labs";

const playstate = new PlaystateClient({ projectId: "my-game", environment: "production" });
const decision = await playstate.director.decide({
  playerId: "player_123",
  sessionId: "session_123",
  gameState: { levelId: "forest-01", playerHealth: 22, recentDeaths: 4 },
  allowedActions: ["reduce_enemy_pressure", "offer_hint", "spawn_reward"],
});

for (const action of decision.actions) {
  if (authorize(action)) gameActionRegistry[action.type]?.(action.payload);
}

No provider required.

The local director always produces a typed rules or fallback decision.

Decision lifecycle

01Validate context→

02Evaluate rules→

03Generate or fallback→

04Filter allowlist→

05Game authorizes→

06Apply action

Outputs carry their source, confidence, reason, priority, and optional expiry so the runtime can make an informed final choice.

Client configuration

Option	Type	Default	Scope
`projectId`	string	required	Both
`environment`	development \| staging \| production	development	Both
`baseUrl`	URL	none	Both
`timeoutMs`	number	30000	Both
`retries`	0..10	3	Both
`cacheTtlMs`	number	30000	Both
`logger`	Logger	silent	Both
`apiKey`	string	environment	Server only

Runtime support

Runtime	Integration	Secrets
Browser / Phaser	PlaystateClient	Never
Unity	Unity JSON adapter	Never
Godot	Dictionary adapter	Never
Unreal	Unreal / generic payload	Never
Node.js backend	PlaystateServerClient	Allowed