Add Inspector debug panel to extras with an examples toolbar toggle

examples/eslint.config.mjs

@@ -15,6 +15,7 @@ const booleanFlags = new Set([
     'HIDDEN',
     'NO_DEVICE_SELECTOR',
     'NO_MINISTATS',
+    'NO_INSPECTOR',
     'WEBGPU_DISABLED',
     'WEBGPU_BARE_DISABLED',
     'WEBGL_DISABLED',

examples/iframe/inspector.mjs

@@ -0,0 +1,83 @@
+import { fire, getQueryParams } from './runtime.mjs';
+
+/** @import { AppBase, Inspector as PcInspector } from 'playcanvas' */
+
+const params = getQueryParams(window.location.href);
+
+// keeps the docked panel clear of the toolbar buttons the app floats over the top-left corner
+const TOOLBAR_INSET = 52;
+
+export default class Inspector {
+    /**
+     * The instance driven by the UI toggle. Either created here on demand, or handed over by an
+     * example which needs custom options, see {@link Inspector.adopt}.
+     *
+     * @type {PcInspector | null}
+     */
+    static instance = null;
+
+    /**
+     * Starts driving an instance: the UI learns about every change of its visibility, whether from
+     * the toolbar button, the panel's close button or its hotkey.
+     *
+     * @param {PcInspector} instance - The instance.
+     */
+    static _bind(instance) {
+        Inspector.instance = instance;
+        instance.onVisibleChange = state => fire('inspector', { state });
+    }
+
+    /**
+     * Takes over an instance created by the example itself, so the UI toggle drives that one
+     * instead of adding a second panel on top of it.
+     *
+     * @param {PcInspector | null | undefined} instance - The instance exported by the example.
+     */
+    static adopt(instance) {
+        if (instance) {
+            Inspector._bind(instance);
+            // thumbnail capture loads the example without the surrounding UI, so there is no toggle
+            // to fold this into - suppress the panel here instead
+            if (params.inspector === 'false') {
+                instance.visible = false;
+            }
+        }
+    }
+
+    /**
+     * @param {AppBase} app - The app instance.
+     * @param {any} state - The requested visibility.
+     * @returns {boolean} The resolved visibility.
+     */
+    static enable(app, state) {
+        if (typeof window.pc === 'undefined' || !window.pc.Inspector) {
+            return false;
+        }
+        if (!app) {
+            return false;
+        }
+
+        // thumbnail capture suppresses the panel
+        const suppressed = params.inspector === 'false';
+        const visible = !suppressed && !!state;
+
+        if (visible && !Inspector.instance) {
+            Inspector._bind(new window.pc.Inspector(app, {
+                dock: 'left',
+                top: TOOLBAR_INSET,
+                visible: false
+            }));
+        }
+        if (!Inspector.instance) {
+            return false;
+        }
+
+        Inspector.instance.visible = visible;
+        return Inspector.instance.visible;
+    }
+
+    static destroy() {
+        Inspector.instance?.destroy();
+        Inspector.instance = null;
+    }
+}

examples/iframe/loader.mjs

@@ -1,4 +1,5 @@
 import files from './files.mjs';
+import Inspector from './inspector.mjs';
 import MiniStats from './ministats.mjs';
 import { fetchFile, importModule, clearImports, parseConfig, fire, win } from './runtime.mjs';
 import { data, deviceType as selectedDeviceType, refreshContext, updateDeviceType } from './state.mjs';
@@ -57,6 +58,13 @@ class ExampleLoader {
      */
     _miniStatsEnabled = false;
 
+    /**
+     * The last requested Inspector visibility, re-applied on hot reload.
+     *
+     * @type {boolean}
+     */
+    _inspectorEnabled = false;
+
     /**
      * @type {Function[]}
      * @private
@@ -97,6 +105,7 @@ class ExampleLoader {
         // here after a hot reload - otherwise the panel stays hidden until the button is toggled twice.
         if (!firstStart) {
             this.setMiniStats(this._miniStatsEnabled);
+            this.setInspector(this._inspectorEnabled);
         }
 
         // Updates controls UI
@@ -216,7 +225,8 @@ class ExampleLoader {
             // just notify to clean UI, but not during hot-reload
             fire('exampleLoading', {
                 showDeviceSelector: !this._config.NO_DEVICE_SELECTOR,
-                showMiniStats: !this._config.NO_MINISTATS
+                showMiniStats: !this._config.NO_MINISTATS,
+                showInspector: !this._config.NO_INSPECTOR
             });
         }
 
@@ -231,6 +241,9 @@ class ExampleLoader {
             // so that the UI toggle drives that instance
             MiniStats.adopt(module.miniStats);
 
+            // likewise for an example that creates its own Inspector
+            Inspector.adopt(module.inspector);
+
             // additional destroy handler for non-app resources
             if (typeof module.destroy === 'function') {
                 this.destroyHandlers.push(module.destroy);
@@ -295,6 +308,19 @@ class ExampleLoader {
         fire('miniStats', { state: MiniStats.enable(this._app, enabled) });
     }
 
+    /**
+     * @param {boolean} enabled - The requested visibility of the inspector panel
+     */
+    setInspector(enabled = false) {
+        this._inspectorEnabled = enabled;
+        if (this._config.NO_INSPECTOR) {
+            // no button, but the example may own a panel whose state the UI still wants to know
+            fire('inspector', { state: Inspector.instance?.visible ?? false });
+            return;
+        }
+        fire('inspector', { state: Inspector.enable(this._app, enabled) });
+    }
+
     hotReload() {
         if (!this._allowRestart) {
             console.warn('Dropping restart while still restarting');
@@ -320,6 +346,7 @@ class ExampleLoader {
 
     destroy() {
         MiniStats.destroy();
+        Inspector.destroy();
         this._destroyApps();
         const handlers = this.destroyHandlers;
         this.destroyHandlers = [];

examples/src/app/components/Example.mjs

@@ -220,6 +220,7 @@ const createState = () => {
  * @property {null|'examples'|'code'|'controls'|'description'} [mobilePanel] - Active mobile panel.
  * @property {(mobilePanel: null|'examples'|'code'|'controls'|'description') => void} [setMobilePanel] - Set active mobile panel.
  * @property {boolean} [showCredits] - Whether the desktop credits overlay is visible.
+ * @property {boolean} [hideDescription] - Hide the desktop description, e.g. while the inspector panel is shown.
  * @property {(event: PointerEvent | import('react').PointerEvent<HTMLElement>) => void} [onMobilePanelDragStart] - Start mobile panel drag.
  */
 
@@ -710,7 +711,7 @@ class Example extends TypedComponent {
 
     renderDescription() {
         const { exampleLoaded, description } = this.state;
-        if (!exampleLoaded || !description || !iframe.ready) {
+        if (!exampleLoaded || !description || !iframe.ready || this.props.hideDescription) {
             return null;
         }
         return jsx(

examples/src/app/components/MainLayout.mjs

@@ -81,6 +81,7 @@ function getDefaultMobilePanelWidth() {
  * @property {number} mobilePanelHeight - Active mobile panel height.
  * @property {number} mobilePanelWidth - Active mobile panel width.
  * @property {boolean} showCredits - Whether the desktop credits overlay is visible.
+ * @property {boolean} showInspector - Whether the inspector panel is shown, which hides the desktop description.
  */
 
 /** @type {typeof Component<Props, State>} */
@@ -101,7 +102,8 @@ class MainLayout extends TypedComponent {
             mobilePanel: getInitialMobilePanel(layout, panel),
             mobilePanelHeight: getMobilePanelHeight(height),
             mobilePanelWidth: getMobilePanelWidth(width),
-            showCredits: localStorage.getItem('showCredits') !== 'false'
+            showCredits: localStorage.getItem('showCredits') !== 'false',
+            showInspector: false
         };
     })();
 
@@ -242,12 +244,14 @@ class MainLayout extends TypedComponent {
     componentDidMount() {
         window.addEventListener('resize', this._onLayoutChange);
         window.addEventListener('orientationchange', this._onLayoutChange);
+        window.addEventListener('inspector', this._handleInspector);
     }
 
     componentWillUnmount() {
         this.stopMobilePanelDrag();
         window.removeEventListener('resize', this._onLayoutChange);
         window.removeEventListener('orientationchange', this._onLayoutChange);
+        window.removeEventListener('inspector', this._handleInspector);
     }
 
     /**
@@ -257,6 +261,22 @@ class MainLayout extends TypedComponent {
         iframe.fire('stats', { state: value });
     };
 
+    /**
+     * @param {boolean} value - Show Inspector state.
+     */
+    updateShowInspector = (value) => {
+        this.setState({ showInspector: value });
+        iframe.fire('inspector', { state: value });
+    };
+
+    /**
+     * @param {Event} event - Inspector state event from the iframe, carrying the resolved state.
+     */
+    _handleInspector = (event) => {
+        const customEvent = /** @type {CustomEvent<{ state: boolean }>} */ (event);
+        this.setState({ showInspector: !!customEvent.detail.state });
+    };
+
     /**
      * @param {boolean} value - Show credits state.
      */
@@ -266,7 +286,7 @@ class MainLayout extends TypedComponent {
     };
 
     render() {
-        const { layout, mobileOrientation, mobilePanel, mobilePanelHeight, mobilePanelWidth, showCredits } = this.state;
+        const { layout, mobileOrientation, mobilePanel, mobilePanelHeight, mobilePanelWidth, showCredits, showInspector } = this.state;
         return jsx(
             'div',
             {
@@ -304,6 +324,7 @@ class MainLayout extends TypedComponent {
                                 jsx(Menu, {
                                     layout,
                                     setShowMiniStats: this.updateShowMiniStats.bind(this),
+                                    setShowInspector: this.updateShowInspector,
                                     showCredits,
                                     setShowCredits: this.setShowCredits
                                 }),
@@ -316,6 +337,7 @@ class MainLayout extends TypedComponent {
                                         mobilePanel,
                                         setMobilePanel: this.setMobilePanel,
                                         showCredits,
+                                        hideDescription: showInspector,
                                         onMobilePanelDragStart: this.startMobilePanelDrag
                                     })
                                 )

examples/src/app/components/Menu.mjs

@@ -11,6 +11,7 @@ import { getLayout } from '../utils.mjs';
 /**
  * @typedef {object} Props
  * @property {(value: boolean) => void} setShowMiniStats - The state set function .
+ * @property {(value: boolean) => void} setShowInspector - Sets whether the inspector panel is shown.
  * @property {'mobile'|'desktop'} [layout] - Current layout.
  * @property {boolean} showCredits - Whether the desktop credits overlay is visible.
  * @property {(value: boolean) => void} setShowCredits - Set credits overlay visibility.
@@ -20,6 +21,8 @@ import { getLayout } from '../utils.mjs';
  * @typedef {object} State
  * @property {boolean} showMiniStats - Show MiniStats state.
  * @property {boolean} hasMiniStats - Whether the loaded example allows the MiniStats overlay.
+ * @property {boolean} showInspector - Show Inspector state.
+ * @property {boolean} hasInspector - Whether the loaded example allows the Inspector toggle.
  * @property {boolean} fullscreen - Fullscreen state.
  * @property {boolean} hasCredits - Whether the loaded example has any credits.
  * @property {boolean} shareDialogOpen - Whether the share dialog is visible.
@@ -38,6 +41,8 @@ class Menu extends TypedComponent {
             showMiniStats: typeof ui.miniStats === 'boolean' ? ui.miniStats : getLayout() === 'desktop',
             fullscreen: typeof ui.fullscreen === 'boolean' ? ui.fullscreen : false,
             hasMiniStats: true,
+            showInspector: typeof ui.inspector === 'boolean' ? ui.inspector : false,
+            hasInspector: true,
             hasCredits: false,
             shareDialogOpen: false,
             shareUrl: '',
@@ -57,6 +62,8 @@ class Menu extends TypedComponent {
         this._handleExampleLoad = this._handleExampleLoad.bind(this);
         this._handleMiniStats = this._handleMiniStats.bind(this);
         this.toggleMiniStats = this.toggleMiniStats.bind(this);
+        this._handleInspector = this._handleInspector.bind(this);
+        this.toggleInspector = this.toggleInspector.bind(this);
         this.toggleCredits = this.toggleCredits.bind(this);
         this.openShareDialog = this.openShareDialog.bind(this);
         this.closeShareDialog = this.closeShareDialog.bind(this);
@@ -134,6 +141,7 @@ class Menu extends TypedComponent {
         window.addEventListener('exampleLoading', this._handleExampleLoading);
         window.addEventListener('exampleLoad', this._handleExampleLoad);
         window.addEventListener('miniStats', this._handleMiniStats);
+        window.addEventListener('inspector', this._handleInspector);
     }
 
     componentWillUnmount() {
@@ -148,6 +156,7 @@ class Menu extends TypedComponent {
         window.removeEventListener('exampleLoading', this._handleExampleLoading);
         window.removeEventListener('exampleLoad', this._handleExampleLoad);
         window.removeEventListener('miniStats', this._handleMiniStats);
+        window.removeEventListener('inspector', this._handleInspector);
     }
 
     openShareDialog() {
@@ -183,15 +192,19 @@ class Menu extends TypedComponent {
      * @param {Event} event - exampleLoading event.
      */
     _handleExampleLoading(event) {
-        const detail = /** @type {CustomEvent<{ showMiniStats?: boolean }>} */ (event).detail;
-        this.setState({ hasMiniStats: detail?.showMiniStats !== false });
+        const detail = /** @type {CustomEvent<{ showMiniStats?: boolean, showInspector?: boolean }>} */ (event).detail;
+        this.setState({
+            hasMiniStats: detail?.showMiniStats !== false,
+            hasInspector: detail?.showInspector !== false
+        });
     }
 
     /**
      * @param {Event} event - exampleLoad event.
      */
     _handleExampleLoad(event) {
         this.props.setShowMiniStats(this.state.showMiniStats);
+        this.props.setShowInspector(this.state.showInspector);
         this.setFullscreen(this.state.fullscreen, true);
         const detail = /** @type {CustomEvent<{ credits?: unknown[] }>} */ (event).detail;
         this.setState({ hasCredits: (detail?.credits?.length ?? 0) > 0 });
@@ -213,8 +226,27 @@ class Menu extends TypedComponent {
         }, () => patchState({ ui: { miniStats: this.state.showMiniStats } }));
     }
 
+    toggleInspector() {
+        const value = !this.state.showInspector;
+        this.setState({ showInspector: value }, () => patchState({ ui: { inspector: this.state.showInspector } }));
+        this.props.setShowInspector(value);
+    }
+
+    /**
+     * @param {Event} event - Inspector state event.
+     */
+    _handleInspector(event) {
+        const customEvent = /** @type {CustomEvent<{ state: boolean }>} */ (event);
+        // an example that owns its panel reports its state too, but that is not the toggle's state:
+        // it must neither persist nor carry over to the next example
+        if (!this.state.hasInspector) return;
+        this.setState({
+            showInspector: !!customEvent.detail.state
+        }, () => patchState({ ui: { inspector: this.state.showInspector } }));
+    }
+
     render() {
-        const { showMiniStats, hasMiniStats, hasCredits, shareDialogOpen, shareUrl, shareTitle } = this.state;
+        const { showMiniStats, hasMiniStats, showInspector, hasInspector, hasCredits, shareDialogOpen, shareUrl, shareTitle } = this.state;
         const { layout, showCredits } = this.props;
         return jsx(
             Container,
@@ -263,6 +295,13 @@ class Menu extends TypedComponent {
                     text: '',
                     onClick: this.toggleMiniStats
                 }),
+                hasInspector && jsx(Button, {
+                    icon: 'E147',
+                    id: 'showInspectorButton',
+                    class: showInspector ? 'selected' : undefined,
+                    text: '',
+                    onClick: this.toggleInspector
+                }),
                 hasCredits && layout === 'desktop' && jsx(Button, {
                     id: 'showCreditsButton',
                     class: showCredits ? 'selected' : undefined,

examples/src/app/events.js

@@ -7,6 +7,7 @@
  * @typedef {object} LoadingEventDetail
  * @property {boolean} showDeviceSelector - Show device selector
  * @property {boolean} showMiniStats - Show the MiniStats toggle
+ * @property {boolean} showInspector - Show the Inspector toggle
  *
  * @typedef {CustomEvent<LoadingEventDetail>} LoadingEvent.
  */