@umicat/three-sdk 1.5.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.
- package/README.md +8 -3
- package/dist/SceneLoader3D.d.ts +2 -1
- package/dist/SceneLoader3D.js +78 -17
- package/dist/editor/EditorDesignPlayer3D.js +346 -9
- package/dist/scene3d.d.ts +66 -2
- package/dist/scene3d.js +83 -0
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -26,9 +26,14 @@ from its CDN url, no manifest entry required — and a full Roblox/Unity-style
|
|
|
26
26
|
`umicat:editor:setGizmoMode3d`, posting `dragEnd3d`/`rotateEnd3d`/`scaleEnd3d`
|
|
27
27
|
on release — plus **Delete** (`umicat:editor:deleteEntity3d`) and
|
|
28
28
|
**transform-only undo** (Ctrl/Cmd+Z; the undo stack itself lives on the
|
|
29
|
-
host, this player only replays a `patchEntity3d` restore)).
|
|
30
|
-
|
|
31
|
-
|
|
29
|
+
host, this player only replays a `patchEntity3d` restore)). The desktop
|
|
30
|
+
camera matches Roblox Studio: left-click/drag selects and manipulates
|
|
31
|
+
(entities, the gizmo), right-drag looks around, WASD flies, Q/E move
|
|
32
|
+
straight down/up, Shift speeds up — touch is untouched (still orbit/
|
|
33
|
+
pinch-zoom via `OrbitControls`, which mouse input no longer reaches at
|
|
34
|
+
all). What it still does not have: undo of entity creation/deletion,
|
|
35
|
+
multi-select, a local/global axis toggle (the gizmo is local-space only),
|
|
36
|
+
middle-mouse pan, F-to-focus, or Studio's comma/period ring-rotate.
|
|
32
37
|
|
|
33
38
|
> This paragraph said "seed, not a product — no input system, no character
|
|
34
39
|
> controller, no audio, and no published package" for ten minor versions after
|
package/dist/SceneLoader3D.d.ts
CHANGED
|
@@ -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
|
*
|
package/dist/SceneLoader3D.js
CHANGED
|
@@ -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
|
-
|
|
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
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
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
|
-
|
|
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 =
|
|
328
|
-
const desc =
|
|
329
|
-
:
|
|
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 =
|
|
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
|
-
:
|
|
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';
|
|
@@ -154,6 +154,101 @@ export async function runEditorDesignPlayer3D(renderer, opts = {}) {
|
|
|
154
154
|
const camera = new THREE.PerspectiveCamera(50, window.innerWidth / window.innerHeight, 0.05, 2000);
|
|
155
155
|
const controls = new OrbitControls(camera, renderer.domElement);
|
|
156
156
|
controls.enableDamping = true;
|
|
157
|
+
// Desktop mouse input is owned entirely by the free-fly controller below
|
|
158
|
+
// (Roblox Studio's scheme: left-select/drag, right-drag-look, WASD/QE fly
|
|
159
|
+
// — see that block's own comment) instead of three.js's stock Unity/
|
|
160
|
+
// Blender-style left-drag-orbit. `controls.enabled` stays true FOREVER —
|
|
161
|
+
// never set false for a mouse reason — because `controls.touches` is
|
|
162
|
+
// deliberately left at its default (ONE: TOUCH.ROTATE, TWO:
|
|
163
|
+
// TOUCH.DOLLY_PAN): touch devices must keep orbiting/pinch-zooming exactly
|
|
164
|
+
// as before. Disabling only the three MOUSE bindings is what makes
|
|
165
|
+
// OrbitControls touch-only — confirmed against the pinned three@0.186.0
|
|
166
|
+
// source, `onMouseDown`'s button→action switch falls through to
|
|
167
|
+
// `default: this.state = STATE.NONE` once each mapping is null, so a
|
|
168
|
+
// mouse button-down is tracked (harmlessly) but never drives rotate/
|
|
169
|
+
// dolly/pan. Wheel is untouched on purpose — it still reaches
|
|
170
|
+
// OrbitControls' own (unmodified) wheel handler, which doesn't gate on
|
|
171
|
+
// `mouseButtons` at all; `syncOrbitTarget()` below is what makes that
|
|
172
|
+
// keep working as a plain forward/back dolly instead of zooming toward a
|
|
173
|
+
// stale point, with zero new wheel code needed.
|
|
174
|
+
controls.mouseButtons = { LEFT: null, MIDDLE: null, RIGHT: null };
|
|
175
|
+
// ---- Desktop free-fly camera (Roblox Studio scheme) ---------------------
|
|
176
|
+
//
|
|
177
|
+
// Yaw/pitch state, NOT re-derived from camera.quaternion every frame —
|
|
178
|
+
// storing the two angles (rather than reading them back out of the
|
|
179
|
+
// quaternion each update) is what avoids roll creeping in: each frame
|
|
180
|
+
// rebuilds the quaternion fresh from (pitch, yaw, 0) in Euler order
|
|
181
|
+
// 'YXZ'. That order specifically — yaw applied around WORLD Y outermost,
|
|
182
|
+
// pitch around the camera's OWN, already-yawed local X innermost — is the
|
|
183
|
+
// standard three.js FPS-camera convention (same one PointerLockControls
|
|
184
|
+
// uses): pitching rotates around an axis pitch itself doesn't move, so
|
|
185
|
+
// the camera's local X ("right") stays exactly horizontal no matter how
|
|
186
|
+
// far you look up/down, and roll can never accumulate since nothing ever
|
|
187
|
+
// writes the Euler's Z component.
|
|
188
|
+
let yaw = 0;
|
|
189
|
+
let pitch = 0;
|
|
190
|
+
const PITCH_LIMIT = Math.PI / 2 - 0.001; // just inside straight up/down — avoids the lookAt singularity
|
|
191
|
+
const flyEuler = new THREE.Euler(0, 0, 0, 'YXZ');
|
|
192
|
+
// How far in front of the camera OrbitControls' own `target` is kept at
|
|
193
|
+
// all times — a CONSTANT, seeded once from the scene's auto-frame
|
|
194
|
+
// distance (see the scene-load block below). Not the live distance to
|
|
195
|
+
// anything in the scene; purely the radius of the invisible pivot sphere
|
|
196
|
+
// the free-fly camera drags around with it so OrbitControls' touch/wheel
|
|
197
|
+
// code (which still runs `controls.update()` every frame and derives its
|
|
198
|
+
// own state from `camera.position`/`target`) always sees a sane,
|
|
199
|
+
// camera-relative target instead of a stale or distant one.
|
|
200
|
+
//
|
|
201
|
+
// This isn't just a touch nicety — confirmed against the pinned
|
|
202
|
+
// OrbitControls source, `update()` unconditionally ends with
|
|
203
|
+
// `this.object.lookAt(this.target)` on EVERY call, mouse-disabled or not.
|
|
204
|
+
// Without this, the render loop's own `controls.update()` call would snap
|
|
205
|
+
// the camera back to face a stale `target` every single frame, fighting
|
|
206
|
+
// whatever `applyLookDelta`/WASD just did.
|
|
207
|
+
let orbitDistance = 5;
|
|
208
|
+
// Scaled once per scene load (see below) so a tiny room and a sprawling
|
|
209
|
+
// level don't share one fixed speed — same "proportional to scene
|
|
210
|
+
// radius" convention `camera.near`/`camera.far` already use a few lines
|
|
211
|
+
// below in the scene-load block.
|
|
212
|
+
let flySpeed = 5;
|
|
213
|
+
const SHIFT_MULTIPLIER = 3;
|
|
214
|
+
const LOOK_SENSITIVITY = 0.0025; // radians per pixel of mouse movement
|
|
215
|
+
/**
|
|
216
|
+
* Keeps OrbitControls' own invariant (camera always faces `target`, at a
|
|
217
|
+
* sane distance) intact even though desktop input never goes through any
|
|
218
|
+
* OrbitControls method. Called after every desktop-driven camera change
|
|
219
|
+
* (a look-drag delta, a WASD/QE frame-step) — a no-op when nothing
|
|
220
|
+
* changed (recomputing from an unchanged camera pose reproduces the same
|
|
221
|
+
* target), but it's what keeps a TOUCH gesture that starts the instant
|
|
222
|
+
* after a desktop gesture ends from seeing a target that's still wherever
|
|
223
|
+
* it was left relative to the OLD camera pose.
|
|
224
|
+
*/
|
|
225
|
+
function syncOrbitTarget() {
|
|
226
|
+
const forward = new THREE.Vector3(0, 0, -1).applyQuaternion(camera.quaternion);
|
|
227
|
+
controls.target.copy(camera.position).addScaledVector(forward, orbitDistance);
|
|
228
|
+
}
|
|
229
|
+
/**
|
|
230
|
+
* Right-drag look: rotates the camera IN PLACE (yaw/pitch only, position
|
|
231
|
+
* untouched) — a FREE-LOOK, not an orbit, matching Roblox Studio's actual
|
|
232
|
+
* behavior ("dragging the mouse moves the camera view around") rather
|
|
233
|
+
* than three.js's default left-drag orbit-around-target. Seeded from the
|
|
234
|
+
* CURRENT `yaw`/`pitch` each call — those two module-scope variables are
|
|
235
|
+
* the single source of truth once seeded at scene load; re-deriving them
|
|
236
|
+
* from `camera.quaternion` via `Euler.setFromQuaternion` on every call
|
|
237
|
+
* would re-introduce the float drift/roll-creep this design avoids.
|
|
238
|
+
*/
|
|
239
|
+
function applyLookDelta(deltaX, deltaY) {
|
|
240
|
+
yaw -= deltaX * LOOK_SENSITIVITY;
|
|
241
|
+
pitch = THREE.MathUtils.clamp(pitch - deltaY * LOOK_SENSITIVITY, -PITCH_LIMIT, PITCH_LIMIT);
|
|
242
|
+
flyEuler.set(pitch, yaw, 0);
|
|
243
|
+
camera.quaternion.setFromEuler(flyEuler);
|
|
244
|
+
syncOrbitTarget();
|
|
245
|
+
}
|
|
246
|
+
// WASD/QE — held-key state, consumed every animation-loop frame with a
|
|
247
|
+
// real delta-time (see the render loop below) rather than acted on at
|
|
248
|
+
// keydown, so holding a key flies continuously instead of nudging once
|
|
249
|
+
// per press.
|
|
250
|
+
const movementKeysDown = new Set();
|
|
251
|
+
let shiftHeld = false;
|
|
157
252
|
// A single persistent marker, repositioned per click — the exact world
|
|
158
253
|
// point clicked (what "put a torch at the spot I clicked" needs), distinct
|
|
159
254
|
// from the box below (which entity was hit, not just where).
|
|
@@ -298,6 +393,15 @@ export async function runEditorDesignPlayer3D(renderer, opts = {}) {
|
|
|
298
393
|
scale: { x: o.scale.x, y: o.scale.y, z: o.scale.z },
|
|
299
394
|
};
|
|
300
395
|
};
|
|
396
|
+
// Test-only — the MAIN camera's current pose, for the desktop camera
|
|
397
|
+
// controls test suite (left-select/right-look/WASD/QE) to assert against
|
|
398
|
+
// without hand-deriving projection math — same posture as every other
|
|
399
|
+
// debug readback in this file.
|
|
400
|
+
globalThis.__umicatCameraPose =
|
|
401
|
+
() => ({
|
|
402
|
+
position: { x: camera.position.x, y: camera.position.y, z: camera.position.z },
|
|
403
|
+
quaternion: [camera.quaternion.x, camera.quaternion.y, camera.quaternion.z, camera.quaternion.w],
|
|
404
|
+
});
|
|
301
405
|
// Only VISIBLE entity roots are ever raycast against. three.js's
|
|
302
406
|
// Mesh.raycast does NOT check `.visible` on its own (confirmed against the
|
|
303
407
|
// pinned three source — no such check in Raycaster.js or Object3D.raycast),
|
|
@@ -324,6 +428,12 @@ export async function runEditorDesignPlayer3D(renderer, opts = {}) {
|
|
|
324
428
|
let downX = 0;
|
|
325
429
|
let downY = 0;
|
|
326
430
|
let moved = false;
|
|
431
|
+
// Right-button look-drag state — a separate gesture channel entirely from
|
|
432
|
+
// the left-button select/drag state above; see `applyLookDelta` and the
|
|
433
|
+
// `e.button === 2` branch in the pointer handlers below.
|
|
434
|
+
let lookDragging = false;
|
|
435
|
+
let lastLookX = 0;
|
|
436
|
+
let lastLookY = 0;
|
|
327
437
|
// Entity drag — Phase 1 of real editing (translate only, ground-plane
|
|
328
438
|
// constrained). Grabbing on an entity moves it; grabbing empty space/sky
|
|
329
439
|
// still orbits, same convention as Unity/Blender. Whether THIS gesture is
|
|
@@ -450,6 +560,30 @@ export async function runEditorDesignPlayer3D(renderer, opts = {}) {
|
|
|
450
560
|
moved = true;
|
|
451
561
|
};
|
|
452
562
|
const onPointerDown = (e) => {
|
|
563
|
+
// Right button — camera look-drag, a separate gesture channel entirely
|
|
564
|
+
// from everything below. Hard-returns before touching any select/drag/
|
|
565
|
+
// gizmo state, so a right-click can never be misread as the start of a
|
|
566
|
+
// left gesture.
|
|
567
|
+
if (e.button === 2) {
|
|
568
|
+
lookDragging = true;
|
|
569
|
+
lastLookX = e.clientX;
|
|
570
|
+
lastLookY = e.clientY;
|
|
571
|
+
try {
|
|
572
|
+
renderer.domElement.setPointerCapture(e.pointerId);
|
|
573
|
+
}
|
|
574
|
+
catch {
|
|
575
|
+
// Same posture as every other setPointerCapture call in this file —
|
|
576
|
+
// capture is an enhancement (keeps the look-drag live off-canvas),
|
|
577
|
+
// not a requirement.
|
|
578
|
+
}
|
|
579
|
+
return;
|
|
580
|
+
}
|
|
581
|
+
// Middle button, or anything else: not ours. Left (button 0) covers
|
|
582
|
+
// both a real left-click AND touch's primary contact (also button 0) —
|
|
583
|
+
// this is how touch stays on the exact same path it's always used,
|
|
584
|
+
// unaffected by the Roblox-style desktop remap.
|
|
585
|
+
if (e.button !== 0)
|
|
586
|
+
return;
|
|
453
587
|
downX = e.clientX;
|
|
454
588
|
downY = e.clientY;
|
|
455
589
|
moved = false;
|
|
@@ -459,6 +593,15 @@ export async function runEditorDesignPlayer3D(renderer, opts = {}) {
|
|
|
459
593
|
raycaster.setFromCamera(ndcFromEvent(e), camera);
|
|
460
594
|
const gizmoHit = gizmo.hitTest(raycaster);
|
|
461
595
|
if (gizmoHit && beginGizmoDrag(gizmoHit, e)) {
|
|
596
|
+
// `controls.enabled` toggling is a TOUCH-only concern now — mouse
|
|
597
|
+
// can't reach OrbitControls regardless, since all three of its
|
|
598
|
+
// mouse bindings are null (see `controls.mouseButtons` above). But
|
|
599
|
+
// `onPointerDown`/`Move`/`Up` have no `pointerType` check and never
|
|
600
|
+
// have, so a touch tap/drag on a gizmo handle or entity body runs
|
|
601
|
+
// through this exact same code — and `controls.touches` is
|
|
602
|
+
// deliberately left reactive. Without this toggle, a touch-drag on
|
|
603
|
+
// an entity would simultaneously manipulate it AND orbit the
|
|
604
|
+
// camera via OrbitControls' own touch handling.
|
|
462
605
|
controls.enabled = false;
|
|
463
606
|
try {
|
|
464
607
|
renderer.domElement.setPointerCapture(e.pointerId);
|
|
@@ -470,22 +613,25 @@ export async function runEditorDesignPlayer3D(renderer, opts = {}) {
|
|
|
470
613
|
}
|
|
471
614
|
}
|
|
472
615
|
const hit = pickEntityAt(e);
|
|
616
|
+
// Empty space: a left-drag here is a no-op now (Roblox scheme — rotate
|
|
617
|
+
// lives on the right button; OrbitControls' LEFT binding is null, so
|
|
618
|
+
// there's nothing left to fall through to). Reserved for a future
|
|
619
|
+
// marquee-select, not built yet.
|
|
473
620
|
if (!hit)
|
|
474
|
-
return;
|
|
621
|
+
return;
|
|
475
622
|
const objectPos = hit.entityRoot.getWorldPosition(new THREE.Vector3());
|
|
476
623
|
const plane = new THREE.Plane(new THREE.Vector3(0, 1, 0), -objectPos.y);
|
|
477
624
|
const planePoint = new THREE.Vector3();
|
|
478
625
|
// Looking exactly parallel to the ground has no plane intersection —
|
|
479
626
|
// vanishingly rare for this camera (auto-framed, always angled down at
|
|
480
|
-
// the scene) but cheap to guard
|
|
481
|
-
// start a drag from a garbage grab offset.
|
|
627
|
+
// the scene) but cheap to guard against a garbage grab offset.
|
|
482
628
|
if (!raycaster.ray.intersectPlane(plane, planePoint))
|
|
483
629
|
return;
|
|
484
630
|
dragEntity = hit.entityRoot;
|
|
485
631
|
dragEntityId = hit.entityId;
|
|
486
632
|
dragPlane = plane;
|
|
487
633
|
dragGrabOffset = planePoint.sub(objectPos);
|
|
488
|
-
controls.enabled = false;
|
|
634
|
+
controls.enabled = false; // touch-only concern now — see the gizmo-drag site's comment above
|
|
489
635
|
try {
|
|
490
636
|
renderer.domElement.setPointerCapture(e.pointerId);
|
|
491
637
|
}
|
|
@@ -499,6 +645,19 @@ export async function runEditorDesignPlayer3D(renderer, opts = {}) {
|
|
|
499
645
|
}
|
|
500
646
|
};
|
|
501
647
|
const onPointerMove = (e) => {
|
|
648
|
+
if (lookDragging) {
|
|
649
|
+
applyLookDelta(e.clientX - lastLookX, e.clientY - lastLookY);
|
|
650
|
+
lastLookX = e.clientX;
|
|
651
|
+
lastLookY = e.clientY;
|
|
652
|
+
return;
|
|
653
|
+
}
|
|
654
|
+
// Defensive: a right-drag that started off-canvas (so this handler
|
|
655
|
+
// never saw its pointerdown) shouldn't be misread as a left gesture.
|
|
656
|
+
// `buttons` (not `button`) is the live bitmask of currently-held
|
|
657
|
+
// buttons — needed because a pointermove with no button transition
|
|
658
|
+
// reports `button === -1`.
|
|
659
|
+
if (e.buttons === 2)
|
|
660
|
+
return;
|
|
502
661
|
if (Math.abs(e.clientX - downX) > 4 || Math.abs(e.clientY - downY) > 4)
|
|
503
662
|
moved = true;
|
|
504
663
|
if (gizmoDrag) {
|
|
@@ -519,6 +678,18 @@ export async function runEditorDesignPlayer3D(renderer, opts = {}) {
|
|
|
519
678
|
selectionBox.setFromObject(dragEntity);
|
|
520
679
|
};
|
|
521
680
|
const onPointerUp = (e) => {
|
|
681
|
+
if (lookDragging && e.button === 2) {
|
|
682
|
+
lookDragging = false;
|
|
683
|
+
try {
|
|
684
|
+
renderer.domElement.releasePointerCapture(e.pointerId);
|
|
685
|
+
}
|
|
686
|
+
catch {
|
|
687
|
+
// Already released, or never captured.
|
|
688
|
+
}
|
|
689
|
+
return;
|
|
690
|
+
}
|
|
691
|
+
if (e.button !== 0)
|
|
692
|
+
return;
|
|
522
693
|
try {
|
|
523
694
|
renderer.domElement.releasePointerCapture(e.pointerId);
|
|
524
695
|
}
|
|
@@ -591,6 +762,13 @@ export async function runEditorDesignPlayer3D(renderer, opts = {}) {
|
|
|
591
762
|
renderer.domElement.addEventListener('pointerdown', onPointerDown);
|
|
592
763
|
renderer.domElement.addEventListener('pointermove', onPointerMove);
|
|
593
764
|
renderer.domElement.addEventListener('pointerup', onPointerUp);
|
|
765
|
+
// Right-click is now a real camera gesture (look-drag) — the native
|
|
766
|
+
// context menu popping up mid-drag would be disruptive. Not strictly
|
|
767
|
+
// load-bearing today (OrbitControls' own `onContextMenu` already calls
|
|
768
|
+
// `preventDefault()` whenever `controls.enabled !== false`, and `enabled`
|
|
769
|
+
// stays permanently true now — see its own comment above), but this
|
|
770
|
+
// shouldn't be left as an implicit dependency on that internal detail.
|
|
771
|
+
renderer.domElement.addEventListener('contextmenu', (e) => e.preventDefault());
|
|
594
772
|
/**
|
|
595
773
|
* Host→iframe messages. `patchEntity3d` (0.18.0) was the first — everything
|
|
596
774
|
* before it went one way: the player reported picks and drags, and the
|
|
@@ -623,6 +801,8 @@ export async function runEditorDesignPlayer3D(renderer, opts = {}) {
|
|
|
623
801
|
return onPatchEntity3d(data);
|
|
624
802
|
if (data.type === 'umicat:editor:dropModel3d')
|
|
625
803
|
return onDropModel3d(data);
|
|
804
|
+
if (data.type === 'umicat:editor:dropPrimitive3d')
|
|
805
|
+
return onDropPrimitive3d(data);
|
|
626
806
|
if (data.type === 'umicat:editor:deleteEntity3d')
|
|
627
807
|
return onDeleteEntity3d(data);
|
|
628
808
|
if (data.type === 'umicat:editor:setGizmoMode3d') {
|
|
@@ -707,7 +887,7 @@ export async function runEditorDesignPlayer3D(renderer, opts = {}) {
|
|
|
707
887
|
console.warn('[umicat/editor] 3D patch failed:', m.entityId, error);
|
|
708
888
|
window.parent.postMessage({ type: 'umicat:editor:patchApplied3d', entityId: m.entityId, ok: !error, error }, '*');
|
|
709
889
|
};
|
|
710
|
-
|
|
890
|
+
let object = objectByEntity.get(m.entityId);
|
|
711
891
|
if (!object)
|
|
712
892
|
return done(`no entity '${m.entityId}' in the scene being shown`);
|
|
713
893
|
if (m.patch?.position !== undefined) {
|
|
@@ -759,6 +939,43 @@ export async function runEditorDesignPlayer3D(renderer, opts = {}) {
|
|
|
759
939
|
return done(e instanceof Error ? e.message : String(e));
|
|
760
940
|
}
|
|
761
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
|
+
}
|
|
762
979
|
done();
|
|
763
980
|
}
|
|
764
981
|
/**
|
|
@@ -816,6 +1033,52 @@ export async function runEditorDesignPlayer3D(renderer, opts = {}) {
|
|
|
816
1033
|
manifest?.models?.push(modelAsset);
|
|
817
1034
|
done(undefined, { x: object.position.x, y: object.position.y, z: object.position.z });
|
|
818
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
|
+
}
|
|
819
1082
|
/**
|
|
820
1083
|
* Frees a subtree's GPU resources the same way the whole-scene `dispose()`
|
|
821
1084
|
* in `SceneLoader3D.ts` does (geometry + material + every texture field a
|
|
@@ -933,10 +1196,72 @@ export async function runEditorDesignPlayer3D(renderer, opts = {}) {
|
|
|
933
1196
|
window.parent.postMessage({ type: 'umicat:editor:requestUndo3d' }, '*');
|
|
934
1197
|
}
|
|
935
1198
|
});
|
|
1199
|
+
// WASD/QE fly-camera + Shift speed boost — held-STATE, not a discrete
|
|
1200
|
+
// action, so this is a separate keydown/keyup PAIR rather than folded
|
|
1201
|
+
// into the action listener above (which only ever needs keydown). Same
|
|
1202
|
+
// focused-input guard as that listener, for the same reason it states
|
|
1203
|
+
// there — "costs nothing," even though nothing focusable exists in this
|
|
1204
|
+
// iframe today.
|
|
1205
|
+
const MOVEMENT_KEYS = new Set(['w', 'a', 's', 'd', 'q', 'e']);
|
|
1206
|
+
window.addEventListener('keydown', (e) => {
|
|
1207
|
+
const target = e.target;
|
|
1208
|
+
if (target && (target.tagName === 'INPUT' || target.tagName === 'TEXTAREA' || target.isContentEditable))
|
|
1209
|
+
return;
|
|
1210
|
+
if (e.key === 'Shift') {
|
|
1211
|
+
shiftHeld = true;
|
|
1212
|
+
return;
|
|
1213
|
+
}
|
|
1214
|
+
const key = e.key.toLowerCase();
|
|
1215
|
+
if (MOVEMENT_KEYS.has(key))
|
|
1216
|
+
movementKeysDown.add(key);
|
|
1217
|
+
});
|
|
1218
|
+
window.addEventListener('keyup', (e) => {
|
|
1219
|
+
if (e.key === 'Shift') {
|
|
1220
|
+
shiftHeld = false;
|
|
1221
|
+
return;
|
|
1222
|
+
}
|
|
1223
|
+
movementKeysDown.delete(e.key.toLowerCase());
|
|
1224
|
+
});
|
|
936
1225
|
// Design mode skips physics and animation entirely (loadScene3D's own
|
|
937
1226
|
// designMode flag) — there are no mixers to advance and no Rapier world to
|
|
938
|
-
// step, so the loop only ever needs to render
|
|
1227
|
+
// step, so the loop only ever needs to render (plus, now, the WASD/QE
|
|
1228
|
+
// fly-camera frame-step below).
|
|
1229
|
+
const flyClock = new THREE.Clock();
|
|
939
1230
|
renderer.setAnimationLoop(() => {
|
|
1231
|
+
// Clamped so a backgrounded tab's first frame back (an arbitrarily
|
|
1232
|
+
// large real-world gap) doesn't teleport the camera.
|
|
1233
|
+
const dt = Math.min(flyClock.getDelta(), 0.1);
|
|
1234
|
+
if (movementKeysDown.size > 0) {
|
|
1235
|
+
// Forward/right are horizontal-projected so looking down and
|
|
1236
|
+
// pressing W doesn't dive into the ground — Q/E (below) are the only
|
|
1237
|
+
// vertical axis. `right` isn't explicitly re-projected: under Euler
|
|
1238
|
+
// order 'YXZ', pitch rotates around the camera's own local X, which
|
|
1239
|
+
// pitch itself never moves, so local X stays horizontal by
|
|
1240
|
+
// construction — the `.y = 0; normalize()` here is cheap, defensive
|
|
1241
|
+
// insurance against float drift, not load-bearing math.
|
|
1242
|
+
const speed = flySpeed * (shiftHeld ? SHIFT_MULTIPLIER : 1) * dt;
|
|
1243
|
+
const forward = new THREE.Vector3(0, 0, -1).applyQuaternion(camera.quaternion);
|
|
1244
|
+
forward.y = 0;
|
|
1245
|
+
if (forward.lengthSq() > 1e-8)
|
|
1246
|
+
forward.normalize();
|
|
1247
|
+
const right = new THREE.Vector3(1, 0, 0).applyQuaternion(camera.quaternion);
|
|
1248
|
+
right.y = 0;
|
|
1249
|
+
if (right.lengthSq() > 1e-8)
|
|
1250
|
+
right.normalize();
|
|
1251
|
+
if (movementKeysDown.has('w'))
|
|
1252
|
+
camera.position.addScaledVector(forward, speed);
|
|
1253
|
+
if (movementKeysDown.has('s'))
|
|
1254
|
+
camera.position.addScaledVector(forward, -speed);
|
|
1255
|
+
if (movementKeysDown.has('d'))
|
|
1256
|
+
camera.position.addScaledVector(right, speed);
|
|
1257
|
+
if (movementKeysDown.has('a'))
|
|
1258
|
+
camera.position.addScaledVector(right, -speed);
|
|
1259
|
+
if (movementKeysDown.has('e'))
|
|
1260
|
+
camera.position.y += speed; // straight world-Y, independent of look direction
|
|
1261
|
+
if (movementKeysDown.has('q'))
|
|
1262
|
+
camera.position.y -= speed;
|
|
1263
|
+
syncOrbitTarget();
|
|
1264
|
+
}
|
|
940
1265
|
controls.update();
|
|
941
1266
|
if (!scene)
|
|
942
1267
|
return;
|
|
@@ -1013,7 +1338,19 @@ export async function runEditorDesignPlayer3D(renderer, opts = {}) {
|
|
|
1013
1338
|
camera.near = Math.max(radius / 100, 0.01);
|
|
1014
1339
|
camera.far = radius * 20;
|
|
1015
1340
|
camera.updateProjectionMatrix();
|
|
1016
|
-
controls.update();
|
|
1341
|
+
controls.update(); // still the simplest way to get camera.quaternion pointed at `center` — ends in object.lookAt(target)
|
|
1342
|
+
// Seed the free-fly controller's own state from the orientation
|
|
1343
|
+
// `controls.update()` just computed, instead of leaving OrbitControls
|
|
1344
|
+
// to keep deriving it forever (it won't — mouse can't drive it
|
|
1345
|
+
// anymore). `Euler.setFromQuaternion` with order 'YXZ' against a pure,
|
|
1346
|
+
// no-roll lookAt orientation decomposes exactly back into
|
|
1347
|
+
// (pitch, yaw, ~0): both constructions ultimately build "rotate to
|
|
1348
|
+
// face `center`, roll locked to zero, up = world Y."
|
|
1349
|
+
flyEuler.setFromQuaternion(camera.quaternion);
|
|
1350
|
+
pitch = THREE.MathUtils.clamp(flyEuler.x, -PITCH_LIMIT, PITCH_LIMIT);
|
|
1351
|
+
yaw = flyEuler.y;
|
|
1352
|
+
orbitDistance = camera.position.distanceTo(center);
|
|
1353
|
+
flySpeed = Math.max(radius * 0.6, 2); // proportional to scene scale, same convention camera.near/far use just above
|
|
1017
1354
|
window.parent.postMessage({ type: 'umicat:editor:scene3dLoaded', sceneId }, '*');
|
|
1018
1355
|
}
|
|
1019
1356
|
catch (e) {
|
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
|
-
/**
|
|
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.
|
|
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",
|