@playcademy/sandbox 0.1.0-beta.18 → 0.1.0-beta.19

package/README.md

@@ -1,344 +1,222 @@
 # @playcademy/sandbox
 
-**Local development server for isolated Playcademy game development**
+**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.
+The Playcademy sandbox provides a complete local simulation of the Playcademy platform, including API services and a real-time server, for development and testing.
 
-## Overview
+## What is the Sandbox?
 
-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.
+The sandbox is a local development server that lets you:
 
-### 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
+- **Develop games locally** with full platform integration.
+- **Test SDK functionality** without needing the live platform.
+- **Simulate user accounts** and game data in a controlled environment.
+- **Work offline** without an internet connection.
 
-- **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
+It's a "mock Playcademy platform" running on your machine that behaves just like the real thing.
 
-## Architecture
+### Key Benefits
 
-The sandbox is built on a lightweight stack optimized for development speed:
+- **Isolated Environment**: Completely local execution with no external dependencies.
+- **Zero Configuration**: Automatic database setup and seeding.
+- **Full API Compatibility**: All Playcademy APIs available locally.
+- **Integrated Real-time Server**: Built-in WebSocket server for multiplayer features.
+- **Fast Development Cycle**: Quick startup with an in-memory database.
 
-- **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
+## How It Works
 
-### Directory Structure
+The sandbox runs two local servers to provide a complete development environment. When using our Vite templates, this is handled automatically.
 
-```
-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
+```mermaid
+graph TD
+    subgraph "Your Machine"
+        A["Your Game (in browser)"] --> B["@playcademy/sdk"];
+        B --> C["API Server (localhost:4321)"];
+        B --> D["Real-time Server (localhost:4322)"];
+        C --> E["In-Memory Database"];
+        D --> E;
+    end
 ```
 
-## Installation & Usage
+## Usage
 
-### Global Installation
+The easiest way to use the sandbox is with our official Vite templates, which handle everything automatically via the `@playcademy/vite-plugin`. You can also run it manually as a standalone CLI for advanced use cases.
 
-```bash
-# Install globally for use anywhere
-bun install -g @playcademy/sandbox
+### Automatic Setup (Recommended)
 
-# Start sandbox in any project
-playcademy-sandbox
-```
+When you start your development server with `bun dev`, the Vite plugin will launch the sandbox in the background.
 
-### Local Installation
+::: code-group
 
-```bash
-# Install in your project
-bun add -D @playcademy/sandbox
-
-# Use via package.json script
-{
-  "scripts": {
-    "sandbox": "playcademy-sandbox"
-  }
-}
+```bash [bun]
+bun dev
 ```
 
-### Command Line Interface
-
-```bash
-# 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
+```bash [pnpm]
+pnpm dev
 ```
 
-### 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
-
+```bash [yarn]
+yarn dev
 ```
-# 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
+```bash [npm]
+npm run dev
 ```
 
-## Database Management
-
-### Automatic Setup
-
-The sandbox automatically:
-
-1. **Creates Database Schema** - Uses programmatic schema creation from TypeScript definitions
-2. **Seeds Demo Data** - Provides realistic test data for development
-3. **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:
+You'll see output confirming that both the API and real-time servers are running:
 
-- **Persistent Storage** (default): Database file stored in project's `node_modules` directory
-- **In-Memory**: No persistent storage, fastest startup, data lost on restart
-
-```bash
-# 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
 ```
+VITE v6.3.5
 
-## 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
+➜  Local:   http://localhost:5173/
+➜  Network: use --host to expose
 
-## Integration with Game Development
+PLAYCADEMY v0.1.0
 
-### Basic Integration
-
-```javascript
-// 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 }),
-})
+➜  Game:      playground
+➜  API:       http://localhost:4321/api
+➜  Realtime:  ws://localhost:4322
 ```
 
-### With Playcademy SDK
-
-```javascript
-import { PlaycademySDK } from '@playcademy/sdk'
-
-// Initialize SDK with sandbox
-const sdk = new PlaycademySDK({
-    apiUrl: 'http://localhost:4321/api',
+```typescript
+// vite.config.ts
+import { defineConfig } from 'vite'
+
+import { playcademy } from '@playcademy/vite-plugin'
+
+export default defineConfig({
+    plugins: [
+        playcademy({
+            sandbox: {
+                autoStart: true,
+                url: 'http://localhost:4321/api',
+                realtime: {
+                    enabled: true,
+                    port: 4322,
+                },
+            },
+        }),
+    ],
 })
-
-// Use SDK methods normally
-const user = await sdk.users.getProfile()
-const inventory = await sdk.inventory.getItems()
 ```
 
-## Development
+### Manual Setup
 
-### Building the Sandbox
+You can run the sandbox as a standalone process from the command line.
 
-```bash
-# Build for distribution
-bun run build
+::: code-group
 
-# Development with auto-reload
-bun run dev
+```bash [bun]
+# Run with defaults
+bunx @playcademy/sandbox
 
-# Start without building
-bun run start
+# Run with custom ports and verbose logging
+bunx @playcademy/sandbox --port 8080 --realtime --realtime-port 8081 --verbose
 ```
 
-### Custom Build Process
-
-The build process includes:
-
-1. **TypeScript Compilation**: Builds CLI and server entry points
-2. **Type Generation**: Creates `.d.ts` files for type safety
-3. **PGlite Binary Bundling**: Includes WebAssembly binaries for distribution
-
-### Project-Specific Development
+```bash [pnpm]
+pnpm dlx @playcademy/sandbox --port 8080 --realtime --realtime-port 8081
+```
 
-When developing a specific game, provide project information for enhanced development experience:
+```bash [yarn]
+yarn dlx @playcademy/sandbox --port 8080 --realtime --realtime-port 8081
+```
 
-```bash
-playcademy-sandbox \
-  --project-name "Equation Arena" \
-  --project-slug "equation-arena"
+```bash [npm]
+npx @playcademy/sandbox --port 8080 --realtime --realtime-port 8081
 ```
 
-This enables:
+:::
+
+#### Command-Line Options
 
-- **Automatic Game Registration**: Your game appears in the games API
-- **Custom Seeding**: Game-specific items and configuration
+| Option                     | Alias | Description                              | Default      |
+| :------------------------- | :---- | :--------------------------------------- | :----------- |
+| `--port <number>`          | `-p`  | Port for the main API server.            | `4321`       |
+| `--realtime`               |       | Enables the real-time WebSocket server.  | `false`      |
+| `--realtime-port <number>` |       | Port for the real-time WebSocket server. | API port + 1 |
+| `--verbose`                | `-v`  | Enables verbose logging for debugging.   | `false`      |
+| `--no-seed`                |       | Disables seeding of demo data.           | `false`      |
+| `--project-name <name>`    |       | Sets the project name for game seeding.  | `undefined`  |
+| `--project-slug <slug>`    |       | Sets the project slug for game seeding.  | `undefined`  |
 
-## Advanced Configuration
+#### Manual SDK Configuration
 
-### Programmatic Usage
+If you run the sandbox manually, you'll need to configure the SDK client to point to it.
 
 ```typescript
-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',
-    },
+import { PlaycademyClient } from '@playcademy/sdk'
+
+const client = await PlaycademyClient.init({
+    baseUrl: 'http://localhost:4321/api',
+    realtimeUrl: 'ws://localhost:4322',
+    // In manual mode, you must provide a mock token
+    token: 'mock-dev-token',
 })
 ```
 
-### Custom Database Configuration
+## Sandbox Features
 
-```typescript
-// Use in-memory database (no persistence)
-const server = await startServer({
-    port: 4321,
-    memoryOnly: true, // Use in-memory database
-})
-```
+| Feature              | Description                                                                                   |
+| :------------------- | :-------------------------------------------------------------------------------------------- |
+| **API Simulation**   | Emulates the entire Playcademy backend API for users, games, inventory, etc.                  |
+| **Real-time Server** | Provides WebSocket-based real-time channels for multiplayer communication.                    |
+| **Data Persistence** | Uses an in-memory database. Data persists until the sandbox is restarted.                     |
+| **Mock Data**        | Automatically seeds with a mock user (`developer@example.com`) and other demo data.           |
+| **Game Context**     | When run via the Vite plugin, it automatically registers your current project as a mock game. |
 
-## Troubleshooting
+## Server Endpoints
 
-### Common Issues
+Once running, the sandbox provides several key endpoints:
 
-**Port Already in Use**
+- **Health Check**: `GET /health`
+- **API Base URL**: `/api`
+- **Real-time URL**: `ws://localhost:{realtimePort}`
 
-```bash
-# Sandbox automatically finds available port
-playcademy-sandbox --port 4321
-# Will use 4322, 4323, etc. if 4321 is taken
-```
+All production Playcademy APIs are available under the `/api` prefix, including `/users`, `/games`, `/inventory`, and more. Note that `/timeback` endpoints are available but return noop responses due to external API dependencies.
 
-**API Not Responding**
+## Debugging
 
-- Check that server started successfully (look for green startup messages)
-- Verify the port isn't blocked by firewall
-- Try accessing `/health` endpoint first
+### Health Check
 
-### Debug Mode
+You can verify the sandbox API server is running by sending a request to its `/health` endpoint.
 
 ```bash
-# Enable verbose logging
-playcademy-sandbox --verbose
-
-# Check server health
-curl http://localhost:4321/health
+curl -sSL http://localhost:4321/health | jq
 ```
 
-## Contributing
+This should return a JSON object with the status:
 
-The sandbox is a crucial development tool for the Playcademy ecosystem. When contributing:
+```json
+{
+    "status": "ok",
+    "timestamp": "2023-10-27T00:00:00.000Z"
+}
+```
+
+### Common Issues
 
-1. **Maintain API Parity**: Ensure sandbox APIs match production behavior
-2. **Keep It Fast**: Optimize for quick development iteration
-3. **Update Documentation**: Keep examples current with API changes
-4. **Test Thoroughly**: Validate with real game development scenarios
+| Issue                          | Solution                                                                                                                                                      |
+| :----------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| **Sandbox doesn't start**      | When using Vite, check that `autoStart: true` in `vite.config.ts` and `@playcademy/vite-plugin` is installed. Check terminal for errors.                      |
+| **API calls return HTML**      | This indicates the API server isn't running or is on a different port. Check your sandbox `url` configuration.                                                |
+| **WebSocket connection fails** | Verify the real-time server is enabled (`--realtime` flag or Vite config) and check its port in the console output.                                           |
+| **Port conflicts**             | Use the `--port` and `--realtime-port` options to choose different ports. The sandbox will automatically try the next available port if its default is taken. |
+| **Data doesn't persist**       | This is expected. The sandbox uses an in-memory database that resets on every restart to ensure a clean state for development.                                |
 
-For general contribution guidelines, see the [monorepo CONTRIBUTING.md](../../CONTRIBUTING.md).
+## Production vs. Sandbox
 
-## Related Packages
+The SDK is designed to work seamlessly in both environments. `PlaycademyClient.init()` automatically detects whether it's running in a production environment or against a local sandbox.
 
-- [`@playcademy/api-core`](../api-core/): API handlers used by sandbox
-- [`@playcademy/data`](../data/): Database schema and types
-- [`@playcademy/sdk`](../sdk/): JavaScript SDK for game development
-- **Game Templates**: See `/templates` for example integrations
+| Feature            | Sandbox         | Production            |
+| :----------------- | :-------------- | :-------------------- |
+| **Data**           | Mock, temporary | Real user data        |
+| **Authentication** | Mock tokens     | Secure authentication |
+| **Persistence**    | Session only    | Permanent             |
 
-## Distribution
+## Contributing
 
-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.
+The sandbox is a crucial development tool for the Playcademy ecosystem. For contribution guidelines, see the [monorepo CONTRIBUTING.md](../../CONTRIBUTING.md).