@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.
- package/dist/SceneLoader3D.d.ts +2 -1
- package/dist/SceneLoader3D.js +78 -17
- package/dist/editor/EditorDesignPlayer3D.js +88 -3
- package/dist/scene3d.d.ts +66 -2
- package/dist/scene3d.js +83 -0
- package/package.json +1 -1
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';
|
|
@@ -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
|
-
|
|
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
|
-
/**
|
|
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",
|