@umicat/three-sdk 0.23.0 → 0.24.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). What it still does not have: undo, multi-select, or a local/
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 is the first field, and adding
494
- * rotation/scale/visible later should be a new `if`, not a new message.
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.23.0",
3
+ "version": "0.24.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",