@xviewer.js/debug

Debug package for xviewer.js with GUI components and debugging tools.

Features

• GUI components for debugging and inspection
• Scene Tree Controller - Interactive Three.js scene hierarchy viewer
• Curve editor for animation curves
• Various controller types (number, string, boolean, color, etc.)
• Touch-friendly interface with responsive design
• Modern CSS styling (converted from SCSS for better maintainability)

Usage

import { GUI } from '@xviewer.js/debug';

const gui = new GUI();
gui.add(controller, 'property', min, max);

// Add a scene tree controller
const sceneTree = gui.addSceneTree(threeScene);
sceneTree.onObjectSelect((object) => {
    console.log('Selected:', object);
});

Styling

The package uses modern CSS with CSS custom properties (variables) for theming. Styles are organized in a modular structure for better maintainability:

• base.css - CSS variables and base layout
• controllers.css - Controller-specific styles
• hierarchy.css - Folder and title styles
• inputs.css - Form input styles
• curve-editor.css - Curve editor styles
• scene-tree.css - Scene tree controller styles

All styles are imported through index.css and automatically bundled by Rollup.

Scene Tree Controller

The Scene Tree Controller provides an interactive view of your Three.js scene hierarchy, allowing you to:

• Navigate through the scene graph with expandable/collapsible nodes
• Select objects by clicking on them in the tree
• Toggle visibility of objects using the eye icon
• Refresh the tree when the scene changes
• Expand/Collapse all nodes at once

Features

• Hierarchical Display: Shows the complete scene structure with proper indentation
• Object Selection: Click any node to select the corresponding Three.js object
• Visibility Control: Toggle object visibility directly from the tree
• Real-time Updates: Automatically reflects changes in the scene
• Dynamic Object Detection: Automatically detects newly added/removed objects
• Performance Optimized: Lightweight change detection with configurable update intervals
• Responsive Design: Adapts to different screen sizes and touch devices

Example Integration

import { GUI } from '@xviewer.js/debug';

// Create GUI and add scene tree
const gui = new GUI({ title: "Scene Inspector" });
const sceneTree = gui.addSceneTree(threeScene);

// Handle object selection
sceneTree.onObjectSelect((object) => {
    console.log('Selected:', object.name, object.type);
    // Add your selection logic here
});

// Utility methods
sceneTree.expandAll();      // Expand all nodes
sceneTree.collapseAll();    // Collapse all nodes
sceneTree.refresh();        // Rebuild the tree
sceneTree.update();         // Update visibility states and check for changes
sceneTree.setAutoUpdate(true); // Enable automatic structure change detection
sceneTree.setUpdateInterval(2000); // Check for changes every 2 seconds (default: 1 second)
sceneTree.forceUpdate();    // Force immediate tree rebuild

Note: The scene tree controller automatically takes the full width of its container, doesn't display a name label, and automatically detects scene changes when update() is called each frame. Performance is optimized by using lightweight change detection and configurable update intervals to avoid rebuilding the entire tree unnecessarily.

CSS Variables

• --background-color: Main background color
• --text-color: Primary text color
• --widget-color: Widget background color
• --hover-color: Hover state color
• --focus-color: Focus state color
• --number-color: Number input color
• --string-color: String input color

Build

The package is built using Rollup with CSS processing support. CSS files are automatically bundled and optimized during the build process.