@umicat/three-sdk 1.3.0 → 1.5.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 +26 -1
- package/dist/SceneLoader3D.js +55 -2
- package/dist/editor/EditorDesignPlayer3D.d.ts +11 -8
- package/dist/editor/EditorDesignPlayer3D.js +75 -84
- package/dist/scene3d.d.ts +45 -1
- package/dist/scene3d.js +40 -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 } from './scene3d.js';
|
|
2
|
+
import { type Scene3D, type Manifest3D, 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). */
|
|
@@ -9,6 +9,10 @@ export interface LoadSceneOptions {
|
|
|
9
9
|
rapier?: RapierLike;
|
|
10
10
|
/** Design view: spawn the authored scene, run no game logic, play no clips. */
|
|
11
11
|
designMode?: boolean;
|
|
12
|
+
/** Needed only to PREFILTER a sky used for lighting (`Sky3D.lighting`).
|
|
13
|
+
* Optional because `loadScene3D` has never needed a renderer and a
|
|
14
|
+
* required one would break every caller; see `applySky`. */
|
|
15
|
+
renderer?: THREE.WebGLRenderer;
|
|
12
16
|
}
|
|
13
17
|
/** The slice of Rapier we use, typed structurally so this module needn't depend on it. */
|
|
14
18
|
export interface RapierLike {
|
|
@@ -75,4 +79,25 @@ export declare function loadModelAsset(manifest: Manifest3D, modelAssetId: strin
|
|
|
75
79
|
object: THREE.Object3D;
|
|
76
80
|
clips: THREE.AnimationClip[];
|
|
77
81
|
}>;
|
|
82
|
+
/**
|
|
83
|
+
* Paint the sky, and optionally light the scene from it.
|
|
84
|
+
*
|
|
85
|
+
* Three things here are easy to get wrong and silent when you do:
|
|
86
|
+
*
|
|
87
|
+
* 1. **Colour space.** A background texture has to be tagged
|
|
88
|
+
* `SRGBColorSpace`. Leave it linear and the sky comes out washed out —
|
|
89
|
+
* which reads as "the art is bad", not "the flag is wrong".
|
|
90
|
+
* 2. **Mapping.** An equirect image used as a background needs
|
|
91
|
+
* `EquirectangularReflectionMapping`; without it THREE treats it as a flat
|
|
92
|
+
* UV texture and you get a stretched smear.
|
|
93
|
+
* 3. **Prefiltering for lighting.** `scene.environment` wants a PMREM — a
|
|
94
|
+
* mip chain matched to roughness. Assigning the raw texture "works": shiny
|
|
95
|
+
* materials look right and rough ones reflect a sharp, wrong image. We warn
|
|
96
|
+
* rather than silently degrade, because the failure is subtle enough to
|
|
97
|
+
* ship.
|
|
98
|
+
*/
|
|
99
|
+
export declare function applySky(scene: THREE.Scene, sky: Sky3D, opts?: {
|
|
100
|
+
assetBase?: string;
|
|
101
|
+
renderer?: THREE.WebGLRenderer;
|
|
102
|
+
}): Promise<THREE.Texture>;
|
|
78
103
|
export declare function loadScene3D(scene3d: Scene3D, manifest: Manifest3D, opts?: LoadSceneOptions): Promise<LoadedScene3D>;
|
package/dist/SceneLoader3D.js
CHANGED
|
@@ -85,6 +85,56 @@ export async function loadModelAsset(manifest, modelAssetId, opts = {}) {
|
|
|
85
85
|
object.userData.modelAssetId = modelAssetId;
|
|
86
86
|
return { object, clips: gltf.animations };
|
|
87
87
|
}
|
|
88
|
+
/**
|
|
89
|
+
* Paint the sky, and optionally light the scene from it.
|
|
90
|
+
*
|
|
91
|
+
* Three things here are easy to get wrong and silent when you do:
|
|
92
|
+
*
|
|
93
|
+
* 1. **Colour space.** A background texture has to be tagged
|
|
94
|
+
* `SRGBColorSpace`. Leave it linear and the sky comes out washed out —
|
|
95
|
+
* which reads as "the art is bad", not "the flag is wrong".
|
|
96
|
+
* 2. **Mapping.** An equirect image used as a background needs
|
|
97
|
+
* `EquirectangularReflectionMapping`; without it THREE treats it as a flat
|
|
98
|
+
* UV texture and you get a stretched smear.
|
|
99
|
+
* 3. **Prefiltering for lighting.** `scene.environment` wants a PMREM — a
|
|
100
|
+
* mip chain matched to roughness. Assigning the raw texture "works": shiny
|
|
101
|
+
* materials look right and rough ones reflect a sharp, wrong image. We warn
|
|
102
|
+
* rather than silently degrade, because the failure is subtle enough to
|
|
103
|
+
* ship.
|
|
104
|
+
*/
|
|
105
|
+
export async function applySky(scene, sky, opts = {}) {
|
|
106
|
+
const base = opts.assetBase ?? '';
|
|
107
|
+
let texture;
|
|
108
|
+
if (sky.kind === 'cubemap') {
|
|
109
|
+
if (sky.paths?.length !== 6) {
|
|
110
|
+
throw new Error(`cubemap sky needs exactly 6 faces, got ${sky.paths?.length ?? 0} — use cubeFacesFromNames to order them`);
|
|
111
|
+
}
|
|
112
|
+
texture = await new THREE.CubeTextureLoader().loadAsync(sky.paths.map((p) => base + p));
|
|
113
|
+
}
|
|
114
|
+
else {
|
|
115
|
+
texture = await new THREE.TextureLoader().loadAsync(base + sky.path);
|
|
116
|
+
texture.mapping = THREE.EquirectangularReflectionMapping;
|
|
117
|
+
}
|
|
118
|
+
texture.colorSpace = THREE.SRGBColorSpace;
|
|
119
|
+
scene.background = texture;
|
|
120
|
+
if (sky.lighting) {
|
|
121
|
+
if (opts.renderer) {
|
|
122
|
+
const pmrem = new THREE.PMREMGenerator(opts.renderer);
|
|
123
|
+
scene.environment = pmrem.fromEquirectangular
|
|
124
|
+
? (sky.kind === 'equirect'
|
|
125
|
+
? pmrem.fromEquirectangular(texture).texture
|
|
126
|
+
: pmrem.fromCubemap(texture).texture)
|
|
127
|
+
: texture;
|
|
128
|
+
pmrem.dispose();
|
|
129
|
+
}
|
|
130
|
+
else {
|
|
131
|
+
console.warn('[three-sdk] sky lighting requested without a renderer — using the raw texture. '
|
|
132
|
+
+ 'Rough materials will reflect a sharp image. Pass `renderer` to loadScene3D to prefilter it.');
|
|
133
|
+
scene.environment = texture;
|
|
134
|
+
}
|
|
135
|
+
}
|
|
136
|
+
return texture;
|
|
137
|
+
}
|
|
88
138
|
export async function loadScene3D(scene3d, manifest, opts = {}) {
|
|
89
139
|
const problems = validateScene(scene3d);
|
|
90
140
|
if (problems.length) {
|
|
@@ -93,8 +143,11 @@ export async function loadScene3D(scene3d, manifest, opts = {}) {
|
|
|
93
143
|
throw new Error(`scene3d '${scene3d.id}' is invalid:\n - ${problems.join('\n - ')}`);
|
|
94
144
|
}
|
|
95
145
|
const scene = new THREE.Scene();
|
|
96
|
-
|
|
97
|
-
|
|
146
|
+
const bg = scene3d.environment?.background;
|
|
147
|
+
if (typeof bg === 'string')
|
|
148
|
+
scene.background = new THREE.Color(bg);
|
|
149
|
+
else if (bg)
|
|
150
|
+
await applySky(scene, bg, opts);
|
|
98
151
|
if (scene3d.environment?.fog) {
|
|
99
152
|
const f = scene3d.environment.fog;
|
|
100
153
|
scene.fog = new THREE.Fog(new THREE.Color(f.color), f.near, f.far);
|
|
@@ -48,14 +48,17 @@ export interface EditorDesignPlayer3DOptions {
|
|
|
48
48
|
* THIS iframe rather than the host page — posts `requestUndo3d` asking
|
|
49
49
|
* the host to do its thing. No entity-creation/deletion undo yet (only
|
|
50
50
|
* transform edits on an entity that already exists).
|
|
51
|
-
* - **HUD
|
|
52
|
-
*
|
|
53
|
-
*
|
|
54
|
-
*
|
|
55
|
-
*
|
|
56
|
-
* boot like every other hand-authored markup.
|
|
57
|
-
*
|
|
58
|
-
*
|
|
51
|
+
* - **HUD overlay** (2026-10-07) — the bound HUD's widgets (pure-DOM, same
|
|
52
|
+
* `loadHud3DScene` Play mode uses, via `loadHud3d{hudId,hudFile}` — the
|
|
53
|
+
* host fetches/parses the file, this only mounts it) render into `#hud`
|
|
54
|
+
* ALWAYS ALONGSIDE the world scene, not as a separate mode — `#hud` is
|
|
55
|
+
* un-hidden once, permanently, right after `hideNonCanvasStaticMarkup`
|
|
56
|
+
* below hides it at boot like every other hand-authored markup. Click,
|
|
57
|
+
* create (`createHud3dEntity`), and patch (`patchHud3dEntity`) all work
|
|
58
|
+
* the same way they do on world entities; selecting a HUD widget clears
|
|
59
|
+
* any active world selection and vice versa (see `clearWorldSelection`),
|
|
60
|
+
* so only one of the two ever looks selected at once. `setHudVisible3d`
|
|
61
|
+
* is a purely cosmetic show/hide toggle for the whole HUD layer.
|
|
59
62
|
*
|
|
60
63
|
* Takes over `renderer`'s animation loop entirely for the rest of the page's
|
|
61
64
|
* life — there is no scene-swap API and no teardown, matching how the
|
|
@@ -43,14 +43,17 @@ import { loadHud3DScene } from '../hud3d/HudRuntime3D.js';
|
|
|
43
43
|
* THIS iframe rather than the host page — posts `requestUndo3d` asking
|
|
44
44
|
* the host to do its thing. No entity-creation/deletion undo yet (only
|
|
45
45
|
* transform edits on an entity that already exists).
|
|
46
|
-
* - **HUD
|
|
47
|
-
*
|
|
48
|
-
*
|
|
49
|
-
*
|
|
50
|
-
*
|
|
51
|
-
* boot like every other hand-authored markup.
|
|
52
|
-
*
|
|
53
|
-
*
|
|
46
|
+
* - **HUD overlay** (2026-10-07) — the bound HUD's widgets (pure-DOM, same
|
|
47
|
+
* `loadHud3DScene` Play mode uses, via `loadHud3d{hudId,hudFile}` — the
|
|
48
|
+
* host fetches/parses the file, this only mounts it) render into `#hud`
|
|
49
|
+
* ALWAYS ALONGSIDE the world scene, not as a separate mode — `#hud` is
|
|
50
|
+
* un-hidden once, permanently, right after `hideNonCanvasStaticMarkup`
|
|
51
|
+
* below hides it at boot like every other hand-authored markup. Click,
|
|
52
|
+
* create (`createHud3dEntity`), and patch (`patchHud3dEntity`) all work
|
|
53
|
+
* the same way they do on world entities; selecting a HUD widget clears
|
|
54
|
+
* any active world selection and vice versa (see `clearWorldSelection`),
|
|
55
|
+
* so only one of the two ever looks selected at once. `setHudVisible3d`
|
|
56
|
+
* is a purely cosmetic show/hide toggle for the whole HUD layer.
|
|
54
57
|
*
|
|
55
58
|
* Takes over `renderer`'s animation loop entirely for the rest of the page's
|
|
56
59
|
* life — there is no scene-swap API and no teardown, matching how the
|
|
@@ -64,28 +67,29 @@ import { loadHud3DScene } from '../hud3d/HudRuntime3D.js';
|
|
|
64
67
|
*/
|
|
65
68
|
export async function runEditorDesignPlayer3D(renderer, opts = {}) {
|
|
66
69
|
hideNonCanvasStaticMarkup(renderer.domElement);
|
|
67
|
-
// ---- HUD
|
|
70
|
+
// ---- World + HUD as simultaneous layers (2026-10-07) ----------------------
|
|
68
71
|
//
|
|
69
|
-
// World
|
|
70
|
-
//
|
|
71
|
-
//
|
|
72
|
-
//
|
|
73
|
-
//
|
|
74
|
-
//
|
|
75
|
-
//
|
|
76
|
-
//
|
|
77
|
-
//
|
|
72
|
+
// World and HUD used to be mutually-exclusive editor sub-modes (a backdrop
|
|
73
|
+
// covered the canvas while HUD was "active"). Replaced: both are always
|
|
74
|
+
// visible and interactive together, Figma-layers style. This needs no new
|
|
75
|
+
// hit-testing code — `renderer.domElement.addEventListener('pointerdown', …)`
|
|
76
|
+
// below attaches directly to the canvas, and HUD widgets are plain DOM
|
|
77
|
+
// sitting on top of it, so ordinary browser hit-testing already gives
|
|
78
|
+
// "topmost element wins": a click landing on a widget never reaches the
|
|
79
|
+
// canvas at all, and a click on genuinely empty HUD space falls through for
|
|
80
|
+
// free (every widget is `position:fixed`, so the HUD root's own box
|
|
81
|
+
// collapses to ~zero area — there's nothing there to intercept a click
|
|
82
|
+
// except actual widgets). `#hud` itself (hidden by `hideNonCanvasStaticMarkup`
|
|
83
|
+
// above, same as every other hand-authored markup) is un-hidden once, right
|
|
84
|
+
// below, for the rest of the Edit session — no more toggling.
|
|
78
85
|
//
|
|
79
|
-
//
|
|
80
|
-
//
|
|
81
|
-
//
|
|
82
|
-
//
|
|
83
|
-
//
|
|
84
|
-
|
|
85
|
-
// more precise: visible exactly when something is actually shown in it).
|
|
86
|
-
let hudMode = 'world';
|
|
86
|
+
// The one thing that doesn't come for free: only one thing should ever
|
|
87
|
+
// look/act selected at a time. World's marker/selectionBox/gizmo and HUD's
|
|
88
|
+
// yellow outline are independent visual states that never used to coexist —
|
|
89
|
+
// `selectHudEntity`/the world pick handlers below now cross-clear each
|
|
90
|
+
// other (see `clearWorldSelection` and its two call sites).
|
|
91
|
+
document.getElementById('hud')?.style.setProperty('display', '');
|
|
87
92
|
let hudHandle = null;
|
|
88
|
-
let hudBackdrop = null;
|
|
89
93
|
// Selection (Phase 4) — a single id, same "one thing selected at a time"
|
|
90
94
|
// model world mode's marker/selectionBox/gizmo already use. No gizmo for
|
|
91
95
|
// HUD widgets (there's nothing to move in 3D — repositioning is an anchor/
|
|
@@ -93,24 +97,6 @@ export async function runEditorDesignPlayer3D(renderer, opts = {}) {
|
|
|
93
97
|
// selection here only needs a visual outline + telling the host what's
|
|
94
98
|
// selected so the Inspector has something to show.
|
|
95
99
|
let hudSelectedId = null;
|
|
96
|
-
function ensureHudBackdrop() {
|
|
97
|
-
if (hudBackdrop)
|
|
98
|
-
return hudBackdrop;
|
|
99
|
-
// Created AFTER hideNonCanvasStaticMarkup already ran once at the top of
|
|
100
|
-
// this function — that function only hides EXISTING document.body
|
|
101
|
-
// children at the moment it's called, so anything appended after is
|
|
102
|
-
// simply never touched by it. No data-umicat-keep needed here either.
|
|
103
|
-
const el = document.createElement('div');
|
|
104
|
-
el.id = 'umicat-hud3d-editor-backdrop';
|
|
105
|
-
// z-index 15: above the canvas (no explicit stacking, renders at the
|
|
106
|
-
// normal in-flow level) but below `#hud` (z-index:20 in every template,
|
|
107
|
-
// see umicat-template/index.html) — the real HUD widgets, mounted into
|
|
108
|
-
// `#hud`, sit on TOP of this backdrop, not behind it.
|
|
109
|
-
el.style.cssText = 'position:fixed;inset:0;z-index:15;background:#2a2d32;display:none;';
|
|
110
|
-
document.body.appendChild(el);
|
|
111
|
-
hudBackdrop = el;
|
|
112
|
-
return el;
|
|
113
|
-
}
|
|
114
100
|
const HUD_OUTLINE = '2px solid #ffd23f'; // same selection-yellow world mode's BoxHelper uses
|
|
115
101
|
/** Select (or clear, for `null`) a HUD entity — outline + ack to the host.
|
|
116
102
|
* Re-looked-up by id on every call rather than holding an element
|
|
@@ -152,6 +138,10 @@ export async function runEditorDesignPlayer3D(renderer, opts = {}) {
|
|
|
152
138
|
handle.root.addEventListener('click', (e) => {
|
|
153
139
|
const target = e.target?.closest('[data-hud3d-entity-id]');
|
|
154
140
|
selectHudEntity(target?.dataset.hud3dEntityId ?? null);
|
|
141
|
+
// Cross-layer deselect — a HUD pick and a World selection should never
|
|
142
|
+
// both look active at once (see this file's header comment).
|
|
143
|
+
if (gizmo.attached)
|
|
144
|
+
clearWorldSelection();
|
|
155
145
|
});
|
|
156
146
|
}
|
|
157
147
|
function mountHud(hudScene) {
|
|
@@ -161,25 +151,6 @@ export async function runEditorDesignPlayer3D(renderer, opts = {}) {
|
|
|
161
151
|
if (hudHandle)
|
|
162
152
|
wireHudEditorInteractivity(hudHandle);
|
|
163
153
|
}
|
|
164
|
-
function enterHudMode(hudScene) {
|
|
165
|
-
hudMode = 'hud';
|
|
166
|
-
ensureHudBackdrop().style.display = 'block';
|
|
167
|
-
const hudEl = document.getElementById('hud');
|
|
168
|
-
if (hudEl)
|
|
169
|
-
hudEl.style.display = '';
|
|
170
|
-
mountHud(hudScene);
|
|
171
|
-
}
|
|
172
|
-
function exitHudMode() {
|
|
173
|
-
hudMode = 'world';
|
|
174
|
-
if (hudBackdrop)
|
|
175
|
-
hudBackdrop.style.display = 'none';
|
|
176
|
-
const hudEl = document.getElementById('hud');
|
|
177
|
-
if (hudEl)
|
|
178
|
-
hudEl.style.display = 'none';
|
|
179
|
-
hudHandle?.destroy();
|
|
180
|
-
hudHandle = null;
|
|
181
|
-
hudSelectedId = null;
|
|
182
|
-
}
|
|
183
154
|
const camera = new THREE.PerspectiveCamera(50, window.innerWidth / window.innerHeight, 0.05, 2000);
|
|
184
155
|
const controls = new OrbitControls(camera, renderer.domElement);
|
|
185
156
|
controls.enableDamping = true;
|
|
@@ -370,6 +341,22 @@ export async function runEditorDesignPlayer3D(renderer, opts = {}) {
|
|
|
370
341
|
let dragEntityId = null;
|
|
371
342
|
let dragPlane = null;
|
|
372
343
|
let dragGrabOffset = null; // world-space, plane-point minus object position at grab time
|
|
344
|
+
/**
|
|
345
|
+
* Deselect whatever's selected in WORLD — marker/box hidden, gizmo
|
|
346
|
+
* detached, and (new, 2026-10-07) the host told, since a miss-click used
|
|
347
|
+
* to deselect visually but post nothing: the host's own `lastPick` kept
|
|
348
|
+
* the stale prior selection forever, harmless only while the Inspector's
|
|
349
|
+
* visibility was gated on a now-removed "world mode" flag rather than on
|
|
350
|
+
* `lastPick` itself. Also called from the HUD click listener below (cross-
|
|
351
|
+
* layer deselect — see this file's header comment on why only one of
|
|
352
|
+
* World/HUD should ever look selected at once).
|
|
353
|
+
*/
|
|
354
|
+
function clearWorldSelection() {
|
|
355
|
+
marker.visible = false;
|
|
356
|
+
selectionBox.visible = false;
|
|
357
|
+
gizmo.detach();
|
|
358
|
+
window.parent.postMessage({ type: 'umicat:editor:pickPoint3d', x: 0, y: 0, z: 0, entityId: null }, '*');
|
|
359
|
+
}
|
|
373
360
|
let gizmoDrag = null;
|
|
374
361
|
const beginGizmoDrag = (hit, e) => {
|
|
375
362
|
const obj = gizmo.attached;
|
|
@@ -583,11 +570,13 @@ export async function runEditorDesignPlayer3D(renderer, opts = {}) {
|
|
|
583
570
|
// Clicked empty space with nothing grabbed — deselect. Previously a
|
|
584
571
|
// no-op (the marker/box from a PRIOR selection just stayed on
|
|
585
572
|
// screen); now load-bearing, since the gizmo also needs to disappear.
|
|
586
|
-
|
|
587
|
-
|
|
588
|
-
|
|
573
|
+
clearWorldSelection();
|
|
574
|
+
if (hudSelectedId)
|
|
575
|
+
selectHudEntity(null); // cross-layer deselect
|
|
589
576
|
return;
|
|
590
577
|
}
|
|
578
|
+
if (hudSelectedId)
|
|
579
|
+
selectHudEntity(null); // cross-layer deselect
|
|
591
580
|
marker.position.copy(hit.point);
|
|
592
581
|
marker.visible = true;
|
|
593
582
|
// Frame the whole entity the click landed on, not just the point on its
|
|
@@ -644,30 +633,28 @@ export async function runEditorDesignPlayer3D(renderer, opts = {}) {
|
|
|
644
633
|
}
|
|
645
634
|
return;
|
|
646
635
|
}
|
|
647
|
-
//
|
|
648
|
-
//
|
|
649
|
-
//
|
|
650
|
-
|
|
651
|
-
|
|
652
|
-
|
|
653
|
-
|
|
654
|
-
|
|
655
|
-
|
|
636
|
+
// Cosmetic-only visibility toggle (the eye icon in the host toolbar) —
|
|
637
|
+
// independent of whether a HUD is actually mounted. World/HUD used to be
|
|
638
|
+
// a mutually-exclusive mode switch (`setEditMode3d`); both layers are
|
|
639
|
+
// always visible+interactive now (see this file's header comment), so
|
|
640
|
+
// this is the only thing left to toggle, and it's purely cosmetic.
|
|
641
|
+
if (data.type === 'umicat:editor:setHudVisible3d') {
|
|
642
|
+
const visible = data.visible;
|
|
643
|
+
const hudEl = document.getElementById('hud');
|
|
644
|
+
if (typeof visible === 'boolean' && hudEl)
|
|
645
|
+
hudEl.style.display = visible ? '' : 'none';
|
|
656
646
|
return;
|
|
657
647
|
}
|
|
658
648
|
// The host already fetched + parsed the HUD file (it owns the binding
|
|
659
649
|
// lookup and the workspace-file read, same division of labor as 2D's
|
|
660
650
|
// `EditorLoadHudMessage`) — this just (re)mounts it. Used both for the
|
|
661
|
-
//
|
|
662
|
-
//
|
|
663
|
-
//
|
|
651
|
+
// active WORLD scene's bound HUD (auto-mounted as soon as the scene
|
|
652
|
+
// loads, host-side) and for "switch which HUD is being edited" (HUD
|
|
653
|
+
// browser, Phase 3) — no mode distinction between the two anymore.
|
|
664
654
|
if (data.type === 'umicat:editor:loadHud3d') {
|
|
665
655
|
const m = data;
|
|
666
656
|
const hudFile = (typeof m.hudId === 'string' ? m.hudFile : undefined);
|
|
667
|
-
|
|
668
|
-
enterHudMode(hudFile ?? null);
|
|
669
|
-
else
|
|
670
|
-
mountHud(hudFile ?? null);
|
|
657
|
+
mountHud(hudFile ?? null);
|
|
671
658
|
window.parent.postMessage({ type: 'umicat:editor:hud3dLoaded', hudId: typeof m.hudId === 'string' ? m.hudId : null, error: !hudFile }, '*');
|
|
672
659
|
return;
|
|
673
660
|
}
|
|
@@ -983,7 +970,11 @@ export async function runEditorDesignPlayer3D(renderer, opts = {}) {
|
|
|
983
970
|
try {
|
|
984
971
|
manifest = await fetch('scenes3d/manifest.json').then((r) => r.json());
|
|
985
972
|
sceneData = await fetch(`scenes3d/${sceneId}.json`).then((r) => r.json());
|
|
986
|
-
|
|
973
|
+
// `renderer` is passed only so a sky used for lighting gets prefiltered
|
|
974
|
+
// here too. Without it the design view would warn on every scene load and
|
|
975
|
+
// show rough materials reflecting a sharp sky — a difference from the game
|
|
976
|
+
// that the author would have to discover by publishing.
|
|
977
|
+
const loaded = await loadScene3D(sceneData, manifest, { assetBase: '', designMode: true, renderer });
|
|
987
978
|
worn = loaded.attachments;
|
|
988
979
|
scene = loaded.scene;
|
|
989
980
|
// Atmospheric fog is a LOOK, and this view's job is to show where things
|
package/dist/scene3d.d.ts
CHANGED
|
@@ -191,12 +191,56 @@ export interface Light3D {
|
|
|
191
191
|
position?: Vec3;
|
|
192
192
|
castShadow?: boolean;
|
|
193
193
|
}
|
|
194
|
+
/**
|
|
195
|
+
* The six faces of a cube map, in THREE's `CubeTextureLoader` order:
|
|
196
|
+
* **+X, −X, +Y, −Y, +Z, −Z**.
|
|
197
|
+
*
|
|
198
|
+
* This is NOT the order skybox packs name their files in. The common
|
|
199
|
+
* convention is `rt lf up dn ft bk`, which maps to +X −X +Y −Y +Z −Z — so
|
|
200
|
+
* `ft` (front) is +Z and `bk` is −Z. Hand the array in the wrong order and
|
|
201
|
+
* nothing errors: you get a sky that is inside out, or whose horizon is on
|
|
202
|
+
* the ceiling. Use `cubeFacesFromNames` rather than ordering by hand.
|
|
203
|
+
*/
|
|
204
|
+
export type CubeFaces = [string, string, string, string, string, string];
|
|
205
|
+
/**
|
|
206
|
+
* What fills the sky behind the scene.
|
|
207
|
+
*
|
|
208
|
+
* Two kinds, because those are the two a renderer can use directly. A
|
|
209
|
+
* cross-layout sheet (one 4:3 image holding all six faces) is deliberately
|
|
210
|
+
* NOT a kind — slicing it belongs at import time, once, not in every game's
|
|
211
|
+
* first frame. Cross layouts differ between packs (horizontal, vertical,
|
|
212
|
+
* strip) and getting it wrong is silent, so the knowledge lives in one place.
|
|
213
|
+
*/
|
|
214
|
+
export type Sky3D = {
|
|
215
|
+
kind: 'equirect';
|
|
216
|
+
/** One 2:1 equirectangular image, resolved against `assetBase`. */
|
|
217
|
+
path: string;
|
|
218
|
+
/** Also light the scene from it (PBR reflections), not just paint the
|
|
219
|
+
* background. Needs `renderer` in the load options to be prefiltered;
|
|
220
|
+
* without one it still works but rough materials reflect badly. */
|
|
221
|
+
lighting?: boolean;
|
|
222
|
+
} | {
|
|
223
|
+
kind: 'cubemap';
|
|
224
|
+
paths: CubeFaces;
|
|
225
|
+
lighting?: boolean;
|
|
226
|
+
};
|
|
227
|
+
/**
|
|
228
|
+
* Order six faces named the way skybox packs name them.
|
|
229
|
+
*
|
|
230
|
+
* Accepts the usual suffixes (`rt/lf/up/dn/ft/bk`, `right/left/...`,
|
|
231
|
+
* `px/nx/py/ny/pz/nz`, `east/west/...`) case-insensitively and returns them
|
|
232
|
+
* in THREE's order. Throws when a face is missing or duplicated, because the
|
|
233
|
+
* alternative is a silently wrong sky.
|
|
234
|
+
*/
|
|
235
|
+
export declare function cubeFacesFromNames(paths: string[]): CubeFaces;
|
|
194
236
|
export interface Scene3D {
|
|
195
237
|
schemaVersion: 1;
|
|
196
238
|
id: string;
|
|
197
239
|
name?: string;
|
|
198
240
|
environment?: {
|
|
199
|
-
|
|
241
|
+
/** A colour (any CSS string) or a sky texture. A bare string stays a
|
|
242
|
+
* colour, so every scene authored before skies keeps working. */
|
|
243
|
+
background?: string | Sky3D;
|
|
200
244
|
fog?: {
|
|
201
245
|
color: string;
|
|
202
246
|
near: number;
|
package/dist/scene3d.js
CHANGED
|
@@ -23,6 +23,46 @@
|
|
|
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
|
+
* Order six faces named the way skybox packs name them.
|
|
28
|
+
*
|
|
29
|
+
* Accepts the usual suffixes (`rt/lf/up/dn/ft/bk`, `right/left/...`,
|
|
30
|
+
* `px/nx/py/ny/pz/nz`, `east/west/...`) case-insensitively and returns them
|
|
31
|
+
* in THREE's order. Throws when a face is missing or duplicated, because the
|
|
32
|
+
* alternative is a silently wrong sky.
|
|
33
|
+
*/
|
|
34
|
+
export function cubeFacesFromNames(paths) {
|
|
35
|
+
const ALIASES = {
|
|
36
|
+
px: ['px', 'rt', 'right', 'east', 'posx', 'x+'],
|
|
37
|
+
nx: ['nx', 'lf', 'left', 'west', 'negx', 'x-'],
|
|
38
|
+
py: ['py', 'up', 'top', 'posy', 'y+'],
|
|
39
|
+
ny: ['ny', 'dn', 'down', 'bottom', 'negy', 'y-'],
|
|
40
|
+
pz: ['pz', 'ft', 'front', 'north', 'posz', 'z+'],
|
|
41
|
+
nz: ['nz', 'bk', 'back', 'south', 'negz', 'z-'],
|
|
42
|
+
};
|
|
43
|
+
const found = {};
|
|
44
|
+
for (const p of paths) {
|
|
45
|
+
const stem = p.split('/').pop().replace(/\.[^.]+$/, '').toLowerCase();
|
|
46
|
+
let hit;
|
|
47
|
+
for (const [face, names] of Object.entries(ALIASES)) {
|
|
48
|
+
// Match a whole trailing segment, so `_front` wins and `frontier` does not.
|
|
49
|
+
if (names.some((n) => stem === n || stem.endsWith(`_${n}`) || stem.endsWith(`-${n}`))) {
|
|
50
|
+
hit = face;
|
|
51
|
+
break;
|
|
52
|
+
}
|
|
53
|
+
}
|
|
54
|
+
if (!hit)
|
|
55
|
+
throw new Error(`cube face not recognised from '${p}' — expected a name ending in rt/lf/up/dn/ft/bk (or px/nx/py/ny/pz/nz)`);
|
|
56
|
+
if (found[hit])
|
|
57
|
+
throw new Error(`two files claim the '${hit}' face: '${found[hit]}' and '${p}'`);
|
|
58
|
+
found[hit] = p;
|
|
59
|
+
}
|
|
60
|
+
const order = ['px', 'nx', 'py', 'ny', 'pz', 'nz'];
|
|
61
|
+
const missing = order.filter((f) => !found[f]);
|
|
62
|
+
if (missing.length)
|
|
63
|
+
throw new Error(`cube map is missing ${missing.length} face(s): ${missing.join(', ')}`);
|
|
64
|
+
return order.map((f) => found[f]);
|
|
65
|
+
}
|
|
26
66
|
/** Identity quaternion, spelled out so callers don't have to remember the order. */
|
|
27
67
|
export const IDENTITY_QUAT = [0, 0, 0, 1];
|
|
28
68
|
export function vec3(x = 0, y = 0, z = 0) { return { x, y, z }; }
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@umicat/three-sdk",
|
|
3
|
-
"version": "1.
|
|
3
|
+
"version": "1.5.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",
|