@umicat/three-sdk 1.14.0 → 1.16.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.
@@ -39,6 +39,21 @@ export interface DualScreenTargets {
39
39
  aspect: number;
40
40
  updateProjectionMatrix(): void;
41
41
  };
42
+ /**
43
+ * For a game that sizes its own buffer (via `viewportSize`) but still wants
44
+ * its canvas put in the right place. The SDK sets the CSS BOX and nothing
45
+ * else — no `setSize`, no aspect.
46
+ *
47
+ * This exists because a game with its own camera framing cannot hand over
48
+ * the renderer, and a buffer sized to the upper panel inside a canvas still
49
+ * stretched across the window is a picture stretched to twice its height.
50
+ * Found exactly that way, on Gomoku: the rig frames the board itself and
51
+ * offsets the view for its chat column, so it asks for the viewport — and
52
+ * then had nowhere correct to draw it.
53
+ *
54
+ * Ignored when `renderer` is given, which already covers the box.
55
+ */
56
+ canvas?: HTMLCanvasElement;
42
57
  }
43
58
  /**
44
59
  * Starts keeping the page laid out for the fold. Call once, after `init`.
@@ -63,8 +63,14 @@ export function viewportSize(umicat) {
63
63
  export function installDualScreen(umicat, targets = {}) {
64
64
  let current = null;
65
65
  const applyCanvas = () => {
66
- if (!targets.renderer || !current)
66
+ if (!current)
67
67
  return;
68
+ if (!targets.renderer) {
69
+ // Box only — the game sizes its own buffer.
70
+ if (targets.canvas)
71
+ placeCanvas(current, targets.canvas);
72
+ return;
73
+ }
68
74
  const size = current.dualScreen && current.top
69
75
  ? { width: current.top.width, height: current.top.height }
70
76
  : { width: window.innerWidth, height: window.innerHeight };
@@ -82,10 +88,10 @@ export function installDualScreen(umicat, targets = {}) {
82
88
  publishVariables(layout);
83
89
  placeControls(layout);
84
90
  applyCanvas();
85
- // A game that drives its own canvas (no `renderer` here) still needs to
86
- // hear about it. Folding is a size change as far as it is concerned, but
87
- // no window resize accompanies it — the window is exactly as big as it
88
- // was, the usable part of it is not.
91
+ // A game that drives its own canvas still needs to hear about it. Folding
92
+ // is a size change as far as it is concerned, but no window resize
93
+ // accompanies it — the window is exactly as big as it was, the usable part
94
+ // of it is not.
89
95
  if (!targets.renderer)
90
96
  window.dispatchEvent(new Event('resize'));
91
97
  });
@@ -182,6 +182,25 @@ function materialRepeatFor(kind, size, tileUnit) {
182
182
  }
183
183
  return new THREE.Vector2(u(size.x), u(size.z));
184
184
  }
185
+ /**
186
+ * ADR-047 — rebuilds a `THREE.BufferGeometry` from a baked CSG result's
187
+ * flat position/index arrays (`Entity3D.primitive.mesh`). `normals` is
188
+ * optional — when the CSG op didn't carry any over, `computeVertexNormals`
189
+ * derives smooth per-vertex ones, same fallback `triangleListGeometry`
190
+ * already uses for wedge/corner-wedge.
191
+ */
192
+ function bakedMeshGeometry(mesh) {
193
+ const geom = new THREE.BufferGeometry();
194
+ geom.setAttribute('position', new THREE.Float32BufferAttribute(mesh.positions, 3));
195
+ geom.setIndex(mesh.indices);
196
+ if (mesh.normals && mesh.normals.length === mesh.positions.length) {
197
+ geom.setAttribute('normal', new THREE.Float32BufferAttribute(mesh.normals, 3));
198
+ }
199
+ else {
200
+ geom.computeVertexNormals();
201
+ }
202
+ return geom;
203
+ }
185
204
  export function makePrimitive(e) {
186
205
  const p = e.primitive;
187
206
  const s = p.size ?? { x: 1, y: 1, z: 1 };
@@ -190,15 +209,16 @@ export function makePrimitive(e) {
190
209
  : p.kind === 'cylinder' ? new THREE.CylinderGeometry(s.x / 2, s.x / 2, s.y, 24)
191
210
  : p.kind === 'wedge' ? wedgeGeometry(s)
192
211
  : p.kind === 'corner-wedge' ? cornerWedgeGeometry(s)
193
- // Lay the plane down by rotating the GEOMETRY, not the object. Rotating the
194
- // object is the obvious move and it is wrong: applyTransform sets the
195
- // object's quaternion from the entity's authored rotation straight
196
- // afterwards, silently discarding it — which left every "ground" standing
197
- // upright like a wall. It renders convincingly until the camera crosses to
198
- // the far side, at which point the scene becomes a flat fill and every
199
- // measurement still says the character is dead centre, because it is —
200
- // behind a 40x40 wall.
201
- : new THREE.PlaneGeometry(s.x, s.z).rotateX(-Math.PI / 2);
212
+ : p.kind === 'mesh' ? bakedMeshGeometry(p.mesh ?? { positions: [], indices: [] })
213
+ // Lay the plane down by rotating the GEOMETRY, not the object. Rotating the
214
+ // object is the obvious move and it is wrong: applyTransform sets the
215
+ // object's quaternion from the entity's authored rotation straight
216
+ // afterwards, silently discarding it — which left every "ground" standing
217
+ // upright like a wall. It renders convincingly until the camera crosses to
218
+ // the far side, at which point the scene becomes a flat fill and every
219
+ // measurement still says the character is dead centre, because it is —
220
+ // behind a 40x40 wall.
221
+ : new THREE.PlaneGeometry(s.x, s.z).rotateX(-Math.PI / 2);
202
222
  const material = new THREE.MeshStandardMaterial({
203
223
  color: new THREE.Color(p.color ?? '#c8c8c8'), roughness: 0.85,
204
224
  // The wedge/corner-wedge faces' winding was verified by hand (no
@@ -206,7 +226,9 @@ export function makePrimitive(e) {
206
226
  // DoubleSide is a pragmatic safety net against a winding mistake
207
227
  // making a face invisible from its intended viewing side; it costs a
208
228
  // little backface-culling perf on two low-poly shapes, not correctness.
209
- side: (p.kind === 'wedge' || p.kind === 'corner-wedge') ? THREE.DoubleSide : THREE.FrontSide,
229
+ // `mesh` joins the same safety net for the same reason — a CSG seam
230
+ // is exactly where a winding inconsistency is most likely to turn up.
231
+ side: (p.kind === 'wedge' || p.kind === 'corner-wedge' || p.kind === 'mesh') ? THREE.DoubleSide : THREE.FrontSide,
210
232
  });
211
233
  const mesh = new THREE.Mesh(geom, material);
212
234
  mesh.castShadow = p.kind !== 'plane';
@@ -0,0 +1,41 @@
1
+ import * as THREE from 'three';
2
+ /**
3
+ * ADR-047 — Boolean operations (Union/Intersect/Negate), copied from Roblox
4
+ * exactly: Negate is a pure marker on a Part (no geometry change by itself);
5
+ * Union computes the union of every NON-negated selected Part, then
6
+ * subtracts the union of every NEGATED one from it; Intersect computes the
7
+ * intersection of every selected Part regardless of any Negate marks.
8
+ *
9
+ * Pure three.js math, no scene/editor dependency (same posture
10
+ * `gizmoMath.ts` already has) — `EditorDesignPlayer3D.ts` is the only
11
+ * caller, and it owns turning a `CsgResult` into a new `Entity3D`.
12
+ */
13
+ export interface CsgOperand {
14
+ object: THREE.Object3D;
15
+ negated?: boolean;
16
+ }
17
+ export interface CsgResultMesh {
18
+ positions: number[];
19
+ indices: number[];
20
+ normals?: number[];
21
+ }
22
+ export interface CsgResult {
23
+ mesh: CsgResultMesh;
24
+ /** The new entity's LOCAL transform — equal to the first operand's (in
25
+ * fold order) WORLD transform, per three-bvh-csg's own documented
26
+ * behavior (`Evaluator.evaluate` always re-stamps the result with
27
+ * operand A's transform) — correct as a scene-root, parentless entity's
28
+ * local transform with no further conversion needed. */
29
+ position: THREE.Vector3;
30
+ quaternion: THREE.Quaternion;
31
+ scale: THREE.Vector3;
32
+ }
33
+ /**
34
+ * Roblox's Union: union of the non-negated Parts, minus the union of the
35
+ * negated ones. If EVERY selected Part is negated (nothing to cut from),
36
+ * negate marks are meaningless here — falls back to a plain union of
37
+ * everything, same as Intersect ignoring them entirely.
38
+ */
39
+ export declare function unionOperands(operands: CsgOperand[]): CsgResult;
40
+ /** Intersection of every selected Part, in selection order. Ignores Negate marks entirely. */
41
+ export declare function intersectOperands(operands: CsgOperand[]): CsgResult;
@@ -0,0 +1,72 @@
1
+ import * as THREE from 'three';
2
+ import { Evaluator, Brush, ADDITION, SUBTRACTION, INTERSECTION } from 'three-bvh-csg';
3
+ /**
4
+ * Wraps a live scene object's geometry + CURRENT WORLD transform into a
5
+ * `Brush` three-bvh-csg can operate on. Clones the geometry rather than
6
+ * handing over the live mesh's own — `Brush.prepareGeometry()` permanently
7
+ * attaches CSG-internal bookkeeping (`boundsTree`/`halfEdges`/
8
+ * `groupIndices`) to whatever geometry it's given, which must not leak onto
9
+ * an object still live in the scene.
10
+ */
11
+ function toBrush(object) {
12
+ const mesh = object;
13
+ const geometry = mesh.geometry.clone();
14
+ const brush = new Brush(geometry, new THREE.MeshStandardMaterial());
15
+ object.updateWorldMatrix(true, false);
16
+ object.matrixWorld.decompose(brush.position, brush.quaternion, brush.scale);
17
+ brush.updateMatrix();
18
+ brush.matrixWorld.copy(object.matrixWorld);
19
+ return brush;
20
+ }
21
+ function extractResult(brush) {
22
+ const geometry = brush.geometry;
23
+ const posAttr = geometry.attributes.position;
24
+ const positions = Array.from(posAttr.array);
25
+ const indexAttr = geometry.index;
26
+ const indices = indexAttr
27
+ ? Array.from(indexAttr.array)
28
+ : Array.from({ length: posAttr.count }, (_, i) => i);
29
+ const normalAttr = geometry.attributes.normal;
30
+ const normals = normalAttr ? Array.from(normalAttr.array) : undefined;
31
+ return {
32
+ mesh: { positions, indices, normals },
33
+ position: brush.position.clone(),
34
+ quaternion: brush.quaternion.clone(),
35
+ scale: brush.scale.clone(),
36
+ };
37
+ }
38
+ function foldAddition(evaluator, objects) {
39
+ let acc = toBrush(objects[0]);
40
+ for (let i = 1; i < objects.length; i++)
41
+ acc = evaluator.evaluate(acc, toBrush(objects[i]), ADDITION);
42
+ return acc;
43
+ }
44
+ /**
45
+ * Roblox's Union: union of the non-negated Parts, minus the union of the
46
+ * negated ones. If EVERY selected Part is negated (nothing to cut from),
47
+ * negate marks are meaningless here — falls back to a plain union of
48
+ * everything, same as Intersect ignoring them entirely.
49
+ */
50
+ export function unionOperands(operands) {
51
+ if (operands.length < 2)
52
+ throw new Error('union needs at least 2 operands');
53
+ const evaluator = new Evaluator();
54
+ const nonNegated = operands.filter((o) => !o.negated).map((o) => o.object);
55
+ const negated = operands.filter((o) => o.negated).map((o) => o.object);
56
+ if (nonNegated.length === 0)
57
+ return extractResult(foldAddition(evaluator, operands.map((o) => o.object)));
58
+ let acc = foldAddition(evaluator, nonNegated);
59
+ if (negated.length > 0)
60
+ acc = evaluator.evaluate(acc, foldAddition(evaluator, negated), SUBTRACTION);
61
+ return extractResult(acc);
62
+ }
63
+ /** Intersection of every selected Part, in selection order. Ignores Negate marks entirely. */
64
+ export function intersectOperands(operands) {
65
+ if (operands.length < 2)
66
+ throw new Error('intersect needs at least 2 operands');
67
+ const evaluator = new Evaluator();
68
+ let acc = toBrush(operands[0].object);
69
+ for (let i = 1; i < operands.length; i++)
70
+ acc = evaluator.evaluate(acc, toBrush(operands[i].object), INTERSECTION);
71
+ return extractResult(acc);
72
+ }
@@ -6,6 +6,7 @@ import { applyAttachments } from '../Attachments.js';
6
6
  import { singleModelManifest, defaultColliderForPrimitive, groundRestOffset } from '../scene3d.js';
7
7
  import { TransformGizmo3D } from './TransformGizmo3D.js';
8
8
  import { closestPointOnLineToRay, raycastPlane, angleAroundAxis } from './gizmoMath.js';
9
+ import { unionOperands, intersectOperands } from './CSG3D.js';
9
10
  import { loadHud3DScene } from '../hud3d/HudRuntime3D.js';
10
11
  /**
11
12
  * The 3D counterpart of `@umicat/phaser-sdk`'s `EditorDesignScene` (ADR-021)
@@ -278,6 +279,38 @@ export async function runEditorDesignPlayer3D(renderer, opts = {}) {
278
279
  // single click never grows a second, redundant box.
279
280
  let multiSelected = new Set();
280
281
  const multiBoxes = new Map();
282
+ // ADR-047 — a persistent magenta outline on any Part marked `negated`
283
+ // (Roblox's own convention for a to-be-subtracted Union operand),
284
+ // independent of selection — a Part stays visibly marked while
285
+ // deselected, since Negate is STATE, not a transient selection
286
+ // highlight. Resynced every frame (below, alongside `gizmo.update`)
287
+ // rather than only at the moments this file already knows a transform
288
+ // changed, specifically because a negated Part can be moved via the
289
+ // ORDINARY single-entity gizmo/free-drag paths — neither of which
290
+ // otherwise has any reason to know this map exists. Deliberately NOT a
291
+ // material-color tint — the shared-material clone trap `Tint.ts`'s own
292
+ // doc comment already warns about elsewhere in this codebase.
293
+ const negatedBoxes = new Map();
294
+ function setNegatedVisual(object, negated) {
295
+ if (negated) {
296
+ if (negatedBoxes.has(object))
297
+ return;
298
+ const box = new THREE.BoxHelper(object, 0xff33cc);
299
+ box.renderOrder = 997;
300
+ box.material.depthTest = false;
301
+ scene?.add(box);
302
+ negatedBoxes.set(object, box);
303
+ }
304
+ else {
305
+ const box = negatedBoxes.get(object);
306
+ if (!box)
307
+ return;
308
+ scene?.remove(box);
309
+ box.geometry.dispose();
310
+ box.material.dispose();
311
+ negatedBoxes.delete(object);
312
+ }
313
+ }
281
314
  // The Move/Rotate/Scale transform gizmo — shows (and is only hit-testable)
282
315
  // on the current mode's handles once something is selected. `gizmo.root`
283
316
  // is added to the scene once, at scene-load time, right alongside the
@@ -1359,6 +1392,10 @@ export async function runEditorDesignPlayer3D(renderer, opts = {}) {
1359
1392
  return onCreateEntity3d(data);
1360
1393
  if (data.type === 'umicat:editor:deleteEntity3d')
1361
1394
  return onDeleteEntity3d(data);
1395
+ if (data.type === 'umicat:editor:csgUnion3d')
1396
+ return onCsgUnion3d(data);
1397
+ if (data.type === 'umicat:editor:csgIntersect3d')
1398
+ return onCsgIntersect3d(data);
1362
1399
  if (data.type === 'umicat:editor:setGizmoMode3d') {
1363
1400
  const mode = data.mode;
1364
1401
  if (mode === 'move' || mode === 'rotate' || mode === 'scale') {
@@ -1460,6 +1497,17 @@ export async function runEditorDesignPlayer3D(renderer, opts = {}) {
1460
1497
  // explicit refresh here, same as a live drag already does.
1461
1498
  selectionBox.setFromObject(object);
1462
1499
  }
1500
+ if (m.patch?.negated !== undefined) {
1501
+ // ADR-047 — pure marker, no geometry/transform change at all.
1502
+ setNegatedVisual(object, m.patch.negated);
1503
+ const authored = sceneData?.entities.find((e) => e.id === m.entityId);
1504
+ if (authored) {
1505
+ if (m.patch.negated)
1506
+ authored.negated = true;
1507
+ else
1508
+ delete authored.negated;
1509
+ }
1510
+ }
1463
1511
  if (m.patch?.parent !== undefined) {
1464
1512
  // ADR-045 Phase 2 — reparent. `Object3D.attach` (standard three.js
1465
1513
  // API) moves `object` under the new parent AND recomputes its local
@@ -1580,6 +1628,14 @@ export async function runEditorDesignPlayer3D(renderer, opts = {}) {
1580
1628
  box.setFromObject(fresh);
1581
1629
  }
1582
1630
  }
1631
+ {
1632
+ const box = negatedBoxes.get(object);
1633
+ if (box) {
1634
+ negatedBoxes.delete(object);
1635
+ negatedBoxes.set(fresh, box);
1636
+ box.setFromObject(fresh);
1637
+ }
1638
+ }
1583
1639
  object = fresh;
1584
1640
  }
1585
1641
  done();
@@ -1704,28 +1760,33 @@ export async function runEditorDesignPlayer3D(renderer, opts = {}) {
1704
1760
  * block the entity from existing at all, unlike a direct user-initiated
1705
1761
  * patch where failing loudly is correct).
1706
1762
  */
1707
- async function onCreateEntity3d(m) {
1708
- const e = m.entity;
1709
- const done = (error) => {
1710
- if (error)
1711
- console.warn('[umicat/editor] 3D entity create failed:', e.id, error);
1712
- window.parent.postMessage({ type: 'umicat:editor:entityCreated3d', entityId: e.id, ok: !error, error }, '*');
1713
- };
1763
+ /**
1764
+ * The actual spawn work behind `onCreateEntity3d`'s message handler,
1765
+ * pulled out with no `postMessage` of its own — same split this file's
1766
+ * `deleteEntityLive`/`onDeleteEntity3d` pair already established —
1767
+ * SPECIFICALLY so ADR-047's CSG handler (below) can create its merged
1768
+ * result entity through the exact same path Paste/Duplicate already use
1769
+ * (parent-honoring, skin/attachment re-apply, registration into every
1770
+ * map) without also emitting an unrelated `entityCreated3d` ack the CSG
1771
+ * flow has no use for — it posts its own `csgResult3d` instead. Returns
1772
+ * an error string on failure, undefined on success.
1773
+ */
1774
+ async function createEntityLive(e) {
1714
1775
  if (!scene)
1715
- return done('no scene loaded yet');
1776
+ return 'no scene loaded yet';
1716
1777
  if (objectByEntity.has(e.id))
1717
- return done(`entity '${e.id}' already exists in this scene`);
1778
+ return `entity '${e.id}' already exists in this scene`;
1718
1779
  let object;
1719
1780
  if (e.modelAssetId) {
1720
1781
  const asset = manifest?.models?.find((x) => x.id === e.modelAssetId);
1721
1782
  if (!asset)
1722
- return done(`entity references model '${e.modelAssetId}', which the manifest does not define`);
1783
+ return `entity references model '${e.modelAssetId}', which the manifest does not define`;
1723
1784
  try {
1724
1785
  const loaded = await loadModelAsset(singleModelManifest(asset), e.modelAssetId, { assetBase: '' });
1725
1786
  object = loaded.object;
1726
1787
  }
1727
1788
  catch (err) {
1728
- return done(err instanceof Error ? err.message : String(err));
1789
+ return err instanceof Error ? err.message : String(err);
1729
1790
  }
1730
1791
  object.traverse((n) => { n.castShadow = e.castShadow !== false; n.receiveShadow = true; });
1731
1792
  if (e.skin) {
@@ -1771,14 +1832,22 @@ export async function runEditorDesignPlayer3D(renderer, opts = {}) {
1771
1832
  if (e.parent) {
1772
1833
  const resolved = objectByEntity.get(e.parent);
1773
1834
  if (!resolved)
1774
- return done(`entity references parent '${e.parent}', which does not exist in this scene`);
1835
+ return `entity references parent '${e.parent}', which does not exist in this scene`;
1775
1836
  parentObject = resolved;
1776
1837
  }
1777
1838
  parentObject.add(object);
1778
1839
  entityByObject.set(object, e.id);
1779
1840
  objectByEntity.set(e.id, object);
1780
1841
  sceneData?.entities.push(e);
1781
- done();
1842
+ if (e.negated)
1843
+ setNegatedVisual(object, true);
1844
+ return undefined;
1845
+ }
1846
+ async function onCreateEntity3d(m) {
1847
+ const error = await createEntityLive(m.entity);
1848
+ if (error)
1849
+ console.warn('[umicat/editor] 3D entity create failed:', m.entity.id, error);
1850
+ window.parent.postMessage({ type: 'umicat:editor:entityCreated3d', entityId: m.entity.id, ok: !error, error }, '*');
1782
1851
  }
1783
1852
  /**
1784
1853
  * Frees a subtree's GPU resources the same way the whole-scene `dispose()`
@@ -1852,6 +1921,7 @@ export async function runEditorDesignPlayer3D(renderer, opts = {}) {
1852
1921
  entityByObject.delete(object);
1853
1922
  objectByEntity.delete(entityId);
1854
1923
  worn.delete(entityId);
1924
+ setNegatedVisual(object, false);
1855
1925
  if (sceneData) {
1856
1926
  const idx = sceneData.entities.findIndex((e) => e.id === entityId);
1857
1927
  if (idx >= 0)
@@ -1865,6 +1935,115 @@ export async function runEditorDesignPlayer3D(renderer, opts = {}) {
1865
1935
  console.warn('[umicat/editor] 3D entity delete failed:', m.entityId, error);
1866
1936
  window.parent.postMessage({ type: 'umicat:editor:entityDeleted3d', entityId: m.entityId, ok: !error, error }, '*');
1867
1937
  }
1938
+ /**
1939
+ * ADR-047 — Roblox's Union/Intersect, copied exactly (confirmed against
1940
+ * a real screenshot of Roblox Studio's own right-click menu): both ops
1941
+ * need 2+ selected Parts; a `plane` or model/group entity (no solid
1942
+ * geometry of its own, or geometry this SDK can't guarantee is
1943
+ * manifold) can't be an operand. Returns an error string naming the
1944
+ * first disqualifying entity, or the resolved `{object, authored}` pair
1945
+ * list on success.
1946
+ */
1947
+ function resolveCsgOperands(entityIds) {
1948
+ const resolved = [];
1949
+ for (const id of entityIds) {
1950
+ const object = objectByEntity.get(id);
1951
+ if (!object)
1952
+ return `no entity '${id}' in the scene being shown`;
1953
+ const authored = sceneData?.entities.find((e) => e.id === id);
1954
+ if (!authored?.primitive || authored.primitive.kind === 'plane') {
1955
+ return `entity '${id}' is not a solid Part — Union/Intersect only work on box/sphere/cylinder/` +
1956
+ `wedge/corner-wedge/mesh Parts`;
1957
+ }
1958
+ resolved.push({ object, authored });
1959
+ }
1960
+ return resolved;
1961
+ }
1962
+ /**
1963
+ * Shared by Union and Intersect — both delete every operand and spawn
1964
+ * ONE new `primitive.kind:'mesh'` entity in their place, reusing
1965
+ * `createEntityLive` (the exact same spawn path Paste/Duplicate use) so
1966
+ * the result is immediately selected, pickable and draggable with zero
1967
+ * new registration code. `compute` is the one thing that differs
1968
+ * between the two ops; everything else (validation, operand deletion,
1969
+ * entity assembly, selection, the ack) is identical.
1970
+ */
1971
+ async function doCsgOp(m, op, compute) {
1972
+ const done = (error, entity) => {
1973
+ if (error)
1974
+ console.warn(`[umicat/editor] 3D CSG ${op} failed:`, error);
1975
+ window.parent.postMessage({
1976
+ // `newEntityId` always echoes back, success or failure — the
1977
+ // host has no other stable key to match this ack to the
1978
+ // request that caused it (unlike `entityCreated3d`'s
1979
+ // `entityId`, which IS always present; `entity` here is only
1980
+ // present on success).
1981
+ type: 'umicat:editor:csgResult3d', op, ok: !error, error, entity, newEntityId: m.newEntityId,
1982
+ removedEntityIds: error ? undefined : m.entityIds,
1983
+ }, '*');
1984
+ };
1985
+ if (!scene)
1986
+ return done('no scene loaded yet');
1987
+ if (m.entityIds.length < 2)
1988
+ return done(`${op} needs at least 2 selected Parts`);
1989
+ if (objectByEntity.has(m.newEntityId))
1990
+ return done(`entity '${m.newEntityId}' already exists in this scene`);
1991
+ const resolved = resolveCsgOperands(m.entityIds);
1992
+ if (typeof resolved === 'string')
1993
+ return done(resolved);
1994
+ let result;
1995
+ try {
1996
+ result = compute(resolved.map((r) => ({ object: r.object, negated: r.authored.negated })));
1997
+ }
1998
+ catch (err) {
1999
+ return done(err instanceof Error ? err.message : String(err));
2000
+ }
2001
+ // Appearance inherits from the SAME operand three-bvh-csg itself used
2002
+ // for the result's TRANSFORM (see `CSG3D.ts`'s own doc comment) — the
2003
+ // first non-negated selected Part for Union (or the first selected
2004
+ // Part at all, if every one was negated), the first selected Part at
2005
+ // all for Intersect. Not re-derived independently of that choice.
2006
+ const appearanceSource = op === 'union' ? (resolved.find((r) => !r.authored.negated) ?? resolved[0]) : resolved[0];
2007
+ const newPrimitive = {
2008
+ kind: 'mesh',
2009
+ mesh: result.mesh,
2010
+ color: appearanceSource.authored.primitive?.color,
2011
+ material: appearanceSource.authored.primitive?.material,
2012
+ };
2013
+ const newEntity = {
2014
+ id: m.newEntityId,
2015
+ primitive: newPrimitive,
2016
+ // Explicit, same convention `onDropPrimitive3d` already established
2017
+ // — the SDK chose this default, so it's echoed back into the
2018
+ // authored entity rather than left for `loadScene3D`'s fallback to
2019
+ // re-derive later (that fallback exists for scenes authored before
2020
+ // a collider field existed at all, not as the normal path here).
2021
+ collider: defaultColliderForPrimitive(newPrimitive),
2022
+ transform: {
2023
+ position: { x: result.position.x, y: result.position.y, z: result.position.z },
2024
+ rotation: [result.quaternion.x, result.quaternion.y, result.quaternion.z, result.quaternion.w],
2025
+ scale: { x: result.scale.x, y: result.scale.y, z: result.scale.z },
2026
+ },
2027
+ };
2028
+ for (const id of m.entityIds) {
2029
+ const err = deleteEntityLive(id);
2030
+ if (err)
2031
+ console.warn('[umicat/editor] CSG: failed to remove operand', id, err);
2032
+ }
2033
+ const createError = await createEntityLive(newEntity);
2034
+ if (createError)
2035
+ return done(createError);
2036
+ const newObject = objectByEntity.get(newEntity.id);
2037
+ if (newObject)
2038
+ applySelection([newObject]);
2039
+ done(undefined, newEntity);
2040
+ }
2041
+ async function onCsgUnion3d(m) {
2042
+ return doCsgOp(m, 'union', unionOperands);
2043
+ }
2044
+ async function onCsgIntersect3d(m) {
2045
+ return doCsgOp(m, 'intersect', intersectOperands);
2046
+ }
1868
2047
  window.addEventListener('message', (e) => { void onHostMessage(e); });
1869
2048
  /**
1870
2049
  * In-iframe keyboard shortcuts — Delete/Backspace and Ctrl/Cmd+Z only work
@@ -1996,6 +2175,8 @@ export async function runEditorDesignPlayer3D(renderer, opts = {}) {
1996
2175
  if (!scene)
1997
2176
  return;
1998
2177
  gizmo.update(camera);
2178
+ for (const [obj, box] of negatedBoxes)
2179
+ box.setFromObject(obj);
1999
2180
  renderer.setScissorTest(false);
2000
2181
  renderer.render(scene, camera);
2001
2182
  // Second pass: the orientation gizmo, into a small scissored corner
@@ -2070,6 +2251,17 @@ export async function runEditorDesignPlayer3D(renderer, opts = {}) {
2070
2251
  multiSelected = new Set();
2071
2252
  multiBoxes.clear();
2072
2253
  groupDrag = null;
2254
+ // ADR-047 — same reasoning as `multiBoxes.clear()` just above: a prior
2255
+ // scene's boxes were added to that scene, not this one. Re-seed from
2256
+ // the freshly loaded authored data, not carried over.
2257
+ negatedBoxes.clear();
2258
+ for (const e of sceneData.entities) {
2259
+ if (e.negated) {
2260
+ const obj = objectByEntity.get(e.id);
2261
+ if (obj)
2262
+ setNegatedVisual(obj, true);
2263
+ }
2264
+ }
2073
2265
  // Frame the whole scene — auto-fit, since a small template scene and a
2074
2266
  // real level's dozens of entities need wildly different orbit distances.
2075
2267
  const box = new THREE.Box3().setFromObject(scene);
package/dist/scene3d.d.ts CHANGED
@@ -111,7 +111,12 @@ export interface Entity3D {
111
111
  * built from.
112
112
  */
113
113
  primitive?: {
114
- kind: 'box' | 'sphere' | 'plane' | 'cylinder' | 'wedge' | 'corner-wedge';
114
+ /**
115
+ * ADR-047 — `mesh` is a BAKED CSG Union/Intersect result (the
116
+ * editor's Boolean operations), not an authorable shape — it carries
117
+ * no `size`, only a fixed `mesh` geometry buffer, below.
118
+ */
119
+ kind: 'box' | 'sphere' | 'plane' | 'cylinder' | 'wedge' | 'corner-wedge' | 'mesh';
115
120
  size?: Vec3;
116
121
  color?: string;
117
122
  /**
@@ -125,8 +130,38 @@ export interface Entity3D {
125
130
  * already does when both `color` and `map` are present).
126
131
  */
127
132
  material?: string;
133
+ /**
134
+ * ADR-047 — only present for `kind: 'mesh'`. Flat `[x,y,z, x,y,z,
135
+ * ...]` vertex positions and `[i,i,i, ...]` triangle indices, in the
136
+ * entity's OWN local space (the same space `Transform3D.position`
137
+ * places the entity's origin at) — written once, at Union/Intersect
138
+ * time, by `CSG3D.ts`'s operation result; never hand-authored and
139
+ * never edited in place (the shape is fixed; move/rotate/scale/
140
+ * re-color/re-material still work normally via the entity's own
141
+ * `transform`/`color`/`material`, same as any other Part). `normals`
142
+ * is optional — omitted, the renderer computes smooth-per-face
143
+ * normals the same way `triangleListGeometry` already does for
144
+ * wedge/corner-wedge.
145
+ */
146
+ mesh?: {
147
+ positions: number[];
148
+ indices: number[];
149
+ normals?: number[];
150
+ };
128
151
  };
129
152
  collider?: Collider3D;
153
+ /**
154
+ * ADR-047 — marks this Part for SUBTRACTION the next time it (or a
155
+ * selection including it) is Union'd — Roblox's own Negate/Union
156
+ * two-step: Negate alone changes nothing geometrically, it is purely
157
+ * the marker `Union` reads at compute time to decide which selected
158
+ * Parts to ADD versus which to CUT AWAY from the rest. Meaningless
159
+ * (and never set) on anything but a `primitive` entity, and always
160
+ * dropped from whatever NEW entity a Union/Intersect produces — the
161
+ * flag describes "how to combine this Part," not a property the
162
+ * resulting merged shape inherits.
163
+ */
164
+ negated?: boolean;
130
165
  /** Which clip to play on spawn, by SEMANTIC name — see `AnimationMap`. */
131
166
  animation?: {
132
167
  play?: string;
package/dist/scene3d.js CHANGED
@@ -97,6 +97,21 @@ export function groundRestOffset(primitive) {
97
97
  */
98
98
  export function defaultColliderForPrimitive(primitive) {
99
99
  const s = primitive.size ?? { x: 1, y: 1, z: 1 };
100
+ // ADR-047 — a `mesh` Part (a baked CSG result) has no `size` at all; its
101
+ // collider is a convex hull of its OWN baked vertices, same "irregular
102
+ // solid → convexHull" fallback wedge/corner-wedge already use below —
103
+ // an approximation for anything non-convex (e.g. a Subtract that
104
+ // carved a hole clean through), but still the right DEFAULT: Rapier has
105
+ // no "exact concave shape" primitive for a DYNAMIC body, and a hull is
106
+ // always at least as permissive (never blocks something it shouldn't),
107
+ // same tradeoff this function already accepts for wedge/corner-wedge.
108
+ if (primitive.kind === 'mesh') {
109
+ const positions = primitive.mesh?.positions ?? [];
110
+ const points = [];
111
+ for (let i = 0; i + 2 < positions.length; i += 3)
112
+ points.push({ x: positions[i], y: positions[i + 1], z: positions[i + 2] });
113
+ return { shape: { kind: 'convexHull', points }, body: 'fixed' };
114
+ }
100
115
  const shape = primitive.kind === 'box' ? { kind: 'box', halfExtents: { x: s.x / 2, y: s.y / 2, z: s.z / 2 } }
101
116
  : primitive.kind === 'sphere' ? { kind: 'sphere', radius: s.x / 2 }
102
117
  : primitive.kind === 'cylinder' ? { kind: 'cylinder', halfHeight: s.y / 2, radius: s.x / 2 }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@umicat/three-sdk",
3
- "version": "1.14.0",
3
+ "version": "1.16.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",
@@ -18,8 +18,10 @@
18
18
  },
19
19
  "dependencies": {
20
20
  "@dimforge/rapier3d-compat": "^0.14.0",
21
+ "@umicat/platform-sdk": "^0.3.0",
21
22
  "three": "0.186.0",
22
- "@umicat/platform-sdk": "^0.3.0"
23
+ "three-bvh-csg": "^0.0.18",
24
+ "three-mesh-bvh": "^0.9.16"
23
25
  },
24
26
  "devDependencies": {
25
27
  "@types/three": "^0.185.4",