castle-web-cli 0.4.2 → 0.4.4

package/dist/index.js

@@ -45,14 +45,20 @@ function getWsPort(dir) {
 }
 function usage() {
     console.log(`Usage:
-  castle-web init <dir> [--kit NAME]   (kits: basic-2d (default), rpg-2d, none)
+  castle-web init <dir> [--kit NAME]   (kits: basic-2d (default), none)
   castle-web serve [dir] [--port PORT] [--host HOST] [--open] [--detach]
   castle-web restart [--port PORT]
   castle-web screenshot [--out FILE] [--port PORT]
   castle-web save-preview-image [dir] [--port PORT] [--no-restart]
   castle-web save-deck [dir]
   castle-web get-deck <dir> [--deck-id ID]
-  castle-web login`);
+  castle-web login
+
+Kits:
+  basic-2d  Actor / behavior / scene framework for 2D games. Includes an editor and Layout / Drawing / Collider / Camera built-ins. Default if --kit is omitted.
+  none      Minimal vite + canvas setup with the castle-web SDK and no kit.
+
+After init, read the scaffolded deck's CLAUDE.md (also AGENTS.md) for the kit's full author guide.`);
     process.exit(1);
 }
 async function main() {

package/dist/init.js

@@ -142,11 +142,14 @@ function scaffoldFromKit(kit, projectDir) {
             // For a deck scaffolded from a globally-installed castle-web, rewrite to
             // the published packages instead.
             const sdkPath = getSdkPackagePath();
-            const cliEntry = getCliEntryPath();
-            const sdkIsLocal = fs.existsSync(sdkPath);
-            const cliIsLocal = fs.existsSync(cliEntry);
-            const sdkRef = sdkIsLocal ? `file:${toPosixPath(sdkPath)}` : `^${PUBLISHED_SDK_VERSION}`;
-            const cliDistAbs = cliIsLocal ? toPosixPath(path.dirname(cliEntry)) : null;
+            // "Workspace mode" = the cli is running from a castle-experimental-web
+            // checkout (sdk/ exists next to cli/). Otherwise we're a globally-
+            // installed npm package and need to use the published refs + binary.
+            const workspaceMode = fs.existsSync(sdkPath);
+            const sdkRef = workspaceMode ? `file:${toPosixPath(sdkPath)}` : `^${PUBLISHED_SDK_VERSION}`;
+            const cliDistAbs = workspaceMode
+                ? toPosixPath(path.dirname(getCliEntryPath()))
+                : null;
             if (pkg.dependencies &&
                 typeof pkg.dependencies['castle-web-sdk'] === 'string' &&
                 pkg.dependencies['castle-web-sdk'].startsWith('file:')) {
@@ -159,7 +162,7 @@ function scaffoldFromKit(kit, projectDir) {
                     if (cliDistAbs) {
                         pkg.scripts[k] = pkg.scripts[k]
                             .replace(/\.\.\/\.\.\/cli\/dist/g, cliDistAbs)
-                            .replace(/\.\.\/\.\.\/sdk/g, sdkIsLocal ? toPosixPath(sdkPath) : '');
+                            .replace(/\.\.\/\.\.\/sdk/g, toPosixPath(sdkPath));
                     }
                     else {
                         // Globally-installed: route through the `castle-web` binary on PATH.

package/package.json

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

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

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

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

@@ -1,131 +0,0 @@
-# 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

@@ -1,43 +0,0 @@
-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

@@ -1,71 +0,0 @@
-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

@@ -1,139 +0,0 @@
-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

@@ -1,16 +0,0 @@
-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

@@ -1,70 +0,0 @@
-{
-  "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"
-  ]
-}