castle-web-cli 0.4.1 → 0.4.2

package/kits/basic-2d/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "basic-2d",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "serve": "node ../../cli/dist/index.js serve . --open",
+    "restart": "node ../../cli/dist/index.js restart .",
+    "screenshot": "node ../../cli/dist/index.js screenshot .",
+    "check": "eslint . && jscpd && node --input-type=module -e \"const { bundleProject } = await import('../../cli/dist/bundle.js'); await bundleProject('.');\""
+  },
+  "jscpd": {
+    "path": [
+      "engine",
+      "editors",
+      "behaviors"
+    ],
+    "threshold": 0,
+    "reporters": [
+      "consoleFull"
+    ]
+  },
+  "dependencies": {
+    "@codemirror/commands": "^6.10.3",
+    "@codemirror/lang-javascript": "^6.2.5",
+    "@codemirror/language": "^6.12.3",
+    "@codemirror/state": "^6.6.0",
+    "@codemirror/view": "^6.41.1",
+    "@fortawesome/free-solid-svg-icons": "^5.15.4",
+    "@lezer/highlight": "^1.2.3",
+    "castle-web-sdk": "file:../../sdk",
+    "codemirror": "^6.0.2",
+    "react": "^19.2.4",
+    "react-dom": "^19.2.4"
+  },
+  "devDependencies": {
+    "eslint": "^9.0.0",
+    "eslint-plugin-react-hooks": "^5.0.0",
+    "jscpd": "^4.0.5",
+    "prettier": "^3.8.3"
+  }
+}

package/kits/basic-2d/scenes/main.scene

@@ -0,0 +1,108 @@
+{
+  "name": "Main Scene",
+  "background": "#1b2030",
+  "actors": [
+    {
+      "id": "actor_1",
+      "components": {
+        "Layout": {
+          "x": 80,
+          "y": 115,
+          "width": 64,
+          "height": 64,
+          "z": 0,
+          "rotation": 0
+        },
+        "Drawing": {
+          "file": "drawings/floor.drawing",
+          "tint": "#ff6b6bff"
+        }
+      }
+    },
+    {
+      "id": "actor_2",
+      "components": {
+        "Layout": {
+          "x": 172,
+          "y": 160,
+          "width": 48,
+          "height": 48,
+          "z": 0,
+          "rotation": 0
+        },
+        "Drawing": {
+          "file": "drawings/floor.drawing",
+          "tint": "#ffd166ff"
+        }
+      }
+    },
+    {
+      "id": "actor_3",
+      "components": {
+        "Layout": {
+          "x": 229,
+          "y": 63,
+          "width": 80,
+          "height": 56,
+          "z": 0,
+          "rotation": 0
+        },
+        "Drawing": {
+          "file": "drawings/floor.drawing",
+          "tint": "#06d6a0ff"
+        }
+      }
+    },
+    {
+      "id": "actor_4",
+      "components": {
+        "Layout": {
+          "x": 184,
+          "y": 239,
+          "width": 56,
+          "height": 56,
+          "z": 0,
+          "rotation": 0
+        },
+        "Drawing": {
+          "file": "drawings/floor.drawing",
+          "tint": "#4dabf7ff"
+        }
+      }
+    },
+    {
+      "id": "actor_5",
+      "components": {
+        "Layout": {
+          "x": 324,
+          "y": 259,
+          "width": 64,
+          "height": 80,
+          "z": 0,
+          "rotation": 0
+        },
+        "Drawing": {
+          "file": "drawings/floor.drawing",
+          "tint": "#b197fcff"
+        }
+      }
+    },
+    {
+      "id": "actor_6",
+      "components": {
+        "Layout": {
+          "x": 292,
+          "y": 389,
+          "width": 96,
+          "height": 64,
+          "z": 0,
+          "rotation": 0
+        },
+        "Drawing": {
+          "file": "drawings/floor.drawing",
+          "tint": "#f06595ff"
+        }
+      }
+    }
+  ]
+}

package/kits/basic-2d/vite.config.js

@@ -0,0 +1 @@
+export default {};

package/kits/basic-2d-frozen/.prettierrc

@@ -0,0 +1,8 @@
+{
+  "printWidth": 100,
+  "tabWidth": 2,
+  "singleQuote": true,
+  "bracketSameLine": true,
+  "trailingComma": "es5",
+  "arrowParens": "always"
+}

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

@@ -0,0 +1,131 @@
+# basic-2d kit
+
+Actor / behavior / scene framework on a 500×700 canvas ("card"). To build a game you (a) write behaviors in `behaviors/*.jsx`, (b) place actors that use them in `scenes/*.scene` (plain JSON). Behaviors auto-register via file glob — drop a new file and it's picked up on next reload.
+
+This kit is plain JavaScript (no TypeScript). Use `.jsx` for files that contain JSX, `.js` otherwise. Don't add types or `.ts`/`.tsx` files.
+
+DO NOT READ `engine/`, `editors/`, OR the built-in `behaviors/` files (`Layout.jsx`, `Drawing.jsx`, `Collider.jsx`, `Camera.jsx`) to build a game. Those are the framework itself; their complete public API (props, helpers, calling conventions) is documented inline below. Read framework source only if you are explicitly modifying the framework.
+
+## Scope
+
+Write the smallest game that satisfies what the user asked for. No sound, particles, menus, multi-level progression, or visual polish unless they specifically asked for it. A typical behavior is 30–80 lines — if yours is hitting 200, you're over-engineering: cut feel-good extras, fewer fields on props, fewer edge cases, fewer comments. Ship the core loop first; the user can ask for more.
+
+## Workflow
+
+1. Edit `behaviors/*.jsx` and `scenes/main.scene`.
+2. `castle-web serve . --detach` (returns the URL, default port 5757). Curl once to confirm.
+3. After every edit: `npm run restart` (no hot reload). Then re-check.
+
+Card size is **500 wide × 700 tall** (origin top-left, +y is down).
+
+## Behavior shape
+
+A behavior is a class. Minimal contract:
+
+```jsx
+// behaviors/MyThing.jsx
+export class MyThing {
+  static behaviorName = 'MyThing'; // must match the key used in .scene
+  static defaultProps = { speed: 200 };
+
+  constructor(props) {
+    this.props = props;
+  }
+
+  // Called every frame in play mode. dt is seconds.
+  update(actor, scene, dt) {
+    const layout = actor.components.Layout;
+    layout.x += this.props.speed * dt; // mutate component in place
+  }
+
+  // Optional. Custom drawing (you usually don't need this; use a Drawing
+  // component instead). ctx is in card units already.
+  draw(actor, scene, ctx) {}
+
+  // Optional. Return React nodes for game-time HUD. Coordinates are card
+  // units. Read state your `update` set; do not start your own loops.
+  ui(actor, scene) {
+    return null;
+  }
+}
+```
+
+A fresh `Behavior` instance is constructed per actor per frame from the actor's component props — DO NOT store per-actor state on `this`. Persist transient state on `actor.runtime` (a free-form object the framework will not serialize) or on the component props themselves.
+
+## Scene file (`scenes/main.scene`, plain JSON)
+
+```json
+{
+  "background": "#1b2030",
+  "actors": [
+    {
+      "id": "paddle",
+      "components": {
+        "Layout": { "x": 210, "y": 640, "width": 80, "height": 12 },
+        "Drawing": { "file": "drawings/floor.drawing" },
+        "Collider": { "kind": "solid", "width": 80, "height": 12 },
+        "Paddle": { "speed": 360 }
+      }
+    }
+  ]
+}
+```
+
+Rules: every actor needs a unique `id` (any string) and almost always a `Layout`. `components` keys are behavior names (the `static behaviorName`). Unspecified props fall back to that behavior's `defaultProps` — omit optional fields (`z`, `rotation`, actor `name`, `tint: '#ffffffff'`, scene `name`) to keep scenes compact, especially when generating many actors. Add a behavior to an actor by adding its key to `components`; remove it by deleting the key.
+
+## Built-in behaviors
+
+- **Layout** — `{ x, y, width, height, z?, rotation? }`. Every actor needs one. `z` orders draw (low first). `rotation` is degrees about the center.
+- **Drawing** — `{ file: "drawings/foo.drawing", tint?: "#rrggbbaa" }`. Renders the pixel-art file scaled into the Layout box. `tint` multiplies; use white (`#ffffffff`) or omit for the original colors. For a solid-color rectangle, point `file` at `drawings/floor.drawing` (an 8×8 white pixel sprite) and set `tint` to your color.
+- **Collider** — `{ kind: 'solid'|'pickup', width, height, offsetX?, offsetY?, debug? }`. Just a rect; the framework does NOT auto-resolve collisions for you. Use it as data:
+
+  ```jsx
+  for (const other of scene.getActors()) {
+    if (other.id === actor.id) continue;
+    if (scene.overlaps(actor, other)) {
+      /* react */
+    }
+  }
+  ```
+
+- **Camera** — `{ target: actorId, followX, followY, roomWidth, roomHeight }`. Place on a dedicated actor; sets `scene.camera` clamped to the room. Omit entirely for a fixed view (no camera = no translation).
+
+## SceneRuntime API (what `scene` exposes to behaviors)
+
+- `scene.time` — seconds since start.
+- `scene.keys` — `Set` of currently-held KeyboardEvent codes (e.g. `'ArrowLeft'`, `'KeyA'`, `'Space'`). Read in `update`.
+- `scene.pointer` — `{ x, y, down }` in world (card) coordinates, camera-adjusted.
+- `scene.getActor(id)` / `scene.getActors()` (sorted by Layout.z) / `scene.getComponent(actor, name)`.
+- `scene.actorWith('GameController')` / `scene.actorsWith('Brick')` — find one / all actors carrying a given behavior. Prefer these to `getActors().find(a => a.components.X)`.
+- `scene.colliderRect(actorOrId)` — rect from Layout + Collider, or null.
+- `scene.overlaps(a, b)` — true when two actors/ids with Collider overlap.
+- `scene.data` — the live scene data. Mutate `actor.components.X = {...}` to change props.
+- `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', ...).
+- `actor.runtime` — per-instance scratchpad for transient state across frames (e.g. velocity, trail history). Not serialized.
+
+## Input shortcuts
+
+```jsx
+if (scene.keys.has('ArrowLeft')) layout.x -= speed * dt;
+if (scene.keys.has('ArrowRight')) layout.x += speed * dt;
+if (scene.keys.has('Space')) /* launch ball */ ;
+```
+
+For HUD text use a behavior's `ui` hook (returns React); for in-world text or shapes, draw with `ctx` from `draw`. The deck has TouchControls overlay support out of the box for mobile play (arrow keys + a button); no setup needed.
+
+## Common breakout-shaped recipe (sketch)
+
+- `Paddle` behavior: read keys, clamp x to `[0, 500 - layout.width]`.
+- `Ball` behavior: store `vx, vy` on `actor.runtime`; integrate; bounce off wall edges (`x<0`, `x+w>500`, `y<0`); on `scene.overlaps(actor, paddle)`, flip `vy`; for each `brick` in `scene.actorsWith('Brick')` check `scene.overlaps(actor, brick)` → flip `vy` and `scene.despawnActor(brick.id)`; if `y > 700` lose a life.
+- `Brick` behavior: typically just a marker — `kind: 'solid'` collider is enough. State (hit count) goes on `actor.runtime` or the brick's own props.
+- `GameController` (no Layout needed if you don't draw it): tracks score / lives / status; expose HUD via `ui()`.
+
+## Don't
+
+- Don't `console.log` in tight loops — flood the serve log.
+- Don't keep per-actor state on the behavior class instance; it's recreated each frame. Use `actor.runtime` or component props.
+- Don't try to import from `editors/`; behaviors run in the play runtime too.
+- Don't add types or `.ts`/`.tsx` files. This kit is JavaScript.
+- Don't add a build step or change `vite.config.js` for a game — it's configured for you.

package/kits/basic-2d-frozen/behaviors/Camera.jsx

@@ -0,0 +1,43 @@
+import { cardSize } from '../engine/scene';
+
+// Follow camera: keeps the target actor centered in the viewport, clamped to
+// the room bounds so the empty area past the room edges never scrolls in.
+export class Camera {
+  static behaviorName = 'Camera';
+
+  static defaultProps = {
+    target: '',
+    followX: true,
+    followY: true,
+    roomWidth: 900,
+    roomHeight: 1100,
+  };
+
+  constructor(props) {
+    this.props = props;
+  }
+
+  update(_actor, scene) {
+    const target = this.props.target ? scene.getActor(this.props.target) : undefined;
+    const targetLayout = target?.components.Layout;
+    if (!targetLayout) return;
+
+    const centerX = targetLayout.x + targetLayout.width / 2;
+    const centerY = targetLayout.y + targetLayout.height / 2;
+    const desiredX = centerX - cardSize.width / 2;
+    const desiredY = centerY - cardSize.height / 2;
+
+    scene.camera = {
+      x: this.props.followX
+        ? clamp(desiredX, 0, this.props.roomWidth - cardSize.width)
+        : 0,
+      y: this.props.followY
+        ? clamp(desiredY, 0, this.props.roomHeight - cardSize.height)
+        : 0,
+    };
+  }
+}
+
+function clamp(value, min, max) {
+  return Math.max(min, Math.min(Math.max(min, max), value));
+}

package/kits/basic-2d-frozen/behaviors/Collider.jsx

@@ -0,0 +1,71 @@
+import React from 'react';
+import { Panel, SelectField } from '../engine/ui';
+import { AutoFields } from '../engine/autoInspector';
+
+export class Collider {
+  static behaviorName = 'Collider';
+
+  static defaultProps = {
+    kind: 'solid',
+    width: 32,
+    height: 32,
+    offsetX: 0,
+    offsetY: 0,
+    debug: false,
+  };
+
+  constructor(props) {
+    this.props = props;
+  }
+
+  draw(actor, _scene, ctx, options) {
+    if (!options.showDebugColliders && !this.props.debug) return;
+    const rect = getColliderRect(actor);
+    if (!rect) return;
+    ctx.save();
+    ctx.strokeStyle = this.props.kind === 'pickup' ? '#ffe17a' : '#8db7ff';
+    ctx.lineWidth = 2;
+    ctx.strokeRect(rect.x + 1, rect.y + 1, rect.width - 2, rect.height - 2);
+    ctx.restore();
+  }
+
+  static Inspector({ component, setComponent }) {
+    return (
+      <Panel title="Collider">
+        <SelectField
+          label="Kind"
+          value={component.kind}
+          onChange={(kind) => setComponent({ kind: kind })}
+          options={['solid', 'pickup']}
+        />
+        <AutoFields
+          defaultProps={Collider.defaultProps}
+          component={component}
+          setComponent={setComponent}
+          exclude={['kind']}
+        />
+      </Panel>
+    );
+  }
+}
+
+export function getColliderRect(actor) {
+  const layout = actor.components.Layout;
+  const collider = actor.components.Collider;
+  if (!layout || !collider) return null;
+  return {
+    x: layout.x + (collider.offsetX ?? 0),
+    y: layout.y + (collider.offsetY ?? 0),
+    width: collider.width ?? layout.width,
+    height: collider.height ?? layout.height,
+  };
+}
+
+export function intersects(a, b) {
+  return (
+    a.x < b.x + b.width &&
+    a.x + a.width > b.x &&
+    a.y < b.y + b.height &&
+    a.y + a.height > b.y
+  );
+}

package/kits/basic-2d-frozen/behaviors/Drawing.jsx

@@ -0,0 +1,139 @@
+import React from 'react';
+import { Panel, SelectField } from '../engine/ui';
+import { AutoFields } from '../engine/autoInspector';
+
+export class Drawing {
+  static behaviorName = 'Drawing';
+
+  static defaultProps = {
+    file: 'drawings/floor.drawing',
+    tint: '#ffffffff',
+  };
+
+  constructor(props) {
+    this.props = props;
+  }
+
+  draw(actor, scene, ctx) {
+    if (actor.runtime?.collected) return;
+    const layout = actor.components.Layout;
+    if (!layout) return;
+    const drawing = scene.drawings[this.props.file];
+    if (!drawing) return;
+    drawPixelDrawing(
+      ctx,
+      drawing,
+      layout.x,
+      layout.y,
+      layout.width,
+      layout.height,
+      this.props.tint
+    );
+  }
+
+  static Inspector({ component, setComponent, files }) {
+    const drawingFiles = getDrawingFiles(files);
+    return (
+      <Panel title="Drawing">
+        <SelectField
+          label="File"
+          value={component.file}
+          onChange={(file) => setComponent({ file })}
+          options={drawingFiles}
+        />
+        <AutoFields
+          defaultProps={Drawing.defaultProps}
+          component={component}
+          setComponent={setComponent}
+          only={['tint']}
+        />
+      </Panel>
+    );
+  }
+}
+
+export function drawPixelDrawing(ctx, drawing, x, y, width, height, tint) {
+  if (drawing.width <= 0 || drawing.height <= 0) return;
+  // Blit the cached native-resolution canvas as a single image. Painting each
+  // pixel as its own `fillRect` left hairline anti-aliased seams under a
+  // rotation transform; one `drawImage` has no inter-pixel edges.
+  const canvas = getDrawingCanvas(drawing, tint);
+  const prevSmoothing = ctx.imageSmoothingEnabled;
+  ctx.imageSmoothingEnabled = false;
+  ctx.drawImage(canvas, x, y, width, height);
+  ctx.imageSmoothingEnabled = prevSmoothing;
+}
+
+// Cache of native-resolution offscreen canvases keyed by drawing data and
+// tint. A drawing edit produces a fresh `DrawingData` object (see
+// DrawingEditor's `structuredClone`), so a new object naturally misses the
+// WeakMap and rebuilds.
+const drawingCanvasCache = new WeakMap();
+
+// Render the pixel art once, unrotated, at 1px per pixel into an offscreen
+// canvas, applying the tint. Cached so the per-frame draw is a single blit.
+function getDrawingCanvas(drawing, tint) {
+  const tintKey = tint ?? '';
+  let byTint = drawingCanvasCache.get(drawing);
+  if (!byTint) {
+    byTint = new Map();
+    drawingCanvasCache.set(drawing, byTint);
+  }
+  const cached = byTint.get(tintKey);
+  if (cached) return cached;
+
+  const canvas = document.createElement('canvas');
+  canvas.width = drawing.width;
+  canvas.height = drawing.height;
+  const octx = canvas.getContext('2d');
+  if (octx) {
+    const tintRgba = parseTint(tint);
+    for (let py = 0; py < drawing.height; py++) {
+      for (let px = 0; px < drawing.width; px++) {
+        const color = drawing.pixels[py * drawing.width + px];
+        if (!color || color === 'transparent' || color.endsWith('00')) continue;
+        octx.fillStyle = tintRgba ? applyTint(color, tintRgba) : color;
+        octx.fillRect(px, py, 1, 1);
+      }
+    }
+  }
+  byTint.set(tintKey, canvas);
+  return canvas;
+}
+
+// Parse a hex color into [r, g, b, a] channels (0-255). Returns null when the
+// string is not a hex color so callers can fall back to the raw color.
+function parseHexColor(color) {
+  const hex = color.trim().replace(/^#/, '');
+  if (hex.length !== 6 && hex.length !== 8) return null;
+  if (!/^[0-9a-fA-F]+$/.test(hex)) return null;
+  const r = parseInt(hex.slice(0, 2), 16);
+  const g = parseInt(hex.slice(2, 4), 16);
+  const b = parseInt(hex.slice(4, 6), 16);
+  const a = hex.length === 8 ? parseInt(hex.slice(6, 8), 16) : 255;
+  return [r, g, b, a];
+}
+
+// Returns the tint as [r, g, b, a] channels, or null when there is no tint or
+// the tint is white (#ffffffff) -- both meaning "no change".
+function parseTint(tint) {
+  if (!tint) return null;
+  const rgba = parseHexColor(tint);
+  if (!rgba) return null;
+  if (rgba[0] === 255 && rgba[1] === 255 && rgba[2] === 255 && rgba[3] === 255) {
+    return null;
+  }
+  return rgba;
+}
+
+// Multiply each channel of a pixel color by the tint color (both 0-255).
+function applyTint(color, tint) {
+  const rgba = parseHexColor(color);
+  if (!rgba) return color;
+  const out = rgba.map((channel, i) => Math.round((channel * tint[i]) / 255));
+  return '#' + out.map((channel) => channel.toString(16).padStart(2, '0')).join('');
+}
+
+function getDrawingFiles(files) {
+  return Object.keys(files).filter((path) => path.endsWith('.drawing'));
+}

package/kits/basic-2d-frozen/behaviors/Layout.jsx

@@ -0,0 +1,16 @@
+export class Layout {
+  static behaviorName = 'Layout';
+
+  static defaultProps = {
+    x: 0,
+    y: 0,
+    width: 32,
+    height: 32,
+    z: 0,
+    rotation: 0,
+  };
+
+  constructor(props) {
+    this.props = props;
+  }
+}

package/kits/basic-2d-frozen/drawings/floor.drawing

@@ -0,0 +1,70 @@
+{
+  "width": 8,
+  "height": 8,
+  "pixels": [
+    "#ffffffff",
+    "#ffffffff",
+    "#ffffffff",
+    "#ffffffff",
+    "#ffffffff",
+    "#ffffffff",
+    "#ffffffff",
+    "#ffffffff",
+    "#ffffffff",
+    "#d8d8d8ff",
+    "#d8d8d8ff",
+    "#d8d8d8ff",
+    "#d8d8d8ff",
+    "#d8d8d8ff",
+    "#d8d8d8ff",
+    "#ffffffff",
+    "#ffffffff",
+    "#d8d8d8ff",
+    "#ffffffff",
+    "#ffffffff",
+    "#ffffffff",
+    "#ffffffff",
+    "#d8d8d8ff",
+    "#ffffffff",
+    "#ffffffff",
+    "#d8d8d8ff",
+    "#ffffffff",
+    "#ffffffff",
+    "#ffffffff",
+    "#ffffffff",
+    "#d8d8d8ff",
+    "#ffffffff",
+    "#ffffffff",
+    "#d8d8d8ff",
+    "#ffffffff",
+    "#ffffffff",
+    "#ffffffff",
+    "#ffffffff",
+    "#d8d8d8ff",
+    "#ffffffff",
+    "#ffffffff",
+    "#d8d8d8ff",
+    "#ffffffff",
+    "#ffffffff",
+    "#ffffffff",
+    "#ffffffff",
+    "#d8d8d8ff",
+    "#ffffffff",
+    "#ffffffff",
+    "#d8d8d8ff",
+    "#d8d8d8ff",
+    "#d8d8d8ff",
+    "#d8d8d8ff",
+    "#d8d8d8ff",
+    "#d8d8d8ff",
+    "#ffffffff",
+    "#ffffffff",
+    "#ffffffff",
+    "#ffffffff",
+    "#ffffffff",
+    "#ffffffff",
+    "#ffffffff",
+    "#ffffffff",
+    "#ffffffff"
+  ]
+}