← Commit history
v0.9.0: layer intro previews (#8)
6 files changed
+188−7
SKILL.md+20@@ -46,3 +46,23 @@ Full API (loadModel, frameModel, toggleAxes, layers toolbar, laser etch, BABYLON namespace re-export) is documented in the README on this page. Source lives on the Files tab; `adom-wiki repo clone adom/adom-3d-viewer` gets you a working checkout.++## What a GLB can declare (0.9.0)++The viewer reads its behaviour from the GLB itself, in glTF `extras` and node+names; the one page that lists it all is the `wiki-hero-glb` skill in+adom/adom-wiki-skillpack, with the full detail in this package's+`docs/CONTENT-CONVENTIONS.md`. The short form:++- `extras.adomLayer { key, label, group, hidden }`: a Layers-panel toggle;+ nearest declaring ancestor wins; two layers (or one declared) make a panel.+ API `getLayers()`, `setLayerVisible(key, on)`.+- `extras.adomLayer.intro { fadeInAt, fadeOutAt, highlightButton, fadeMs }`+ on a hidden layer: after load it fades in, holds, fades out, with its+ toggle pressed and pulsing meanwhile; a click during the intro keeps it+ on. API `getIntros()`, `replayIntros()`, `stopIntros()`;+ `init(host, { intros: false })` never plays them.+- `extras.tooltip`: hover text; `extras.adomRole` or an `Adom.<Name>` node:+ a switchable group (a lens skin and its `KHR_lights_punctual` light switch+ together). API `getStateGroups()`, `setStateGroupEnabled()`,+ `getContentLights()`, `setLightBudget()`.
VERSION+1−1@@ -1 +1 @@-0.8.0+0.9.0
docs/CONTENT-CONVENTIONS.md+31@@ -68,6 +68,37 @@ Notes that matter in practice: follow in the order they appear in the file. - Fewer than two layers means no panel. One layer is not a choice. +### Intro preview of a hidden layer (adom/adom-3d-viewer#8)++A hidden layer can introduce itself once after the model loads: it fades in,+holds, fades out, and while it shows its toggle in the Layers panel reads as+pressed and pulses, so the reader learns the switch exists. Afterwards the+layer rests hidden and the toggle rests off. Declare it on the same+`adomLayer`:++```json+{ "name": "Adom.FOV",+ "extras": { "adomLayer": { "key": "fov", "label": "Field of view", "group": "Optics", "hidden": true,+ "intro": { "fadeInAt": 1.5, "fadeOutAt": 6.5, "highlightButton": true } } } }+```++| Field | Default | Meaning |+|-------|---------|---------|+| `fadeInAt` | 1.5 | Seconds after load when the fade-in starts (0 to 120). |+| `fadeOutAt` | `fadeInAt` + 5 | Seconds after load when the fade-out starts; a value at or before `fadeInAt` falls back to the default. |+| `highlightButton` | true | Render the panel toggle as pressed and pulsing while the layer shows. |+| `fadeMs` | 700 | Length of each fade (100 to 5000 ms). |++Rules: an `intro` is honoured only on a `hidden: true` layer (a visible layer+has nothing to introduce). The fade is the meshes' `visibility`, so it works on+any material; translucent artwork (alphaMode BLEND) fades as you would expect.+A click on the toggle during the intro keeps the layer on: the reader asked for+it. `setLayerVisible()` cancels a running intro on that layer. The panel gains+a "Replay intro" button whenever a layer declares one; the API is+`getIntros()`, `replayIntros()`, `stopIntros()`, and `init(..., { intros: false })`+never plays them (the wiki passes that for `?animate=0`). A new model or+`clearScene()` cancels everything.+ ## Hover tooltips (adom/wiki #35) - Put a `tooltip` string in the glTF `extras` of the node or mesh:
package.json+1−1@@ -1,6 +1,6 @@ { "name": "adom-3d-viewer-babylon9",- "version": "0.8.0",+ "version": "0.9.0", "description": "The Babylon 9.5 engine behind every component page's 3D tab on wiki.adom.inc. Versioned ESM bundle with GLB loading, view cube, layers toolbar, ground shadows, and Z-up CAD framing.", "type": "app", "main": "./dist/index.js",
src/ThreeDViewer.svelte+122−5@@ -346,11 +346,23 @@ const STATE_PREF = (key: string) => `a3d.state.${key}`; /** A declared layer, from glTF extras or the built-in vocabulary. */- type LayerSpec = { key: string; label?: string; group?: string; hidden?: boolean };+ type LayerSpec = { key: string; label?: string; group?: string; hidden?: boolean; intro?: LayerIntro };+ /**+ * Intro preview of a HIDDEN layer (adom/adom-3d-viewer#8): after the+ * model loads, fade the layer in at `fadeInAt` seconds, hold it, fade it+ * out by `fadeOutAt`, and while it shows render its panel toggle as+ * pressed and pulsing, so the reader learns the switch exists. Afterwards+ * the layer rests hidden and the toggle rests off. A click on the toggle+ * during the intro keeps the layer on (the reader asked for it).+ */+ type LayerIntro = { fadeInAt: number; fadeOutAt: number; highlightButton: boolean; fadeMs: number }; type DetectedLayer = { name: string; label: string; group: string | null; visible: boolean; meshes: AbstractMesh[]; declared: boolean;+ intro: LayerIntro | null; introActive: boolean; };+ /** Play declared layer intros after load (the page passes false with animate=0). */+ export let intros: boolean = true; /** Sanitize a declared spec: content is untrusted and ends up in the DOM. */ function normalizeSpec(raw: any): LayerSpec | null {@@ -359,7 +371,19 @@ if (!key || key.length > 64) return null; const label = typeof raw.label === 'string' && raw.label.trim() ? raw.label.trim().slice(0, 64) : undefined; const group = typeof raw.group === 'string' && raw.group.trim() ? raw.group.trim().slice(0, 64) : undefined;- return { key: key.slice(0, 64), label, group, hidden: raw.hidden === true };+ return { key: key.slice(0, 64), label, group, hidden: raw.hidden === true, intro: raw.hidden === true ? normalizeIntro(raw.intro) : undefined };+ }+ /** An intro only makes sense on a hidden layer; bad numbers fall back. */+ function normalizeIntro(raw: any): LayerIntro | undefined {+ if (!raw || typeof raw !== 'object') return undefined;+ const num = (v: any, d: number, lo: number, hi: number) => { const n = Number(v); return Number.isFinite(n) ? Math.min(hi, Math.max(lo, n)) : d; };+ const fadeInAt = num(raw.fadeInAt, 1.5, 0, 120);+ // A fade-out at or before the fade-in is nonsense: fall back to the+ // default hold rather than clamp it into a blink.+ const outRaw = Number(raw.fadeOutAt);+ const fadeOutAt = Number.isFinite(outRaw) && outRaw > fadeInAt ? Math.min(600, outRaw) : fadeInAt + 5;+ const fadeMs = num(raw.fadeMs, 700, 100, 5000);+ return { fadeInAt, fadeOutAt, highlightButton: raw.highlightButton !== false, fadeMs }; } /**@@ -429,6 +453,7 @@ group: spec.group || null, visible, meshes, declared: !BUILTIN_BY_KEY.has(name),+ intro: spec.intro || null, introActive: false, }; }); // A lone NAME-matched layer is suppressed (a model that is entirely@@ -462,6 +487,7 @@ export function setLayerVisible(name: string, visible: boolean): boolean { const layer = layers.find(l => l.name === name); if (!layer) return false;+ if (introRuns.has(name) || layer.introActive) cancelIntro(layer); layer.visible = visible; layer.meshes.forEach(m => { m.isVisible = visible; }); layers = layers; // trigger svelte reactivity@@ -471,7 +497,88 @@ function toggleLayerRow(name: string): void { const layer = layers.find(l => l.name === name);- if (layer) setLayerVisible(name, !layer.visible);+ if (!layer) return;+ // Pressed during its intro: the reader wants the layer, keep it on.+ if (layer.introActive) { cancelIntro(layer); setLayerVisible(name, true); return; }+ setLayerVisible(name, !layer.visible);+ }++ // ---- Layer intros (adom/adom-3d-viewer#8) ------------------------------+ // Timers and a per-frame observer per layer; everything cancels on a+ // user toggle, a replay, a new model or clearScene.+ type IntroRun = { timers: number[]; observer: any; layer: DetectedLayer };+ const introRuns = new Map<string, IntroRun>();+ let introsScheduled = false;++ function setLayerAlpha(layer: DetectedLayer, alpha: number): void {+ layer.meshes.forEach(m => { m.visibility = alpha; });+ }+ function rampLayer(run: IntroRun, from: number, to: number, ms: number, done: () => void): void {+ const scene = AdomStatics.scene;+ if (!scene) { setLayerAlpha(run.layer, to); done(); return; }+ const t0 = performance.now();+ if (run.observer) { scene.onBeforeRenderObservable.remove(run.observer); run.observer = null; }+ run.observer = scene.onBeforeRenderObservable.add(() => {+ const k = Math.min(1, (performance.now() - t0) / ms);+ const eased = k < 0.5 ? 2 * k * k : 1 - Math.pow(-2 * k + 2, 2) / 2;+ setLayerAlpha(run.layer, from + (to - from) * eased);+ if (k >= 1) { scene.onBeforeRenderObservable.remove(run.observer); run.observer = null; done(); }+ });+ }+ function cancelIntro(layer: DetectedLayer): void {+ const run = introRuns.get(layer.name);+ if (run) {+ run.timers.forEach(t => clearTimeout(t));+ if (run.observer && AdomStatics.scene) AdomStatics.scene.onBeforeRenderObservable.remove(run.observer);+ introRuns.delete(layer.name);+ }+ setLayerAlpha(layer, 1);+ if (layer.introActive) { layer.introActive = false; layer.meshes.forEach(m => { m.isVisible = layer.visible; }); layers = layers; }+ }+ function scheduleIntros(): void {+ stopIntros();+ if (!intros) return;+ for (const layer of layers) {+ if (!layer.intro || layer.visible) continue;+ const it = layer.intro;+ const run: IntroRun = { timers: [], observer: null, layer };+ introRuns.set(layer.name, run);+ run.timers.push(window.setTimeout(() => {+ if (layer.visible) { introRuns.delete(layer.name); return; }+ layer.introActive = true; layers = layers;+ setLayerAlpha(layer, 0);+ layer.meshes.forEach(m => { m.isVisible = true; });+ AdomStatics.refreshShadows();+ rampLayer(run, 0, 1, it.fadeMs, () => {});+ }, it.fadeInAt * 1000));+ run.timers.push(window.setTimeout(() => {+ if (!layer.introActive) return;+ rampLayer(run, 1, 0, it.fadeMs, () => {+ layer.meshes.forEach(m => { m.isVisible = false; m.visibility = 1; });+ layer.introActive = false; layers = layers;+ introRuns.delete(layer.name);+ AdomStatics.refreshShadows();+ });+ }, it.fadeOutAt * 1000));+ }+ introsScheduled = introRuns.size > 0;+ }+ /** Cancel every running or pending intro; layers rest at their own state. */+ export function stopIntros(): void {+ for (const layer of [...introRuns.values()].map(r => r.layer)) cancelIntro(layer);+ introRuns.clear();+ introsScheduled = false;+ }+ /** Replay the declared intros from the start (the reader's replay control). */+ export function replayIntros(): boolean {+ if (!layers.some(l => l.intro)) return false;+ const saved = intros; intros = true;+ scheduleIntros();+ intros = saved;+ return true;+ }+ export function getIntros(): { name: string; fadeInAt: number; fadeOutAt: number; highlightButton: boolean; active: boolean; pending: boolean }[] {+ return layers.filter(l => l.intro).map(l => ({ name: l.name, fadeInAt: l.intro!.fadeInAt, fadeOutAt: l.intro!.fadeOutAt, highlightButton: l.intro!.highlightButton, active: l.introActive, pending: introRuns.has(l.name) && !l.introActive })); } /** "Adom.LED.State" -> "LED State"; "mpn-marking" -> "Mpn marking". */@@ -832,6 +939,7 @@ detectStateGroups(); mitigateCoplanarFighting(result.meshes); frameModel();+ scheduleIntros(); } } @@ -935,6 +1043,7 @@ export function clearScene(): void { // Content lights hang off transform nodes, not meshes, so disposing the // mesh roots can leave them lighting the NEXT model. Dispose them here.+ stopIntros(); contentLights?.clear(); loadedRootNodes.forEach((node) => node.dispose()); for (const g of stateGroups) for (const r of g.roots) { try { r.dispose?.(false, true); } catch { /* already gone */ } }@@ -1492,6 +1601,9 @@ </button> {#if layersPanelOpen} <div class="layers-panel">+ {#if layers.some(l => l.intro)}+ <button type="button" class="layers-replay" title="Play the layer intro again" on:click={() => replayIntros()}>Replay intro</button>+ {/if} {#if stateGroups.length > 0} <div class="layers-group">Parts</div> {#each stateGroups as group (group.key)}@@ -1510,10 +1622,10 @@ <div class="layers-group">{section.group}</div> {/if} {#each section.items as layer (layer.name)}- <label class="layers-row">+ <label class="layers-row" class:intro={layer.introActive && layer.intro?.highlightButton !== false}> <input type="checkbox"- checked={layer.visible}+ checked={layer.visible || layer.introActive} on:change={() => toggleLayerRow(layer.name)} /> <span>{layer.label}</span>@@ -1658,6 +1770,11 @@ user-select: none; } .layers-row:hover { background: rgba(255, 255, 255, 0.08); }+ .layers-row.intro { background: rgba(0, 184, 176, 0.18); animation: a3d-intro-pulse 1.2s ease-in-out infinite; }+ .layers-row.intro input { box-shadow: 0 0 0 2px rgba(0, 230, 220, 0.6); border-radius: 3px; }+ @keyframes a3d-intro-pulse { 0%, 100% { background: rgba(0, 184, 176, 0.12); } 50% { background: rgba(0, 184, 176, 0.3); } }+ .layers-replay { display: block; width: 100%; margin: 0 0 6px; padding: 4px 8px; border: 1px solid rgba(0, 184, 176, 0.35); border-radius: 6px; background: rgba(0, 184, 176, 0.1); color: #e6edf3; font: inherit; font-size: 12px; cursor: pointer; }+ .layers-replay:hover { background: rgba(0, 184, 176, 0.2); } .layers-row input { accent-color: #00b8b0; cursor: pointer; } /* Orbit-center chip — live indicator while shift+alt is held, and the
standalone.ts+13@@ -77,6 +77,13 @@ interface ViewerInstance { * content asked for the layer rather than matching the built-in names. */ getLayers: () => { name: string; label: string; group: string | null; visible: boolean; declared: boolean }[]; setLayerVisible: (name: string, visible: boolean) => boolean;+ /** Intro previews declared on hidden layers (extras.adomLayer.intro,+ * adom/adom-3d-viewer#8): what is declared and whether it is playing. */+ getIntros: () => { name: string; fadeInAt: number; fadeOutAt: number; highlightButton: boolean; active: boolean; pending: boolean }[];+ /** Play the declared intros again from the start; false when none declared. */+ replayIntros: () => boolean;+ /** Cancel every running or pending intro. */+ stopIntros: () => void; /** Switchable groups the GLB declares (extras.adomRole, or an Adom.<Name> * node): Adom.LED.State carries the lens skin AND its light, so switching * the group off turns both off. One entry per role, every placement behind@@ -130,6 +137,8 @@ function init(container: HTMLElement, options?: { * (default 4). A board with forty lit LEDs keeps the nearest and brightest * this many; the rest stay emissive-only. 0 leaves them all off. */ lightBudget?: number;+ /** Play layer intros declared in the GLB (extras.adomLayer.intro); default true. */+ intros?: boolean; }): ViewerInstance { const opts = options || {}; @@ -148,6 +157,7 @@ function init(container: HTMLElement, options?: { onMeshHover: opts.onMeshHover, onGroundCreated: opts.onGroundCreated, lightBudget: opts.lightBudget !== undefined ? opts.lightBudget : 4,+ intros: opts.intros !== false, }, }); @@ -184,6 +194,9 @@ function init(container: HTMLElement, options?: { captureScreenshot: (o?: { width?: number; height?: number }) => component.captureScreenshot(o), getLayers: () => component.getLayers(), setLayerVisible: (name: string, visible: boolean) => component.setLayerVisible(name, visible),+ getIntros: () => component.getIntros(),+ replayIntros: () => component.replayIntros(),+ stopIntros: () => component.stopIntros(), getStateGroups: () => component.getStateGroups(), setStateGroupEnabled: (key: string, enabled: boolean) => component.setStateGroupEnabled(key, enabled), setStateInstanceEnabled: (key: string, index: number, enabled: boolean) => component.setStateInstanceEnabled(key, index, enabled),