castle-web-cli 0.4.177 → 0.4.179

package/kits/physics-2d/behaviors/Sprite.jsx

@@ -7,6 +7,7 @@ import { Panel, SelectField } from '../engine/ui';
 import { SpriteField } from '../engine/spriteField';
 import { AutoFields, overrideProps } from '../engine/autoInspector';
 import { parseTint, tintCanvas } from './tint';
+import { paintActorStyle, styleContentBox, styleOpacity } from './Style';
 
 // Runtime behavior for a deck's 2D art: the pixel-art `.pxart` format, or an
 // image file (png / jpg / gif / webp / svg) the deck uploaded. Both come out of
@@ -81,6 +82,9 @@ export class Sprite {
     if (actor.runtime?.collected) return;
     const layout = actor.components.Layout;
     if (!layout) return;
+    // Style chrome first so background/border sit behind the blit even when
+    // the Style key is after Sprite on the components object.
+    paintActorStyle(actor, ctx);
     const sprite = this.resolveSprite(scene);
     if (!sprite) return;
     const total = artFrameCount(sprite);
@@ -99,6 +103,8 @@ export class Sprite {
     const smoothing =
       isVectorRenderer(sprite.renderer) || sprite.cornerRadius > 0 || isImageArt(sprite);
 
+    const box = styleContentBox(actor, layout);
+
     // Snap the destination rect to whole device pixels so tiles that abut
     // exactly in card units (e.g. adjacent 100-unit-wide tiles) land on the
     // same device-pixel edge instead of each getting its own antialiased
@@ -117,7 +123,9 @@ export class Sprite {
     // Everything downstream (snapping, tiling's clip box) works off `dest`: the
     // Layout box itself for every mode except `fit`/`cover`, which resize to the
     // art's own aspect ratio (see `spriteDestRect`).
-    const dest = spriteDestRect(this.props.mode, layout, artSize);
+    const dest = spriteDestRect(this.props.mode, box, artSize);
+    ctx.save();
+    ctx.globalAlpha *= styleOpacity(actor);
     if (transform.b === 0 && transform.c === 0) {
       const x0 = dest.x * transform.a + transform.e;
       const y0 = dest.y * transform.d + transform.f;
@@ -133,12 +141,12 @@ export class Sprite {
       if (tiling) {
         drawTilesSnapped(ctx, canvas, artSize, this.props.tileSize, dest, transform, x0, y0, rx0, ry0, rx1, ry1);
       } else {
-        // Clip cover's overflow to the snapped Layout box (undone by restore).
+        // Clip cover's overflow to the snapped content box (undone by restore).
         if (covering) {
-          const lx0 = Math.round(layout.x * transform.a + transform.e);
-          const ly0 = Math.round(layout.y * transform.d + transform.f);
-          const lx1 = Math.round((layout.x + layout.width) * transform.a + transform.e);
-          const ly1 = Math.round((layout.y + layout.height) * transform.d + transform.f);
+          const lx0 = Math.round(box.x * transform.a + transform.e);
+          const ly0 = Math.round(box.y * transform.d + transform.f);
+          const lx1 = Math.round((box.x + box.width) * transform.a + transform.e);
+          const ly1 = Math.round((box.y + box.height) * transform.d + transform.f);
           ctx.beginPath();
           ctx.rect(lx0, ly0, lx1 - lx0, ly1 - ly0);
           ctx.clip();
@@ -151,10 +159,10 @@ export class Sprite {
       if (tiling) {
         drawTilesUnsnapped(ctx, canvas, artSize, this.props.tileSize, dest);
       } else if (covering) {
-        // Rotated: clip cover's overflow to the Layout box in card units.
+        // Rotated: clip cover's overflow to the content box in card units.
         ctx.save();
         ctx.beginPath();
-        ctx.rect(layout.x, layout.y, layout.width, layout.height);
+        ctx.rect(box.x, box.y, box.width, box.height);
         ctx.clip();
         ctx.drawImage(canvas, dest.x, dest.y, dest.width, dest.height);
         ctx.restore();
@@ -163,6 +171,7 @@ export class Sprite {
       }
       ctx.imageSmoothingEnabled = prevSmoothing;
     }
+    ctx.restore();
   }
 
   static Inspector({ component, setComponent, sprites, override }) {

package/kits/physics-2d/behaviors/Style.jsx

@@ -0,0 +1,270 @@
+import React from 'react';
+import { PaletteColorField } from '../engine/paletteField';
+import { NumberField, Panel } from '../engine/ui';
+import { AutoFields, overrideProps } from '../engine/autoInspector';
+import { UNIT } from '../engine/propertyRanges';
+import { inActorWorldSpace } from '../engine/physics/controls';
+
+// Shared chrome for Text and Sprite: fill, border, radius, padding, drop
+// shadow, and opacity. Draws behind content. Sprite/Video paint this themselves
+// before their blit so Style can't land on top when its key is after theirs in
+// JSON; Text relies on forEachBehavior running Style first.
+// Padding insets Text wrap / Sprite blit; opacity multiplies on Style and is
+// also read by Text/Sprite so content fades with the chrome.
+//
+// Drop shadow mirrors CSS `filter: drop-shadow()`: offset X/Y, blur, color.
+// `shadowColor: ''` means no shadow.
+export class Style {
+  static behaviorName = 'Style';
+
+  static defaultProps = {
+    background: '',
+    border: '',
+    borderWidth: 0,
+    borderRadius: 0,
+    padding: 0,
+    shadowX: 0,
+    shadowY: 0,
+    shadowBlur: 0,
+    shadowColor: '',
+    opacity: 1,
+  };
+
+  static propertyMeta = {
+    borderWidth: { min: 0, max: 24, step: 0.5 },
+    borderRadius: { min: 0, max: 200, step: 1 },
+    padding: { min: 0, step: 1 },
+    shadowX: { step: 1 },
+    shadowY: { step: 1 },
+    shadowBlur: { min: 0, max: 64, step: 1 },
+    opacity: UNIT,
+  };
+
+  constructor(props) {
+    this.props = props;
+  }
+
+  static summary(props) {
+    const bits = [];
+    if (props.background) bits.push('fill');
+    if (props.border && props.borderWidth > 0) bits.push('border');
+    if (props.borderRadius > 0) bits.push(`r${Math.round(props.borderRadius)}`);
+    if (resolveShadow(props)) bits.push('shadow');
+    if (props.opacity != null && props.opacity < 1) bits.push(`${Math.round(props.opacity * 100)}%`);
+    return bits.join(' · ');
+  }
+
+  paint(actor, ctx) {
+    paintStyleChrome(actor, ctx, this.props);
+  }
+
+  // Match Text's world/screen split so chrome stays on the selectable box in
+  // edit mode and on the HUD in play. An enabled Sprite/Video paints Style
+  // itself before its blit — skip here so we don't cover that blit when Style
+  // runs after in component order. A disabled Sprite still needs Style.draw.
+  draw(actor, scene, ctx, options) {
+    if (contentPaintsStyle(actor)) return;
+    if (actor.components.Text?.space === 'screen') {
+      if (!options?.editPlaceholders) return;
+      inActorWorldSpace(ctx, actor.components.Layout, (g) => this.paint(actor, g));
+      return;
+    }
+    this.paint(actor, ctx);
+  }
+
+  drawUi(actor, scene, ctx, options) {
+    if (contentPaintsStyle(actor)) return;
+    if (actor.components.Text?.space !== 'screen') return;
+    if (options?.editPlaceholders) return;
+    this.paint(actor, ctx);
+  }
+
+  static Inspector({ component, setComponent, override, files }) {
+    return (
+      <Panel title="Style" overridden={override?.anyOverridden()}>
+        <PaletteColorField
+          label="Background"
+          value={component.background}
+          onChange={(background) => setComponent({ background })}
+          files={files}
+          allowNone
+          {...overrideProps(override, 'background')}
+        />
+        <PaletteColorField
+          label="Border"
+          value={component.border}
+          onChange={(border) => setComponent({ border })}
+          files={files}
+          allowNone
+          {...overrideProps(override, 'border')}
+        />
+        <NumberField
+          label="Border Width"
+          value={component.borderWidth}
+          onChange={(borderWidth) => setComponent({ borderWidth })}
+          min={0}
+          max={24}
+          step={0.5}
+          {...overrideProps(override, 'borderWidth')}
+        />
+        <NumberField
+          label="Border Radius"
+          value={component.borderRadius}
+          onChange={(borderRadius) => setComponent({ borderRadius })}
+          min={0}
+          max={200}
+          step={1}
+          {...overrideProps(override, 'borderRadius')}
+        />
+        <PaletteColorField
+          label="Shadow Color"
+          value={component.shadowColor}
+          onChange={(shadowColor) => setComponent({ shadowColor })}
+          files={files}
+          allowNone
+          {...overrideProps(override, 'shadowColor')}
+        />
+        <AutoFields
+          defaultProps={Style.defaultProps}
+          meta={Style.propertyMeta}
+          component={component}
+          setComponent={setComponent}
+          only={['shadowX', 'shadowY', 'shadowBlur', 'padding', 'opacity']}
+          override={override}
+        />
+      </Panel>
+    );
+  }
+}
+
+/** Paint sibling Style chrome behind content. No-op when Style is absent/off. */
+export function paintActorStyle(actor, ctx) {
+  const props = actor.components?.Style;
+  if (!props || props.$enabled === false) return;
+  paintStyleChrome(actor, ctx, props);
+}
+
+function contentPaintsStyle(actor) {
+  const sprite = actor.components?.Sprite;
+  const video = actor.components?.Video;
+  return (
+    (Boolean(sprite) && sprite.$enabled !== false) || (Boolean(video) && video.$enabled !== false)
+  );
+}
+
+function paintStyleChrome(actor, ctx, props) {
+  const layout = actor.components.Layout;
+  if (!layout || !props) return;
+  const { background, border, borderWidth, borderRadius, opacity } = props;
+  const alpha = Number.isFinite(opacity) ? Math.min(1, Math.max(0, opacity)) : 1;
+  const bw = Math.max(0, Number(borderWidth) || 0);
+  const radius = clampRadius(borderRadius, layout.width, layout.height);
+  const shadow = resolveShadow(props);
+  const hasFill = Boolean(background);
+  const hasBorder = Boolean(border) && bw > 0;
+  if (!hasFill && !hasBorder && !shadow) return;
+
+  ctx.save();
+  ctx.globalAlpha *= alpha;
+  if (shadow) {
+    ctx.shadowColor = shadow.color;
+    ctx.shadowBlur = shadow.blur;
+    ctx.shadowOffsetX = shadow.x;
+    ctx.shadowOffsetY = shadow.y;
+  }
+  if (hasFill) {
+    ctx.fillStyle = background;
+    fillRoundRect(ctx, layout.x, layout.y, layout.width, layout.height, radius);
+  } else if (shadow) {
+    // Shadow needs a filled path; use a near-invisible fill when there's no
+    // background so the drop shadow still casts.
+    ctx.fillStyle = 'rgba(0, 0, 0, 0.01)';
+    fillRoundRect(ctx, layout.x, layout.y, layout.width, layout.height, radius);
+  }
+  if (shadow) {
+    ctx.shadowColor = 'transparent';
+    ctx.shadowBlur = 0;
+    ctx.shadowOffsetX = 0;
+    ctx.shadowOffsetY = 0;
+  }
+  if (hasBorder) {
+    ctx.strokeStyle = border;
+    ctx.lineWidth = bw;
+    const inset = bw / 2;
+    // Inset the stroke so it sits inside the fill edge; shrink the radius by
+    // the same amount so the outer curve still matches the fill's corner.
+    strokeRoundRect(
+      ctx,
+      layout.x + inset,
+      layout.y + inset,
+      Math.max(0, layout.width - bw),
+      Math.max(0, layout.height - bw),
+      Math.max(0, radius - inset)
+    );
+  }
+  ctx.restore();
+}
+
+// Non-empty shadowColor enables the drop shadow. Legacy `shadow: true` (pre
+// drop-shadow props) keeps the old soft black defaults so existing decks
+// don't go flat.
+function resolveShadow(props) {
+  if (props.shadowColor) {
+    return {
+      color: props.shadowColor,
+      blur: Math.max(0, Number(props.shadowBlur) || 0),
+      x: Number(props.shadowX) || 0,
+      y: Number(props.shadowY) || 0,
+    };
+  }
+  if (props.shadow) {
+    return { color: 'rgba(0, 0, 0, 0.35)', blur: 14, x: 0, y: 5 };
+  }
+  return null;
+}
+
+function clampRadius(value, width, height) {
+  const r = Math.max(0, Number(value) || 0);
+  if (!(width > 0) || !(height > 0)) return 0;
+  return Math.min(r, width / 2, height / 2);
+}
+
+function roundRectPath(ctx, x, y, width, height, radius) {
+  ctx.beginPath();
+  if (radius > 0 && ctx.roundRect) ctx.roundRect(x, y, width, height, radius);
+  else ctx.rect(x, y, width, height);
+}
+
+function fillRoundRect(ctx, x, y, width, height, radius) {
+  roundRectPath(ctx, x, y, width, height, radius);
+  ctx.fill();
+}
+
+function strokeRoundRect(ctx, x, y, width, height, radius) {
+  roundRectPath(ctx, x, y, width, height, radius);
+  ctx.stroke();
+}
+
+/** Padding from a sibling Style, or 0. */
+export function stylePadding(actor) {
+  const pad = actor.components.Style?.padding;
+  return Number.isFinite(pad) ? Math.max(0, pad) : 0;
+}
+
+/** Layout box inset by Style.padding, or the layout itself when padding is 0. */
+export function styleContentBox(actor, layout) {
+  const pad = stylePadding(actor);
+  if (!(pad > 0) || !layout) return layout;
+  return {
+    x: layout.x + pad,
+    y: layout.y + pad,
+    width: Math.max(0, layout.width - pad * 2),
+    height: Math.max(0, layout.height - pad * 2),
+  };
+}
+
+/** Opacity from a sibling Style, or 1. */
+export function styleOpacity(actor) {
+  const opacity = actor.components.Style?.opacity;
+  return Number.isFinite(opacity) ? Math.min(1, Math.max(0, opacity)) : 1;
+}

package/kits/physics-2d/behaviors/Text.jsx

@@ -0,0 +1,213 @@
+import { writeFile } from 'castle-web-sdk';
+import React from 'react';
+import { drawTextBlock } from '../engine/text';
+import { PaletteColorField } from '../engine/paletteField';
+import {
+  DECK_FONT_MODULE,
+  OFFICIAL_FONTS,
+  collectTextFontsFromFiles,
+  ensureOfficialFace,
+  fontsGeneratedSource,
+  generatedFontName,
+  orderedDeckFonts,
+  resolveTextFont,
+  themeFontName,
+} from '../engine/fonts';
+import { parseThemeData, THEME_STYLE_PATH } from '../engine/palettes';
+import { FieldNote, NumberField, Panel, SelectField, TextAreaField } from '../engine/ui';
+import { AutoFields, overrideProps } from '../engine/autoInspector';
+import { inActorWorldSpace } from '../engine/physics/controls';
+import { styleOpacity, stylePadding } from './Style';
+
+// In-scene (or screen-fixed) text drawn into the Layout box. Word-wraps to the
+// box minus Style.padding; lines may overflow vertically with no clipping.
+// Colors are opaque deck-palette hexes. Chrome (fill/border/shadow/opacity)
+// lives on the sibling Style behavior. Dynamic text is
+// `actor.components.Text.text = …` from deck code — no $var interpolation.
+export class Text {
+  static behaviorName = 'Text';
+
+  static defaultProps = {
+    text: 'Your text goes here',
+    font: '',
+    size: 24,
+    color: '#131313',
+    align: 'left',
+    verticalAlign: 'top',
+    lineHeight: 1.25,
+    space: 'world',
+    outlineWidth: 0,
+    outlineColor: '#ffffff',
+  };
+
+  static propertyMeta = {
+    size: { min: 4, max: 160, step: 1 },
+    lineHeight: { min: 0.8, max: 3, step: 0.05 },
+    outlineWidth: { min: 0, max: 12, step: 0.5 },
+  };
+
+  constructor(props) {
+    this.props = props;
+  }
+
+  static summary(props) {
+    const first = String(props?.text ?? '').split(/\r?\n/)[0] ?? '';
+    return first;
+  }
+
+  paint(actor, scene, ctx) {
+    const layout = actor.components.Layout;
+    if (!layout) return;
+    const {
+      text,
+      font,
+      size,
+      color,
+      align,
+      verticalAlign,
+      lineHeight,
+      outlineWidth,
+      outlineColor,
+    } = this.props;
+
+    ctx.save();
+    ctx.globalAlpha *= styleOpacity(actor);
+    drawTextBlock(ctx, {
+      x: layout.x,
+      y: layout.y,
+      width: layout.width,
+      height: layout.height,
+      text,
+      size,
+      font: resolveTextFont(font),
+      color,
+      align,
+      verticalAlign,
+      padding: stylePadding(actor),
+      lineHeight,
+      outlineWidth,
+      outlineColor,
+    });
+    ctx.restore();
+  }
+
+  // World-space: paint in the camera+rotation pass. Screen-space in edit mode
+  // also paints here (on the selectable Layout box) so pan/zoom don't detach
+  // the glyph from its handles — see drawUi for play-mode screen paint.
+  draw(actor, scene, ctx, options) {
+    if (this.props.space === 'screen') {
+      if (!options?.editPlaceholders) return;
+      inActorWorldSpace(ctx, actor.components.Layout, (g) => this.paint(actor, scene, g));
+      return;
+    }
+    this.paint(actor, scene, ctx);
+  }
+
+  drawUi(actor, scene, ctx, options) {
+    if (this.props.space !== 'screen') return;
+    if (options?.editPlaceholders) return;
+    this.paint(actor, scene, ctx);
+  }
+
+  static Inspector({ component, setComponent, override, files }) {
+    const fontOptions = [
+      { value: '', label: 'Deck default' },
+      ...OFFICIAL_FONTS.map((face) => ({ value: face.name, label: face.label || face.name })),
+    ];
+
+    function setFont(font) {
+      setComponent({ font });
+      // Install into document.fonts now — fontsReady() only runs the faces that
+      // were in fonts.generated.js at module load, so a newly picked face would
+      // otherwise stay as the fallback until the panel reloads (play is a fresh
+      // load, which is why it looks right there).
+      if (font) void ensureOfficialFace(font);
+      const primary =
+        themeFontName(parseThemeData(files?.[THEME_STYLE_PATH])) ?? generatedFontName;
+      const fonts = orderedDeckFonts(primary, [...collectTextFontsFromFiles(files), font]);
+      void writeFile(
+        DECK_FONT_MODULE,
+        fonts.length ? fontsGeneratedSource(primary ?? fonts[0], fonts) : fontsGeneratedSource(null, [])
+      ).catch(() => {});
+    }
+
+    return (
+      <Panel title="Text" overridden={override?.anyOverridden()}>
+        <TextAreaField
+          label="Text"
+          value={component.text}
+          onChange={(text) => setComponent({ text })}
+          {...overrideProps(override, 'text')}
+        />
+        <SelectField
+          label="Font"
+          value={component.font ?? ''}
+          onChange={setFont}
+          options={fontOptions}
+          {...overrideProps(override, 'font')}
+        />
+        <FieldNote>Picking a face adds it to fonts.generated.js for publish.</FieldNote>
+        <PaletteColorField
+          label="Color"
+          value={component.color}
+          onChange={(color) => setComponent({ color })}
+          files={files}
+          allowNone
+          {...overrideProps(override, 'color')}
+        />
+        <PaletteColorField
+          label="Text Outline"
+          value={component.outlineColor}
+          onChange={(outlineColor) => setComponent({ outlineColor })}
+          files={files}
+          allowNone
+          {...overrideProps(override, 'outlineColor')}
+        />
+        <NumberField
+          label="Outline Width"
+          value={component.outlineWidth}
+          onChange={(outlineWidth) => setComponent({ outlineWidth })}
+          min={0}
+          max={12}
+          step={0.5}
+          {...overrideProps(override, 'outlineWidth')}
+        />
+        <SelectField
+          label="Align"
+          value={component.align}
+          onChange={(align) => setComponent({ align })}
+          options={['left', 'center', 'right']}
+          {...overrideProps(override, 'align')}
+        />
+        <SelectField
+          label="Vertical"
+          value={component.verticalAlign}
+          onChange={(verticalAlign) => setComponent({ verticalAlign })}
+          options={['top', 'middle', 'bottom']}
+          {...overrideProps(override, 'verticalAlign')}
+        />
+        <SelectField
+          label="Space"
+          value={component.space}
+          onChange={(space) => setComponent({ space })}
+          options={[
+            { value: 'world', label: 'world' },
+            { value: 'screen', label: 'screen' },
+          ]}
+          {...overrideProps(override, 'space')}
+        />
+        <FieldNote>
+          world scrolls with the camera; screen stays fixed on the card (HUD).
+        </FieldNote>
+        <AutoFields
+          defaultProps={Text.defaultProps}
+          meta={Text.propertyMeta}
+          component={component}
+          setComponent={setComponent}
+          exclude={['text', 'font', 'color', 'outlineColor', 'outlineWidth', 'align', 'verticalAlign', 'space']}
+          override={override}
+        />
+      </Panel>
+    );
+  }
+}

package/kits/physics-2d/behaviors/Video.jsx

@@ -6,6 +6,7 @@ import { spriteDestRect } from '../engine/spriteGeometry';
 import { FileField, Panel, SelectField } from '../engine/ui';
 import { AutoFields, overrideProps } from '../engine/autoInspector';
 import { UNIT } from '../engine/propertyRanges';
+import { paintActorStyle, styleContentBox, styleOpacity } from './Style';
 
 // Plays a video file (.mp4 / .webm / .mov / .m4v) inside the actor's Layout box.
 //
@@ -59,23 +60,26 @@ export class Video {
     if (actor.runtime?.collected) return;
     const layout = actor.components.Layout;
     if (!layout) return;
+    paintActorStyle(actor, ctx);
     const element = this.element(actor);
     // HAVE_CURRENT_DATA: there is a frame to draw. Below it the element has
     // nothing decoded yet and drawImage would throw.
     if (!element || element.readyState < 2) return;
     const size = { width: element.videoWidth, height: element.videoHeight };
     if (!size.width || !size.height) return;
-    const dest = spriteDestRect(this.props.mode, layout, size);
+    const box = styleContentBox(actor, layout);
+    const dest = spriteDestRect(this.props.mode, box, size);
     const covering = this.props.mode === 'cover';
+    ctx.save();
+    ctx.globalAlpha *= styleOpacity(actor);
     if (covering) {
       // `cover` fills the box by overflowing it; the overflow is cropped.
-      ctx.save();
       ctx.beginPath();
-      ctx.rect(layout.x, layout.y, layout.width, layout.height);
+      ctx.rect(box.x, box.y, box.width, box.height);
       ctx.clip();
     }
     ctx.drawImage(element, dest.x, dest.y, dest.width, dest.height);
-    if (covering) ctx.restore();
+    ctx.restore();
   }
 
   // Used by the inspector's "stop" affordance and by game code that wants the

package/kits/physics-2d/blueprints/text.scene

@@ -0,0 +1,12 @@
+{
+  "name": "Text",
+  "actors": [
+    {
+      "components": {
+        "Layout": { "width": 280, "height": 50, "z": 5 },
+        "Style": { "padding": 8 },
+        "Text": { "text": "Your text goes here" }
+      }
+    }
+  ]
+}

package/kits/physics-2d/castle.json

@@ -34,7 +34,8 @@
         "new": "New scene",
         "icon": "globe",
         "editor": "kit",
-        "data": true
+        "data": true,
+        "width": 800
       },
       {
         "ext": ".sprite",
@@ -42,14 +43,16 @@
         "new": "New sprite",
         "icon": "images-square",
         "editor": "kit",
-        "data": true
+        "data": true,
+        "width": 360
       },
       {
         "ext": ".pxart",
         "label": "Sprite",
         "icon": "images-square",
         "editor": "kit",
-        "data": true
+        "data": true,
+        "width": 360
       },
       {
         "ext": ".jsx",
@@ -62,7 +65,8 @@
         "label": "Theme",
         "icon": "palette",
         "editor": "kit",
-        "data": true
+        "data": true,
+        "width": 400
       }
     ],
     "defaultPlayFile": "scenes/main.scene"
@@ -72,11 +76,11 @@
   "main": "main.jsx",
   "autoUpdateWhenImported": true,
   "title": "physics-2d",
-  "publishedVersion": "2026-09-10T22:05:01.629Z",
+  "publishedVersion": "2026-09-11T20:21:14.346Z",
   "imports": {
     "castle.base": {
       "deckId": "yRcmH4_aYllE",
-      "version": "2026-09-10T00:56:59.388Z"
+      "version": "2026-09-11T20:21:04.335Z"
     }
   }
 }