@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.
@@ -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>;
@@ -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
- if (scene3d.environment?.background)
97
- scene.background = new THREE.Color(scene3d.environment.background);
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 sub-mode** (Phase 2, 2026-10-06, read-only) — `setEditMode3d
52
- * {mode:'hud'}` covers the canvas with a neutral backdrop and mounts the
53
- * bound HUD's widgets (same pure-DOM `loadHud3DScene` Play mode uses, via
54
- * `loadHud3d{hudId,hudFile}` — the host fetches/parses the file, this only
55
- * mounts it) into `#hud`, which `hideNonCanvasStaticMarkup` below hid at
56
- * boot like every other hand-authored markup. No drag/patch/select yet —
57
- * that's a later phase; this one proves World↔HUD actually switches and
58
- * renders correctly.
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 sub-mode** (Phase 2, 2026-10-06, read-only) — `setEditMode3d
47
- * {mode:'hud'}` covers the canvas with a neutral backdrop and mounts the
48
- * bound HUD's widgets (same pure-DOM `loadHud3DScene` Play mode uses, via
49
- * `loadHud3d{hudId,hudFile}` — the host fetches/parses the file, this only
50
- * mounts it) into `#hud`, which `hideNonCanvasStaticMarkup` below hid at
51
- * boot like every other hand-authored markup. No drag/patch/select yet —
52
- * that's a later phase; this one proves World↔HUD actually switches and
53
- * renders correctly.
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 sub-mode (2026-10-06, HUD editing Phase 2) -----------------------
70
+ // ---- World + HUD as simultaneous layers (2026-10-07) ----------------------
68
71
  //
69
- // World↔HUD is a separate axis from this whole function's own existence —
70
- // unlike 2D's design player, which is ONE thing (world OR HUD, chosen at
71
- // iframe construction via which Scene gets launched), this player already
72
- // owns the renderer loop permanently (ADR-021, no teardown), so HUD mode is
73
- // a STATE inside it, not a new entry point. Switching needs no camera/scene
74
- // coordination at all — categorically simpler than world-mode editing —
75
- // because a HUD widget is pure DOM (see `hud3d/HudRuntime3D.ts`): HUD mode
76
- // is just "cover the canvas with a neutral backdrop and mount the same
77
- // DOM tree Play mode would show."
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
- // `#hud` itself was just hidden by `hideNonCanvasStaticMarkup` above (it is
80
- // an existing `index.html` child with no `data-umicat-keep`, same as every
81
- // other hand-authored markup in Edit mode) — that hide is UNDONE here only
82
- // while HUD sub-mode is active, not by tagging `#hud` `data-umicat-keep` at
83
- // the top (which would make it visible in WORLD mode too, where nothing
84
- // mounts into it and it would just sit there empty — harmless, but this is
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
- marker.visible = false;
587
- selectionBox.visible = false;
588
- gizmo.detach();
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
- // World/HUD toggle (HUD editing Phase 2) — see the "HUD sub-mode" block
648
- // above this function's camera setup for why this needs no camera/scene
649
- // work at all, unlike every other message here.
650
- if (data.type === 'umicat:editor:setEditMode3d') {
651
- const mode = data.mode;
652
- if (mode === 'hud')
653
- enterHudMode(null);
654
- else if (mode === 'world')
655
- exitHudMode();
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
- // FIRST mount (host sends this once it has the bound HUD ready, shortly
662
- // after `setEditMode3d{mode:'hud'}`) and for "switch which HUD is being
663
- // edited" (HUD browser, Phase 3) without a mode change.
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
- if (hudMode !== 'hud')
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
- const loaded = await loadScene3D(sceneData, manifest, { assetBase: '', designMode: true });
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
- background?: string;
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.0",
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",