SDK
TypeScript SDK for platform features and integrations
Overview
The Playcademy SDK provides a TypeScript interface for interacting with the Playcademy platform API from your projects.
Installation
Add the Playcademy SDK to your project:
bun add @playcademy/sdknpm install @playcademy/sdkpnpm add @playcademy/sdkyarn add @playcademy/sdkInitialization
Automatic (Recommended)
For most use cases, especially when using our Vite plugin (@playcademy/vite-plugin), use automatic initialization:
import { PlaycademyClient } from '@playcademy/sdk'
const client = await PlaycademyClient.init()
const user = await client.users.me()
console.log('Current user:', user)How it works:
| Environment | Behavior |
|---|---|
| Development | Connects to local sandbox (via @playcademy/vite-plugin or @playcademy/sandbox) |
| Production | Receives configuration from the Playcademy platform or demo shell loader |
| Standalone | Falls back to mock configuration for testing |
Launch Mode Awareness
Every client exposes client.mode, which is one of 'platform', 'demo', or 'standalone'.
Branch on it when behavior must differ across scenarios:
const client = await PlaycademyClient.init()
if (client.mode === 'platform') {
const user = await client.users.me()
}See the Launch Modes concept for the full picture.
Manual
For server-side applications, standalone scripts, or custom environments:
Authenticate
import { PlaycademyClient } from '@playcademy/sdk'
const baseUrl = 'https://api.playcademy.com'
const email = 'your-email@example.com'
const password = process.env.PLAYCADEMY_PASSWORD
const loginData = await PlaycademyClient.login(baseUrl, email, password)Create Client Instance
const client = new PlaycademyClient({
baseUrl: baseUrl,
token: loginData.token,
gameId: 'your-game-id', // Optional: scopes scores and leaderboard queries
})Quick Start
A simple example demonstrating common SDK operations:
import { PlaycademyClient } from '@playcademy/sdk'
async function runProject() {
const client = await PlaycademyClient.init()
try {
// Get current user
const user = await client.users.me()
console.log('Current user:', user.name)
// Submit a score
await client.scores.submit(1500, {
level: 5,
difficulty: 'hard',
})
console.log('Score submitted')
// Exit
client.runtime.exit()
} catch (error) {
console.error('Error:', error)
}
}
runProject()Event System
The SDK includes an event system for responding to platform events:
import { PlaycademyClient } from '@playcademy/sdk'
const client = await PlaycademyClient.init()
// Listen for pause events
client.on('pause', () => {
console.log('Paused by platform')
pauseGame()
})
// Listen for resume events
client.on('resume', () => {
console.log('Resumed')
resumeGame()
})Available Events:
| Event | Payload | Description |
|---|---|---|
pause | void | Should pause |
resume | void | Should resume |
exit | void | Should clean up and exit |
Error Handling
The SDK uses a custom error type for consistent error handling:
import { PlaycademyClient, PlaycademyError } from '@playcademy/sdk'
try {
const client = await PlaycademyClient.init()
await client.scores.submit(1500)
} catch (error) {
if (error instanceof PlaycademyError) {
console.error('API error:', error.message)
console.error('Status:', error.status)
console.error('Code:', error.code)
} else {
console.error('Unexpected error:', error)
}
}