@umicat/three-sdk 1.6.0 → 1.7.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.
@@ -1,5 +1,5 @@
1
1
  import * as THREE from 'three';
2
- import { type Scene3D, type Manifest3D, type Sky3D } from './scene3d.js';
2
+ import { type Scene3D, type Manifest3D, type Entity3D, type Sky3D } from './scene3d.js';
3
3
  import { type WornMap } from './Attachments.js';
4
4
  export interface LoadSceneOptions {
5
5
  /** Base url assets resolve against (the project's asset host). */
@@ -54,6 +54,7 @@ export interface LoadedScene3D {
54
54
  update(dt: number): void;
55
55
  dispose(): void;
56
56
  }
57
+ export declare function makePrimitive(e: Entity3D): THREE.Mesh;
57
58
  /**
58
59
  * Turn scene3d design data into a running three.js scene.
59
60
  *
@@ -1,12 +1,18 @@
1
1
  import * as THREE from 'three';
2
2
  import { GLTFLoader } from 'three/examples/jsm/loaders/GLTFLoader.js';
3
3
  import { clone as cloneRigged } from 'three/examples/jsm/utils/SkeletonUtils.js';
4
- import { validateScene, IDENTITY_QUAT, } from './scene3d.js';
4
+ import { validateScene, IDENTITY_QUAT, wedgeVertices, cornerWedgeVertices, defaultColliderForPrimitive, } from './scene3d.js';
5
5
  import { applySkin } from './Skin.js';
6
6
  import { applyAttachments } from './Attachments.js';
7
7
  function toVec(v, d = 0) {
8
8
  return new THREE.Vector3(v?.x ?? d, v?.y ?? d, v?.z ?? d);
9
9
  }
10
+ /** `Rapier.ColliderDesc.convexHull` wants a flat `[x,y,z, x,y,z, ...]` buffer. */
11
+ function flattenPoints(points) {
12
+ const out = new Float32Array(points.length * 3);
13
+ points.forEach((v, i) => { out[i * 3] = v.x; out[i * 3 + 1] = v.y; out[i * 3 + 2] = v.z; });
14
+ return out;
15
+ }
10
16
  /** Does this model deform with bones? Decides which clone it needs. */
11
17
  function isRigged(root) {
12
18
  let rigged = false;
@@ -24,23 +30,71 @@ function applyTransform(obj, e) {
24
30
  else if (t.scale)
25
31
  obj.scale.copy(toVec(t.scale, 1));
26
32
  }
27
- function makePrimitive(e) {
33
+ /**
34
+ * Builds a non-indexed, per-face-normal `BufferGeometry` out of a flat list
35
+ * of CCW-wound triangles (`[A,B,C, A,B,C, ...]`) — the shape a hand-authored
36
+ * low-poly solid (wedge/corner-wedge) needs: NON-indexed specifically so
37
+ * `computeVertexNormals()` yields one flat normal per FACE rather than
38
+ * blending across a shared vertex between two faces at different angles
39
+ * (which would wrongly soften the wedge's sharp ridge edge into a curve).
40
+ */
41
+ function triangleListGeometry(triangles) {
42
+ const positions = new Float32Array(triangles.length * 3);
43
+ triangles.forEach((v, i) => { positions[i * 3] = v.x; positions[i * 3 + 1] = v.y; positions[i * 3 + 2] = v.z; });
44
+ const geom = new THREE.BufferGeometry();
45
+ geom.setAttribute('position', new THREE.BufferAttribute(positions, 3));
46
+ geom.computeVertexNormals();
47
+ return geom;
48
+ }
49
+ /** Winding verified by hand (right-hand rule, outward normal per face) —
50
+ * see `scene3d.ts`'s `wedgeVertices` doc comment for the vertex layout. */
51
+ function wedgeGeometry(size) {
52
+ const [v0, v1, v2, v3, v4, v5] = wedgeVertices(size);
53
+ return triangleListGeometry([
54
+ v0, v1, v2, v0, v2, v3, // bottom (-Y)
55
+ v0, v5, v1, v0, v4, v5, // back (-Z)
56
+ v0, v3, v4, // left end cap
57
+ v1, v5, v2, // right end cap
58
+ v3, v2, v4, v2, v5, v4, // slope (hypotenuse)
59
+ ]);
60
+ }
61
+ /** Winding verified by hand the same way as `wedgeGeometry` — see
62
+ * `scene3d.ts`'s `cornerWedgeVertices` doc comment for the vertex layout. */
63
+ function cornerWedgeGeometry(size) {
64
+ const [v0, v1, v2, v3, v4] = cornerWedgeVertices(size);
65
+ return triangleListGeometry([
66
+ v0, v1, v2, v0, v2, v3, // bottom (-Y)
67
+ v0, v4, v1, // back side
68
+ v1, v4, v2, // right side
69
+ v2, v4, v3, // front side
70
+ v3, v4, v0, // left side
71
+ ]);
72
+ }
73
+ export function makePrimitive(e) {
28
74
  const p = e.primitive;
29
75
  const s = p.size ?? { x: 1, y: 1, z: 1 };
30
76
  const geom = p.kind === 'box' ? new THREE.BoxGeometry(s.x, s.y, s.z)
31
77
  : p.kind === 'sphere' ? new THREE.SphereGeometry(s.x / 2, 24, 16)
32
78
  : p.kind === 'cylinder' ? new THREE.CylinderGeometry(s.x / 2, s.x / 2, s.y, 24)
33
- // Lay the plane down by rotating the GEOMETRY, not the object. Rotating the
34
- // object is the obvious move and it is wrong: applyTransform sets the
35
- // object's quaternion from the entity's authored rotation straight
36
- // afterwards, silently discarding it — which left every "ground" standing
37
- // upright like a wall. It renders convincingly until the camera crosses to
38
- // the far side, at which point the scene becomes a flat fill and every
39
- // measurement still says the character is dead centre, because it is —
40
- // behind a 40x40 wall.
41
- : new THREE.PlaneGeometry(s.x, s.z).rotateX(-Math.PI / 2);
79
+ : p.kind === 'wedge' ? wedgeGeometry(s)
80
+ : p.kind === 'corner-wedge' ? cornerWedgeGeometry(s)
81
+ // Lay the plane down by rotating the GEOMETRY, not the object. Rotating the
82
+ // object is the obvious move and it is wrong: applyTransform sets the
83
+ // object's quaternion from the entity's authored rotation straight
84
+ // afterwards, silently discarding it — which left every "ground" standing
85
+ // upright like a wall. It renders convincingly until the camera crosses to
86
+ // the far side, at which point the scene becomes a flat fill and every
87
+ // measurement still says the character is dead centre, because it is —
88
+ // behind a 40x40 wall.
89
+ : new THREE.PlaneGeometry(s.x, s.z).rotateX(-Math.PI / 2);
42
90
  const mesh = new THREE.Mesh(geom, new THREE.MeshStandardMaterial({
43
91
  color: new THREE.Color(p.color ?? '#c8c8c8'), roughness: 0.85,
92
+ // The wedge/corner-wedge faces' winding was verified by hand (no
93
+ // browser available to render and visually confirm it in this pass) —
94
+ // DoubleSide is a pragmatic safety net against a winding mistake
95
+ // making a face invisible from its intended viewing side; it costs a
96
+ // little backface-culling perf on two low-poly shapes, not correctness.
97
+ side: (p.kind === 'wedge' || p.kind === 'corner-wedge') ? THREE.DoubleSide : THREE.FrontSide,
44
98
  }));
45
99
  mesh.castShadow = p.kind !== 'plane';
46
100
  mesh.receiveShadow = true;
@@ -320,23 +374,30 @@ export async function loadScene3D(scene3d, manifest, opts = {}) {
320
374
  const g = scene3d.gravity ?? { x: 0, y: -9.81, z: 0 };
321
375
  world = new opts.rapier.World(g);
322
376
  for (const e of scene3d.entities) {
323
- if (!e.collider)
377
+ // ADR-043 — a primitive Part gets physics even with no collider
378
+ // explicitly authored (an editor-placed Block should be standable on
379
+ // the moment it's dropped). An explicit collider always wins; this
380
+ // only fills the gap for a primitive entity that has none.
381
+ const collider = e.collider ?? (e.primitive ? defaultColliderForPrimitive(e.primitive) : undefined);
382
+ if (!collider)
324
383
  continue;
325
384
  const R = opts.rapier;
326
385
  const p = e.transform.position;
327
- const off = e.collider.offset ?? { x: 0, y: 0, z: 0 };
328
- const desc = e.collider.body === 'fixed' ? R.RigidBodyDesc.fixed()
329
- : e.collider.body === 'kinematic' ? R.RigidBodyDesc.kinematicPositionBased()
386
+ const off = collider.offset ?? { x: 0, y: 0, z: 0 };
387
+ const desc = collider.body === 'fixed' ? R.RigidBodyDesc.fixed()
388
+ : collider.body === 'kinematic' ? R.RigidBodyDesc.kinematicPositionBased()
330
389
  : R.RigidBodyDesc.dynamic();
331
390
  desc.setTranslation(p.x + off.x, p.y + off.y, p.z + off.z);
332
391
  const q = e.transform.rotation ?? IDENTITY_QUAT;
333
392
  desc.setRotation({ x: q[0], y: q[1], z: q[2], w: q[3] });
334
393
  const body = world.createRigidBody(desc);
335
- const s = e.collider.shape;
394
+ const s = collider.shape;
336
395
  const shape = s.kind === 'box' ? R.ColliderDesc.cuboid(s.halfExtents.x, s.halfExtents.y, s.halfExtents.z)
337
396
  : s.kind === 'sphere' ? R.ColliderDesc.ball(s.radius)
338
397
  : s.kind === 'capsule' ? R.ColliderDesc.capsule(s.halfHeight, s.radius)
339
- : null;
398
+ : s.kind === 'cylinder' ? R.ColliderDesc.cylinder(s.halfHeight, s.radius)
399
+ : s.kind === 'convexHull' ? R.ColliderDesc.convexHull(flattenPoints(s.points))
400
+ : null;
340
401
  if (!shape)
341
402
  throw new Error(`entity '${e.id}': trimesh colliders are not supported yet`);
342
403
  world.createCollider(shape, body);
@@ -1,9 +1,9 @@
1
1
  import * as THREE from 'three';
2
2
  import { OrbitControls } from 'three/examples/jsm/controls/OrbitControls.js';
3
- import { loadScene3D, loadModelAsset } from '../SceneLoader3D.js';
3
+ import { loadScene3D, loadModelAsset, makePrimitive } from '../SceneLoader3D.js';
4
4
  import { applySkin } from '../Skin.js';
5
5
  import { applyAttachments } from '../Attachments.js';
6
- import { singleModelManifest } from '../scene3d.js';
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
9
  import { loadHud3DScene } from '../hud3d/HudRuntime3D.js';
@@ -801,6 +801,8 @@ export async function runEditorDesignPlayer3D(renderer, opts = {}) {
801
801
  return onPatchEntity3d(data);
802
802
  if (data.type === 'umicat:editor:dropModel3d')
803
803
  return onDropModel3d(data);
804
+ if (data.type === 'umicat:editor:dropPrimitive3d')
805
+ return onDropPrimitive3d(data);
804
806
  if (data.type === 'umicat:editor:deleteEntity3d')
805
807
  return onDeleteEntity3d(data);
806
808
  if (data.type === 'umicat:editor:setGizmoMode3d') {
@@ -885,7 +887,7 @@ export async function runEditorDesignPlayer3D(renderer, opts = {}) {
885
887
  console.warn('[umicat/editor] 3D patch failed:', m.entityId, error);
886
888
  window.parent.postMessage({ type: 'umicat:editor:patchApplied3d', entityId: m.entityId, ok: !error, error }, '*');
887
889
  };
888
- const object = objectByEntity.get(m.entityId);
890
+ let object = objectByEntity.get(m.entityId);
889
891
  if (!object)
890
892
  return done(`no entity '${m.entityId}' in the scene being shown`);
891
893
  if (m.patch?.position !== undefined) {
@@ -937,6 +939,43 @@ export async function runEditorDesignPlayer3D(renderer, opts = {}) {
937
939
  return done(e instanceof Error ? e.message : String(e));
938
940
  }
939
941
  }
942
+ if (m.patch?.primitive !== undefined) {
943
+ // Unlike skin (repaints the existing material in place), a size
944
+ // change means a DIFFERENT geometry — there is no "resize this
945
+ // BoxGeometry" in three.js, so this rebuilds the mesh via the same
946
+ // `makePrimitive` the drop handler and the normal scene load both
947
+ // use, and swaps it in. Color-only patches rebuild too rather than
948
+ // branching (one code path, and rebuilding for a color change is
949
+ // cheap — these are a handful of triangles).
950
+ const authored = sceneData?.entities.find((e) => e.id === m.entityId);
951
+ if (!authored?.primitive)
952
+ return done(`entity '${m.entityId}' is not a primitive Part`);
953
+ authored.primitive = { ...authored.primitive, ...m.patch.primitive };
954
+ const fresh = makePrimitive(authored);
955
+ fresh.position.copy(object.position);
956
+ fresh.quaternion.copy(object.quaternion);
957
+ fresh.scale.copy(object.scale);
958
+ fresh.castShadow = authored.primitive.kind !== 'plane';
959
+ fresh.receiveShadow = true;
960
+ if (object instanceof THREE.Mesh) {
961
+ object.geometry.dispose();
962
+ (Array.isArray(object.material) ? object.material : [object.material]).forEach((mat) => mat.dispose());
963
+ }
964
+ scene?.remove(object);
965
+ scene?.add(fresh);
966
+ entityByObject.delete(object);
967
+ entityByObject.set(fresh, m.entityId);
968
+ objectByEntity.set(m.entityId, fresh);
969
+ // Same "gizmo attachment IS the selection state" convention the
970
+ // position/rotation/scale branch above already relies on — there is
971
+ // no separate "currently selected" variable to update.
972
+ if (gizmo.attached === object) {
973
+ gizmo.detach();
974
+ gizmo.attach(fresh, camera);
975
+ selectionBox.setFromObject(fresh);
976
+ }
977
+ object = fresh;
978
+ }
940
979
  done();
941
980
  }
942
981
  /**
@@ -994,6 +1033,52 @@ export async function runEditorDesignPlayer3D(renderer, opts = {}) {
994
1033
  manifest?.models?.push(modelAsset);
995
1034
  done(undefined, { x: object.position.x, y: object.position.y, z: object.position.z });
996
1035
  }
1036
+ /**
1037
+ * ADR-043 — ground-raycast placement for a built-in shape (Roblox-style
1038
+ * "Parts"), deliberately mirroring `onDropModel3d` almost line for line:
1039
+ * same ground-plane raycast, same registration into `entityByObject`/
1040
+ * `objectByEntity`/`scene` so the new object is immediately pickable and
1041
+ * draggable with ZERO changes to `pickEntityAt`/the gizmo (neither cares
1042
+ * how an object got into those maps).
1043
+ *
1044
+ * One real difference from a model drop: a Part needs a COLLIDER to be
1045
+ * useful as a building block, and the host has no way to know what
1046
+ * default this SDK would choose — so unlike `modelDropped3d` (which
1047
+ * never echoes the url back; the host already has it), this ack DOES
1048
+ * echo the derived `collider` so the host can persist the exact same
1049
+ * thing this live object was just given.
1050
+ */
1051
+ function onDropPrimitive3d(m) {
1052
+ const done = (error, position, collider) => {
1053
+ if (error)
1054
+ console.warn('[umicat/editor] 3D primitive drop failed:', m.entityId, error);
1055
+ window.parent.postMessage({ type: 'umicat:editor:primitiveDropped3d', entityId: m.entityId, ok: !error, error, position, collider }, '*');
1056
+ };
1057
+ if (!scene)
1058
+ return done('no scene loaded yet');
1059
+ if (objectByEntity.has(m.entityId))
1060
+ return done(`entity '${m.entityId}' already exists in this scene`);
1061
+ const worldPoint = raycastGroundPlane(m.x, m.y, 0);
1062
+ if (!worldPoint)
1063
+ return done('the drop point does not land on the ground plane (camera is looking edge-on)');
1064
+ // Sit the shape ON the ground rather than straddling it — see
1065
+ // `groundRestOffset`'s own doc comment.
1066
+ const restPosition = { x: worldPoint.x, y: worldPoint.y + groundRestOffset(m.primitive), z: worldPoint.z };
1067
+ const entity = { id: m.entityId, transform: { position: restPosition }, primitive: m.primitive };
1068
+ const object = makePrimitive(entity);
1069
+ object.position.set(restPosition.x, restPosition.y, restPosition.z);
1070
+ object.castShadow = m.primitive.kind !== 'plane';
1071
+ object.receiveShadow = true;
1072
+ scene.add(object);
1073
+ entityByObject.set(object, m.entityId);
1074
+ objectByEntity.set(m.entityId, object);
1075
+ const collider = defaultColliderForPrimitive(m.primitive);
1076
+ entity.collider = collider;
1077
+ // Keep this session's own closure state consistent with what the host
1078
+ // is about to write to disk — see onDropModel3d's matching comment.
1079
+ sceneData?.entities.push(entity);
1080
+ done(undefined, { x: object.position.x, y: object.position.y, z: object.position.z }, collider);
1081
+ }
997
1082
  /**
998
1083
  * Frees a subtree's GPU resources the same way the whole-scene `dispose()`
999
1084
  * in `SceneLoader3D.ts` does (geometry + material + every texture field a
package/dist/scene3d.d.ts CHANGED
@@ -47,6 +47,17 @@ export type ColliderShape = {
47
47
  kind: 'capsule';
48
48
  halfHeight: number;
49
49
  radius: number;
50
+ } | {
51
+ kind: 'cylinder';
52
+ halfHeight: number;
53
+ radius: number;
54
+ }
55
+ /** A convex hull of the given points — the right fit for an irregular
56
+ * solid (ADR-043's wedge/corner-wedge Parts) where Rapier has no native
57
+ * primitive shape of its own. */
58
+ | {
59
+ kind: 'convexHull';
60
+ points: Vec3[];
50
61
  }
51
62
  /** Static geometry only. Never use this for a dynamic body. */
52
63
  | {
@@ -89,9 +100,18 @@ export interface Entity3D {
89
100
  transform: Transform3D;
90
101
  /** Manifest asset id for a glTF model. */
91
102
  modelAssetId?: string;
92
- /** A built-in shape, for blocking out a scene before art exists. */
103
+ /**
104
+ * A built-in shape, for blocking out a scene before art exists — the
105
+ * data this platform's "Parts" editor UI places (ADR-043). `wedge` is a
106
+ * right-angle triangular-prism ramp (the slope rises from the `+z` edge
107
+ * to the `-z` edge); `corner-wedge` is a right pyramid whose apex sits
108
+ * above the `(-x,-z)` bottom corner rather than the centre (Roblox's
109
+ * `CornerWedgePart` shape) — see `wedgeVertices`/`cornerWedgeVertices`
110
+ * for the exact geometry both the renderer and the physics collider are
111
+ * built from.
112
+ */
93
113
  primitive?: {
94
- kind: 'box' | 'sphere' | 'plane' | 'cylinder';
114
+ kind: 'box' | 'sphere' | 'plane' | 'cylinder' | 'wedge' | 'corner-wedge';
95
115
  size?: Vec3;
96
116
  color?: string;
97
117
  };
@@ -119,6 +139,50 @@ export interface Entity3D {
119
139
  */
120
140
  castShadow?: boolean;
121
141
  }
142
+ /**
143
+ * The 6 distinct vertices of a wedge (a right-angle triangular-prism ramp)
144
+ * sized `size` and centred on the entity's own origin, in the SAME local
145
+ * space `Transform3D.position` places the entity's origin at.
146
+ *
147
+ * Exported as plain data — not hidden inside the renderer — so the
148
+ * RENDERER (`SceneLoader3D.makePrimitive`, 8 triangular faces built from
149
+ * these 6 points) and the PHYSICS COLLIDER (`defaultColliderForPrimitive`,
150
+ * a convex hull of the same 6 points) can never silently disagree about
151
+ * the shape's extent — a renderer/collider mismatch on an irregular solid
152
+ * is exactly the kind of bug that only shows up as "I can walk partway
153
+ * into the ramp."
154
+ *
155
+ * The ramp's slope rises from `z = +size.z/2` (low edge, on the ground)
156
+ * to `z = -size.z/2` (the top ridge) — i.e. standing at `-z` looking
157
+ * toward `+z`, the ramp climbs toward you.
158
+ */
159
+ export declare function wedgeVertices(size: Vec3): Vec3[];
160
+ /**
161
+ * The 5 distinct vertices of a corner wedge — a right pyramid whose apex
162
+ * sits above the `(-x,-z)` bottom corner rather than the centre (Roblox's
163
+ * `CornerWedgePart`), same role as `wedgeVertices` above.
164
+ */
165
+ export declare function cornerWedgeVertices(size: Vec3): Vec3[];
166
+ /**
167
+ * How far ABOVE a ground point a dropped primitive's ORIGIN should sit so
168
+ * its bottom rests exactly on the ground, not half-buried in it (ADR-043 —
169
+ * every primitive is built centred on its own origin, same as three.js's
170
+ * own `BoxGeometry`/`SphereGeometry`/etc., so placing the origin straight
171
+ * at the raycast point would sink half the shape below y=0).
172
+ */
173
+ export declare function groundRestOffset(primitive: NonNullable<Entity3D['primitive']>): number;
174
+ /**
175
+ * The collider an editor-placed primitive gets when nothing was authored
176
+ * explicitly (ADR-043 — a Part is a building block, not a decoration; it
177
+ * should be stood on the moment it's dropped, matching every other 3D
178
+ * editor's default). `body: 'fixed'` — a dropped block behaves like static
179
+ * level geometry (Roblox's own Part default, Anchored), not a physics prop
180
+ * that would fall over or get pushed the instant the game boots.
181
+ *
182
+ * Only ever consulted when `Entity3D.collider` is absent — an explicitly
183
+ * authored collider (hand-written JSON, agent-authored) always wins.
184
+ */
185
+ export declare function defaultColliderForPrimitive(primitive: NonNullable<Entity3D['primitive']>): Collider3D;
122
186
  /**
123
187
  * Semantic clip name → the clip actually inside the model.
124
188
  *
package/dist/scene3d.js CHANGED
@@ -23,6 +23,89 @@
23
23
  * - **Colliders are explicit.** Using a render mesh as a dynamic collider is the
24
24
  * classic way to make a game that is correct and unplayably slow.
25
25
  */
26
+ /**
27
+ * The 6 distinct vertices of a wedge (a right-angle triangular-prism ramp)
28
+ * sized `size` and centred on the entity's own origin, in the SAME local
29
+ * space `Transform3D.position` places the entity's origin at.
30
+ *
31
+ * Exported as plain data — not hidden inside the renderer — so the
32
+ * RENDERER (`SceneLoader3D.makePrimitive`, 8 triangular faces built from
33
+ * these 6 points) and the PHYSICS COLLIDER (`defaultColliderForPrimitive`,
34
+ * a convex hull of the same 6 points) can never silently disagree about
35
+ * the shape's extent — a renderer/collider mismatch on an irregular solid
36
+ * is exactly the kind of bug that only shows up as "I can walk partway
37
+ * into the ramp."
38
+ *
39
+ * The ramp's slope rises from `z = +size.z/2` (low edge, on the ground)
40
+ * to `z = -size.z/2` (the top ridge) — i.e. standing at `-z` looking
41
+ * toward `+z`, the ramp climbs toward you.
42
+ */
43
+ export function wedgeVertices(size) {
44
+ const hw = size.x / 2, hh = size.y / 2, hd = size.z / 2;
45
+ return [
46
+ { x: -hw, y: -hh, z: -hd }, // 0 bottom-back-left
47
+ { x: hw, y: -hh, z: -hd }, // 1 bottom-back-right
48
+ { x: hw, y: -hh, z: hd }, // 2 bottom-front-right
49
+ { x: -hw, y: -hh, z: hd }, // 3 bottom-front-left
50
+ { x: -hw, y: hh, z: -hd }, // 4 top-back-left (ridge)
51
+ { x: hw, y: hh, z: -hd }, // 5 top-back-right (ridge)
52
+ ];
53
+ }
54
+ /**
55
+ * The 5 distinct vertices of a corner wedge — a right pyramid whose apex
56
+ * sits above the `(-x,-z)` bottom corner rather than the centre (Roblox's
57
+ * `CornerWedgePart`), same role as `wedgeVertices` above.
58
+ */
59
+ export function cornerWedgeVertices(size) {
60
+ const hw = size.x / 2, hh = size.y / 2, hd = size.z / 2;
61
+ return [
62
+ { x: -hw, y: -hh, z: -hd }, // 0 bottom-back-left
63
+ { x: hw, y: -hh, z: -hd }, // 1 bottom-back-right
64
+ { x: hw, y: -hh, z: hd }, // 2 bottom-front-right
65
+ { x: -hw, y: -hh, z: hd }, // 3 bottom-front-left
66
+ { x: -hw, y: hh, z: -hd }, // 4 apex, above corner 0
67
+ ];
68
+ }
69
+ /**
70
+ * How far ABOVE a ground point a dropped primitive's ORIGIN should sit so
71
+ * its bottom rests exactly on the ground, not half-buried in it (ADR-043 —
72
+ * every primitive is built centred on its own origin, same as three.js's
73
+ * own `BoxGeometry`/`SphereGeometry`/etc., so placing the origin straight
74
+ * at the raycast point would sink half the shape below y=0).
75
+ */
76
+ export function groundRestOffset(primitive) {
77
+ const s = primitive.size ?? { x: 1, y: 1, z: 1 };
78
+ // A plane is zero-thickness and already flush at its own origin.
79
+ if (primitive.kind === 'plane')
80
+ return 0;
81
+ if (primitive.kind === 'sphere')
82
+ return s.x / 2;
83
+ // box / cylinder / wedge / corner-wedge are all centred on the Y axis
84
+ // the same way (`wedgeVertices`/`cornerWedgeVertices` run -hh..+hh too).
85
+ return s.y / 2;
86
+ }
87
+ /**
88
+ * The collider an editor-placed primitive gets when nothing was authored
89
+ * explicitly (ADR-043 — a Part is a building block, not a decoration; it
90
+ * should be stood on the moment it's dropped, matching every other 3D
91
+ * editor's default). `body: 'fixed'` — a dropped block behaves like static
92
+ * level geometry (Roblox's own Part default, Anchored), not a physics prop
93
+ * that would fall over or get pushed the instant the game boots.
94
+ *
95
+ * Only ever consulted when `Entity3D.collider` is absent — an explicitly
96
+ * authored collider (hand-written JSON, agent-authored) always wins.
97
+ */
98
+ export function defaultColliderForPrimitive(primitive) {
99
+ const s = primitive.size ?? { x: 1, y: 1, z: 1 };
100
+ const shape = primitive.kind === 'box' ? { kind: 'box', halfExtents: { x: s.x / 2, y: s.y / 2, z: s.z / 2 } }
101
+ : primitive.kind === 'sphere' ? { kind: 'sphere', radius: s.x / 2 }
102
+ : primitive.kind === 'cylinder' ? { kind: 'cylinder', halfHeight: s.y / 2, radius: s.x / 2 }
103
+ // A ground/wall sheet with zero thickness has nothing for Rapier to
104
+ // represent — give it a thin slab so it still blocks.
105
+ : primitive.kind === 'plane' ? { kind: 'box', halfExtents: { x: s.x / 2, y: 0.05, z: s.z / 2 } }
106
+ : { kind: 'convexHull', points: primitive.kind === 'wedge' ? wedgeVertices(s) : cornerWedgeVertices(s) };
107
+ return { shape, body: 'fixed' };
108
+ }
26
109
  /**
27
110
  * Order six faces named the way skybox packs name them.
28
111
  *
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@umicat/three-sdk",
3
- "version": "1.6.0",
3
+ "version": "1.7.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",