@umicat/three-sdk 0.23.0 → 1.0.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.
package/README.md
CHANGED
|
@@ -24,7 +24,10 @@ raycasts the drop point against the ground plane and fetches the GLB straight
|
|
|
24
24
|
from its CDN url, no manifest entry required — and a full Roblox/Unity-style
|
|
25
25
|
3-axis **Move/Rotate/Scale gizmo** on the selected entity, mode switched via
|
|
26
26
|
`umicat:editor:setGizmoMode3d`, posting `dragEnd3d`/`rotateEnd3d`/`scaleEnd3d`
|
|
27
|
-
on release
|
|
27
|
+
on release — plus **Delete** (`umicat:editor:deleteEntity3d`) and
|
|
28
|
+
**transform-only undo** (Ctrl/Cmd+Z; the undo stack itself lives on the
|
|
29
|
+
host, this player only replays a `patchEntity3d` restore)). What it still
|
|
30
|
+
does not have: undo of entity creation/deletion, multi-select, or a local/
|
|
28
31
|
global axis toggle (the gizmo is local-space only).
|
|
29
32
|
|
|
30
33
|
> This paragraph said "seed, not a product — no input system, no character
|
|
@@ -35,6 +35,19 @@ export interface EditorDesignPlayer3DOptions {
|
|
|
35
35
|
* anything — it only moves/rotates/scales the live `THREE.Object3D` and
|
|
36
36
|
* posts the final LOCAL transform on release (`dragEnd3d` / `rotateEnd3d`
|
|
37
37
|
* / `scaleEnd3d`); the host owns turning that into a disk write.
|
|
38
|
+
* - **Delete** (0.24.0) — select an entity, press Delete, it's gone from
|
|
39
|
+
* the live scene immediately (`umicat:editor:deleteEntity3d` in /
|
|
40
|
+
* `entityDeleted3d` out — same ack shape as everything else here). The
|
|
41
|
+
* host owns removing it from disk once it sees `ok:true`.
|
|
42
|
+
* - **Undo** (0.24.0, transform-only) — Ctrl/Cmd+Z restores an entity's
|
|
43
|
+
* PRIOR position/rotation/scale. The undo stack itself lives on the host
|
|
44
|
+
* (see `umicat-home-ui`'s `useScene3DDesignView` CLAUDE.md note) — this
|
|
45
|
+
* player only ever receives an ordinary `patchEntity3d` with the restored
|
|
46
|
+
* value (its `patch` bag grew `position`/`rotation`/`scale` fields for
|
|
47
|
+
* exactly this), or — when the keypress happens while focus is inside
|
|
48
|
+
* THIS iframe rather than the host page — posts `requestUndo3d` asking
|
|
49
|
+
* the host to do its thing. No entity-creation/deletion undo yet (only
|
|
50
|
+
* transform edits on an entity that already exists).
|
|
38
51
|
*
|
|
39
52
|
* Takes over `renderer`'s animation loop entirely for the rest of the page's
|
|
40
53
|
* life — there is no scene-swap API and no teardown, matching how the
|
|
@@ -29,6 +29,19 @@ import { closestPointOnLineToRay, raycastPlane, angleAroundAxis } from './gizmoM
|
|
|
29
29
|
* anything — it only moves/rotates/scales the live `THREE.Object3D` and
|
|
30
30
|
* posts the final LOCAL transform on release (`dragEnd3d` / `rotateEnd3d`
|
|
31
31
|
* / `scaleEnd3d`); the host owns turning that into a disk write.
|
|
32
|
+
* - **Delete** (0.24.0) — select an entity, press Delete, it's gone from
|
|
33
|
+
* the live scene immediately (`umicat:editor:deleteEntity3d` in /
|
|
34
|
+
* `entityDeleted3d` out — same ack shape as everything else here). The
|
|
35
|
+
* host owns removing it from disk once it sees `ok:true`.
|
|
36
|
+
* - **Undo** (0.24.0, transform-only) — Ctrl/Cmd+Z restores an entity's
|
|
37
|
+
* PRIOR position/rotation/scale. The undo stack itself lives on the host
|
|
38
|
+
* (see `umicat-home-ui`'s `useScene3DDesignView` CLAUDE.md note) — this
|
|
39
|
+
* player only ever receives an ordinary `patchEntity3d` with the restored
|
|
40
|
+
* value (its `patch` bag grew `position`/`rotation`/`scale` fields for
|
|
41
|
+
* exactly this), or — when the keypress happens while focus is inside
|
|
42
|
+
* THIS iframe rather than the host page — posts `requestUndo3d` asking
|
|
43
|
+
* the host to do its thing. No entity-creation/deletion undo yet (only
|
|
44
|
+
* transform edits on an entity that already exists).
|
|
32
45
|
*
|
|
33
46
|
* Takes over `renderer`'s animation loop entirely for the rest of the page's
|
|
34
47
|
* life — there is no scene-swap API and no teardown, matching how the
|
|
@@ -173,6 +186,22 @@ export async function runEditorDesignPlayer3D(renderer, opts = {}) {
|
|
|
173
186
|
// dropped model's `importScale` means that's almost never true).
|
|
174
187
|
globalThis.__umicatGizmoAttachedScale =
|
|
175
188
|
() => gizmo.attached ? { x: gizmo.attached.scale.x, y: gizmo.attached.scale.y, z: gizmo.attached.scale.z } : null;
|
|
189
|
+
// Test-only — an arbitrary entity's current LOCAL transform, by id (not
|
|
190
|
+
// just the attached/selected one) — lets a test verify a `patchEntity3d`
|
|
191
|
+
// position/rotation/scale override actually reached the live object,
|
|
192
|
+
// and that a deleted entity is genuinely gone from `objectByEntity`
|
|
193
|
+
// rather than just visually hidden.
|
|
194
|
+
globalThis.__umicatEntityTransform =
|
|
195
|
+
(entityId) => {
|
|
196
|
+
const o = objectByEntity.get(entityId);
|
|
197
|
+
if (!o)
|
|
198
|
+
return null;
|
|
199
|
+
return {
|
|
200
|
+
position: { x: o.position.x, y: o.position.y, z: o.position.z },
|
|
201
|
+
rotation: [o.quaternion.x, o.quaternion.y, o.quaternion.z, o.quaternion.w],
|
|
202
|
+
scale: { x: o.scale.x, y: o.scale.y, z: o.scale.z },
|
|
203
|
+
};
|
|
204
|
+
};
|
|
176
205
|
// Only VISIBLE entity roots are ever raycast against. three.js's
|
|
177
206
|
// Mesh.raycast does NOT check `.visible` on its own (confirmed against the
|
|
178
207
|
// pinned three source — no such check in Raycaster.js or Object3D.raycast),
|
|
@@ -480,6 +509,8 @@ export async function runEditorDesignPlayer3D(renderer, opts = {}) {
|
|
|
480
509
|
return onPatchEntity3d(data);
|
|
481
510
|
if (data.type === 'umicat:editor:dropModel3d')
|
|
482
511
|
return onDropModel3d(data);
|
|
512
|
+
if (data.type === 'umicat:editor:deleteEntity3d')
|
|
513
|
+
return onDeleteEntity3d(data);
|
|
483
514
|
if (data.type === 'umicat:editor:setGizmoMode3d') {
|
|
484
515
|
const mode = data.mode;
|
|
485
516
|
if (mode === 'move' || mode === 'rotate' || mode === 'scale') {
|
|
@@ -490,8 +521,9 @@ export async function runEditorDesignPlayer3D(renderer, opts = {}) {
|
|
|
490
521
|
}
|
|
491
522
|
}
|
|
492
523
|
/**
|
|
493
|
-
* `patch` is an open bag deliberately: skin
|
|
494
|
-
* rotation/scale
|
|
524
|
+
* `patch` is an open bag deliberately: skin was the first field, and each
|
|
525
|
+
* one after it (attachments, now position/rotation/scale) is a new `if`,
|
|
526
|
+
* not a new message.
|
|
495
527
|
*/
|
|
496
528
|
async function onPatchEntity3d(m) {
|
|
497
529
|
const done = (error) => {
|
|
@@ -502,6 +534,22 @@ export async function runEditorDesignPlayer3D(renderer, opts = {}) {
|
|
|
502
534
|
const object = objectByEntity.get(m.entityId);
|
|
503
535
|
if (!object)
|
|
504
536
|
return done(`no entity '${m.entityId}' in the scene being shown`);
|
|
537
|
+
if (m.patch?.position !== undefined) {
|
|
538
|
+
object.position.set(m.patch.position.x, m.patch.position.y, m.patch.position.z);
|
|
539
|
+
}
|
|
540
|
+
if (m.patch?.rotation !== undefined) {
|
|
541
|
+
const [rx, ry, rz, rw] = m.patch.rotation;
|
|
542
|
+
object.quaternion.set(rx, ry, rz, rw);
|
|
543
|
+
}
|
|
544
|
+
if (m.patch?.scale !== undefined) {
|
|
545
|
+
object.scale.set(m.patch.scale.x, m.patch.scale.y, m.patch.scale.z);
|
|
546
|
+
}
|
|
547
|
+
if ((m.patch?.position || m.patch?.rotation || m.patch?.scale) && gizmo.attached === object) {
|
|
548
|
+
// The gizmo itself re-syncs every frame via the render loop's
|
|
549
|
+
// `gizmo.update(camera)` call — only the selection box needs an
|
|
550
|
+
// explicit refresh here, same as a live drag already does.
|
|
551
|
+
selectionBox.setFromObject(object);
|
|
552
|
+
}
|
|
505
553
|
if (m.patch?.attachments !== undefined) {
|
|
506
554
|
const authored = sceneData?.entities.find((e) => e.id === m.entityId);
|
|
507
555
|
const asset = manifest?.models?.find((x) => x.id === authored?.modelAssetId);
|
|
@@ -592,7 +640,123 @@ export async function runEditorDesignPlayer3D(renderer, opts = {}) {
|
|
|
592
640
|
manifest?.models?.push(modelAsset);
|
|
593
641
|
done(undefined, { x: object.position.x, y: object.position.y, z: object.position.z });
|
|
594
642
|
}
|
|
643
|
+
/**
|
|
644
|
+
* Frees a subtree's GPU resources the same way the whole-scene `dispose()`
|
|
645
|
+
* in `SceneLoader3D.ts` does (geometry + material + every texture field a
|
|
646
|
+
* material holds, deduped against double-freeing a texture two materials
|
|
647
|
+
* share) — just scoped to one entity instead of the whole scene, since
|
|
648
|
+
* removing ONE entity must not touch anything a sibling is still using.
|
|
649
|
+
*/
|
|
650
|
+
function disposeObjectTree(root) {
|
|
651
|
+
const disposedTextures = new Set();
|
|
652
|
+
const disposeMaterial = (mat) => {
|
|
653
|
+
for (const value of Object.values(mat)) {
|
|
654
|
+
if (value instanceof THREE.Texture && !disposedTextures.has(value)) {
|
|
655
|
+
disposedTextures.add(value);
|
|
656
|
+
value.dispose();
|
|
657
|
+
}
|
|
658
|
+
}
|
|
659
|
+
mat.dispose();
|
|
660
|
+
};
|
|
661
|
+
root.traverse((o) => {
|
|
662
|
+
const mesh = o;
|
|
663
|
+
if (mesh.geometry)
|
|
664
|
+
mesh.geometry.dispose();
|
|
665
|
+
const mat = mesh.material;
|
|
666
|
+
if (Array.isArray(mat))
|
|
667
|
+
mat.forEach(disposeMaterial);
|
|
668
|
+
else if (mat)
|
|
669
|
+
disposeMaterial(mat);
|
|
670
|
+
});
|
|
671
|
+
}
|
|
672
|
+
/**
|
|
673
|
+
* Removes an entity from the live scene AND this session's own closure
|
|
674
|
+
* state — the exact reverse of `onDropModel3d`'s registration step, so an
|
|
675
|
+
* entity that was dropped and then deleted in the same session leaves
|
|
676
|
+
* nothing dangling behind it (not in `entityByObject`/`objectByEntity`,
|
|
677
|
+
* not in `sceneData.entities`, not selected/gizmo'd/mid-drag). Returns an
|
|
678
|
+
* error string on failure, undefined on success — same convention as
|
|
679
|
+
* `onPatchEntity3d`'s inner checks, just returned instead of routed
|
|
680
|
+
* through a `done()` closure, since this is also called directly from the
|
|
681
|
+
* in-iframe Delete-key handler below (no message/ack involved there).
|
|
682
|
+
*
|
|
683
|
+
* Deliberately does NOT touch `manifest.models` — the model ASSET
|
|
684
|
+
* definition is not necessarily entity-specific (an authored scene
|
|
685
|
+
* routinely has several entities sharing one model), so there is no safe
|
|
686
|
+
* way to tell from here whether deleting this placement should also
|
|
687
|
+
* delete the asset entry. An unreferenced manifest entry left behind is
|
|
688
|
+
* harmless — same as any other unused asset reference.
|
|
689
|
+
*/
|
|
690
|
+
function deleteEntityLive(entityId) {
|
|
691
|
+
const object = objectByEntity.get(entityId);
|
|
692
|
+
if (!object)
|
|
693
|
+
return `no entity '${entityId}' in the scene being shown`;
|
|
694
|
+
if (dragEntity === object) {
|
|
695
|
+
dragEntity = null;
|
|
696
|
+
dragEntityId = null;
|
|
697
|
+
dragPlane = null;
|
|
698
|
+
dragGrabOffset = null;
|
|
699
|
+
}
|
|
700
|
+
if (gizmoDrag && gizmo.attached === object)
|
|
701
|
+
gizmoDrag = null;
|
|
702
|
+
if (gizmo.attached === object) {
|
|
703
|
+
gizmo.detach();
|
|
704
|
+
marker.visible = false;
|
|
705
|
+
selectionBox.visible = false;
|
|
706
|
+
}
|
|
707
|
+
scene?.remove(object);
|
|
708
|
+
disposeObjectTree(object);
|
|
709
|
+
entityByObject.delete(object);
|
|
710
|
+
objectByEntity.delete(entityId);
|
|
711
|
+
worn.delete(entityId);
|
|
712
|
+
if (sceneData) {
|
|
713
|
+
const idx = sceneData.entities.findIndex((e) => e.id === entityId);
|
|
714
|
+
if (idx >= 0)
|
|
715
|
+
sceneData.entities.splice(idx, 1);
|
|
716
|
+
}
|
|
717
|
+
return undefined;
|
|
718
|
+
}
|
|
719
|
+
async function onDeleteEntity3d(m) {
|
|
720
|
+
const error = deleteEntityLive(m.entityId);
|
|
721
|
+
if (error)
|
|
722
|
+
console.warn('[umicat/editor] 3D entity delete failed:', m.entityId, error);
|
|
723
|
+
window.parent.postMessage({ type: 'umicat:editor:entityDeleted3d', entityId: m.entityId, ok: !error, error }, '*');
|
|
724
|
+
}
|
|
595
725
|
window.addEventListener('message', (e) => { void onHostMessage(e); });
|
|
726
|
+
/**
|
|
727
|
+
* In-iframe keyboard shortcuts — Delete/Backspace and Ctrl/Cmd+Z only work
|
|
728
|
+
* from the HOST page's own keydown listener while focus is still on the
|
|
729
|
+
* host (chat, panels); clicking the canvas moves focus INTO this iframe's
|
|
730
|
+
* browsing context, after which the host's `window.addEventListener`
|
|
731
|
+
* never fires again until focus returns. Exactly the same gap
|
|
732
|
+
* `@umicat/phaser-sdk`'s 2D editor overlay already solves for Cmd+S/Z/Y —
|
|
733
|
+
* this is the 3D counterpart.
|
|
734
|
+
*
|
|
735
|
+
* Delete acts immediately and locally (this player already owns the live
|
|
736
|
+
* scene graph — there is nothing to ask the host's permission for, same
|
|
737
|
+
* as a drag self-applying before telling the host). Undo does NOT: the
|
|
738
|
+
* undo STACK lives on the host (it is what decided there was something to
|
|
739
|
+
* undo in the first place), so this only asks — `requestUndo3d`, no
|
|
740
|
+
* payload — and the host answers with an ordinary `patchEntity3d` restoring
|
|
741
|
+
* the prior value, the exact same inbound message a host-initiated undo
|
|
742
|
+
* uses.
|
|
743
|
+
*/
|
|
744
|
+
window.addEventListener('keydown', (e) => {
|
|
745
|
+
const target = e.target;
|
|
746
|
+
if (target && (target.tagName === 'INPUT' || target.tagName === 'TEXTAREA' || target.isContentEditable))
|
|
747
|
+
return;
|
|
748
|
+
if (e.key === 'Delete' && gizmo.attached) {
|
|
749
|
+
const entityId = entityByObject.get(gizmo.attached);
|
|
750
|
+
if (entityId) {
|
|
751
|
+
e.preventDefault();
|
|
752
|
+
void onDeleteEntity3d({ entityId });
|
|
753
|
+
}
|
|
754
|
+
}
|
|
755
|
+
else if ((e.metaKey || e.ctrlKey) && e.key.toLowerCase() === 'z') {
|
|
756
|
+
e.preventDefault();
|
|
757
|
+
window.parent.postMessage({ type: 'umicat:editor:requestUndo3d' }, '*');
|
|
758
|
+
}
|
|
759
|
+
});
|
|
596
760
|
// Design mode skips physics and animation entirely (loadScene3D's own
|
|
597
761
|
// designMode flag) — there are no mixers to advance and no Rapier world to
|
|
598
762
|
// step, so the loop only ever needs to render.
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@umicat/three-sdk",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "1.0.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",
|