castle-web-cli 0.4.144 → 0.4.145

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (37) hide show
  1. package/dist/imports.js +18 -3
  2. package/dist/init.js +1 -1
  3. package/dist/serve.d.ts +2 -0
  4. package/dist/serve.js +130 -10
  5. package/dist/serveSecurity.d.ts +5 -1
  6. package/dist/serveSecurity.js +27 -8
  7. package/dist/shell/assets/index-BaiRLZ8p.css +1 -0
  8. package/dist/shell/assets/{index-qbygvQIx.js → index-CbRAepsq.js} +68 -68
  9. package/dist/shell/index.html +2 -2
  10. package/kits/physics-2d/CLAUDE.md +44 -0
  11. package/kits/physics-2d/behaviors/Collider.jsx +21 -0
  12. package/kits/physics-2d/behaviors/Draggable.jsx +9 -0
  13. package/kits/physics-2d/behaviors/Layout.jsx +7 -0
  14. package/kits/physics-2d/behaviors/RigidBody.jsx +6 -0
  15. package/kits/physics-2d/behaviors/Sprite.jsx +7 -0
  16. package/kits/physics-2d/editors/BlueprintLibrary.jsx +64 -32
  17. package/kits/physics-2d/editors/NewBlueprintModal.jsx +69 -0
  18. package/kits/physics-2d/editors/PlayOnly.jsx +1 -1
  19. package/kits/physics-2d/editors/SceneEditor.jsx +333 -108
  20. package/kits/physics-2d/editors/SelectionOverlay.jsx +6 -2
  21. package/kits/physics-2d/editors/behaviorRegistry.js +78 -5
  22. package/kits/physics-2d/engine/SceneUI.jsx +2 -2
  23. package/kits/physics-2d/engine/blueprint.js +212 -15
  24. package/kits/physics-2d/engine/editorFlags.js +50 -0
  25. package/kits/physics-2d/engine/files.js +9 -0
  26. package/kits/physics-2d/engine/liveReload.js +16 -4
  27. package/kits/physics-2d/engine/panelPrefs.js +78 -0
  28. package/kits/physics-2d/engine/panelSorting.jsx +84 -0
  29. package/kits/physics-2d/engine/physics/PhysicsSystem.js +5 -2
  30. package/kits/physics-2d/engine/physics/matterBridge.js +12 -2
  31. package/kits/physics-2d/engine/scene.js +94 -3
  32. package/kits/physics-2d/engine/ui.jsx +157 -4
  33. package/kits/physics-2d/engine/ui.module.css +615 -1
  34. package/kits/physics-2d/package-lock.json +78 -1
  35. package/kits/physics-2d/package.json +4 -0
  36. package/package.json +1 -1
  37. package/dist/shell/assets/index-CcVJjnL3.css +0 -1
@@ -10,8 +10,8 @@
10
10
  <link rel="icon" type="image/png" sizes="32x32" href="/__castle/ide/favicon-32x32.png" />
11
11
  <link rel="icon" type="image/png" sizes="16x16" href="/__castle/ide/favicon-16x16.png" />
12
12
  <link rel="icon" href="/__castle/ide/favicon.ico" sizes="any" />
13
- <script type="module" crossorigin src="/__castle/ide/assets/index-qbygvQIx.js"></script>
14
- <link rel="stylesheet" crossorigin href="/__castle/ide/assets/index-CcVJjnL3.css">
13
+ <script type="module" crossorigin src="/__castle/ide/assets/index-CbRAepsq.js"></script>
14
+ <link rel="stylesheet" crossorigin href="/__castle/ide/assets/index-BaiRLZ8p.css">
15
15
  </head>
16
16
  <body>
17
17
  <div id="root"></div>
@@ -236,6 +236,17 @@ export class MyThing {
236
236
  ui(actor, scene) {
237
237
  return null;
238
238
  }
239
+
240
+ // Optional. A one-line summary of this behavior's state, shown beside the
241
+ // title when its inspector panel is collapsed. Keep it short.
242
+ static summary(props) {
243
+ return `${props.speed}`;
244
+ }
245
+
246
+ // Optional. Fired when `$enabled` flips (see "Switching a behavior off").
247
+ // For letting go of anything held outside your own props.
248
+ onDisable(actor, scene) {}
249
+ onEnable(actor, scene) {}
239
250
  }
240
251
  ```
241
252
 
@@ -256,6 +267,37 @@ A scene is a background plus a list of actors. Every actor is an **instance of a
256
267
  }
257
268
  ```
258
269
 
270
+ ### Switching a behavior off without losing its settings
271
+
272
+ Any component may carry `"$enabled": false` to stop the behavior running while
273
+ keeping every prop it has. Absent means on — never write `"$enabled": true`.
274
+
275
+ ```json
276
+ "Slingshot": { "speed": 0.1, "maxDrag": 200, "$enabled": false }
277
+ ```
278
+
279
+ Use this instead of deleting the component when the behavior should come back:
280
+ deleting it throws the configuration away, and re-adding it starts from
281
+ `defaultProps`. It merges per-property like any other prop, so a blueprint can
282
+ ship a behavior switched off and one instance turn it on.
283
+
284
+ **`$` marks a RESERVED property — one the engine owns, not a behavior.** Do not
285
+ name a behavior prop with a leading `$`, and do not expect one to appear in
286
+ `defaultProps` or the inspector's field list. The prefix exists because
287
+ behaviors come from decks and from imports, so any bare name the engine reserved
288
+ could already be in use somewhere — and a silent collision on a name like
289
+ `enabled` would switch somebody's behavior off rather than error. `$enabled` is
290
+ the only one today; the namespace is what makes adding another safe.
291
+
292
+ Disabling `Collider` is the big hammer: a body only exists for an actor with
293
+ one, so its `RigidBody`, `Joints` and controls all go inert with it. Disabling
294
+ `RigidBody` alone leaves the Collider as a static obstacle, which is what a lone
295
+ Collider already means.
296
+
297
+ A behavior can react to the transition with `onDisable(actor, scene)` /
298
+ `onEnable(actor, scene)` — for releasing something it was holding. `Draggable`
299
+ uses it to let go of a grab.
300
+
259
301
  Rules: every actor needs a unique `id` (any string). An instance's `components` holds ONLY props that differ from its blueprint (merged per-property on top of the template); anything unspecified falls back to the blueprint, then to the behavior's `defaultProps`. Position (`Layout.x`/`y`/`rotation`) always lives on the instance. Omit optional fields (`z`, `rotation`, actor `name`, `tint: '#ffffffff'`, scene `name`) to keep scenes compact, especially when generating many actors.
260
302
 
261
303
  ## Blueprints
@@ -665,6 +707,8 @@ For HUD text use a behavior's `ui` hook (returns React); for in-world text or sh
665
707
 
666
708
  ## Don't
667
709
 
710
+ - Don't name a behavior prop with a leading `$` — the engine reserves that prefix (see `$enabled`).
711
+
668
712
  - Don't `console.log` in tight loops — flood the serve log.
669
713
  - Don't keep per-actor state on the behavior class instance; it's recreated each frame. Use `actor.runtime` or component props.
670
714
  - Don't try to import from `editors/`; behaviors run in the play runtime too.
@@ -47,6 +47,12 @@ const SHAPE_DEFAULTS = {
47
47
  },
48
48
  };
49
49
 
50
+ // The pre-list spelling of the shape, still on decks authored before shapes
51
+ // became a list. Only consulted when there is no `shapes[0]` to ask.
52
+ function legacyShape(props) {
53
+ return typeof props.shape === 'string' && props.shape ? props.shape : 'box';
54
+ }
55
+
50
56
  // The collider's shapes, materialized (default = one full box).
51
57
  function currentShapes(component) {
52
58
  return Array.isArray(component.shapes) && component.shapes.length > 0 ? component.shapes : [FULL_BOX];
@@ -100,6 +106,21 @@ export class Collider {
100
106
  density: 0.001,
101
107
  };
102
108
 
109
+ // Shape, and how many of them -- a compound collider's shape count is the
110
+ // thing you cannot see from the canvas without turning debug on.
111
+ static summary(props) {
112
+ const list = Array.isArray(props.shapes) ? props.shapes : [];
113
+ // A compound collider's shape COUNT is the thing you cannot see from the
114
+ // canvas without turning debug on, so it wins over naming one of them.
115
+ const shape =
116
+ list.length > 1
117
+ ? `${list.length} shapes`
118
+ // `shapes[0].type` is where the shape lives now; `props.shape` is the
119
+ // pre-list spelling, still on decks authored before the change.
120
+ : list[0]?.type ?? legacyShape(props);
121
+ return props.isTrigger ? `${shape} · trigger` : shape;
122
+ }
123
+
103
124
  // Inspector ranges. No `max` on any of these: matter treats them as open-ended
104
125
  // (bounciness "can exceed 1" per the docs, and stiction above 1 is meaningful),
105
126
  // and a max is a hard authoring ceiling here -- typed entry is clamped to it,
@@ -41,6 +41,15 @@ export class Draggable {
41
41
  this.props = props;
42
42
  }
43
43
 
44
+ // Switched off mid-drag, this is the only thing that can let go: `update` is
45
+ // the sole caller of `release`, and it stops running the moment the behavior
46
+ // is disabled. Without this the actor stays welded to the pointer.
47
+ onDisable(actor, scene) {
48
+ if (actor.runtime._dragPointerId == null) return;
49
+ scene.physics.release(actor);
50
+ actor.runtime._dragPointerId = null;
51
+ }
52
+
44
53
  update(actor, scene) {
45
54
  const rt = actor.runtime;
46
55
  const held = rt._dragPointerId == null ? null : scene.pointers.get(rt._dragPointerId);
@@ -13,6 +13,13 @@ export class Layout {
13
13
  debug: false,
14
14
  };
15
15
 
16
+ // Position first: it is what tells two instances of the same blueprint apart,
17
+ // and the first thing you look for when the panel is shut.
18
+ static summary(props) {
19
+ const round = (n) => Math.round(Number(n) || 0);
20
+ return `${round(props.x)}, ${round(props.y)} · ${round(props.width)}×${round(props.height)}`;
21
+ }
22
+
16
23
  // Position/rotation/z never inherit from a blueprint: they're always written
17
24
  // as instance values at placement time (z gets an explicit top-of-stack value
18
25
  // on spawn), and a blueprint edit to its own template x/y/z/rotation only
@@ -35,6 +35,12 @@ export class RigidBody {
35
35
  angularVelocity: 0,
36
36
  };
37
37
 
38
+ // Body type is the whole question about a rigid body: does this thing fall,
39
+ // sit still, or get pushed around by hand.
40
+ static summary(props) {
41
+ return typeof props.bodyType === 'string' ? props.bodyType : '';
42
+ }
43
+
38
44
  // `drag`/`angularDrag` are matter's air friction, where values above 1 flip
39
45
  // the velocity sign and destabilize the body -- so 1 is a real ceiling, not a
40
46
  // convenience. `gravityScale` deliberately has none: negative is legitimate
@@ -38,6 +38,13 @@ export class Sprite {
38
38
  tileSize: 50,
39
39
  };
40
40
 
41
+ // The art's filename, without the folder -- `drawings/` is the same for
42
+ // nearly every sprite and the header has no room to spend on it.
43
+ static summary(props) {
44
+ const file = typeof props.file === 'string' ? props.file : '';
45
+ return file.split('/').pop() ?? '';
46
+ }
47
+
41
48
  // Tile cell size in card units -- a floor of 1 (0 would divide by zero when
42
49
  // laying out the repeat), no ceiling since a deck may tile larger than a card.
43
50
  static propertyMeta = {
@@ -1,8 +1,8 @@
1
1
  import React, { useEffect, useRef, useState } from 'react';
2
- import { onArtLoaded, renderArtFrame } from '../engine/art';
2
+ import { isImageArt, onArtLoaded, renderArtFrame } from '../engine/art';
3
3
  import { screenToCard } from '../engine/scene';
4
4
  import { countBlueprintInstances, listBlueprints } from '../engine/blueprint';
5
- import { ConfirmDialog, ContextMenu, cx, Icon, styles } from '../engine/ui';
5
+ import { ConfirmDialog, ContextMenu, cx, Icon, styles, useWheelToHorizontal } from '../engine/ui';
6
6
 
7
7
  const DRAG_THRESHOLD = 4;
8
8
 
@@ -31,21 +31,8 @@ export function BlueprintLibrary({
31
31
  const [contextMenu, setContextMenu] = useState(null);
32
32
  const [confirmDelete, setConfirmDelete] = useState(null);
33
33
 
34
- // Map a vertical mouse wheel gesture onto horizontal scroll so plain-mouse
35
- // users (no trackpad/touch) can pan the hotbar. Bound natively rather than via
36
- // React's onWheel so the listener is non-passive and can preventDefault.
37
- useEffect(() => {
38
- const bar = hotbarRef.current;
39
- if (!bar) return undefined;
40
- const onWheel = (event) => {
41
- if (event.deltaY !== 0 && Math.abs(event.deltaY) > Math.abs(event.deltaX)) {
42
- bar.scrollLeft += event.deltaY;
43
- event.preventDefault();
44
- }
45
- };
46
- bar.addEventListener('wheel', onWheel, { passive: false });
47
- return () => bar.removeEventListener('wheel', onWheel);
48
- }, []);
34
+ // Vertical wheel/trackpad pans the hotbar (see the hook for the direction).
35
+ useWheelToHorizontal(hotbarRef);
49
36
 
50
37
  const onSlotContextMenu = (event, blueprint) => {
51
38
  if (isPlaying) return;
@@ -121,7 +108,7 @@ export function BlueprintLibrary({
121
108
  type="button"
122
109
  className={styles.bpActionSlot}
123
110
  aria-label="Add actor"
124
- title="New blueprint"
111
+ title="New blueprint (hold Alt for a blank one)"
125
112
  onClick={onAddActor}
126
113
  disabled={isPlaying}>
127
114
  <Icon name="plus" />
@@ -218,32 +205,77 @@ function BlueprintDragPreview({ preview, sprites }) {
218
205
  );
219
206
  }
220
207
 
221
- export function BlueprintThumbnail({ blueprint, sprites, preview = false }) {
208
+ // Asked of the CANVAS, not the source art: counting non-transparent grid chars
209
+ // would call a path-drawn sprite blank. Skipped for image art, whose native
210
+ // resolution is whatever was uploaded.
211
+ function rendersNothing(sprite, canvas) {
212
+ if (isImageArt(sprite)) return false;
213
+ try {
214
+ const ctx = canvas.getContext('2d', { willReadFrequently: true });
215
+ const { data } = ctx.getImageData(0, 0, canvas.width, canvas.height);
216
+ for (let i = 3; i < data.length; i += 4) if (data[i] !== 0) return false;
217
+ return true;
218
+ } catch {
219
+ // Tainted or zero-sized canvas: assume it draws something rather than
220
+ // mislabeling real art as blank.
221
+ return false;
222
+ }
223
+ }
224
+
225
+ // A blueprint's slot art, falling back to its NAME when there is nothing to
226
+ // show -- no Sprite, a file that doesn't resolve, or art that is entirely
227
+ // transparent (a "Draw new" sprite nobody has drawn in yet). Without it a belt
228
+ // of not-yet-drawn actors is a row of identical placeholders.
229
+ // `showName={false}` for callers that already print the name right beside the
230
+ // thumbnail (the creation modal's tiles) -- otherwise a sprite-less blueprint
231
+ // renders its name inside the tile AND under it, reading as "GoalGoal".
232
+ export function BlueprintThumbnail({ blueprint, sprites, preview = false, showName = true }) {
222
233
  const canvasRef = useRef(null);
223
234
  const spritePath = blueprint.components?.Sprite?.file;
224
235
  const sprite = spritePath ? sprites?.[spritePath] : null;
225
236
  // Thumbnails draw on change, not on a frame loop, so an image that finishes
226
237
  // decoding after this rendered has to say so or the slot stays blank.
227
238
  const [loadTick, setLoadTick] = useState(0);
239
+ const [blank, setBlank] = useState(false);
228
240
  useEffect(() => onArtLoaded(() => setLoadTick((tick) => tick + 1)), []);
229
241
  useEffect(() => {
230
242
  const canvas = canvasRef.current;
231
243
  if (!canvas || !sprite) return;
232
- renderArtFrame(sprite, 0, canvas);
244
+ const drew = renderArtFrame(sprite, 0, canvas);
245
+ // `false` means "not here yet" (an image still loading), not blank.
246
+ if (drew !== false) setBlank(rendersNothing(sprite, canvas));
233
247
  }, [sprite, loadTick]);
234
- if (!sprite) {
235
- return (
236
- <span className={styles.bpSlotFallback}>
237
- <Icon name="clone" />
238
- </span>
239
- );
240
- }
248
+ const name = showName && typeof blueprint.name === 'string' ? blueprint.name.trim() : '';
249
+ // The canvas stays mounted underneath, so art arriving later clears this.
250
+ // The inner span is load-bearing, not decoration: bare text inside a flex
251
+ // container becomes an anonymous item sized to max-content, so it never
252
+ // "overflows a line" and `overflow-wrap` never fires -- a long single-word
253
+ // name silently clipped at both edges instead of wrapping. A real child can
254
+ // be held to the box's width, which is what gives the wrap something to
255
+ // break against.
256
+ const label = name ? (
257
+ <span className={cx(styles.bpSlotName, preview && styles.bpSlotNamePreview)} title={name}>
258
+ <span className={styles.bpSlotNameText}>{name}</span>
259
+ </span>
260
+ ) : (
261
+ <span className={styles.bpSlotFallback}>
262
+ <Icon name="clone" />
263
+ </span>
264
+ );
265
+ if (!sprite) return label;
241
266
  return (
242
- <canvas
243
- ref={canvasRef}
244
- className={cx(styles.bpSlotThumb, preview && styles.bpPreviewThumb)}
245
- aria-hidden="true"
246
- />
267
+ <span className={styles.bpSlotArt}>
268
+ <canvas
269
+ ref={canvasRef}
270
+ className={cx(
271
+ styles.bpSlotThumb,
272
+ preview && styles.bpPreviewThumb,
273
+ blank && styles.bpSlotThumbHidden
274
+ )}
275
+ aria-hidden="true"
276
+ />
277
+ {blank ? label : null}
278
+ </span>
247
279
  );
248
280
  }
249
281
 
@@ -0,0 +1,69 @@
1
+ import React, { useMemo } from 'react';
2
+ import { listBuiltinBlueprints } from '../engine/blueprint';
3
+ import { cx, Icon, styles } from '../engine/ui';
4
+ import { BlueprintThumbnail } from './BlueprintLibrary';
5
+
6
+ // The "New blueprint" modal: one decision, made from pictures. It asks only
7
+ // "what is this roughly" -- the name and the sprite are answered afterwards in
8
+ // the blueprint inspector, against an actor you can see.
9
+ //
10
+ // Nothing is written until a tile is picked. Cancel leaves the deck untouched.
11
+ //
12
+ // Off by default; see `newBlueprintModal` in engine/editorFlags.js.
13
+
14
+ // The only choice that isn't a built-in, so it leads.
15
+ const BLANK = { key: '__blank__', label: 'Blank Drawing', hint: 'An empty canvas to draw in' };
16
+
17
+ export function NewBlueprintModal({ files, sprites, onCancel, onCreate }) {
18
+ const builtins = useMemo(() => listBuiltinBlueprints(files), [files]);
19
+ return (
20
+ <div
21
+ className={styles.confirmBackdrop}
22
+ onPointerDown={onCancel}
23
+ onKeyDown={(event) => {
24
+ if (event.key === 'Escape') onCancel();
25
+ }}>
26
+ <div
27
+ className={styles.newBpDialog}
28
+ role="dialog"
29
+ aria-label="New blueprint"
30
+ onPointerDown={(event) => event.stopPropagation()}>
31
+ <div className={styles.confirmTitle}>New blueprint</div>
32
+ <div className={styles.newBpSubtitle}>
33
+ Pick a starting point. You can rename it and edit its art next.
34
+ </div>
35
+
36
+ <div className={styles.newBpChoiceGrid}>
37
+ <button
38
+ type="button"
39
+ className={styles.newBpArtTile}
40
+ title={BLANK.hint}
41
+ autoFocus
42
+ onClick={() => onCreate({})}>
43
+ <span className={styles.bpSlotFallback}>
44
+ <Icon name="plus" />
45
+ </span>
46
+ <span className={styles.newBpArtLabel}>{BLANK.label}</span>
47
+ </button>
48
+ {builtins.map((builtin) => (
49
+ <button
50
+ key={builtin.path}
51
+ type="button"
52
+ className={styles.newBpArtTile}
53
+ title={`Start from ${builtin.name}`}
54
+ onClick={() => onCreate({ builtin: builtin.path })}>
55
+ <BlueprintThumbnail blueprint={builtin} sprites={sprites} showName={false} />
56
+ <span className={styles.newBpArtLabel}>{builtin.name}</span>
57
+ </button>
58
+ ))}
59
+ </div>
60
+
61
+ <div className={cx(styles.newBpActions, styles.newBpActionsSingle)}>
62
+ <button type="button" className={styles.newBpSecondary} onClick={onCancel}>
63
+ Cancel
64
+ </button>
65
+ </div>
66
+ </div>
67
+ </div>
68
+ );
69
+ }
@@ -23,7 +23,7 @@ import { behaviorClasses } from './behaviorRegistry';
23
23
  const DEFAULT_SCENE = 'scenes/main.scene';
24
24
 
25
25
  export function PlayOnly({ initialScene } = {}) {
26
- const { files } = useLiveDeckFiles({ live: false });
26
+ const { files } = useLiveDeckFiles({ live: false, hydrateDeclared: false });
27
27
  const scenePath = initialScene && files[initialScene] !== undefined ? initialScene : DEFAULT_SCENE;
28
28
  const { value: sceneData } = parseJsonFile(scenePath, files[scenePath] ?? '');
29
29
  if (!sceneData) return null;