@playcademy/sdk

Official TypeScript SDK for the Playcademy platform

The Playcademy SDK provides a comprehensive, type-safe interface for building games on the Playcademy platform. It handles authentication, game sessions, user data, inventory management, and all platform APIs through a unified client interface.

Overview

The SDK serves as the primary interface between your game and the Playcademy platform, providing:

Automatic Environment Detection: Seamlessly works in development and production
Type-Safe API Access: Full TypeScript support with comprehensive type definitions
Session Management: Automatic game session handling and state persistence
Event System: Real-time notifications for inventory changes, level ups, and more
Developer Tools: Built-in support for game development and testing workflows

Public vs Internal SDK

The Playcademy SDK is split into two entry points:

Public SDK (`@playcademy/sdk`)

For game developers building games on the Playcademy platform. Includes 8 essential namespaces:

Core: identity, runtime, backend, users
Economy: credits
Gameplay: scores
Multiplayer: realtime
Integrations: timeback

import { PlaycademyClient } from '@playcademy/sdk'

const client = await PlaycademyClient.init()
await client.timeback.endActivity({
    /* ... */
})
await client.users.inventory.add('gold-coin', 100)

Internal SDK (`@playcademy/sdk/internal`)

For CLI, platform, and admin tools. Includes all 21 namespaces (8 public + 13 internal):

Additional internal namespaces:

Platform Auth: auth (email/password login, API keys)
Administration: admin (game management, items, currencies)
Developer Tools: dev (publish games, uploads)
Game Directory: games (fetch, list, sessions)
Overworld Features: character, achievements, leaderboard, levels, shop, maps, sprites, notifications
Analytics: telemetry

import { PlaycademyClient } from '@playcademy/sdk/internal'

const client = new PlaycademyClient({ baseUrl: 'https://hub.playcademy.net' })
await client.auth.login({ email: 'dev@example.com', password: '***' })
const games = await client.games.list()
await client.admin.games.pauseGame('game-123')

Note: The internal SDK is for trusted code only (CLI, platform internals). Game developers should use the public SDK.

Key Benefits

Zero Configuration: Automatic initialization with environment detection
Production Ready: Battle-tested API patterns with robust error handling
Real-Time Communication: Open game-scoped WebSocket channels for multiplayer features.
Event System: Subscribe to platform events like inventory changes and level ups
Comprehensive Coverage: Access to all Playcademy platform features
Development Experience: Integrated with sandbox environment for local development

Use Cases

Game Development: Primary SDK for building games on Playcademy
Web Applications: Frontend applications interacting with the platform
Developer Tools: Scripts and utilities for game management
Server Integration: Backend services integrating with Playcademy APIs
Testing & Automation: Automated testing of platform integrations

Connection Monitoring

The SDK automatically monitors network connectivity and provides hooks for games to handle disconnects gracefully:

Automatic Detection: Multi-signal approach detects offline, slow, and degraded connections
Game Handlers: Implement custom disconnect behavior (e.g., return to lobby, pause game)
Platform Integration: Built-in helpers for displaying connection alerts
Zero Config: Works out of the box, customizable when needed

See the SDK Browser documentation for detailed connection monitoring documentation and examples.

Installation

Install the SDK using your preferred package manager:

# Using Bun (recommended)
bun add @playcademy/sdk

# Using npm
npm install @playcademy/sdk

# Using yarn
yarn add @playcademy/sdk

# Using pnpm
pnpm add @playcademy/sdk

Quick Start

Automatic Initialization (Recommended)

For most game development scenarios, use automatic initialization:

import { PlaycademyClient } from '@playcademy/sdk'

async function initializeGame() {
    try {
        // Automatic initialization - detects environment and configures appropriately
        const client = await PlaycademyClient.init({
            // Optional: Handle connection issues gracefully
            onDisconnect: ({ state, displayAlert }) => {
                if (state === 'offline') {
                    displayAlert?.('Connection lost. Reconnecting...', { type: 'warning' })
                    // Return to safe state (e.g., lobby)
                }
            },
        })

        // Get current user
        const user = await client.users.me()
        console.log('Welcome,', user.name)

        // The client is ready for all platform operations
        return client
    } catch (error) {
        console.error('Failed to initialize Playcademy SDK:', error)
        throw error
    }
}

Environment Detection

The SDK automatically detects and configures for different environments:

Development: Connects to local sandbox (started by @playcademy/vite-plugin)
Production: Receives configuration from Playcademy platform loader
Testing: Falls back to mock configuration for automated testing

Core Features

Game Session Management

// Automatic session management when gameId is available
const client = await PlaycademyClient.init()

// Save transient game state (position, health, temporary data)
await client.games.saveState({
    currentLevel: 'forest_glade',
    playerPosition: { x: 100, y: 200 },
    health: 85,
    activePowerUps: ['speed_boost'],
})

// Load previously saved state
const gameState = await client.games.loadState()
console.log('Loaded state:', gameState)

// Exit game (automatically ends session if managed)
await client.runtime.exit()

User & Inventory Management

// Get user information
const user = await client.users.me()

// Inventory operations (accepts UUIDs or slugs)
const inventory = await client.users.inventory.get()
await client.users.inventory.add('magic-sword', 1)
await client.users.inventory.remove('health-potion', 1)

// Check item quantities and ownership
const goldCount = await client.users.inventory.quantity('gold-coin')
const hasKey = await client.users.inventory.has('dungeon-key')
const hasEnoughGold = await client.users.inventory.has('gold-coin', 100)

Credits & Currency

// Platform currency management
const balance = await client.credits.balance()
await client.credits.add(100)
await client.credits.spend(50)

// Check affordability
if ((await client.credits.balance()) >= 100) {
    await client.credits.spend(100)
    console.log('Purchase successful!')
}

Experience & Levels

// Level management
const userLevel = await client.levels.get()
const progress = await client.levels.progress()
console.log(`Level ${userLevel.currentLevel}, ${progress.xpToNextLevel} XP to next level`)

// Note: XP is now managed entirely through TimeBack integration.
// XP updates come from TimeBack webhooks only.

TimeBack Integration

Access user role and enrollments, and track learning activities:

// Access TimeBack role and enrollments
const role = client.timeback.role // 'student' | 'parent' | 'teacher' | 'administrator'
const enrollments = client.timeback.enrollments // [{ subject, grade, courseId }]

// Check if user is enrolled in a specific grade
const grade3Enrollment = enrollments.find(e => e.grade === 3)
if (grade3Enrollment) {
    // Show grade 3 content
}

// Start tracking an activity (only activityId required!)
client.timeback.startActivity({
    activityId: 'math-quiz-level-1',
})
// Auto-derived: activityName "Math Quiz Level 1"
// Auto-filled by backend: appName, subject, sensorUrl

// ... player completes activity ...

// End activity and submit results (XP calculated automatically)
await client.timeback.endActivity({
    correctQuestions: 8,
    totalQuestions: 10,
})
// XP calculation: base (1 min = 1 XP) × accuracy multiplier
// 100%: 1.25x | 80-99%: 1.0x | 65-79%: 0.5x | <65%: 0x

Real-time Authentication

Get authentication tokens for WebSocket connections used by the platform's multiplayer system.

// Get a realtime token for WebSocket authentication
const { token } = await client.realtime.token.get()

// Token is used internally by the platform's multiplayer WebSocket client
// for presence tracking, player positions, and real-time game features

API Reference

Core Modules

Authentication (`client.auth`)

logout(): Logs out user and clears authentication token

Users (`client.users`)

me(): Get current user information
Inventory (client.users.inventory):
- get(): Get user's inventory
- add(identifier, quantity): Add items to inventory
- remove(identifier, quantity): Remove items from inventory
- quantity(identifier): Get item quantity
- has(identifier, minQuantity?): Check item ownership

Games (`client.games`)

list(): Get all available games
fetch(gameIdOrSlug): Get specific game details
saveState(state): Save transient game state
loadState(): Load saved game state
startSession(gameId?): Start game session
endSession(sessionId, gameId?): End game session

Credits (`client.credits`)

balance(): Get current credits balance
add(amount): Add credits to user
spend(amount): Spend user credits

Levels (`client.levels`)

get(): Get current user level information
progress(): Get level progress and XP to next level
addXP(amount): Add experience points
Config (client.levels.config):
- list(): Get all level configurations
- get(level): Get specific level configuration

Maps (`client.maps`)

elements(mapId): Get map elements and points of interest

Runtime (`client.runtime`)

getGameToken(gameId, options?): Get game-specific authentication token
exit(): Signal platform to exit game view

Real-time (`client.realtime`)

token.get(): Retrieves a JWT for WebSocket authentication (used by the platform's multiplayer system).

TimeBack (`client.timeback`)

role: The user's TimeBack role ('student', 'parent', 'teacher', or 'administrator')
enrollments: Array of course enrollments with subject, grade, and courseId
startActivity(metadata): Start tracking an activity (stores start time and metadata)
- metadata.activityId: Unique activity identifier (required)
- metadata.activityName: Human-readable activity name
- metadata.subject: Subject area (Math, Reading, Science, etc.)
- metadata.appName: Application name
- metadata.sensorUrl: Sensor URL for tracking
endActivity(scoreData): End activity and submit results
- scoreData.correctQuestions: Number of correct answers
- scoreData.totalQuestions: Total number of questions
XP Query (client.timeback.xp):
- today(options?): Get today's XP (supports timezone parameter)
- total(): Get total accumulated XP
- history(options?): Get XP history with optional date filtering
- summary(options?): Get both today's and total XP in one call

Leaderboard (`client.leaderboard`) - Game-specific

fetch(options?): Get leaderboard for a specific game
- options.timeframe: Filter by time period ('all_time', 'monthly', 'weekly', 'daily')
- options.gameId: Game ID to fetch leaderboard for (required)
- options.limit: Number of entries to return (default: 10)
- options.offset: Pagination offset (default: 0)

Scores (`client.scores`) - Platform-wide

submit(gameId, score, metadata?): Submit a score for any game
getUserScores(userId, options?): Get all scores for a user
- options.gameId: Filter by specific game (optional)
- options.limit: Number of scores to return (default: 50)

Developer Tools

Developer Authentication (`client.dev.auth`)

applyForDeveloper(): Apply for developer status
getDeveloperStatus(): Check current developer status

Game Management (`client.dev.games`)

upsert(slug, metadata, gameFile): Create or update game
update(gameId, updates): Update game properties
delete(gameId): Delete game

API Keys (`client.dev.keys`)

createKey(gameId, name): Create API key for server authentication
listKeys(): List all API keys
revokeKey(keyId): Revoke API key

Item Management (`client.dev.items`)

list(gameId): List all items for a game
get(gameId, slug): Get specific item
create(gameId, slug, data): Create new game item
update(gameId, itemId, updates): Update existing item
delete(gameId, itemId): Delete item

Event System

The SDK provides real-time event notifications for important platform changes:

Available Events

// Authentication changes
client.on('authChange', payload => {
    console.log('Authentication changed:', payload.token)
})

// Connection state changes
client.on('connectionChange', ({ state, reason }) => {
    console.log(`Connection: ${state} - ${reason}`)
})

// Inventory changes
client.on('inventoryChange', payload => {
    console.log(`Item ${payload.itemId}: ${payload.delta} (total: ${payload.newTotal})`)
})

// Experience gained
client.on('xpGained', payload => {
    console.log(`Gained ${payload.amount} XP (total: ${payload.totalXP})`)
})

// Level up notifications
client.on('levelUp', payload => {
    console.log(`Level up! ${payload.oldLevel} → ${payload.newLevel}`)
    console.log('Credits awarded:', payload.creditsAwarded)
})

Disconnect Handling

For convenience, use the onDisconnect method to handle only offline/degraded states:

const cleanup = client.onDisconnect(({ state, reason, displayAlert }) => {
    console.log(`Disconnect detected: ${state}`)
    displayAlert?.(`Connection ${state}: ${reason}`, { type: 'warning' })
})

// Later: cleanup() to unregister

Event-Driven UI Updates

// Update UI in response to platform events
client.on('inventoryChange', payload => {
    updateInventoryDisplay(payload.itemId, payload.newTotal)
})

client.on('levelUp', payload => {
    showLevelUpAnimation(payload.newLevel)
    showCreditsAwarded(payload.creditsAwarded)
})

client.on('xpGained', payload => {
    updateXPBar(payload.totalXP, payload.leveledUp)
})

Advanced Usage

Manual Initialization

For server-side applications or custom environments:

import { PlaycademyClient } from '@playcademy/sdk'

import type { LoginResponse } from '@playcademy/sdk'

// Step 1: Authenticate
const loginData: LoginResponse = await PlaycademyClient.login(
    'https://api.playcademy.com',
    'user@example.com',
    'password',
)

// Step 2: Initialize client
const client = new PlaycademyClient({
    baseUrl: 'https://api.playcademy.com',
    token: loginData.token,
    gameId: 'your-game-id', // Optional: enables automatic session management
})

Custom Configuration

const client = new PlaycademyClient({
    baseUrl: 'https://api.playcademy.com',
    token: 'your-auth-token',
    gameId: 'your-game-id',
    // Additional options
    timeout: 10000, // Request timeout in milliseconds
    retries: 3, // Number of retry attempts
})

Error Handling

import { PlaycademyError } from '@playcademy/sdk'

try {
    const user = await client.users.me()
    // Handle success
} catch (error) {
    if (error instanceof PlaycademyError) {
        console.error('Playcademy API Error:', error.message)
        console.error('Status Code:', error.statusCode)
        console.error('Error Code:', error.code)
    } else {
        console.error('Unexpected error:', error)
    }
}

Development Environment

Integration with Playcademy Vite Plugin

When using the official Playcademy Vite templates, the development environment is automatically configured:

// In your game's main file
import { PlaycademyClient } from '@playcademy/sdk'

// The vite plugin automatically starts the sandbox
const client = await PlaycademyClient.init()
// SDK automatically connects to local sandbox at http://localhost:4321

Manual Sandbox Setup

If not using the Vite plugin, start the sandbox manually:

# Start sandbox server (will also start realtime server on port 4322)
bunx @playcademy/sandbox --port 4321 --verbose

# In your application
const client = new PlaycademyClient({
    baseUrl: 'http://localhost:4321/api',
    realtimeUrl: 'ws://localhost:4322',
    token: 'dev-token' // Sandbox provides mock authentication
})

Best Practices

Initialization & Setup

Always use automatic initialization for game development with PlaycademyClient.init()
Handle initialization errors gracefully with proper try-catch blocks
Store the client instance for reuse throughout your application lifecycle

State Management

Use games.saveState() for transient data (current level, position, temporary status)
Use users.inventory for persistent items and resources that carry between sessions
Save state periodically, not on every frame or minor change
Load state once at game start, then manage locally

Performance Optimization

Cache frequently accessed data like user information and inventory
Batch inventory operations when possible instead of individual API calls
Use event listeners to update UI reactively rather than polling
Implement proper loading states for better user experience

Error Handling

Wrap all SDK calls in appropriate try-catch blocks
Provide fallback behavior for network errors and API failures
Show meaningful error messages to users when operations fail
Implement retry logic for non-critical operations

Development Workflow

Use the sandbox environment for all local development
Test both online and offline scenarios to ensure robust error handling
Enable verbose logging during development for debugging
Validate API responses and handle edge cases appropriately

Testing

Unit Testing

// Mock the SDK for unit tests
import { jest } from '@jest/globals'

// Mock the entire SDK module
jest.mock('@playcademy/sdk', () => ({
    PlaycademyClient: {
        init: jest.fn().mockResolvedValue({
            users: {
                me: jest.fn().mockResolvedValue({ id: 'test-user', name: 'Test User' }),
                inventory: {
                    get: jest.fn().mockResolvedValue([]),
                    add: jest.fn().mockResolvedValue(undefined),
                },
            },
        }),
    },
}))

Integration Testing

// Test with real sandbox
import { PlaycademyClient } from '@playcademy/sdk'

describe('Playcademy Integration', () => {
    let client: PlaycademyClient

    beforeAll(async () => {
        // Initialize with sandbox
        client = new PlaycademyClient({
            baseUrl: 'http://localhost:4321/api',
            token: 'test-token',
        })
    })

    test('should fetch user data', async () => {
        const user = await client.users.me()
        expect(user).toBeDefined()
        expect(user.name).toEqual(expect.any(String))
    })
})

Troubleshooting

Common Issues

SDK Initialization Timeout

Error: PLAYCADEMY_INIT not received within 5000ms

Ensure you're running in the correct environment (development with sandbox, or production with platform)
Check that the Vite plugin is properly configured
Verify the sandbox is running on the expected port

Authentication Errors

Error: Unauthorized (401)

Check that your authentication token is valid
Ensure you have the necessary permissions for the operation
Try re-authenticating with PlaycademyClient.login()

Network Connection Issues

Error: Failed to fetch

Verify the API endpoint is accessible
Check network connectivity
Ensure CORS is properly configured for cross-origin requests

Debugging

Use these debugging techniques for troubleshooting SDK issues:

// Check initialization process
try {
    const client = await PlaycademyClient.init()
    console.log('SDK initialized successfully')
} catch (error) {
    console.error('SDK initialization failed:', error)
}

// Monitor network requests in browser dev tools (Network tab)
// Check console for SDK error messages
// Verify API responses and error details

Contributing

The SDK is a critical component of the Playcademy platform ecosystem. When contributing:

Maintain Type Safety: Ensure all new APIs are fully typed
Update Documentation: Keep this README and JSDoc comments current
Add Tests: Include both unit and integration tests for new features
Follow Patterns: Use consistent patterns with existing SDK methods
Handle Errors: Implement proper error handling and user feedback

For general contribution guidelines, see the monorepo CONTRIBUTING.md.

Enumerations

MessageEvents

Defined in: messaging.ts:51

Enumeration of all message types used in the Playcademy messaging system.

Message Flow Patterns:

Parent → Game (Overworld → Game):

INIT: Provides game with authentication token and configuration
TOKEN_REFRESH: Updates game's authentication token before expiry
PAUSE/RESUME: Controls game execution state
FORCE_EXIT: Immediately terminates the game
OVERLAY: Shows/hides UI overlays over the game

Game → Parent (Game → Overworld):

READY: Game has loaded and is ready to receive messages
EXIT: Game requests to be closed (user clicked exit, game ended, etc.)
TELEMETRY: Game reports performance metrics (FPS, memory usage, etc.)

Enumeration Members

AUTH_CALLBACK

AUTH_CALLBACK: "PLAYCADEMY_AUTH_CALLBACK";

Defined in: messaging.ts:180

OAuth callback data from popup/new-tab windows. Sent from popup window back to parent after OAuth completes. Payload:

code: string (OAuth authorization code)
state: string (OAuth state for CSRF protection)
error: string | null (OAuth error if any)

AUTH_STATE_CHANGE

AUTH_STATE_CHANGE: "PLAYCADEMY_AUTH_STATE_CHANGE";

Defined in: messaging.ts:170

Notifies about authentication state changes. Can be sent in both directions depending on auth flow. Payload:

authenticated: boolean
user: UserInfo | null
error: Error | null

CONNECTION_STATE

CONNECTION_STATE: "PLAYCADEMY_CONNECTION_STATE";

Defined in: messaging.ts:110

Broadcasts connection state changes to games. Sent by platform when network connectivity changes. Payload:

state: 'online' | 'offline' | 'degraded'
reason: string

DISPLAY_ALERT

DISPLAY_ALERT: "PLAYCADEMY_DISPLAY_ALERT";

Defined in: messaging.ts:156

Game requests platform to display an alert. Sent when connection issues are detected or other important events occur. Payload:

message: string
options: { type?: 'info' | 'warning' | 'error', duration?: number }

EXIT

EXIT: "PLAYCADEMY_EXIT";

Defined in: messaging.ts:128

Game requests to be closed/exited. Sent when user clicks exit button or game naturally ends. Payload: void

FORCE_EXIT

FORCE_EXIT: "PLAYCADEMY_FORCE_EXIT";

Defined in: messaging.ts:94

Forces immediate game termination (emergency exit). Game should clean up resources and exit immediately. Payload: void

INIT

INIT: "PLAYCADEMY_INIT";

Defined in: messaging.ts:64

Initializes the game with authentication context and configuration. Sent immediately after game iframe loads. Payload:

baseUrl: string
token: string
gameId: string

KEY_EVENT

KEY_EVENT: "PLAYCADEMY_KEY_EVENT";

Defined in: messaging.ts:147

Game reports key events to parent. Sent when certain keys are pressed within the game iframe. Payload:

key: string
code?: string
type: 'keydown' | 'keyup'

OVERLAY

OVERLAY: "PLAYCADEMY_OVERLAY";

Defined in: messaging.ts:101

Shows or hides UI overlays over the game. Game may need to pause or adjust rendering accordingly. Payload: boolean (true = show overlay, false = hide overlay)

PAUSE

PAUSE: "PLAYCADEMY_PAUSE";

Defined in: messaging.ts:80

Pauses game execution (e.g., when user switches tabs). Game should pause timers, animations, and user input. Payload: void

READY

READY: "PLAYCADEMY_READY";

Defined in: messaging.ts:121

Game has finished loading and is ready to receive messages. Sent once after game initialization is complete. Payload: void

RESUME

RESUME: "PLAYCADEMY_RESUME";

Defined in: messaging.ts:87

Resumes game execution after being paused. Game should restore timers, animations, and user input. Payload: void

TELEMETRY

TELEMETRY: "PLAYCADEMY_TELEMETRY";

Defined in: messaging.ts:137

Game reports performance telemetry data. Sent periodically for monitoring and analytics. Payload:

fps: number
mem: number

TOKEN_REFRESH

TOKEN_REFRESH: "PLAYCADEMY_TOKEN_REFRESH";

Defined in: messaging.ts:73

Updates the game's authentication token before it expires. Sent periodically to maintain valid authentication. Payload:

token: string
exp: number

Classes

ApiError

Defined in: core/errors.ts:86

API error thrown when a request fails.

Contains structured error information from the API response:

status - HTTP status code (e.g., 404)
code - API error code (e.g., "NOT_FOUND")
message - Human-readable error message
details - Optional additional error context

Example

try {
  await client.games.get('nonexistent')
} catch (error) {
  if (error instanceof ApiError) {
    console.log(error.status)   // 404
    console.log(error.code)     // "NOT_FOUND"
    console.log(error.message)  // "Game not found"
    console.log(error.details)  // { identifier: "nonexistent" }
  }
}

Extends

Error

Constructors

Constructor

new ApiError(
   status, 
   code, 
   message, 
   details?, 
   rawBody?): ApiError;

Defined in: core/errors.ts:107

Parameters

status

number

HTTP status code

code

string

API error code

message

string

Human-readable error message

details?

unknown

Additional error context

rawBody?

unknown

Raw response body