@playcademy/vite-plugin 0.1.40 → 0.2.1

package/README.md

@@ -8,7 +8,7 @@ This plugin integrates Playcademy's development sandbox and build tools into you
 
 The Playcademy Vite plugin streamlines game development by providing:
 
-- **Development Sandbox**: Automatically starts a local Playcademy API server and real-time WebSocket server during development.
+- **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
@@ -87,10 +87,6 @@ export default defineConfig({
                 seed: true, // Seed database with demo data
                 recreateDb: false, // Recreate database on each start
                 memoryOnly: false, // Use in-memory database
-                realtime: {
-                    enabled: false, // Disabled by default, enable for multiplayer
-                    port: 4322, // Defaults to API port + 1
-                },
             },
         }),
     ],
@@ -132,14 +128,25 @@ export default defineConfig({
 
 ## 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 manifest generation and build output:
+Configuration for build output:
 
-| Option     | Type      | Default | Description                                    |
-| ---------- | --------- | ------- | ---------------------------------------------- |
-| `platform` | `string`  | `'web'` | Platform identifier (e.g., 'web', 'godot@4.3') |
-| `autoZip`  | `boolean` | `true`  | Create deployment zip archive                  |
+| Option    | Type      | Default | Description                   |
+| --------- | --------- | ------- | ----------------------------- |
+| `autoZip` | `boolean` | `true`  | Create deployment zip archive |
 
 ### Sandbox Options (`sandbox`)
 
@@ -155,24 +162,33 @@ Configuration for the development sandbox server:
 | `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           |
-| `realtime`     | `object`                                 | `{ enabled: false }`          | Real-time server configuration          |
 
-#### Realtime Options (`sandbox.realtime`)
+### Display Options (`display`)
+
+Configuration for visual elements during development:
 
-| Option    | Type      | Default      | Description                      |
-| --------- | --------- | ------------ | -------------------------------- |
-| `enabled` | `boolean` | `false`      | Enable WebSocket server          |
-| `port`    | `number`  | API port + 1 | Custom port for WebSocket server |
+| 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:
+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                                                    |
-| ------------ | ------------------------------------------------------- | ----------- | -------------------------------------------------------------- |
-| `timebackId` | `'mock' \| string`                                      | `'mock'`    | TimeBack student ID (defaults to mock when courses configured) |
-| `courses`    | `Record<string, 'mock' \| string>`                      | `undefined` | Course enrollments mapping (`'Subject:Grade'`)                 |
-| `role`       | `'student' \| 'parent' \| 'teacher' \| 'administrator'` | `'student'` | User role for testing different permission levels              |
+| 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
 
@@ -181,13 +197,43 @@ export default defineConfig({
     plugins: [
         playcademy({
             timeback: {
-                // timebackId defaults to 'mock' when courses are configured
+                // 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': 'mock', // Mock enrollment for grade 4
+                    'FastMath:4': null, // Exclude from enrollment (test partial)
                     'Science:5': 'real-course-id-123', // Real TimeBack course
                 },
-                role: 'student', // Test as student (default)
+            },
+        }),
+    ],
+})
+
+// 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',
+                },
             },
         }),
     ],
@@ -202,9 +248,10 @@ During development, the plugin provides keyboard shortcuts in the terminal:
 | --- | -------------------------------------------------------- |
 | `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) |
 
-The `t` hotkey automatically reloads your browser when the role changes, making it easy to test different user permission levels without modifying configuration.
+> **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
 
@@ -361,24 +408,6 @@ export default defineConfig({
 })
 ```
 
-### Enabling Real-time Features
-
-```typescript
-// Enable the real-time server for multiplayer games
-export default defineConfig({
-    plugins: [
-        playcademy({
-            sandbox: {
-                realtime: {
-                    enabled: true,
-                    port: 4322, // Optional: custom WebSocket port
-                },
-            },
-        }),
-    ],
-})
-```
-
 ### Testing with Clean Database
 
 ```typescript
@@ -448,7 +477,7 @@ export default defineConfig({
     plugins: [
         playcademy({
             timeback: {
-                timebackId: 'mock',
+                // id defaults to auto-generated mock ID
                 courses: {
                     'FastMath:3': 'mock',
                     'FastMath:4': 'mock',
@@ -460,7 +489,7 @@ export default defineConfig({
 })
 ```
 
-During development, press `t` in the terminal to cycle through roles (student → parent → teacher → administrator) and test different permission levels. The browser reloads automatically.
+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