@umicat/three-sdk 1.1.0 → 1.2.0

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.
@@ -48,6 +48,14 @@ export interface EditorDesignPlayer3DOptions {
48
48
  * THIS iframe rather than the host page — posts `requestUndo3d` asking
49
49
  * the host to do its thing. No entity-creation/deletion undo yet (only
50
50
  * transform edits on an entity that already exists).
51
+ * - **HUD sub-mode** (Phase 2, 2026-10-06, read-only) — `setEditMode3d
52
+ * {mode:'hud'}` covers the canvas with a neutral backdrop and mounts the
53
+ * bound HUD's widgets (same pure-DOM `loadHud3DScene` Play mode uses, via
54
+ * `loadHud3d{hudId,hudFile}` — the host fetches/parses the file, this only
55
+ * mounts it) into `#hud`, which `hideNonCanvasStaticMarkup` below hid at
56
+ * boot like every other hand-authored markup. No drag/patch/select yet —
57
+ * that's a later phase; this one proves World↔HUD actually switches and
58
+ * renders correctly.
51
59
  *
52
60
  * Takes over `renderer`'s animation loop entirely for the rest of the page's
53
61
  * life — there is no scene-swap API and no teardown, matching how the
@@ -6,6 +6,7 @@ import { applyAttachments } from '../Attachments.js';
6
6
  import { singleModelManifest } from '../scene3d.js';
7
7
  import { TransformGizmo3D } from './TransformGizmo3D.js';
8
8
  import { closestPointOnLineToRay, raycastPlane, angleAroundAxis } from './gizmoMath.js';
9
+ import { loadHud3DScene } from '../hud3d/HudRuntime3D.js';
9
10
  /**
10
11
  * The 3D counterpart of `@umicat/phaser-sdk`'s `EditorDesignScene` (ADR-021)
11
12
  * — renders a scene's AUTHORED data with no game code and no save, so the
@@ -42,6 +43,14 @@ import { closestPointOnLineToRay, raycastPlane, angleAroundAxis } from './gizmoM
42
43
  * THIS iframe rather than the host page — posts `requestUndo3d` asking
43
44
  * the host to do its thing. No entity-creation/deletion undo yet (only
44
45
  * transform edits on an entity that already exists).
46
+ * - **HUD sub-mode** (Phase 2, 2026-10-06, read-only) — `setEditMode3d
47
+ * {mode:'hud'}` covers the canvas with a neutral backdrop and mounts the
48
+ * bound HUD's widgets (same pure-DOM `loadHud3DScene` Play mode uses, via
49
+ * `loadHud3d{hudId,hudFile}` — the host fetches/parses the file, this only
50
+ * mounts it) into `#hud`, which `hideNonCanvasStaticMarkup` below hid at
51
+ * boot like every other hand-authored markup. No drag/patch/select yet —
52
+ * that's a later phase; this one proves World↔HUD actually switches and
53
+ * renders correctly.
45
54
  *
46
55
  * Takes over `renderer`'s animation loop entirely for the rest of the page's
47
56
  * life — there is no scene-swap API and no teardown, matching how the
@@ -55,6 +64,65 @@ import { closestPointOnLineToRay, raycastPlane, angleAroundAxis } from './gizmoM
55
64
  */
56
65
  export async function runEditorDesignPlayer3D(renderer, opts = {}) {
57
66
  hideNonCanvasStaticMarkup(renderer.domElement);
67
+ // ---- HUD sub-mode (2026-10-06, HUD editing Phase 2) -----------------------
68
+ //
69
+ // World↔HUD is a separate axis from this whole function's own existence —
70
+ // unlike 2D's design player, which is ONE thing (world OR HUD, chosen at
71
+ // iframe construction via which Scene gets launched), this player already
72
+ // owns the renderer loop permanently (ADR-021, no teardown), so HUD mode is
73
+ // a STATE inside it, not a new entry point. Switching needs no camera/scene
74
+ // coordination at all — categorically simpler than world-mode editing —
75
+ // because a HUD widget is pure DOM (see `hud3d/HudRuntime3D.ts`): HUD mode
76
+ // is just "cover the canvas with a neutral backdrop and mount the same
77
+ // DOM tree Play mode would show."
78
+ //
79
+ // `#hud` itself was just hidden by `hideNonCanvasStaticMarkup` above (it is
80
+ // an existing `index.html` child with no `data-umicat-keep`, same as every
81
+ // other hand-authored markup in Edit mode) — that hide is UNDONE here only
82
+ // while HUD sub-mode is active, not by tagging `#hud` `data-umicat-keep` at
83
+ // the top (which would make it visible in WORLD mode too, where nothing
84
+ // mounts into it and it would just sit there empty — harmless, but this is
85
+ // more precise: visible exactly when something is actually shown in it).
86
+ let hudMode = 'world';
87
+ let hudHandle = null;
88
+ let hudBackdrop = null;
89
+ function ensureHudBackdrop() {
90
+ if (hudBackdrop)
91
+ return hudBackdrop;
92
+ // Created AFTER hideNonCanvasStaticMarkup already ran once at the top of
93
+ // this function — that function only hides EXISTING document.body
94
+ // children at the moment it's called, so anything appended after is
95
+ // simply never touched by it. No data-umicat-keep needed here either.
96
+ const el = document.createElement('div');
97
+ el.id = 'umicat-hud3d-editor-backdrop';
98
+ // z-index 15: above the canvas (no explicit stacking, renders at the
99
+ // normal in-flow level) but below `#hud` (z-index:20 in every template,
100
+ // see umicat-template/index.html) — the real HUD widgets, mounted into
101
+ // `#hud`, sit on TOP of this backdrop, not behind it.
102
+ el.style.cssText = 'position:fixed;inset:0;z-index:15;background:#2a2d32;display:none;';
103
+ document.body.appendChild(el);
104
+ hudBackdrop = el;
105
+ return el;
106
+ }
107
+ function enterHudMode(hudScene) {
108
+ hudMode = 'hud';
109
+ ensureHudBackdrop().style.display = 'block';
110
+ const hudEl = document.getElementById('hud');
111
+ if (hudEl)
112
+ hudEl.style.display = '';
113
+ hudHandle?.destroy();
114
+ hudHandle = hudScene ? loadHud3DScene(hudScene) : null;
115
+ }
116
+ function exitHudMode() {
117
+ hudMode = 'world';
118
+ if (hudBackdrop)
119
+ hudBackdrop.style.display = 'none';
120
+ const hudEl = document.getElementById('hud');
121
+ if (hudEl)
122
+ hudEl.style.display = 'none';
123
+ hudHandle?.destroy();
124
+ hudHandle = null;
125
+ }
58
126
  const camera = new THREE.PerspectiveCamera(50, window.innerWidth / window.innerHeight, 0.05, 2000);
59
127
  const controls = new OrbitControls(camera, renderer.domElement);
60
128
  controls.enableDamping = true;
@@ -519,6 +587,35 @@ export async function runEditorDesignPlayer3D(renderer, opts = {}) {
519
587
  }
520
588
  return;
521
589
  }
590
+ // World/HUD toggle (HUD editing Phase 2) — see the "HUD sub-mode" block
591
+ // above this function's camera setup for why this needs no camera/scene
592
+ // work at all, unlike every other message here.
593
+ if (data.type === 'umicat:editor:setEditMode3d') {
594
+ const mode = data.mode;
595
+ if (mode === 'hud')
596
+ enterHudMode(null);
597
+ else if (mode === 'world')
598
+ exitHudMode();
599
+ return;
600
+ }
601
+ // The host already fetched + parsed the HUD file (it owns the binding
602
+ // lookup and the workspace-file read, same division of labor as 2D's
603
+ // `EditorLoadHudMessage`) — this just (re)mounts it. Used both for the
604
+ // FIRST mount (host sends this once it has the bound HUD ready, shortly
605
+ // after `setEditMode3d{mode:'hud'}`) and for "switch which HUD is being
606
+ // edited" (HUD browser, Phase 3) without a mode change.
607
+ if (data.type === 'umicat:editor:loadHud3d') {
608
+ const m = data;
609
+ const hudFile = (typeof m.hudId === 'string' ? m.hudFile : undefined);
610
+ if (hudMode !== 'hud')
611
+ enterHudMode(hudFile ?? null);
612
+ else {
613
+ hudHandle?.destroy();
614
+ hudHandle = hudFile ? loadHud3DScene(hudFile) : null;
615
+ }
616
+ window.parent.postMessage({ type: 'umicat:editor:hud3dLoaded', hudId: typeof m.hudId === 'string' ? m.hudId : null, error: !hudFile }, '*');
617
+ return;
618
+ }
522
619
  }
523
620
  /**
524
621
  * `patch` is an open bag deliberately: skin was the first field, and each
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@umicat/three-sdk",
3
- "version": "1.1.0",
3
+ "version": "1.2.0",
4
4
  "description": "Three.js runtime for Umicat games: the scene3d design format, its loader with physics, a kinematic character controller, and the Umicat platform via @umicat/platform-sdk.",
5
5
  "type": "module",
6
6
  "main": "dist/index.js",