@umicat/three-sdk 1.1.0 → 1.3.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,122 @@ 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
|
+
// Selection (Phase 4) — a single id, same "one thing selected at a time"
|
|
90
|
+
// model world mode's marker/selectionBox/gizmo already use. No gizmo for
|
|
91
|
+
// HUD widgets (there's nothing to move in 3D — repositioning is an anchor/
|
|
92
|
+
// offset EDIT, done through the Inspector's AnchorSection, not a drag);
|
|
93
|
+
// selection here only needs a visual outline + telling the host what's
|
|
94
|
+
// selected so the Inspector has something to show.
|
|
95
|
+
let hudSelectedId = null;
|
|
96
|
+
function ensureHudBackdrop() {
|
|
97
|
+
if (hudBackdrop)
|
|
98
|
+
return hudBackdrop;
|
|
99
|
+
// Created AFTER hideNonCanvasStaticMarkup already ran once at the top of
|
|
100
|
+
// this function — that function only hides EXISTING document.body
|
|
101
|
+
// children at the moment it's called, so anything appended after is
|
|
102
|
+
// simply never touched by it. No data-umicat-keep needed here either.
|
|
103
|
+
const el = document.createElement('div');
|
|
104
|
+
el.id = 'umicat-hud3d-editor-backdrop';
|
|
105
|
+
// z-index 15: above the canvas (no explicit stacking, renders at the
|
|
106
|
+
// normal in-flow level) but below `#hud` (z-index:20 in every template,
|
|
107
|
+
// see umicat-template/index.html) — the real HUD widgets, mounted into
|
|
108
|
+
// `#hud`, sit on TOP of this backdrop, not behind it.
|
|
109
|
+
el.style.cssText = 'position:fixed;inset:0;z-index:15;background:#2a2d32;display:none;';
|
|
110
|
+
document.body.appendChild(el);
|
|
111
|
+
hudBackdrop = el;
|
|
112
|
+
return el;
|
|
113
|
+
}
|
|
114
|
+
const HUD_OUTLINE = '2px solid #ffd23f'; // same selection-yellow world mode's BoxHelper uses
|
|
115
|
+
/** Select (or clear, for `null`) a HUD entity — outline + ack to the host.
|
|
116
|
+
* Re-looked-up by id on every call rather than holding an element
|
|
117
|
+
* reference, since `patchEntity` REPLACES the node on every field change
|
|
118
|
+
* (full respawn — see `spawnHud3DEntity.ts`'s own doc comment) and a held
|
|
119
|
+
* reference would go stale the moment anything about the selected widget
|
|
120
|
+
* changes. */
|
|
121
|
+
function selectHudEntity(entityId) {
|
|
122
|
+
if (hudSelectedId) {
|
|
123
|
+
const prev = document.getElementById(`umicat-hud3d-${hudSelectedId}`);
|
|
124
|
+
if (prev)
|
|
125
|
+
prev.style.outline = '';
|
|
126
|
+
}
|
|
127
|
+
hudSelectedId = entityId;
|
|
128
|
+
if (entityId) {
|
|
129
|
+
const el = document.getElementById(`umicat-hud3d-${entityId}`);
|
|
130
|
+
if (el)
|
|
131
|
+
el.style.outline = HUD_OUTLINE;
|
|
132
|
+
}
|
|
133
|
+
window.parent.postMessage({ type: 'umicat:editor:pickHud3dEntity', entityId }, '*');
|
|
134
|
+
}
|
|
135
|
+
/**
|
|
136
|
+
* Makes every spawned widget clickable + selectable in the EDITOR, on top
|
|
137
|
+
* of whatever `pointer-events` the widget's own Play-mode default is
|
|
138
|
+
* (`spawnHud3DEntity.ts` defaults most kinds to `none` — correct for a
|
|
139
|
+
* static label the PLAYER should click through, wrong for the EDITOR,
|
|
140
|
+
* where every widget needs to be selectable regardless of kind). One
|
|
141
|
+
* capture-phase click listener on the mount root, not a listener per
|
|
142
|
+
* widget — works for widgets created later by `createHud3dEntity` too,
|
|
143
|
+
* with no extra wiring, and re-asserts the pointer-events override after
|
|
144
|
+
* every (fully-respawning) patch for the same reason `selectHudEntity`
|
|
145
|
+
* re-looks-up its element rather than holding a reference.
|
|
146
|
+
*/
|
|
147
|
+
function wireHudEditorInteractivity(handle) {
|
|
148
|
+
for (const el of Array.from(handle.root.children)) {
|
|
149
|
+
if (el instanceof HTMLElement)
|
|
150
|
+
el.style.pointerEvents = 'auto';
|
|
151
|
+
}
|
|
152
|
+
handle.root.addEventListener('click', (e) => {
|
|
153
|
+
const target = e.target?.closest('[data-hud3d-entity-id]');
|
|
154
|
+
selectHudEntity(target?.dataset.hud3dEntityId ?? null);
|
|
155
|
+
});
|
|
156
|
+
}
|
|
157
|
+
function mountHud(hudScene) {
|
|
158
|
+
hudHandle?.destroy();
|
|
159
|
+
hudSelectedId = null;
|
|
160
|
+
hudHandle = hudScene ? loadHud3DScene(hudScene) : null;
|
|
161
|
+
if (hudHandle)
|
|
162
|
+
wireHudEditorInteractivity(hudHandle);
|
|
163
|
+
}
|
|
164
|
+
function enterHudMode(hudScene) {
|
|
165
|
+
hudMode = 'hud';
|
|
166
|
+
ensureHudBackdrop().style.display = 'block';
|
|
167
|
+
const hudEl = document.getElementById('hud');
|
|
168
|
+
if (hudEl)
|
|
169
|
+
hudEl.style.display = '';
|
|
170
|
+
mountHud(hudScene);
|
|
171
|
+
}
|
|
172
|
+
function exitHudMode() {
|
|
173
|
+
hudMode = 'world';
|
|
174
|
+
if (hudBackdrop)
|
|
175
|
+
hudBackdrop.style.display = 'none';
|
|
176
|
+
const hudEl = document.getElementById('hud');
|
|
177
|
+
if (hudEl)
|
|
178
|
+
hudEl.style.display = 'none';
|
|
179
|
+
hudHandle?.destroy();
|
|
180
|
+
hudHandle = null;
|
|
181
|
+
hudSelectedId = null;
|
|
182
|
+
}
|
|
58
183
|
const camera = new THREE.PerspectiveCamera(50, window.innerWidth / window.innerHeight, 0.05, 2000);
|
|
59
184
|
const controls = new OrbitControls(camera, renderer.domElement);
|
|
60
185
|
controls.enableDamping = true;
|
|
@@ -519,6 +644,70 @@ export async function runEditorDesignPlayer3D(renderer, opts = {}) {
|
|
|
519
644
|
}
|
|
520
645
|
return;
|
|
521
646
|
}
|
|
647
|
+
// World/HUD toggle (HUD editing Phase 2) — see the "HUD sub-mode" block
|
|
648
|
+
// above this function's camera setup for why this needs no camera/scene
|
|
649
|
+
// work at all, unlike every other message here.
|
|
650
|
+
if (data.type === 'umicat:editor:setEditMode3d') {
|
|
651
|
+
const mode = data.mode;
|
|
652
|
+
if (mode === 'hud')
|
|
653
|
+
enterHudMode(null);
|
|
654
|
+
else if (mode === 'world')
|
|
655
|
+
exitHudMode();
|
|
656
|
+
return;
|
|
657
|
+
}
|
|
658
|
+
// The host already fetched + parsed the HUD file (it owns the binding
|
|
659
|
+
// lookup and the workspace-file read, same division of labor as 2D's
|
|
660
|
+
// `EditorLoadHudMessage`) — this just (re)mounts it. Used both for the
|
|
661
|
+
// FIRST mount (host sends this once it has the bound HUD ready, shortly
|
|
662
|
+
// after `setEditMode3d{mode:'hud'}`) and for "switch which HUD is being
|
|
663
|
+
// edited" (HUD browser, Phase 3) without a mode change.
|
|
664
|
+
if (data.type === 'umicat:editor:loadHud3d') {
|
|
665
|
+
const m = data;
|
|
666
|
+
const hudFile = (typeof m.hudId === 'string' ? m.hudFile : undefined);
|
|
667
|
+
if (hudMode !== 'hud')
|
|
668
|
+
enterHudMode(hudFile ?? null);
|
|
669
|
+
else
|
|
670
|
+
mountHud(hudFile ?? null);
|
|
671
|
+
window.parent.postMessage({ type: 'umicat:editor:hud3dLoaded', hudId: typeof m.hudId === 'string' ? m.hudId : null, error: !hudFile }, '*');
|
|
672
|
+
return;
|
|
673
|
+
}
|
|
674
|
+
// HUD editing Phase 4 — drag-to-place + Inspector live patch. The host
|
|
675
|
+
// builds the full entity (anchor computed from the drop's pixel
|
|
676
|
+
// position — pure 2D math it can do itself, unlike a world-space drop,
|
|
677
|
+
// which needs THIS player's camera/raycast) and sends it whole; this
|
|
678
|
+
// only spawns it. `createHud3dEntity` is deliberately NOT patched
|
|
679
|
+
// through `patchHud3dEntity` as "patch an entity that doesn't exist
|
|
680
|
+
// yet" — creation and property-edit are different operations with
|
|
681
|
+
// different failure modes (a create can fail because the id collides;
|
|
682
|
+
// a patch fails because the entity is gone).
|
|
683
|
+
if (data.type === 'umicat:editor:createHud3dEntity') {
|
|
684
|
+
const m = data;
|
|
685
|
+
const entity = m.entity;
|
|
686
|
+
const ok = !!entity?.id && !!hudHandle && !hudHandle.entities.has(entity.id);
|
|
687
|
+
if (ok && entity && hudHandle) {
|
|
688
|
+
hudHandle.spawnEntity(entity);
|
|
689
|
+
wireHudEditorInteractivity(hudHandle); // the new node needs the editor pointer-events override too
|
|
690
|
+
}
|
|
691
|
+
window.parent.postMessage({ type: 'umicat:editor:hud3dEntityCreated', entity, ok, error: ok ? undefined : 'no scene loaded, or an entity with this id already exists' }, '*');
|
|
692
|
+
return;
|
|
693
|
+
}
|
|
694
|
+
if (data.type === 'umicat:editor:patchHud3dEntity') {
|
|
695
|
+
const m = data;
|
|
696
|
+
const entityId = typeof m.entityId === 'string' ? m.entityId : null;
|
|
697
|
+
const ok = !!entityId && !!hudHandle && hudHandle.entities.has(entityId);
|
|
698
|
+
if (ok && entityId && hudHandle) {
|
|
699
|
+
hudHandle.patchEntity(entityId, (m.patch ?? {}));
|
|
700
|
+
wireHudEditorInteractivity(hudHandle); // patch respawns the node — redo the override
|
|
701
|
+
if (hudSelectedId === entityId) {
|
|
702
|
+
// The outline was lost with the old node too — same respawn.
|
|
703
|
+
const el = document.getElementById(`umicat-hud3d-${entityId}`);
|
|
704
|
+
if (el)
|
|
705
|
+
el.style.outline = HUD_OUTLINE;
|
|
706
|
+
}
|
|
707
|
+
}
|
|
708
|
+
window.parent.postMessage({ type: 'umicat:editor:patchAppliedHud3d', entityId, ok, error: ok ? undefined : 'no entity with this id in the HUD being edited' }, '*');
|
|
709
|
+
return;
|
|
710
|
+
}
|
|
522
711
|
}
|
|
523
712
|
/**
|
|
524
713
|
* `patch` is an open bag deliberately: skin was the first field, and each
|
|
@@ -63,7 +63,14 @@ export function loadHud3DScene(hudScene, opts) {
|
|
|
63
63
|
nodes.delete(entityId);
|
|
64
64
|
return;
|
|
65
65
|
}
|
|
66
|
-
patchHud3DEntityDom
|
|
66
|
+
// patchHud3DEntityDom REPLACES the node (full respawn — see its own doc
|
|
67
|
+
// comment on why), so `nodes` must be re-pointed at the fresh element or
|
|
68
|
+
// the NEXT patch would operate on a now-detached, stale node — confirmed
|
|
69
|
+
// live-bug-worthy by reading `.replaceWith`'s semantics: it swaps the OLD
|
|
70
|
+
// node out of the live DOM, it does not retroactively fix up anyone
|
|
71
|
+
// still holding a reference to that old node.
|
|
72
|
+
const fresh = patchHud3DEntityDom(el, next, safeArea, { resolveText: resolveHudText3D, resolveNumber: resolveHudNumber3D });
|
|
73
|
+
nodes.set(entityId, fresh);
|
|
67
74
|
}
|
|
68
75
|
for (const entity of hudScene.entities ?? [])
|
|
69
76
|
spawnEntity(entity);
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@umicat/three-sdk",
|
|
3
|
-
"version": "1.
|
|
3
|
+
"version": "1.3.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",
|