@playcademy/vite-plugin

Vite plugin for Playcademy app development and deployment

This plugin integrates Playcademy's development sandbox and build tools into your Vite workflow, automatically generating manifests, managing development environments, and creating deployment-ready archives.

Overview

The Playcademy Vite plugin streamlines app development by providing:

Development Sandbox: Automatically starts a local Playcademy API server during development.
Manifest Generation: Creates required playcademy.manifest.json files for platform deployment
Build Optimization: Configures Vite settings for optimal Playcademy platform compatibility
Deployment Packaging: Optionally creates zip archives ready for platform upload

Key Benefits

Zero-Config Development: Works out of the box with sensible defaults
Hot Reload Integration: Seamless development experience with Vite's hot module replacement
Platform Compatibility: Ensures builds work correctly on the Playcademy platform
Type Safety: Full TypeScript support with comprehensive type definitions
Flexible Configuration: Extensive options for customizing both development and build processes

Installation

Install the plugin in your Playcademy project:

# Using Bun (recommended)
bun add -D @playcademy/vite-plugin

# Using npm
npm install --save-dev @playcademy/vite-plugin

# Using yarn
yarn add --dev @playcademy/vite-plugin

# Using pnpm
pnpm add -D @playcademy/vite-plugin

Quick Start

Add the plugin to your vite.config.ts:

import { defineConfig } from 'vite'

import { playcademy } from '@playcademy/vite-plugin'

export default defineConfig({
    plugins: [
        playcademy(), // Uses all defaults
    ],
})

Start development:

bun dev

The plugin will:

Start the sandbox server at http://localhost:4321/api
Enable API integration for your app
Provide hot reload for rapid development

Configuration

Basic Configuration

import { playcademy } from '@playcademy/vite-plugin'

export default defineConfig({
    plugins: [
        playcademy({
            export: {
                autoZip: true, // Create deployment zip (enabled by default)
            },
            sandbox: {
                autoStart: true, // Start sandbox automatically
                verbose: false, // Enable debug logging
                logLevel: 'info', // Log level (debug, info, warn, error)
                seed: true, // Seed database with demo data
                recreateDb: false, // Recreate database on each start
                memoryOnly: false, // Use in-memory database
            },
        }),
    ],
})

Disabling Auto-Zip

By default, the plugin creates a deployment archive. To disable:

export default defineConfig({
    plugins: [
        playcademy({
            export: {
                autoZip: false, // Disable automatic zip creation
            },
        }),
    ],
})

Custom Sandbox Configuration

export default defineConfig({
    plugins: [
        playcademy({
            sandbox: {
                autoStart: false, // Disable auto-start
                url: 'http://localhost:8080', // Custom port
                verbose: true, // Enable verbose logging
                logLevel: 'debug', // Set log level (debug, info, warn, error)
            },
        }),
    ],
})

Plugin Options

Top-Level Options

Option	Type	Default	Description
`configPath`	`string`	`undefined`	Path to playcademy.config.js (auto-detected)
`mode`	`'platform' \| 'standalone'`	`'platform'`	Plugin operation mode

Mode Options:

'platform': Full Playcademy experience with sandbox server, backend bundling, and shell wrapper (recommended)
'standalone': Backend bundling only, no platform features

Export Options (`export`)

Configuration for build output:

Option	Type	Default	Description
`autoZip`	`boolean`	`true`	Create deployment zip archive

Sandbox Options (`sandbox`)

Configuration for the development sandbox server:

Option	Type	Default	Description
`autoStart`	`boolean`	`true`	Start sandbox during development
`url`	`string`	`'http://localhost:4321/api'`	Sandbox server URL
`verbose`	`boolean`	`false`	Enable verbose logging
`logLevel`	`'debug' \| 'info' \| 'warn' \| 'error'`	`'info'`	Log level for sandbox server
`recreateDb`	`boolean`	`false`	Recreate database on each start
`seed`	`boolean`	`true`	Seed database with demo data
`memoryOnly`	`boolean`	`false`	Use in-memory database (non-persistent)
`databasePath`	`string`	`undefined`	Custom path for database file

Display Options (`display`)

Configuration for visual elements during development:

Option	Type	Default	Description
`hideBadge`	`boolean`	`false`	Hide the Playcademy badge in the corner

TimeBack Options (`timeback`)

Configuration for TimeBack integration testing during local development. Set to false to explicitly disable TimeBack even if configured in playcademy.config.

Option	Type	Default	Description
`id`	`string`	auto-generated mock ID	TimeBack student ID
`role`	`'student' \| 'parent' \| 'teacher' \| 'administrator' \| 'guardian'`	`'student'`	User role for testing different permission levels
`organization`	`'mock' \| object`	`'mock'`	Organization (school/district) configuration
`courses`	`Record<string, 'mock' \| string \| null>`	all courses from config	Course enrollment overrides

Organization Object Properties

Property	Type	Default	Description
`id`	`string`	`'PLAYCADEMY'`	Organization sourcedId
`name`	`string`	`'Playcademy Studios'`	Organization name
`type`	`'school' \| 'district' \| 'department' \| 'local' \| 'state' \| 'national'`	`'department'`	Organization type

TimeBack Configuration Example

export default defineConfig({
    plugins: [
        playcademy({
            timeback: {
                // All courses from playcademy.config.js enrolled by default with mock IDs
                role: 'student', // Test as student (default)
            },
        }),
    ],
})

// Override specific courses
export default defineConfig({
    plugins: [
        playcademy({
            timeback: {
                courses: {
                    'FastMath:3': 'mock', // Mock enrollment for grade 3
                    'FastMath:4': null, // Exclude from enrollment (test partial)
                    'Science:5': 'real-course-id-123', // Real TimeBack course
                },
            },
        }),
    ],
})

// Full real TimeBack integration
export default defineConfig({
    plugins: [
        playcademy({
            timeback: {
                id: 'real-student-sourced-id',
                organization: {
                    id: 'real-org-id',
                    name: 'Springfield Elementary',
                    type: 'school',
                },
                courses: {
                    'FastMath:3': 'real-course-id-g3',
                    'FastMath:4': 'real-course-id-g4',
                },
            },
        }),
    ],
})

CLI Hotkeys

During development, the plugin provides keyboard shortcuts in the terminal:

Key	Description
`m`	Toggle between platform and standalone modes
`d`	Recreate sandbox database (resets to fresh seeded state)
`p`	Cycle platform user role (player → developer → admin)
`t`	Cycle TimeBack role (student → parent → teacher → admin)

Note: Some configuration changes require recreating the sandbox database to take effect. Press d after changing options like timeback.id, timeback.organization, or timeback.courses in your vite.config.ts.

Build Output

Development Mode

During bun dev, the plugin:

Starts the sandbox server (if enabled)
Provides API simulation
Enables hot reload for your code
Seamlessly wraps your app in the Playcademy environment

Console output:

VITE v6.3.5  ready in 500ms

➜  Local:   http://localhost:5173/
➜  Network: use --host to expose

PLAYCADEMY v1.2.3

➜  Project:  my-app
➜  Sandbox:  http://localhost:4321/api

How it works: When you visit http://localhost:5173/ in your browser, you'll see your app wrapped in the Playcademy development shell (which mimics the production platform environment). Inside the iframe, your app is served at the root path /, so client-side routers (React Router, wouter, etc.) work naturally without any special configuration.

The plugin uses the Sec-Fetch-Dest header to intelligently detect whether a request is from the shell's iframe or top-level browser navigation, automatically serving the appropriate content.

Client-side routing: Both in development and production, your routers will see clean paths like / and /game. In production, the platform uses a runner that loads your app from the CDN while presenting clean routing paths. You don't need to configure anything - just write your routes normally:

<Router>
    <Route path="/" component={Home} />
    <Route path="/game" component={Game} />
    <Route path="/settings" component={Settings} />
</Router>

Runtime asset loading: If your app loads assets dynamically at runtime (files that Vite can't analyze at build time), use the SDK's CDN helpers:

import { PlaycademyClient } from '@playcademy/sdk'

const client = await PlaycademyClient.init()

// Load dynamic JSON data (e.g., level selected by user)
const levelData = await client.runtime.assets.json`levels/level-${levelId}.json`

// Load images dynamically using tagged template literals
img.src = client.runtime.assets.url`badges/${badgeType}.png`
audio.src = client.runtime.assets.url`sfx/${soundEffect}.wav`

// Or use regular function calls
const data = await client.runtime.assets.fetch('data/config.json')
const blob = await client.runtime.assets.blob('images/hero.png')

These helpers automatically resolve to the correct asset URLs in production and relative paths in local development.

Production Build

During bun run build, the plugin:

Generates playcademy.manifest.json in dist/
Generates .vite/manifest.json for optimal asset loading
Creates deployment zip (if autoZip: true)
Optimizes build for platform deployment

Console output:

dist/index.html                           2.45 kB │ gzip:  1.12 kB
dist/assets/index-Bj8fxu6c.js           135.24 kB │ gzip: 43.82 kB

[Playcademy]
playcademy.manifest.json                   0.25 kB
.playcademy/my-game.zip                1,234.56 kB

Generated Files

Manifest File

The plugin generates dist/playcademy.manifest.json:

{
    "version": "1",
    "platform": "web",
    "createdAt": "2024-01-01T12:00:00.000Z"
}

Deployment Archive

By default, the plugin creates .playcademy/{project-name}.zip containing all build files ready for platform upload. This can be disabled by setting autoZip: false.

Development

Development Workflow

# Start the development environment from monorepo root
bun dev

# This starts all applications with proper port allocation:
# - Landing: http://localhost:5173
# - Hub: http://localhost:5174
# - Docs: http://localhost:5175
# - Blog: http://localhost:5176
# - Sandbox: http://localhost:4321

For package-specific development:

# Change to package directory
cd packages/vite-plugin

# Build the plugin
bun run build

# Publish to npm (requires permissions)
bun run pub

Dependencies

Runtime Dependencies

archiver: Zip file creation for deployment packages
picocolors: Terminal color output for logging

Development Dependencies

@playcademy/sandbox: Development sandbox server
@types/archiver: TypeScript definitions for archiver
yocto-spinner: Progress indicators for build operations

Peer Dependencies

typescript: TypeScript compiler (v5+)

Common Use Cases

Basic Web App

// Minimal configuration for most web games
export default defineConfig({
    plugins: [playcademy()],
})

Testing with Clean Database

// Start with a fresh database on each dev server restart
export default defineConfig({
    plugins: [
        playcademy({
            sandbox: {
                recreateDb: true, // Recreate database on each start
            },
        }),
    ],
})

In-Memory Database for CI

// Use in-memory database for fast, ephemeral testing
export default defineConfig({
    plugins: [
        playcademy({
            sandbox: {
                memoryOnly: true, // Database in RAM only
            },
        }),
    ],
})

Godot Export

// Configuration for Godot HTML5 exports
export default defineConfig({
    plugins: [
        playcademy({
            export: {
                platform: 'godot',
                entryPoint: 'game.html',
            },
        }),
    ],
})

Mode-Based Configuration

// Different settings for development vs production
export default defineConfig(({ mode }) => ({
    plugins: [
        playcademy({
            sandbox: {
                verbose: mode === 'development',
            },
        }),
    ],
}))

TimeBack Integration

// Test TimeBack enrollments and role-based features
export default defineConfig({
    plugins: [
        playcademy({
            timeback: {
                // id defaults to auto-generated mock ID
                courses: {
                    'FastMath:3': 'mock',
                    'FastMath:4': 'mock',
                },
                role: 'student',
            },
        }),
    ],
})

During development, press t in the terminal to cycle through roles (student → parent → teacher → administrator → guardian) and test different permission levels. The browser reloads automatically.

Troubleshooting

Common Issues

Manifest not generated

Ensure plugin is properly configured in vite.config.ts
Check for build errors in console output
Verify the build completes successfully

Zip file not created

Auto-zip is enabled by default - check that build completed without errors
Look for zip in .playcademy/ directory
If you previously disabled it, remove autoZip: false from export options

Debug Mode

Enable verbose logging for troubleshooting:

playcademy({
    sandbox: {
        verbose: true,
    },
})

Interfaces

BannerOptions

Defined in: types/internal.ts:171

Options for the startup banner

Properties

backend?

optional backend: {
  port: number;
  vitePort?: number;
};

Defined in: types/internal.ts:189

Backend server info

port

port: number;

vitePort?

optional vitePort: number;

Vite port for proxied URL display

gameName?

optional gameName: string;

Defined in: types/internal.ts:176

Game/project name (platform mode only)

sandbox?

optional sandbox: 
  | {
  enabled: true;
  port: number;
}
  | {
  enabled: false;
};

Defined in: types/internal.ts:179

Sandbox server info

timeback?

optional timeback: {
  courseCount: number;
  enrolledCount: number;
  mode: "mock" | "local" | "remote";
};

Defined in: types/internal.ts:196

Timeback info (platform mode only)

courseCount

courseCount: number;

enrolledCount

enrolledCount: number;

mode

mode: "mock" | "local" | "remote";

version

version: string;

Defined in: types/internal.ts:173

Plugin version

CliDevServerOptions

Defined in: types/internal.ts:125

Options for setting up the CLI dev server

Properties

configPath?

optional configPath: string;

Defined in: types/internal.ts:129

gameId?

optional gameId: string;

Defined in: types/internal.ts:130

platformUrl?

optional platformUrl: string;

Defined in: types/internal.ts:128

port

port: number;

Defined in: types/internal.ts:126

viteConfig

viteConfig: ResolvedConfig;

Defined in: types/internal.ts:127

CliServerManager

Defined in: types/internal.ts:113

CLI server manager interface for controlling backend server lifecycle

Properties

cleanup()

cleanup: () => void;

Defined in: types/internal.ts:119

Returns

void

port

port: number;

Defined in: types/internal.ts:117

server

server: {
  dispose: () => Promise<void>;
};

Defined in: types/internal.ts:114

dispose()

dispose: () => Promise<void>;

Returns

Promise<void>

stopHotReload()

stopHotReload: () => void;

Defined in: types/internal.ts:118

Returns

void

HotkeyOptions

Defined in: types/internal.ts:163

Options for hotkeys and mode switching

Properties

platformModeOptions

platformModeOptions: PlatformModeOptions;

Defined in: types/internal.ts:165

viteConfig

viteConfig: ResolvedConfig;

Defined in: types/internal.ts:164

PlatformModeOptions

Defined in: types/internal.ts:136

Options for platform mode (sandbox + backend + shell)

Properties

backendPort

backendPort: number;

Defined in: types/internal.ts:147

configPath?

optional configPath: string;

Defined in: types/internal.ts:148

databasePath?

optional databasePath: string;

Defined in: types/internal.ts:145

hideBadge

hideBadge: boolean;

Defined in: types/internal.ts:146

logLevel

logLevel: "debug" | "info" | "warn" | "error";

Defined in: types/internal.ts:140

memoryOnly

memoryOnly: boolean;

Defined in: types/internal.ts:144

recreateDb

recreateDb: boolean;

Defined in: types/internal.ts:142

sandboxPort

sandboxPort: number;

Defined in: types/internal.ts:138

sandboxUrl

sandboxUrl: string;

Defined in: types/internal.ts:141

seed

seed: boolean;

Defined in: types/internal.ts:143

startSandbox

startSandbox: boolean;

Defined in: types/internal.ts:137

timeback?

optional timeback: 
  | false
  | PlaycademyTimebackOptions;

Defined in: types/internal.ts:149

verbose

verbose: boolean;

Defined in: types/internal.ts:139

PlaycademyDisplayOptions

Defined in: types/options.ts:276

Configuration options for the development shell wrapper

The shell provides the platform UI during development, including the Playcademy badge, game selection, and other platform features.

Properties

hideBadge?

optional hideBadge: boolean;

Defined in: types/options.ts:288

Hide the Playcademy badge in the corner during development.

Default

false

Example

display: {
  hideBadge: true // Hide the badge
}

PlaycademyExportOptions

Defined in: types/options.ts:21

Configuration options for exporting/building Playcademy games

Controls how your game is packaged for deployment.

Properties

autoZip?

optional autoZip: boolean;

Defined in: types/options.ts:36

Automatically create a deployment zip archive after build.

The zip file is created at .playcademy/{project-name}.zip and contains all files needed for deployment (frontend assets + backend bundle).

Default

true

Example

export: {
  autoZip: false // Disable auto-zipping
}

PlaycademyOutputData

Defined in: types/internal.ts:54

Build output data for logging and tracking

Properties

manifestPath?

optional manifestPath: string;

Defined in: types/internal.ts:55

manifestSizeKb?

optional manifestSizeKb: string;

Defined in: types/internal.ts:56

zipPath?

optional zipPath: string;

Defined in: types/internal.ts:57

zipSizeKb?

optional zipSizeKb: string;

Defined in: types/internal.ts:58

PlaycademyPluginOptions

Defined in: types/options.ts:318

Main configuration options for the Playcademy Vite plugin

Configure how your game integrates with the Playcademy platform during development and build.

Example

// vite.config.ts
import { playcademy } from '@playcademy/vite-plugin'

export default defineConfig({
  plugins: [
    playcademy({
      mode: 'platform',
      sandbox: {
        logLevel: 'debug',
        recreateDb: true
      },
      display: {
        hideBadge: true
      }
    })
  ]
})

Properties

configPath?

optional configPath: string;

Defined in: types/options.ts:334

Path to the playcademy.config.js file.

By default, the plugin searches for the config file in the current directory and up to 3 parent directories. Use this option to explicitly specify the config file path when using non-standard project structures.

Example

// When running from a client/ subdirectory with config in root
{
  configPath: '../playcademy.config.js'
}

display?

optional display: PlaycademyDisplayOptions;

Defined in: types/options.ts:401

Display configuration options.

Control visual elements during development.

Example

{
  display: {
    hideBadge: true
  }
}

export?

optional export: PlaycademyExportOptions;

Defined in: types/options.ts:368

Export/build configuration options.

Controls how your game is packaged for deployment.

Example

{
  export: {
    autoZip: true // Create deployment zip automatically
  }
}

mode?

optional mode: PlaycademyMode;

Defined in: types/options.ts:352

Plugin operation mode.

'platform': Full development experience with sandbox server and shell (recommended)
'standalone': Backend bundling only, no platform features

Most games should use 'platform' mode.

Default

'platform'

Example

{
  mode: 'standalone' // For testing backend in isolation
}

sandbox?

optional sandbox: PlaycademySandboxOptions;

Defined in: types/options.ts:385

Sandbox server configuration options.

The sandbox provides a local Playcademy platform environment for development.

Example

{
  sandbox: {
    logLevel: 'debug',
    recreateDb: true
  }
}

timeback?

optional timeback: 
  | false
  | PlaycademyTimebackOptions;

Defined in: types/options.ts:421

Timeback integration configuration.

Configure mock or real Timeback enrollments for local development. Timeback id is auto-generated for mock testing.

Example

timeback: {
  courses: {
    'FastMath:3': 'mock',
    'FastMath:4': 'mock',
  },
}

Set to false to explicitly disable Timeback even if configured in playcademy.config.

PlaycademySandboxOptions

Defined in: types/options.ts:45

Configuration options for the Playcademy sandbox server

The sandbox server provides a local development environment that simulates the Playcademy platform, including API endpoints, authentication, and database.

Properties

autoStart?

optional autoStart: boolean;

Defined in: types/options.ts:59

Automatically start the sandbox server when Vite starts.

Set to false if you want to start the sandbox server manually.

Default

true

Example

sandbox: {
  autoStart: false // Start sandbox manually
}

databasePath?

optional databasePath: string;

Defined in: types/options.ts:186

Custom path for the database file.

Specifies where the SQLite database file should be stored. If not provided, defaults to a path based on node_modules location.

Special value ':memory:' creates an in-memory database (equivalent to memoryOnly: true).

Examples

sandbox: {
  databasePath: './my-game-sandbox.db'
}

sandbox: {
  databasePath: ':memory:' // In-memory database
}

logLevel?

optional logLevel: "debug" | "info" | "warn" | "error";

Defined in: types/options.ts:110

Log level for the sandbox server.

Controls the verbosity of sandbox server logs:

'debug': Very detailed logs (all operations)
'info': Standard operational logs
'warn': Warnings only
'error': Errors only

Default

'info'

Example

sandbox: {
  logLevel: 'debug' // Show all debug info
}

memoryOnly?

optional memoryOnly: boolean;

Defined in: types/options.ts:161

Use an in-memory database instead of a file.

The database only exists in RAM and is lost when the server stops. Faster but non-persistent. Useful for testing and CI environments.

Default

false

Example

sandbox: {
  memoryOnly: true // Database in RAM only
}

recreateDb?

optional recreateDb: boolean;

Defined in: types/options.ts:129

Recreate the sandbox database on each server start.

When true, the database is dropped and recreated with seed data every time the dev server starts. Useful for ensuring a clean state during development.

Warning: All existing data will be lost on each restart.

Default

false

Example

sandbox: {
  recreateDb: true // Fresh database on every restart
}

seed?

optional seed: boolean;

Defined in: types/options.ts:145

Seed the database with demo data on startup.

Creates demo users, games, achievements, and other platform data for testing. Disable if you want to start with an empty database.

Default

true

Example

sandbox: {
  seed: false // Start with empty database
}

url?

optional url: string;

Defined in: types/options.ts:75

Custom URL for the sandbox server.

Useful if you need to run the sandbox on a specific host or port. By default, the sandbox uses http://localhost:{port} where port is auto-assigned.

Example

sandbox: {
  url: 'http://localhost:8788'
}

verbose?

optional verbose: boolean;

Defined in: types/options.ts:91

Enable verbose logging for the sandbox server.

Shows detailed information about requests, database operations, and more. Equivalent to setting logLevel: 'debug'.

Default

false

Example

sandbox: {
  verbose: true
}

PlaycademyTimebackOptions

Defined in: types/options.ts:229

Timeback integration configuration for local development.

By default, all courses from playcademy.config.js are enrolled with mock IDs. Use this to override specific courses or exclude them from enrollment.

Example

// Use all defaults (all courses from config with mock IDs)
timeback: {}

// Override role only (still enrolls all courses with mock IDs)
timeback: {
  role: 'teacher',
}

// Override specific course with real ID (others still use mock)
timeback: {
  courses: {
    'FastMath:3': 'real-course-id-g3',
  },
}

// Exclude a course from enrollment (test partial enrollment)
timeback: {
  courses: {
    'FastMath:4': false,  // Not enrolled in grade 4
  },
}

// Full real Timeback integration
timeback: {
  id: 'real-student-sourced-id',
  courses: {
    'FastMath:3': 'real-course-id-g3',
    'FastMath:4': 'real-course-id-g4',
  },
}

Properties

courses?

optional courses: Record<string, null | string | false>;

Defined in: types/options.ts:267

Course enrollment overrides. By default, all courses from playcademy.config.js are enrolled with mock IDs.

Omit entirely: Use all courses from config with mock IDs
'mock' or omit key: Use mock ID for that course
Real string: Use that course ID
null or false: Exclude from enrollment

id?

optional id: string;

Defined in: types/options.ts:234

Timeback ID for the test user. Defaults to auto-generated mock ID. Set to a real student sourcedId for testing against real Timeback.

organization?

optional organization: 
  | "mock"
  | {
  id?: string;
  name?: string;
  type?: "school" | "district" | "department" | "local" | "state" | "national";
};

Defined in: types/options.ts:247

Organization (school/district) configuration. Defaults to PLAYCADEMY mock organization. All properties are optional - only override what you need.

Type declaration

"mock"

{
  id?: string;
  name?: string;
  type?: "school" | "district" | "department" | "local" | "state" | "national";
}

id?

optional id: string;

Organization sourcedId (defaults to PLAYCADEMY)

name?

optional name: string;

Organization display name (defaults to 'Playcademy Studios')

type?

optional type: "school" | "district" | "department" | "local" | "state" | "national";

Organization type (defaults to 'department')

role?

optional role: "student" | "parent" | "teacher" | "administrator" | "guardian";

Defined in: types/options.ts:240

User role for testing. Defaults to 'student'. Use this to test parent/teacher views of your game.

PluginContext

Defined in: types/internal.ts:43

Plugin context shared across hooks

Properties

backendPort

backendPort: null | number;

Defined in: types/internal.ts:46

buildOutputs

buildOutputs: PlaycademyOutputData;

Defined in: types/internal.ts:48

options

options: ResolvedPluginOptions;

Defined in: types/internal.ts:44

sandboxPort

sandboxPort: null | number;

Defined in: types/internal.ts:47

viteConfig

viteConfig: null | ResolvedConfig;

Defined in: types/internal.ts:45

ProjectInfo

Defined in: types/internal.ts:89

Project information extracted from package.json and directory structure

Properties

description?

optional description: string;

Defined in: types/internal.ts:93

displayName

displayName: string;

Defined in: types/internal.ts:91

slug

slug: string;

Defined in: types/internal.ts:90

timebackCourses?

optional timebackCourses: TimebackCourseConfig[];

Defined in: types/internal.ts:94

version

version: string;

Defined in: types/internal.ts:92

ResolvedPluginOptions

Defined in: types/internal.ts:24

Internal resolved plugin options

Properties

autoZip

autoZip: boolean;

Defined in: types/internal.ts:27

configPath?

optional configPath: string;

Defined in: types/internal.ts:25

databasePath?

optional databasePath: string;

Defined in: types/internal.ts:35

hideBadge

hideBadge: boolean;

Defined in: types/internal.ts:36

logLevel

logLevel: "debug" | "info" | "warn" | "error";

Defined in: types/internal.ts:31

memoryOnly

memoryOnly: boolean;

Defined in: types/internal.ts:34

mode

mode: PlaycademyMode;

Defined in: types/internal.ts:26

recreateDb

recreateDb: boolean;

Defined in: types/internal.ts:32

sandboxUrl

sandboxUrl: string;

Defined in: types/internal.ts:28

seed

seed: boolean;

Defined in: types/internal.ts:33

startSandbox

startSandbox: boolean;

Defined in: types/internal.ts:29

timeback?

optional timeback: 
  | false
  | PlaycademyTimebackOptions;

Defined in: types/internal.ts:37

verbose

verbose: boolean;

Defined in: types/internal.ts:30

SandboxManager

Defined in: types/internal.ts:100

Sandbox manager interface for controlling sandbox lifecycle

Properties

baseUrl

baseUrl: string;

Defined in: types/internal.ts:101

cleanup()

cleanup: () => void | Promise<void>;

Defined in: types/internal.ts:107

Returns

void | Promise<void>

gameId?

optional gameId: string;

Defined in: types/internal.ts:104

port

port: number;

Defined in: types/internal.ts:102

project

project: null | ProjectInfo;

Defined in: types/internal.ts:103

setRole()?

optional setRole: (role) => void;

Defined in: types/internal.ts:106

Parameters

role

"student" | "parent" | "teacher" | "administrator"

Returns

void

timebackMode?

optional timebackMode: null | "mock" | "local" | "remote";

Defined in: types/internal.ts:105

StandaloneModeOptions

Defined in: types/internal.ts:155

Options for standalone mode (backend only)

Properties

backendPort

backendPort: number;

Defined in: types/internal.ts:156

configPath?

optional configPath: string;

Defined in: types/internal.ts:157

TimebackCourseConfig

Defined in: types/internal.ts:64

TimeBack course configuration from playcademy.config

Properties

courseId?

optional courseId: string;

Defined in: types/internal.ts:67

grade

grade: number;

Defined in: types/internal.ts:66

masterableUnits?

optional masterableUnits: null | number;

Defined in: types/internal.ts:69

subject

subject: string;

Defined in: types/internal.ts:65

totalXp?

optional totalXp: null | number;

Defined in: types/internal.ts:68

TimebackPluginContext

Defined in: types/internal.ts:79

Combined TimeBack context for vite-plugin internal use. Bundles base courses (from config) with user overrides (from plugin options).

NOTE: This is different from SDK's TimebackInitContext which is the payload sent to games. This is for plugin configuration bundling.

Properties

baseCourses

baseCourses: TimebackCourseConfig[];

Defined in: types/internal.ts:81

Base courses from playcademy.config.js

overrides?

optional overrides: PlaycademyTimebackOptions;

Defined in: types/internal.ts:83

User overrides from vite.config.ts plugin options

Type Aliases

PlatformRoleOverride

type PlatformRoleOverride = typeof PLATFORM_ROLES[number];

Defined in: types/internal.ts:19

PlaycademyMode

type PlaycademyMode = "platform" | "standalone";

Defined in: types/options.ts:14

Plugin operation mode

Controls how the Vite plugin operates during development:

'platform': Full Playcademy platform experience with sandbox server, backend bundling, and shell wrapper (default)
'standalone': Backend only, no sandbox or shell

Default

'platform'

TimebackRoleOverride

type TimebackRoleOverride = typeof TIMEBACK_ROLES[number];

Defined in: types/internal.ts:13

Variables

PLATFORM_ROLES

const PLATFORM_ROLES: readonly ["player", "developer", "admin"];

Defined in: types/internal.ts:18

Platform roles that can be cycled through in dev mode

TIMEBACK_ROLES

const TIMEBACK_ROLES: readonly ["student", "parent", "teacher", "administrator"];

Defined in: types/internal.ts:12

TimeBack roles that can be cycled through in dev mode

Functions

playcademy()

function playcademy(options): Plugin;

Defined in: plugin.ts:65

Playcademy Vite Plugin

Provides:

Auto-starting sandbox server during development
Hijacking dev server to serve Playcademy loader environment
Build-time manifest generation and optional zip packaging