@playcademy/vite-plugin 0.0.1-beta.13 → 0.0.1-beta.15

package/README.md

@@ -1,137 +1,342 @@
 # @playcademy/vite-plugin
 
-A Vite plugin to generate a `playcademy.manifest.json` for Playcademy games and optionally create a zip archive of the build output.
+**Vite plugin for Playcademy game 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 game 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 game project:
+
 ```bash
-# Using bun
+# Using Bun (recommended)
 bun add -D @playcademy/vite-plugin
 
-# Using pnpm
-pnpm add -D @playcademy/vite-plugin
+# Using npm
+npm install --save-dev @playcademy/vite-plugin
 
 # Using yarn
 yarn add --dev @playcademy/vite-plugin
 
-# Using npm
-npm install --save-dev @playcademy/vite-plugin
+# Using pnpm
+pnpm add -D @playcademy/vite-plugin
 ```
 
-## Usage
+## Quick Start
 
-Add the plugin to your `vite.config.ts` or `vite.config.js`:
+Add the plugin to your `vite.config.ts`:
 
 ```typescript
-// vite.config.ts
 import { defineConfig } from 'vite'
 
 import { playcademy } from '@playcademy/vite-plugin'
 
+export default defineConfig({
+    plugins: [
+        playcademy(), // Uses all defaults
+    ],
+})
+```
+
+Start development:
+
+```bash
+bun dev
+```
+
+The plugin will:
+
+- Start the sandbox server at `http://localhost:4321/api`
+- Enable API integration for your game
+- Provide hot reload for rapid development
+
+## Configuration
+
+### Basic Configuration
+
+```typescript
+import { playcademy } from '@playcademy/vite-plugin'
+
 export default defineConfig({
     plugins: [
         playcademy({
             export: {
-                // bootMode: 'iframe',
-                // entryPoint: 'my-game.html',
-                // styles: ['src/main.css'],
-                // platform: 'web',
-                // autoZip: true, // Set to true to enable zipping locally
+                bootMode: 'iframe', // 'iframe' | 'module'
+                entryPoint: 'index.html', // Main HTML file
+                platform: 'web', // 'web' | 'godot' | 'unity'
+                autoZip: false, // Create deployment zip
+                styles: [], // Additional CSS files
             },
             sandbox: {
-                // autoStart: true, // Auto-start sandbox during development
-                // url: 'http://localhost:4321/api', // Custom sandbox URL
-                // verbose: true, // Enable verbose logging from sandbox
+                autoStart: true, // Start sandbox automatically
+                url: 'http://localhost:4321/api', // Sandbox URL
+                verbose: false, // Enable debug logging
             },
         }),
     ],
-    // ...other Vite config
 })
 ```
 
-## What it does
+### Production Build Configuration
 
-1.  **Auto-starts Development Sandbox**:
-    During development (`vite dev`), the plugin automatically starts a local Playcademy sandbox server that provides game APIs for testing. This allows you to develop your game locally with full API integration.
-
-2.  **Generates `playcademy.manifest.json`**:
-    This file is created in your Vite build's output directory (`dist` by default). It contains metadata about your game, such as its entry point, boot mode, and engine type, which is used by the Playcademy platform.
-
-3.  **Creates Output Zip Archive (Optional)**:
-    If `autoZip` is enabled, the plugin will create a zip file named `{your-project-name}.zip` inside a `.playcademy` directory at the root of your project (e.g., `my-game/.playcademy/my-game.zip`).
-    This archive contains all the contents of your build output directory and can be uploaded directly to the Playcademy platform.
+```typescript
+export default defineConfig({
+    plugins: [
+        playcademy({
+            export: {
+                autoZip: true, // Creates .playcademy/{project-name}.zip
+            },
+        }),
+    ],
+})
+```
 
-4.  **Sets Vite `base` Configuration (if not set by user)**:
-    The plugin defaults Vite's `base` configuration to `'./'`. This is necessary for games to correctly reference assets when deployed on the Playcademy platform. If you explicitly set a `base` path in your `vite.config.ts`, the plugin will respect your configuration and not override it.
+### Custom Sandbox Configuration
 
-## Options (`PlaycademyPluginOptions`)
+```typescript
+export default defineConfig({
+    plugins: [
+        playcademy({
+            sandbox: {
+                autoStart: false, // Disable auto-start
+                url: 'http://localhost:8080/api', // Custom port
+                verbose: true, // Enable debug logs
+            },
+        }),
+    ],
+})
+```
 
-The `playcademy()` plugin accepts an optional options object with two main namespaces:
+## Plugin Options
 
 ### Export Options (`export`)
 
 Configuration for manifest generation and build output:
 
-- **`bootMode`**:
+| Option       | Type                          | Default        | Description                     |
+| ------------ | ----------------------------- | -------------- | ------------------------------- |
+| `bootMode`   | `'iframe' \| 'module'`        | `'iframe'`     | How the game should be launched |
+| `entryPoint` | `string`                      | `'index.html'` | Main HTML file for your game    |
+| `platform`   | `'web' \| 'godot' \| 'unity'` | `'web'`        | Game engine/platform type       |
+| `autoZip`    | `boolean`                     | `false`        | Create deployment zip archive   |
+| `styles`     | `string[]`                    | `[]`           | Additional CSS files to load    |
 
-    - Type: `'iframe' | 'module'`
-    - Default: `'iframe'`
-    - Specifies how the game should be launched.
+### Sandbox Options (`sandbox`)
 
-- **`entryPoint`**:
+Configuration for the development sandbox server:
 
-    - Type: `string`
-    - Default: `'index.html'`
-    - The main HTML file for your game.
+| 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           |
 
-- **`styles`**:
+## Build Output
 
-    - Type: `string[]`
-    - Default: `[]`
-    - An array of CSS file paths (relative to the project root) that should be loaded by the Playcademy platform.
+### Development Mode
 
-- **`platform`**:
+During `bun dev`, the plugin:
 
-    - Type: `'web' | 'godot' | 'unity'`
-    - Default: `'web'`
-    - Specifies the game engine used.
+- Starts the sandbox server (if enabled)
+- Provides game API simulation
+- Enables hot reload for game code
 
-- **`autoZip`**:
-    - Type: `boolean`
-    - Default: `false`
-    - Controls whether to automatically create a zip archive of the build output.
+Console output:
 
-### Sandbox Options (`sandbox`)
+```
+VITE v6.3.5  ready in 500ms
 
-Configuration for the development sandbox server:
+➜  Local:   http://localhost:5173/
+➜  Network: use --host to expose
+
+PLAYCADEMY v1.2.3
+
+➜  Game:    my-game
+➜  Sandbox: http://localhost:4321/api
+```
+
+### Production Build
 
-- **`autoStart`**:
+During `bun run build`, the plugin:
 
-    - Type: `boolean`
-    - Default: `true`
-    - Controls whether to automatically start the development sandbox during `vite dev`.
+- Generates `playcademy.manifest.json` in `dist/`
+- Creates deployment zip (if `autoZip: true`)
+- Optimizes build for platform deployment
 
-- **`url`**:
+Console output:
 
-    - Type: `string`
-    - Default: `'http://localhost:4321/api'`
-    - The URL of the sandbox server to use (useful if you're running your own sandbox instance).
+```
+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`:
+
+```json
+{
+    "version": 1,
+    "slug": "my-game",
+    "displayName": "My Game",
+    "description": "An awesome Playcademy game",
+    "entryPoint": "index.html",
+    "bootMode": "iframe",
+    "platform": "web",
+    "styles": [],
+    "gameVersion": "1.0.0"
+}
+```
 
-- **`verbose`**:
-    - Type: `boolean`
-    - Default: `false`
-    - Enables verbose logging from the sandbox server and API handlers for debugging.
+### Deployment Archive
+
+With `autoZip: true`, creates `.playcademy/{project-name}.zip` containing all build files ready for platform upload.
 
 ## Development
 
-To install dependencies for this package:
+### Development Workflow
 
 ```bash
-bun install
+# 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
 ```
 
-To build the plugin:
+For package-specific development:
 
 ```bash
+# 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 Game
+
+```typescript
+// Minimal configuration for most web games
+export default defineConfig({
+    plugins: [playcademy()],
+})
 ```
+
+### Godot Export
+
+```typescript
+// Configuration for Godot HTML5 exports
+export default defineConfig({
+    plugins: [
+        playcademy({
+            export: {
+                platform: 'godot',
+                entryPoint: 'game.html',
+            },
+        }),
+    ],
+})
+```
+
+### Production Deployment
+
+```typescript
+// Optimized for production builds
+export default defineConfig(({ mode }) => ({
+    plugins: [
+        playcademy({
+            export: {
+                autoZip: mode === 'production',
+            },
+            sandbox: {
+                verbose: mode === 'development',
+            },
+        }),
+    ],
+}))
+```
+
+## 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**
+
+- Enable `autoZip: true` in export options
+- Check that build completed without errors
+- Look for zip in `.playcademy/` directory
+
+### Debug Mode
+
+Enable verbose logging for troubleshooting:
+
+```typescript
+playcademy({
+    sandbox: {
+        verbose: true,
+    },
+})
+```
+
+## Related Packages
+
+- [`@playcademy/sandbox`](../sandbox/): Development sandbox server
+- [`@playcademy/data`](../data/): Platform data types and schemas
+- [`@playcademy/sdk`](../sdk/): Game development SDK
+- [`@playcademy/utils`](../utils/): Shared utility functions