@playcademy/sandbox

@playcademy/sandbox

Local development server for isolated Playcademy game development

The sandbox provides a complete, isolated development environment for building games on the Playcademy platform. It runs entirely locally with a PostgreSQL database (PGLite) that can be configured for either persistent storage or in-memory operation, and serves all Playcademy APIs without requiring external services or authentication.

Overview

The sandbox is designed to solve the key challenge of game development: providing a local environment that accurately mirrors the production Playcademy platform while remaining completely isolated and easy to set up.

Key Benefits

• Isolated Environment: Completely local execution with no external dependencies
• Zero Configuration: Automatic database setup and seeding
• Full API Compatibility: All Playcademy APIs available locally
• Fast Development Cycle: Quick startup with configurable database storage (persistent or in-memory)
• Production Parity: Same business logic as production platform
• Game-Specific Seeding: Automatically seeds your game's data for development

Use Cases

• Game Development: Local testing of Playcademy API integration
• Template Development: Building new game templates
• SDK Testing: Validating Playcademy SDK functionality
• API Exploration: Understanding available platform features
• Rapid Prototyping: Quick game concept validation

Architecture

The sandbox is built on a lightweight stack optimized for development speed:

• Hono: Fast, lightweight web framework
• PGLite: PostgreSQL database (WebAssembly) - configurable for persistent or in-memory storage
• Drizzle ORM: Type-safe database operations
• @playcademy/api-core: Production API handlers
• @playcademy/data: Database schema and types

Directory Structure

packages/sandbox/src/
├── cli.ts              # Command-line interface
├── server.ts           # HTTP server setup
├── constants.ts        # Configuration and defaults
├── types.ts            # TypeScript definitions
├── database/           # Database setup and seeding
│   ├── index.ts        # Database initialization
│   ├── path-manager.ts # Database file management
│   └── seed.ts         # Demo data and game seeding
├── lib/                # Core functionality
│   └── auth.ts         # Authentication middleware
├── routes/             # API route handlers
└── utils/              # Utility functions
    └── port.ts         # Port availability checking

Installation & Usage

Global Installation

# Install globally for use anywhere
bun install -g @playcademy/sandbox

# Start sandbox in any project
playcademy-sandbox

Local Installation

# Install in your project
bun add -D @playcademy/sandbox

# Use via package.json script
{
  "scripts": {
    "sandbox": "playcademy-sandbox"
  }
}

Command Line Interface

# Basic usage
playcademy-sandbox

# Custom port
playcademy-sandbox --port 3000

# With project information (enables game-specific seeding)
playcademy-sandbox --project-name "My Game" --project-slug "my-game"

# Verbose logging
playcademy-sandbox --verbose

CLI Options

Option	Description	Default
--port, -p	Server port	4321
--verbose, -v	Enable verbose logging	true
--project-name	Display name for your game	-
--project-slug	URL-safe slug for your game	-

Server Endpoints

Once running, the sandbox provides several key endpoints:

Health & Status

• GET /health - Server health check and status information

API Base

• GET /api - API manifest and available endpoints

Playcademy APIs

All production Playcademy APIs are available locally:

• /api/users - User management and profiles
• /api/games - Game sessions, state, and uploads
• /api/inventory - User inventory management
• /api/items - Item definitions and operations
• /api/shop - In-game shop functionality
• /api/shop-listings - Marketplace listings
• /api/currencies - Virtual currency systems
• /api/levels - User progression and XP
• /api/maps - Game world data and elements
• /api/dev - Developer tools and utilities

Example URLs

# Server status
http://localhost:4321/health

# API manifest
http://localhost:4321/api

# User profile
http://localhost:4321/api/users/me

# Game sessions
http://localhost:4321/api/games/{gameId}/sessions

Database Management

Automatic Setup

The sandbox automatically:

• Creates Database Schema - Uses programmatic schema creation from TypeScript definitions
• Seeds Demo Data - Provides realistic test data for development
• Seeds Game Data - Creates your specific game when project options are provided

Demo Data Includes

• Users: Test user accounts with different roles
• Games: Sample games for testing
• Items: Various item types and categories
• Currencies: Virtual currency systems
• Maps: Basic world/map structures

Database Storage Options

The sandbox supports two database storage modes:

• Persistent Storage (default): Database file stored in project's node_modules directory
• In-Memory: No persistent storage, fastest startup, data lost on restart

# Default persistent storage location:
# ./node_modules/@playcademy/vite-plugin/node_modules/.playcademy/sandbox.db

# In-memory mode can be enabled via:
# - memoryOnly: true in programmatic usage
# - setupDatabase(':memory:') for custom path

Authentication

The sandbox includes simplified authentication for development:

• No Real Authentication Required: Automatically provides a test user context
• JWT Token Support: Compatible with real Playcademy authentication flows
• Developer Keys: Supports development API keys for testing

Integration with Game Development

Basic Integration

// Your game code
const API_BASE = 'http://localhost:4321/api'

// Fetch user inventory
const inventory = await fetch(`${API_BASE}/inventory`)
const items = await inventory.json()

// Add item to user inventory
await fetch(`${API_BASE}/inventory/add`, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ itemId: 'sword-001', quantity: 1 }),
})

With Playcademy SDK

import { PlaycademySDK } from '@playcademy/sdk'

// Initialize SDK with sandbox
const sdk = new PlaycademySDK({
    apiUrl: 'http://localhost:4321/api',
})

// Use SDK methods normally
const user = await sdk.users.getProfile()
const inventory = await sdk.inventory.getItems()

Development

Building the Sandbox

# Build for distribution
bun run build

# Development with auto-reload
bun run dev

# Start without building
bun run start

Custom Build Process

The build process includes:

• TypeScript Compilation: Builds CLI and server entry points
• Type Generation: Creates .d.ts files for type safety
• PGlite Binary Bundling: Includes WebAssembly binaries for distribution

Project-Specific Development

When developing a specific game, provide project information for enhanced development experience:

playcademy-sandbox \
  --project-name "Equation Arena" \
  --project-slug "equation-arena"

This enables:

• Automatic Game Registration: Your game appears in the games API
• Custom Seeding: Game-specific items and configuration

Advanced Configuration

Programmatic Usage

import { startServer } from '@playcademy/sandbox'

const server = await startServer({
    port: 4321,
    verbose: true,
    memoryOnly: true,
    seed: true,
    project: {
        slug: 'my-game',
        displayName: 'My Game',
        version: '1.0.0',
    },
})

Custom Database Configuration

// Use in-memory database (no persistence)
const server = await startServer({
    port: 4321,
    memoryOnly: true, // Use in-memory database
})

Troubleshooting

Common Issues

Port Already in Use

# Sandbox automatically finds available port
playcademy-sandbox --port 4321
# Will use 4322, 4323, etc. if 4321 is taken

API Not Responding

• Check that server started successfully (look for green startup messages)
• Verify the port isn't blocked by firewall
• Try accessing /health endpoint first

Debug Mode

# Enable verbose logging
playcademy-sandbox --verbose

# Check server health
curl http://localhost:4321/health

Contributing

The sandbox is a crucial development tool for the Playcademy ecosystem. When contributing:

• Maintain API Parity: Ensure sandbox APIs match production behavior
• Keep It Fast: Optimize for quick development iteration
• Update Documentation: Keep examples current with API changes
• Test Thoroughly: Validate with real game development scenarios

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

Related Packages

• @playcademy/api-core: API handlers used by sandbox
• @playcademy/data: Database schema and types
• @playcademy/sdk: JavaScript SDK for game development
• Game Templates: See /templates for example integrations

Distribution

The sandbox is distributed as a standalone npm package for use in game development. It can be installed globally or as a development dependency in game projects.