castle-web-cli 0.4.55 → 0.4.56

package/dist/bundle.js

@@ -1,10 +1,11 @@
 import * as path from 'path';
 import { build } from 'vite';
 import { viteSingleFile } from 'vite-plugin-singlefile';
+import { sceneFilesPlugin } from './vitePlugins.js';
 export async function bundleProject(dir) {
     const result = await build({
         root: dir,
-        plugins: [viteSingleFile()],
+        plugins: [viteSingleFile(), sceneFilesPlugin()],
         build: {
             write: false,
             rollupOptions: {

package/dist/serve.js

@@ -6,6 +6,7 @@ import { createServer } from 'vite';
 import { WebSocketServer, WebSocket } from 'ws';
 import { createIdeServer, DECK_FOCUS_SCRIPT } from './ide.js';
 import { createAgentServer } from './agent.js';
+import { sceneFilesPlugin } from './vitePlugins.js';
 import * as config from './config.js';
 function isPortFree(port) {
     return new Promise((resolve) => {
@@ -194,7 +195,7 @@ export async function serve(dir, options = {}) {
     process.on('exit', () => agentServer.shutdown());
     const vite = await createServer({
         root: projectDir,
-        plugins: [castlePlugin(wsPort, ideServer, agentServer)],
+        plugins: [castlePlugin(wsPort, ideServer, agentServer), sceneFilesPlugin()],
         server: {
             port,
             strictPort: true,

package/dist/vitePlugins.d.ts

@@ -0,0 +1,2 @@
+import type { Plugin } from 'vite';
+export declare function sceneFilesPlugin(): Plugin;

package/dist/vitePlugins.js

@@ -0,0 +1,27 @@
+import * as fs from 'fs';
+// Safety net for `.scene` / `.drawing` files imported as JS modules.
+//
+// These files are DATA (JSON), not modules. The blessed way to read them is the
+// engine's file APIs (`scene.readFromFile(name)` / the `?raw` glob in
+// engine/files.js). But agents sometimes still write a plain
+// `import scene from './scenes/main.scene'`, which Vite would otherwise serve as
+// raw JSON-as-JS and the browser throws "Unexpected token ':'". This plugin
+// makes that import resolve to the parsed object so it just works.
+//
+// `?raw` (and any other query suffix) is left untouched so the engine's
+// `import.meta.glob(..., { query: '?raw' })` still gets raw text.
+export function sceneFilesPlugin() {
+    return {
+        name: 'castle-scene-files',
+        load(id) {
+            const [filePath, query] = id.split('?');
+            if (query !== undefined)
+                return null;
+            if (filePath.endsWith('.scene') || filePath.endsWith('.drawing')) {
+                const text = fs.readFileSync(filePath, 'utf-8');
+                return `export default JSON.parse(${JSON.stringify(text)});\n`;
+            }
+            return null;
+        },
+    };
+}

package/kits/basic-2d/CLAUDE.md

@@ -17,7 +17,7 @@ The deck is already serving when you start (`castle-web init` set that up; see `
 1. **Build incrementally.** Start with the smallest playable thing (one mechanic, one scene change), `npm run restart`, then add the next piece. Do NOT write the whole game in one shot.
 2. **After every edit:** `npm run restart` (no hot reload). The served page refreshes and the user sees the change.
 3. **Prefer real, editable assets.** For game objects, characters, and scenery, make actual drawings (`drawings/*.drawing`) and place them as real actors in `scenes/*.scene` — not shapes drawn in code. Real assets let the creator move and re-skin things in the editor and let other creators remix the deck. Data-driven UI (health bars, score/text, HUD gauges) and dynamic things (bullets, particles, effects) are correctly procedural/code — don't force those into drawings.
-4. **Separate scenes per screen.** Use a separate `scenes/*.scene` file for each distinct screen — menu/title, each level, game-over, etc. — not one mega-scene. Each stays independently editable in the editor. Switch at runtime with `scene.load(targetSceneData)`; wire the transition deck-side (e.g. import the target `.scene` JSON and call `scene.load` on play / win / level change).
+4. **Separate scenes per screen.** Use a separate `scenes/*.scene` file for each distinct screen — menu/title, each level, game-over, etc. — not one mega-scene. Each stays independently editable in the editor. Switch at runtime with `scene.loadFromFile('gameover.scene')` (reads the file and transitions) on play / win / level change. NEVER `import` a `.scene` file as a module — scene files are data, not modules; use `scene.readFromFile` / `scene.loadFromFile`.
 
 Card size is **500 wide × 700 tall** (origin top-left, +y is down).
 
@@ -107,6 +107,9 @@ Rules: every actor needs a unique `id` (any string) and almost always a `Layout`
 - `scene.spawnActor({ components: { Layout: {...}, MyBehavior: {...} } })` — add a new actor at runtime. Returns the actor (with auto-minted `id` and `runtime = {}`). Use this; don't push to `scene.data.actors` by hand.
 - `scene.despawnActor(id)` — remove an actor at runtime. Use this; don't `splice` + `delete` by hand.
 - `scene.status` — string you can set/read for game-state ('playing', 'gameover', ...).
+- `scene.load(sceneData)` — replace the running scene with the given scene data object.
+- `scene.readFromFile(name)` — read and parse a scene file (`'gameover.scene'`, `'levels/2.scene'`), returning its scene data. Use this instead of importing a `.scene` file.
+- `scene.loadFromFile(name)` — read a scene file and transition the running scene to it. The way to switch screens/levels and to restart, e.g. `scene.loadFromFile('main.scene')`.
 - `actor.runtime` — per-instance scratchpad for transient state across frames (e.g. velocity, trail history). Not serialized.
 
 ## Input shortcuts

package/kits/basic-2d/engine/scene.js

@@ -1,8 +1,23 @@
+import { initialFiles, parseJsonFile } from './files';
+
 const CARD_WIDTH = 500;
 const CARD_HEIGHT = 700;
 
 export const cardSize = { width: CARD_WIDTH, height: CARD_HEIGHT };
 
+// Resolve a scene-file name to its key in the loaded file map. Accepts
+// 'main.scene', 'scenes/main.scene', './scenes/main.scene', or 'main' -- the
+// `.scene` extension and a leading `scenes/` are both optional.
+function resolveSceneFileKey(name) {
+  const key = String(name).replace(/^\.?\//, '');
+  const candidates = [key];
+  if (!key.endsWith('.scene')) candidates.push(`${key}.scene`);
+  for (const candidate of [...candidates]) {
+    if (!candidate.startsWith('scenes/')) candidates.push(`scenes/${candidate}`);
+  }
+  return candidates.find((candidate) => initialFiles[candidate] !== undefined) ?? key;
+}
+
 export class SceneRuntime {
   constructor(sceneData, behaviors, drawings) {
     this.behaviors = new Map(behaviors.map((Behavior) => [Behavior.behaviorName, Behavior]));
@@ -35,6 +50,26 @@ export class SceneRuntime {
     }
   }
 
+  // Read and parse a scene file by name, returning its scene data. Use this
+  // instead of `import x from './scenes/foo.scene'` -- scene files are data, not
+  // JS modules, so importing them is unsupported.
+  readFromFile(name) {
+    const key = resolveSceneFileKey(name);
+    const text = initialFiles[key];
+    if (text === undefined) {
+      throw new Error(`scene file not found: ${name}`);
+    }
+    const { value, error } = parseJsonFile(key, text);
+    if (error) throw new Error(error);
+    return value;
+  }
+
+  // Transition the running scene to the scene stored in the named file (read it
+  // fresh, then load it). The building block for "go to scene" / restart.
+  loadFromFile(name) {
+    this.load(this.readFromFile(name));
+  }
+
   clone() {
     return new SceneRuntime(this.serialize(), [...this.behaviors.values()], this.drawings);
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "castle-web-cli",
-  "version": "0.4.55",
+  "version": "0.4.56",
   "type": "module",
   "bin": {
     "castle-web": "./dist/index.js"