Launch Modes

Overview

Every Playcademy project runs in one of three launch modes.

The mode determines which features are available and how the SDK behaves.

Mode	Where it runs	User	SDK behavior
Platform	Inside the Playcademy hub	Authenticated	Full SDK (all namespaces available)
Demo	Inside a landing-page iframe	Anonymous	Limited set of namespace methods enabled
Standalone	Third-party embed	No user	Mock token; real platform calls will not succeed

Two URLs after deploy

When you deploy, Playcademy displays two URLs for your project:

Platform link: runs your project inside the Playcademy hub (platform mode)
Standalone link: runs your project directly (standalone mode)

Demo mode is a third scenario relevant to landing page demos.

Choosing a Mode

You don't pick a mode in production. Instead, the runtime decides:

Scenario	Launch Mode
Embedded in the hub	platform
Embedded in a demo shell	demo
Opened directly	standalone

Local development

For local development with the Vite plugin, you pick the mode to simulate.

Platform

Your project is embedded in the Playcademy hub with an authenticated user and a real session.

Full SDK access: users, scores, runtime, etc.
Authenticated playcademyUser in custom routes
This is the default for the Vite plugin (mode: 'platform')

const client = await PlaycademyClient.init()

if (client.mode === 'platform') {
    const user = await client.users.me()
}

In demo mode, your project runs inside our landing page. There is no authenticated user — the experience is anonymous — but the shell environment is present, allowing the SDK to communicate demo-specific events and lifecycle updates.

Available in demo mode:

Method	Description
`scores.submit()`	Record a score (no identity required)
`leaderboard.fetch()`	Read the game's leaderboard
`runtime.*`	Lifecycle, assets, and pause/resume events
`backend.*`	Call your custom API routes over HTTP
`client.demo`	Demo-only namespace

Example

const client = await PlaycademyClient.init()

if (client.mode === 'demo') {
    // Commence the demo variant of the game
}

Guard identity-bound calls

Identity-bound namespaces — e.g. users.* — throw PlaycademyError in demo mode.

There's no real user behind the session. Gate them behind client.mode === 'platform'.

Standalone

Your project is opened directly, i.e. not inside an iframe, and there is no platform context.

No real user, no sandbox, no shell
Real platform API calls will not succeed
Useful raw previews, or embedding your project outside Playcademy entirely
If you need real user accounts in standalone, use the Authentication integration

Example

const client = await PlaycademyClient.init()

if (client.mode === 'standalone') {
    // Skip platform-specific UI, or show a "launch on Playcademy" CTA
}

Writing Mode-Aware Code

The SDK exposes the current mode as client.mode. Branch on it when behavior must differ:

Example

import { PlaycademyClient } from '@playcademy/sdk'

const client = await PlaycademyClient.init()

switch (client.mode) {
    case 'platform':
        await renderAuthenticatedUI(client)
        break
    case 'demo':
        await renderDemoUI(client)
        break
    case 'standalone':
        await renderStandaloneUI(client)
        break
}

Local Development

The Vite plugin simulates each mode locally:

Mode	Sandbox	Dev shell	Use case
Platform	✅	✅	Day-to-day development against the full platform
Demo	✅	✅	Building and testing the landing-page demo flow
Standalone	❌	❌	Testing without any Playcademy context