castle-web-cli 0.4.193 → 0.4.194

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 (75) hide show
  1. package/dist/agent.js +87 -4
  2. package/dist/api.d.ts +1 -0
  3. package/dist/api.js +5 -0
  4. package/dist/bundle.js +2 -1
  5. package/dist/castleJson.d.ts +1 -0
  6. package/dist/check.js +14 -6
  7. package/dist/devSessionServer.d.ts +6 -0
  8. package/dist/devSessionServer.js +23 -1
  9. package/dist/filesChanged.js +7 -3
  10. package/dist/importUpdateHook.d.ts +31 -0
  11. package/dist/importUpdateHook.js +135 -0
  12. package/dist/importUpdateHookRunner.d.ts +2 -0
  13. package/dist/importUpdateHookRunner.js +24 -0
  14. package/dist/imports.js +56 -6
  15. package/dist/index.js +58 -7
  16. package/dist/init.d.ts +1 -0
  17. package/dist/init.js +6 -1
  18. package/dist/native/loop.js +29 -9
  19. package/dist/platformDoc.js +4 -4
  20. package/dist/remix.js +4 -1
  21. package/dist/serve.js +133 -32
  22. package/dist/serverBundle.js +1 -1
  23. package/dist/versions.d.ts +14 -0
  24. package/dist/versions.js +21 -0
  25. package/dist/vitePlugins.d.ts +1 -0
  26. package/dist/vitePlugins.js +18 -0
  27. package/kits/multiplayer-2d/CLAUDE.md +9 -2
  28. package/kits/multiplayer-2d/blueprints/crate.scene +32 -4
  29. package/kits/multiplayer-2d/blueprints/other-player.scene +31 -4
  30. package/kits/multiplayer-2d/blueprints/player.scene +38 -6
  31. package/kits/multiplayer-2d/blueprints/wall.scene +25 -3
  32. package/kits/multiplayer-2d/castle.json +3 -3
  33. package/kits/multiplayer-2d/test/two-client-test.mjs +4 -4
  34. package/kits/multiplayer-3d/CLAUDE.md +5 -2
  35. package/kits/multiplayer-3d/castle.json +3 -3
  36. package/kits/multiplayer-3d/scenes/main.scene +128 -0
  37. package/kits/physics-2d/CLAUDE.md +11 -5
  38. package/kits/physics-2d/behaviors/Camera.jsx +5 -6
  39. package/kits/physics-2d/behaviors/Goal.jsx +5 -2
  40. package/kits/physics-2d/behaviors/Joints.jsx +4 -3
  41. package/kits/physics-2d/behaviors/Layout.jsx +120 -3
  42. package/kits/physics-2d/behaviors/Sprite.jsx +9 -9
  43. package/kits/physics-2d/behaviors/Style.jsx +22 -15
  44. package/kits/physics-2d/behaviors/Text.jsx +7 -6
  45. package/kits/physics-2d/blueprints/ball.scene +27 -5
  46. package/kits/physics-2d/blueprints/block.scene +16 -3
  47. package/kits/physics-2d/blueprints/cauldron.scene +3 -1
  48. package/kits/physics-2d/blueprints/crate.scene +23 -4
  49. package/kits/physics-2d/blueprints/goal.scene +12 -2
  50. package/kits/physics-2d/blueprints/text.scene +13 -3
  51. package/kits/physics-2d/castle.json +2 -1
  52. package/kits/physics-2d/editors/SceneEditor.jsx +26 -2
  53. package/kits/physics-2d/editors/SelectionOverlay.jsx +27 -20
  54. package/kits/physics-2d/engine/blueprint.js +111 -54
  55. package/kits/physics-2d/engine/blueprintCore.js +59 -0
  56. package/kits/physics-2d/engine/collider.js +28 -17
  57. package/kits/physics-2d/engine/layout.js +61 -0
  58. package/kits/physics-2d/engine/layoutOriginMigration.js +223 -0
  59. package/kits/physics-2d/engine/physics/PhysicsSystem.js +11 -7
  60. package/kits/physics-2d/engine/physics/controls.js +4 -8
  61. package/kits/physics-2d/engine/physics/matterBridge.js +13 -8
  62. package/kits/physics-2d/engine/scene.js +38 -34
  63. package/kits/physics-2d/engine/spriteGeometry.js +17 -9
  64. package/kits/physics-2d/engine/tap.js +4 -3
  65. package/kits/physics-2d/scenes/main.scene +59 -6
  66. package/kits/physics-2d/scenes/sandbox.scene +69 -7
  67. package/kits/physics-2d/scripts/onUpdate.mjs +199 -0
  68. package/kits/real-time/castle.json +2 -2
  69. package/kits/real-time/code/server/persist.js +14 -0
  70. package/kits/turn-based/CLAUDE.md +12 -7
  71. package/kits/turn-based/blueprints/board.scene +3 -1
  72. package/kits/turn-based/blueprints/square.scene +3 -1
  73. package/kits/turn-based/castle.json +5 -3
  74. package/kits/turn-based/code/behaviors/Board.jsx +33 -21
  75. package/package.json +1 -1
@@ -1,5 +1,6 @@
1
1
  import React, { useCallback, useEffect, useRef, useState } from 'react';
2
2
  import { getColliderShapes } from '../behaviors/Collider';
3
+ import { layoutCenter, layoutOriginX, layoutOriginY, layoutXYForRect } from '../engine/layout';
3
4
  import { cardSize, screenToCard, isBehaviorEnabled } from '../engine/scene';
4
5
  import { cx, Icon, styles, useElementSize } from '../engine/ui';
5
6
 
@@ -497,6 +498,7 @@ function getSelectedColliderFrames(sceneData, actorIds, sprites) {
497
498
  // needs no such check -- it runs through `forEachBehavior`, which is
498
499
  // gated -- but this overlay reads the component directly.
499
500
  if (!layout || !isBehaviorEnabled(collider) || !shapes) return [];
501
+ const center = layoutCenter(layout);
500
502
  const isTrigger = Boolean(collider.isTrigger) || collider.kind === 'pickup';
501
503
  // One preview box per collider shape, from the shared geometry so the
502
504
  // preview matches the physics body. A circle renders as a radius-sized
@@ -545,8 +547,10 @@ function getSelectedColliderFrames(sceneData, actorIds, sprites) {
545
547
  height,
546
548
  rotation: layout.rotation ?? 0,
547
549
  shapeAngle: s.type === 'box' ? s.angle ?? 0 : 0,
548
- originX: layout.x + layout.width / 2 - x,
549
- originY: layout.y + layout.height / 2 - y,
550
+ // CSS transform-origin for the actor's rotation, relative to this
551
+ // shape's own top-left: the Layout box center, as ever.
552
+ originX: center.x - x,
553
+ originY: center.y - y,
550
554
  };
551
555
  });
552
556
  });
@@ -584,10 +588,7 @@ function getOrientedLayoutBounds(layouts, rotation) {
584
588
  }
585
589
 
586
590
  function getLayoutWorldCorners(layout) {
587
- const center = {
588
- x: layout.x + layout.width / 2,
589
- y: layout.y + layout.height / 2,
590
- };
591
+ const center = layoutCenter(layout);
591
592
  const halfW = layout.width / 2;
592
593
  const halfH = layout.height / 2;
593
594
  const rotation = layout.rotation ?? 0;
@@ -705,12 +706,17 @@ function collectLayoutStarts(sceneData, actorIds) {
705
706
  if (!wanted.has(actor.id)) continue;
706
707
  const layout = actor.components.Layout;
707
708
  if (layout) {
709
+ // Layout-shaped on purpose: the origin travels with the snapshot, so
710
+ // `layoutCenter(start)` / `layoutXYForRect(rect, start)` read and write it
711
+ // exactly as they do a live Layout.
708
712
  starts[actor.id] = {
709
713
  x: layout.x,
710
714
  y: layout.y,
711
715
  width: layout.width,
712
716
  height: layout.height,
713
717
  rotation: layout.rotation ?? 0,
718
+ originX: layoutOriginX(layout),
719
+ originY: layoutOriginY(layout),
714
720
  };
715
721
  }
716
722
  }
@@ -759,17 +765,23 @@ function moveSelected(sceneData, previewSceneData, actorIds, starts, dx, dy) {
759
765
  });
760
766
  }
761
767
 
768
+ // The rounded Layout `x`/`y` that leaves a `width`x`height` box centered on
769
+ // `center`, under the origin `start` carries. Every gesture below computes where
770
+ // the BOX should end up (as it always did) and comes back through here.
771
+ function roundedXYForBox(center, width, height, start) {
772
+ const xy = layoutXYForRect(
773
+ { x: center.x - width / 2, y: center.y - height / 2, width, height },
774
+ start
775
+ );
776
+ return { x: Math.round(xy.x), y: Math.round(xy.y) };
777
+ }
778
+
762
779
  // Common-pivot rotation: actor centers orbit the selection pivot while each
763
780
  // actor also spins by the same delta, matching a temporary group transform.
764
781
  function rotateSelected(sceneData, previewSceneData, actorIds, starts, pivot, deltaDeg) {
765
782
  return updateSelectedLayouts(sceneData, previewSceneData, actorIds, starts, (layout, start) => {
766
- const center = {
767
- x: start.x + start.width / 2,
768
- y: start.y + start.height / 2,
769
- };
770
- const nextCenter = rotatePoint(center, pivot, deltaDeg);
771
- const x = Math.round(nextCenter.x - start.width / 2);
772
- const y = Math.round(nextCenter.y - start.height / 2);
783
+ const nextCenter = rotatePoint(layoutCenter(start), pivot, deltaDeg);
784
+ const { x, y } = roundedXYForBox(nextCenter, start.width, start.height, start);
773
785
  const rotation = normalizeAngle((start.rotation ?? 0) + deltaDeg);
774
786
  if (layout.x === x && layout.y === y && (layout.rotation ?? 0) === rotation) return null;
775
787
  return { x, y, rotation };
@@ -781,11 +793,7 @@ function scaleSelected(sceneData, previewSceneData, actorIds, starts, startTrans
781
793
  const scaleX = startBounds.width === 0 ? 1 : nextLocalBounds.width / startBounds.width;
782
794
  const scaleY = startBounds.height === 0 ? 1 : nextLocalBounds.height / startBounds.height;
783
795
  return updateSelectedLayouts(sceneData, previewSceneData, actorIds, starts, (layout, start) => {
784
- const startCenter = {
785
- x: start.x + start.width / 2,
786
- y: start.y + start.height / 2,
787
- };
788
- const localCenter = worldToLocal(startCenter, startTransform);
796
+ const localCenter = worldToLocal(layoutCenter(start), startTransform);
789
797
  const nextLocalCenter = {
790
798
  x: nextLocalBounds.left + (localCenter.x - startBounds.left) * scaleX,
791
799
  y: nextLocalBounds.top + (localCenter.y - startBounds.top) * scaleY,
@@ -793,8 +801,7 @@ function scaleSelected(sceneData, previewSceneData, actorIds, starts, startTrans
793
801
  const nextCenter = localToWorld(nextLocalCenter, startTransform);
794
802
  const width = Math.max(MIN_LAYOUT_SIZE, Math.round(start.width * scaleX));
795
803
  const height = Math.max(MIN_LAYOUT_SIZE, Math.round(start.height * scaleY));
796
- const x = Math.round(nextCenter.x - width / 2);
797
- const y = Math.round(nextCenter.y - height / 2);
804
+ const { x, y } = roundedXYForBox(nextCenter, width, height, start);
798
805
  if (layout.x === x && layout.y === y && layout.width === width && layout.height === height) {
799
806
  return null;
800
807
  }
@@ -7,21 +7,18 @@
7
7
  // (`scene.js`, so play mode and `PlayOnly` resolve blueprints too) and the
8
8
  // editors (which also mint/fork/migrate/cascade-delete blueprint files).
9
9
  import { deckPrefixOf, IMPORTS_DIR, IMPORTS_PREFIX, resolveDeckFile } from 'castle-web-sdk';
10
+ import { BLUEPRINTS_DIR, isBlueprintPath, mergeComponents, parseBlueprintText } from './blueprintCore.js';
10
11
  import { formatJson } from './files';
12
+ import { DEFAULT_ORIGIN_X, DEFAULT_ORIGIN_Y, layoutOriginX, layoutOriginY, layoutXYForRect } from './layout';
11
13
  import { DEFAULT_RESOLUTION, TRANSPARENT, serializeCompact } from './pxart';
12
14
  import { cardSize, dedupeActorId } from './scene';
13
15
 
14
- export const BLUEPRINTS_DIR = 'blueprints';
15
- export const DRAWINGS_DIR = 'drawings';
16
-
17
- // A blueprint of this deck (`blueprints/x.scene`) OR of one it imports
18
- // (`imports/<alias>/blueprints/x.scene`) -- an imported deck's blueprints are
19
- // placeable like any other, which is most of the point of importing one.
20
- const BLUEPRINT_PATH_RE = new RegExp(`^(imports/[^/]+/)?${BLUEPRINTS_DIR}/`);
16
+ // The pieces a Node script of the kit's shares with the runtime live in
17
+ // `blueprintCore.js` (no imports of its own). Re-exported so every existing
18
+ // importer of this module keeps resolving them here.
19
+ export { BLUEPRINTS_DIR, isBlueprintPath, mergeComponents, parseBlueprintText };
21
20
 
22
- export function isBlueprintPath(path) {
23
- return typeof path === 'string' && path.endsWith('.scene') && BLUEPRINT_PATH_RE.test(path);
24
- }
21
+ export const DRAWINGS_DIR = 'drawings';
25
22
 
26
23
  // Blueprints an import owns: placeable, but not editable or deletable from here
27
24
  // (they belong to the deck they came from).
@@ -53,23 +50,6 @@ export function isInheritedProp(Behavior, prop) {
53
50
  return getPropertyMeta(Behavior, prop).inherit !== false;
54
51
  }
55
52
 
56
- // Parse a blueprint file's text into { name, components } (the template
57
- // actor's components), or null if the text isn't a valid blueprint (used to
58
- // treat a tombstoned/deleted blueprint file as absent).
59
- function parseBlueprintText(text) {
60
- if (typeof text !== 'string') return null;
61
- let data;
62
- try {
63
- data = JSON.parse(text);
64
- } catch {
65
- return null;
66
- }
67
- const actor = data?.actors?.[0];
68
- if (!actor || typeof actor !== 'object' || !actor.components) return null;
69
- const name = typeof data.name === 'string' && data.name.trim() ? data.name : 'Blueprint';
70
- return { name, components: actor.components };
71
- }
72
-
73
53
  // A reference names a file the way its own deck sees it -- `drawings/rock.pxart`
74
54
  // for one of its own, `@imports/<alias>/...` for one of a deck it imports (the
75
55
  // SDK's resolveDeckFile is the single definition of that rule). Templates are
@@ -168,25 +148,6 @@ export function listBlueprints(files) {
168
148
  return out;
169
149
  }
170
150
 
171
- // Per-property merge: the blueprint template is the base, instance overrides
172
- // win per-property within each component (not whole-component replacement). A
173
- // component present on only one side appears whole.
174
- export function mergeComponents(templateComponents, instanceComponents) {
175
- const merged = {};
176
- const names = new Set([
177
- ...Object.keys(templateComponents ?? {}),
178
- ...Object.keys(instanceComponents ?? {}),
179
- ]);
180
- for (const name of names) {
181
- const templateProps = templateComponents?.[name];
182
- const instanceProps = instanceComponents?.[name];
183
- if (templateProps === undefined) merged[name] = { ...instanceProps };
184
- else if (instanceProps === undefined) merged[name] = { ...templateProps };
185
- else merged[name] = { ...templateProps, ...instanceProps };
186
- }
187
- return merged;
188
- }
189
-
190
151
  // The fully resolved components for one actor: its blueprint's template
191
152
  // merged with its own sparse overrides, or its raw components when it carries
192
153
  // no `blueprint` ref (the blueprint's own template actor, or a not-yet
@@ -501,6 +462,18 @@ function topZ(actors, files) {
501
462
  return max === -Infinity ? 0 : max + 1;
502
463
  }
503
464
 
465
+ // The Layout every blueprint the editor mints starts from. Centre origin: the
466
+ // anchor an author reaches for is the middle of the thing ("put it HERE"), and
467
+ // it keeps a resize growing from the centre rather than the top-left corner.
468
+ // The kit's shipped presets use the same centre origin.
469
+ const MINTED_TEMPLATE_LAYOUT = {
470
+ width: 50,
471
+ height: 50,
472
+ z: 0,
473
+ originX: DEFAULT_ORIGIN_X,
474
+ originY: DEFAULT_ORIGIN_Y,
475
+ };
476
+
504
477
  // A freshly minted blueprint's first instance, at the card centre and on top.
505
478
  function appendCenteredInstance(sceneData, files, blueprintFile) {
506
479
  const layout = blueprintFile.components?.Layout ?? {};
@@ -509,8 +482,16 @@ function appendCenteredInstance(sceneData, files, blueprintFile) {
509
482
  const next = structuredClone(sceneData);
510
483
  const existingIds = new Set(next.actors.map((actor) => actor.id));
511
484
  const newId = mintActorIdFromName(existingIds, blueprintFile.name);
512
- const x = Math.round((cardSize.width - width) / 2);
513
- const y = Math.round((cardSize.height - height) / 2);
485
+ // Where the BOX goes, then stated as the x/y the template's origin wants.
486
+ const { x, y } = layoutXYForRect(
487
+ {
488
+ x: Math.round((cardSize.width - width) / 2),
489
+ y: Math.round((cardSize.height - height) / 2),
490
+ width,
491
+ height,
492
+ },
493
+ layout
494
+ );
514
495
  // Guarantee the new actor renders on top of whatever's already there.
515
496
  const z = topZ(next.actors, files);
516
497
  next.actors.push({ id: newId, blueprint: blueprintFile.path, components: { Layout: { x, y, z } } });
@@ -520,7 +501,7 @@ function appendCenteredInstance(sceneData, files, blueprintFile) {
520
501
  export function addActorWithBlueprint(sceneData, files) {
521
502
  const drawingFile = { path: mintDrawingPath(files), text: blankPxArtText() };
522
503
  const components = {
523
- Layout: { width: 50, height: 50, z: 0 },
504
+ Layout: { ...MINTED_TEMPLATE_LAYOUT },
524
505
  Sprite: { file: drawingFile.path },
525
506
  };
526
507
  const minted = mintBlueprintFile(files, components);
@@ -619,7 +600,7 @@ export function createBlueprint(sceneData, files, spec) {
619
600
  const drawingPath =
620
601
  mintPathFromName(existingPaths, name, DRAWINGS_DIR, DRAWING_EXT) ?? mintDrawingPath(files);
621
602
  drawingFile = { path: drawingPath, text: blankPxArtText() };
622
- components = { Layout: { width: 50, height: 50, z: 0 }, Sprite: { file: drawingPath } };
603
+ components = { Layout: { ...MINTED_TEMPLATE_LAYOUT }, Sprite: { file: drawingPath } };
623
604
  }
624
605
  const blueprintFile = { path, name, components, text: formatBlueprintFileText(name, components) };
625
606
  const { sceneData: next, newId } = appendCenteredInstance(sceneData, files, blueprintFile);
@@ -629,6 +610,10 @@ export function createBlueprint(sceneData, files, spec) {
629
610
  // Centered, grid-snapped Layout x/y for a blueprint's template at a
630
611
  // card-space point. Shared by initial drag-in placement and the subsequent
631
612
  // moves while the drag is still in progress, so both snap identically.
613
+ //
614
+ // The BOX is what gets centered and snapped -- the same rect as before the
615
+ // origin existed -- and `layoutXYForRect` then states it as the x/y the
616
+ // template's origin means, so what lands under the cursor doesn't depend on it.
632
617
  export function blueprintDropXY(files, blueprintPath, position, snap) {
633
618
  const template = getBlueprintTemplate(files, blueprintPath);
634
619
  const layout = template?.components?.Layout ?? {};
@@ -636,10 +621,15 @@ export function blueprintDropXY(files, blueprintPath, position, snap) {
636
621
  const height = layout.height ?? 50;
637
622
  const dropX = position?.x ?? cardSize.width / 2;
638
623
  const dropY = position?.y ?? cardSize.height / 2;
639
- return {
640
- x: snapValue(dropX - width / 2, snap),
641
- y: snapValue(dropY - height / 2, snap),
642
- };
624
+ return layoutXYForRect(
625
+ {
626
+ x: snapValue(dropX - width / 2, snap),
627
+ y: snapValue(dropY - height / 2, snap),
628
+ width,
629
+ height,
630
+ },
631
+ layout
632
+ );
643
633
  }
644
634
 
645
635
  // Place a new instance of an existing blueprint at a drop point (card units,
@@ -868,6 +858,73 @@ export function renameBlueprintCascade(files, blueprintPath, nextName) {
868
858
  return { path: nextPath, name, fileRenames, writes };
869
859
  }
870
860
 
861
+ // Change a blueprint's Layout origin without moving anything on screen.
862
+ //
863
+ // The origin is inherited, so rewriting it on the template silently re-anchors
864
+ // every instance that doesn't override it: their stored x/y suddenly names a
865
+ // different point of the box, and they all jump by the fraction that moved.
866
+ // This compensates them -- `x += (nextOx - ox) * width` -- in every scene of
867
+ // this deck, the same shape as `renameBlueprintCascade`. Returns the
868
+ // { path, text } writes for the caller to apply, or null when the blueprint is
869
+ // missing/unparseable.
870
+ //
871
+ // An instance that overrides the origin ITSELF is left alone: its x/y is
872
+ // already anchored to its own value, which this change doesn't touch.
873
+ //
874
+ // Never change the origin of a blueprint another deck imports. The importers'
875
+ // scenes aren't in `files`, so their instances are out of reach here and would
876
+ // shift -- the same hazard as changing an imported blueprint's width, but
877
+ // positional.
878
+ export function setBlueprintOriginCascade(files, blueprintPath, nextOrigin) {
879
+ const template = parseBlueprintText(files?.[blueprintPath]);
880
+ if (!template) return null;
881
+ const layout = template.components?.Layout ?? {};
882
+ const originX = layoutOriginX(layout);
883
+ const originY = layoutOriginY(layout);
884
+ const nextX = nextOrigin?.originX ?? originX;
885
+ const nextY = nextOrigin?.originY ?? originY;
886
+ const components = { ...template.components, Layout: { ...layout, originX: nextX, originY: nextY } };
887
+ const text = setBlueprintTemplateComponents(files, blueprintPath, components);
888
+ if (text == null) return null;
889
+ const writes = [{ path: blueprintPath, text }];
890
+ const dx = nextX - originX;
891
+ const dy = nextY - originY;
892
+ if (dx === 0 && dy === 0) return { writes };
893
+ for (const { path, data } of parseSceneFiles(files)) {
894
+ const shifted = shiftInstancesForOrigin(files, data.actors ?? [], path, blueprintPath, dx, dy);
895
+ if (shifted) writes.push({ path, text: formatJson({ ...data, actors: shifted }) });
896
+ }
897
+ return { writes };
898
+ }
899
+
900
+ // One scene's actor list with every non-overriding instance of `blueprintPath`
901
+ // re-anchored, or null when the scene holds none to move. Merged width/height,
902
+ // because an instance inheriting its size has no `Layout.width` of its own to
903
+ // scale the fraction by.
904
+ function shiftInstancesForOrigin(files, actors, scenePath, blueprintPath, dx, dy) {
905
+ let moved = false;
906
+ const next = actors.map((actor) => {
907
+ if (!actorUsesBlueprint(actor, blueprintPath, scenePath)) return actor;
908
+ const own = actor.components?.Layout ?? {};
909
+ if (own.originX !== undefined || own.originY !== undefined) return actor;
910
+ const merged = resolveActorComponents(files, actor).Layout;
911
+ if (!merged) return actor;
912
+ moved = true;
913
+ return {
914
+ ...actor,
915
+ components: {
916
+ ...actor.components,
917
+ Layout: {
918
+ ...own,
919
+ x: (merged.x ?? 0) + dx * (merged.width ?? 0),
920
+ y: (merged.y ?? 0) + dy * (merged.height ?? 0),
921
+ },
922
+ },
923
+ };
924
+ });
925
+ return moved ? next : null;
926
+ }
927
+
871
928
  // Auto-migrate a scene's orphan actors (no `blueprint` field -- the pre-v1
872
929
  // shape) into blueprint instances: mint one blueprint per orphan (its
873
930
  // authored components split by propertyMeta, same as fork), rewrite the actor
@@ -0,0 +1,59 @@
1
+ // The blueprint facts that need nothing from the browser.
2
+ //
3
+ // `blueprint.js` is the blueprint system and it only runs in a page: it imports
4
+ // the SDK and `./scene`, whose file map comes from `import.meta.glob`. These four
5
+ // pieces need none of that, and the kit's own update migration
6
+ // (`scripts/onUpdate.mjs` via `engine/layoutOriginMigration.js`) reads a deck's
7
+ // files under plain Node. So they live here, with NO imports at all, and
8
+ // `blueprint.js` re-exports them -- there is one definition of what a blueprint
9
+ // path is and how a template merges, whichever side is asking.
10
+ //
11
+ // Same shape as `engine/pxart.js` beside `scripts/draw.mjs`: the format is the
12
+ // kit's, and a Node script of the kit's is entitled to read it.
13
+
14
+ export const BLUEPRINTS_DIR = 'blueprints';
15
+
16
+ // A blueprint of this deck (`blueprints/x.scene`) OR of one it imports
17
+ // (`imports/<alias>/blueprints/x.scene`) -- an imported deck's blueprints are
18
+ // placeable like any other, which is most of the point of importing one.
19
+ const BLUEPRINT_PATH_RE = new RegExp(`^(imports/[^/]+/)?${BLUEPRINTS_DIR}/`);
20
+
21
+ export function isBlueprintPath(path) {
22
+ return typeof path === 'string' && path.endsWith('.scene') && BLUEPRINT_PATH_RE.test(path);
23
+ }
24
+
25
+ // Parse a blueprint file's text into { name, components } (the template
26
+ // actor's components), or null if the text isn't a valid blueprint (used to
27
+ // treat a tombstoned/deleted blueprint file as absent).
28
+ export function parseBlueprintText(text) {
29
+ if (typeof text !== 'string') return null;
30
+ let data;
31
+ try {
32
+ data = JSON.parse(text);
33
+ } catch {
34
+ return null;
35
+ }
36
+ const actor = data?.actors?.[0];
37
+ if (!actor || typeof actor !== 'object' || !actor.components) return null;
38
+ const name = typeof data.name === 'string' && data.name.trim() ? data.name : 'Blueprint';
39
+ return { name, components: actor.components };
40
+ }
41
+
42
+ // Per-property merge: the blueprint template is the base, instance overrides
43
+ // win per-property within each component (not whole-component replacement). A
44
+ // component present on only one side appears whole.
45
+ export function mergeComponents(templateComponents, instanceComponents) {
46
+ const merged = {};
47
+ const names = new Set([
48
+ ...Object.keys(templateComponents ?? {}),
49
+ ...Object.keys(instanceComponents ?? {}),
50
+ ]);
51
+ for (const name of names) {
52
+ const templateProps = templateComponents?.[name];
53
+ const instanceProps = instanceComponents?.[name];
54
+ if (templateProps === undefined) merged[name] = { ...instanceProps };
55
+ else if (instanceProps === undefined) merged[name] = { ...templateProps };
56
+ else merged[name] = { ...templateProps, ...instanceProps };
57
+ }
58
+ return merged;
59
+ }
@@ -14,9 +14,15 @@
14
14
  // side (keeps circles round under non-uniform box scaling). Legacy single-shape
15
15
  // colliders (shape/width/height/radius/offset[/mode]) normalize to one box shape.
16
16
  //
17
+ // The box itself is `layoutRect(layout)` -- Layout's own `originX/originY` decides
18
+ // where `layout.x/y` sits in it (see engine/layout.js), and these fractions are
19
+ // measured from that box's top-left either way. So a shape list is unaffected by
20
+ // an origin change, exactly as it is by a resize.
21
+ //
17
22
  // Shapes are in the UNROTATED box frame; the draw pipeline (scene.js) and the
18
23
  // matter body (matterBridge) apply Layout.rotation, so nothing here rotates.
19
24
  import { artFrameCount, artReady, renderArtFrame } from './art';
25
+ import { layoutRect } from './layout';
20
26
  import { spriteDestRect } from './spriteGeometry';
21
27
 
22
28
  // ---------------------------------------------------------------------------
@@ -75,18 +81,19 @@ export function spriteIsEmpty(sprite) {
75
81
  }
76
82
 
77
83
  // The sprite's opaque-pixel rect in world units through the draw mode, or null.
78
- function autoRect(layout, spriteProps, sprite) {
84
+ // `box` is the actor's Layout box (origin already applied).
85
+ function autoRect(box, spriteProps, sprite) {
79
86
  if (!sprite || spriteProps.mode === 'tile') return null;
80
87
  const bounds = opaqueBoundsFraction(sprite);
81
88
  if (!bounds) return null;
82
- const dest = spriteDestRect(spriteProps.mode, layout, sprite.resolution);
89
+ const dest = spriteDestRect(spriteProps.mode, box, sprite.resolution);
83
90
  const rect = {
84
91
  x: dest.x + bounds.x * dest.width,
85
92
  y: dest.y + bounds.y * dest.height,
86
93
  width: bounds.width * dest.width,
87
94
  height: bounds.height * dest.height,
88
95
  };
89
- if (spriteProps.mode === 'cover') return intersectRect(rect, layout);
96
+ if (spriteProps.mode === 'cover') return intersectRect(rect, box);
90
97
  return rect;
91
98
  }
92
99
 
@@ -129,11 +136,13 @@ function legacyShapeFraction(collider, layout) {
129
136
  }
130
137
 
131
138
  // Resolve one box-fraction shape to world coordinates (unrotated box frame).
132
- function resolveShape(shape, layout) {
133
- const bx = layout.x;
134
- const by = layout.y;
135
- const bw = layout.width;
136
- const bh = layout.height;
139
+ // `box` is the actor's Layout box from `layoutRect` -- the origin is applied
140
+ // there, so everything here is measured from a real top-left.
141
+ function resolveShape(shape, box) {
142
+ const bx = box.x;
143
+ const by = box.y;
144
+ const bw = box.width;
145
+ const bh = box.height;
137
146
  const wx = (fx) => bx + fx * bw;
138
147
  const wy = (fy) => by + fy * bh;
139
148
  if (shape.type === 'circle') {
@@ -157,7 +166,8 @@ export function getColliderShapes(actor) {
157
166
  const layout = actor?.components?.Layout;
158
167
  const collider = actor?.components?.Collider;
159
168
  if (!layout || !collider) return null;
160
- return colliderShapeFractions(collider, layout).map((s) => resolveShape(s, layout));
169
+ const box = layoutRect(layout);
170
+ return colliderShapeFractions(collider, layout).map((s) => resolveShape(s, box));
161
171
  }
162
172
 
163
173
  // Back-compat single-shape accessor (the first shape).
@@ -220,16 +230,17 @@ export function getColliderRect(actor) {
220
230
  // draw mode, or null when there's nothing to fit to. `asCircle` returns a circle
221
231
  // that encloses those bounds. Powers the inspector's "Auto-fit to sprite".
222
232
  export function computeAutoFit(actor, sprites, asCircle = false) {
223
- const rawLayout = actor?.components?.Layout;
224
233
  const spriteProps = actor?.components?.Sprite;
225
- if (!rawLayout || !spriteProps) return null;
226
- const layout = { ...rawLayout, x: rawLayout.x ?? 0, y: rawLayout.y ?? 0 };
227
- const rect = autoRect(layout, spriteProps, sprites?.[spriteProps.file]);
234
+ const box = layoutRect(actor?.components?.Layout);
235
+ if (!box || !spriteProps || !(box.width > 0) || !(box.height > 0)) return null;
236
+ const rect = autoRect(box, spriteProps, sprites?.[spriteProps.file]);
228
237
  if (!rect || rect.width <= 0 || rect.height <= 0) return null;
229
- const x = (rect.x + rect.width / 2 - layout.x) / layout.width;
230
- const y = (rect.y + rect.height / 2 - layout.y) / layout.height;
231
- const w = rect.width / layout.width;
232
- const h = rect.height / layout.height;
238
+ // Back to box fractions -- the inverse of `resolveShape`, so the fit survives
239
+ // a later resize or origin change like any other shape.
240
+ const x = (rect.x + rect.width / 2 - box.x) / box.width;
241
+ const y = (rect.y + rect.height / 2 - box.y) / box.height;
242
+ const w = rect.width / box.width;
243
+ const h = rect.height / box.height;
233
244
  if (asCircle) return { type: 'circle', x, y, r: Math.max(w, h) / 2 };
234
245
  return { type: 'box', x, y, w, h };
235
246
  }
@@ -0,0 +1,61 @@
1
+ // The one place the Layout origin is applied.
2
+ //
3
+ // `Layout.x/y` is not the box's top-left: it is the point of the box named by
4
+ // `originX`/`originY`, stored as FRACTIONS of the box from its own top-left --
5
+ // `0,0` top-left, `0.5,0.5` center, `1,1` bottom-right, not clamped (the same
6
+ // model as Collider shape fractions, so an origin survives a resize and a
7
+ // per-instance size override). Absent means CENTER (`DEFAULT_ORIGIN_*` below) --
8
+ // the same value `Layout.defaultProps` and editor-minted blueprints write.
9
+ //
10
+ // `rotation` is unaffected: it still pivots on the box CENTER. The origin
11
+ // anchors position only.
12
+ //
13
+ // Engine-internal, like `engine/physics/controls.js` -- behaviors import it,
14
+ // deck code goes through `scene.layoutRect(actorOrId)`.
15
+
16
+ // Single source of truth for "no origin written". Every reader goes through
17
+ // `layoutOriginX` / `layoutOriginY` (or these constants) -- never a bare `?? 0`.
18
+ export const DEFAULT_ORIGIN_X = 0.5;
19
+ export const DEFAULT_ORIGIN_Y = 0.5;
20
+
21
+ export function layoutOriginX(layout) {
22
+ return layout?.originX ?? DEFAULT_ORIGIN_X;
23
+ }
24
+
25
+ export function layoutOriginY(layout) {
26
+ return layout?.originY ?? DEFAULT_ORIGIN_Y;
27
+ }
28
+
29
+ // The unrotated axis-aligned box an actor occupies, or null with no Layout.
30
+ export function layoutRect(layout) {
31
+ if (!layout) return null;
32
+ const width = layout.width ?? 0;
33
+ const height = layout.height ?? 0;
34
+ return {
35
+ x: (layout.x ?? 0) - layoutOriginX(layout) * width,
36
+ y: (layout.y ?? 0) - layoutOriginY(layout) * height,
37
+ width,
38
+ height,
39
+ };
40
+ }
41
+
42
+ // Center of the Layout box -- the rotation pivot, and where a matter body and
43
+ // the joint overlay anchor.
44
+ export function layoutCenter(layout) {
45
+ const rect = layoutRect(layout);
46
+ if (!rect) return null;
47
+ return { x: rect.x + rect.width / 2, y: rect.y + rect.height / 2 };
48
+ }
49
+
50
+ // Inverse of `layoutRect`: the `x`/`y` to store so the box's top-left lands at
51
+ // `rect.x`/`rect.y` under this origin. `rect`'s own size wins when it has one,
52
+ // so a gesture that resizes and repositions in one step (scale handles) can
53
+ // hand over the whole next rect.
54
+ export function layoutXYForRect(rect, layout) {
55
+ const width = rect?.width ?? layout?.width ?? 0;
56
+ const height = rect?.height ?? layout?.height ?? 0;
57
+ return {
58
+ x: (rect?.x ?? 0) + layoutOriginX(layout) * width,
59
+ y: (rect?.y ?? 0) + layoutOriginY(layout) * height,
60
+ };
61
+ }