@playcademy/sandbox 0.1.0-beta.9 → 0.1.0

package/README.md

@@ -1,15 +1,222 @@
-# sandbox
+# @playcademy/sandbox
 
-To install dependencies:
+**Local development server for isolated Playcademy game development.**
 
-```bash
-bun install
+The Playcademy sandbox provides a complete local simulation of the Playcademy platform, including API services and a real-time server, for development and testing.
+
+## What is the Sandbox?
+
+The sandbox is a local development server that lets you:
+
+- **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.
+
+It's a "mock Playcademy platform" running on your machine that behaves just like the real thing.
+
+### 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.
+- **Integrated Real-time Server**: Built-in WebSocket server for multiplayer features.
+- **Fast Development Cycle**: Quick startup with an in-memory database.
+
+## How It Works
+
+The sandbox runs two local servers to provide a complete development environment. When using our Vite templates, this is handled automatically.
+
+```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
+```
+
+## Usage
+
+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.
+
+### Automatic Setup (Recommended)
+
+When you start your development server with `bun dev`, the Vite plugin will launch the sandbox in the background.
+
+::: code-group
+
+```bash [bun]
+bun dev
+```
+
+```bash [pnpm]
+pnpm dev
+```
+
+```bash [yarn]
+yarn dev
+```
+
+```bash [npm]
+npm run dev
+```
+
+:::
+
+You'll see output confirming that both the API and real-time servers are running:
+
+```
+VITE v6.3.5
+
+➜  Local:   http://localhost:5173/
+➜  Network: use --host to expose
+
+PLAYCADEMY v0.1.0
+
+➜  Game:      playground
+➜  API:       http://localhost:4321/api
+➜  Realtime:  ws://localhost:4322
+```
+
+```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,
+                },
+            },
+        }),
+    ],
+})
+```
+
+### Manual Setup
+
+You can run the sandbox as a standalone process from the command line.
+
+::: code-group
+
+```bash [bun]
+# Run with defaults
+bunx @playcademy/sandbox
+
+# Run with custom ports and verbose logging
+bunx @playcademy/sandbox --port 8080 --realtime --realtime-port 8081 --verbose
+```
+
+```bash [pnpm]
+pnpm dlx @playcademy/sandbox --port 8080 --realtime --realtime-port 8081
+```
+
+```bash [yarn]
+yarn dlx @playcademy/sandbox --port 8080 --realtime --realtime-port 8081
+```
+
+```bash [npm]
+npx @playcademy/sandbox --port 8080 --realtime --realtime-port 8081
+```
+
+:::
+
+#### Command-Line Options
+
+| 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`  |
+
+#### Manual SDK Configuration
+
+If you run the sandbox manually, you'll need to configure the SDK client to point to it.
+
+```typescript
+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',
+})
 ```
 
-To run:
+## Sandbox Features
+
+| 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. |
+
+## Server Endpoints
+
+Once running, the sandbox provides several key endpoints:
+
+- **Health Check**: `GET /health`
+- **API Base URL**: `/api`
+- **Real-time URL**: `ws://localhost:{realtimePort}`
+
+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.
+
+## Debugging
+
+### Health Check
+
+You can verify the sandbox API server is running by sending a request to its `/health` endpoint.
 
 ```bash
-bun run index.ts
+curl -sSL http://localhost:4321/health | jq
 ```
 
-This project was created using `bun init` in bun v1.2.10. [Bun](https://bun.sh) is a fast all-in-one JavaScript runtime.
+This should return a JSON object with the status:
+
+```json
+{
+    "status": "ok",
+    "timestamp": "2023-10-27T00:00:00.000Z"
+}
+```
+
+### Common Issues
+
+| 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.                                |
+
+## Production vs. Sandbox
+
+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.
+
+| Feature            | Sandbox         | Production            |
+| :----------------- | :-------------- | :-------------------- |
+| **Data**           | Mock, temporary | Real user data        |
+| **Authentication** | Mock tokens     | Secure authentication |
+| **Persistence**    | Session only    | Permanent             |
+
+## Contributing
+
+The sandbox is a crucial development tool for the Playcademy ecosystem. For contribution guidelines, see the [monorepo CONTRIBUTING.md](../../CONTRIBUTING.md).