babylon.quarks-editor 0.26.0 → 0.28.0

package/src/react/host/hostHooks.ts

@@ -0,0 +1,198 @@
+import {Viewport} from '@babylonjs/core/Maths/math.viewport.js';
+import type {TransformNode} from '@babylonjs/core/Meshes/transformNode.js';
+import {useEffect, useRef, useState} from 'react';
+import type {EditorSession} from '../../core/editorSession.js';
+import {notifyTransformChanged} from '../../core/transformStore.js';
+import {DRAWER_HEIGHT} from './hostStyles.js';
+import type {GizmoMode} from './ViewportPane.js';
+
+/** True for a field that takes typed text, where editor shortcuts stay out of the way. */
+export function isTextInput(target: EventTarget | null): boolean {
+    const el = target as HTMLElement | null;
+    return !!el && (el.isContentEditable || ['INPUT', 'TEXTAREA', 'SELECT'].includes(el.tagName));
+}
+
+/**
+ * Inspector value controls (numbers, checkboxes, selects): Ctrl+Z there means the effect's undo,
+ * not the browser's per-field text undo. Free-text inputs (names, filters) keep the native one.
+ */
+export function isInspectorValueControl(target: EventTarget | null): boolean {
+    const el = target as HTMLElement | null;
+    if (!el) return false;
+    if (el.tagName === 'SELECT') return true;
+    return el.tagName === 'INPUT' && ['number', 'checkbox', 'range', 'color'].includes((el as HTMLInputElement).type);
+}
+
+/** What the editor's keyboard shortcuts do. */
+export interface HostShortcuts {
+    /** Ctrl+S: save the scene, or ask about the open prefab. */
+    save(): void;
+    /** Ctrl+Space: open or close the Assets drawer. */
+    toggleAssets(): void;
+    /** Space: play or pause the stage. */
+    togglePlayback(): void;
+    /** Escape: close the floating Assets drawer. */
+    closeDrawer(): void;
+    /** Ctrl+Z / Ctrl+Y / Ctrl+Shift+Z. */
+    historyStep(redo: boolean): void;
+    /** Delete: remove the focused effect; returns whether it did. */
+    deleteFocused(): boolean;
+}
+
+/** Handles a keydown on the editor's window; exported for tests. */
+export function handleHostShortcut(e: KeyboardEvent, shortcuts: HostShortcuts): void {
+    const key = e.key.toLowerCase();
+    const command = e.ctrlKey || e.metaKey;
+    if (command && key === 's') {
+        e.preventDefault();
+        shortcuts.save();
+        return;
+    }
+    if (e.code === 'Space' && command) {
+        e.preventDefault();
+        shortcuts.toggleAssets();
+        return;
+    }
+    const target = e.target as HTMLElement | null;
+    if (e.code === 'Space' && !isTextInput(target) && target?.tagName !== 'BUTTON') {
+        e.preventDefault();
+        shortcuts.togglePlayback();
+        return;
+    }
+    if (e.key === 'Escape') {
+        shortcuts.closeDrawer();
+    }
+    if (command && (key === 'z' || key === 'y')) {
+        if (isTextInput(e.target) && !isInspectorValueControl(e.target)) {
+            return;
+        }
+        e.preventDefault();
+        // Leave the field first so it shows the restored value instead of its draft text.
+        (e.target as HTMLElement | null)?.blur?.();
+        shortcuts.historyStep(key === 'y' || e.shiftKey);
+        return;
+    }
+    if (e.key === 'Delete' && !isTextInput(e.target) && shortcuts.deleteFocused()) {
+        e.preventDefault();
+    }
+}
+
+/** Installs the editor's keyboard shortcuts on the window; the latest `shortcuts` are always used. */
+export function useHostShortcuts(shortcuts: HostShortcuts): void {
+    const ref = useRef(shortcuts);
+    ref.current = shortcuts;
+    useEffect(() => {
+        const onKey = (e: KeyboardEvent) => handleHostShortcut(e, ref.current);
+        window.addEventListener('keydown', onKey);
+        return () => window.removeEventListener('keydown', onKey);
+    }, []);
+}
+
+/**
+ * Puts the stage gizmo in `mode` and attaches it to `target`, leaving it where it is while
+ * `paused`. One gizmo drag is one undo step: the binding snapshots at drag start, and the UI
+ * refreshes at most once a frame while dragging.
+ */
+export function useStageGizmo(
+    session: EditorSession | null,
+    mode: GizmoMode,
+    target: TransformNode | null,
+    paused: boolean
+): void {
+    useEffect(() => {
+        const gm = session?.gizmoManager;
+        if (!gm) return;
+        gm.positionGizmoEnabled = mode === 'position';
+        gm.rotationGizmoEnabled = mode === 'rotation';
+        gm.scaleGizmoEnabled = mode === 'scale';
+        const activeGizmo =
+            mode === 'position'
+                ? gm.gizmos.positionGizmo
+                : mode === 'rotation'
+                  ? gm.gizmos.rotationGizmo
+                  : mode === 'scale'
+                    ? gm.gizmos.scaleGizmo
+                    : null;
+        let dragRaf = 0;
+        const scheduleTransformRefresh = () => {
+            if (dragRaf !== 0) {
+                return;
+            }
+            dragRaf = requestAnimationFrame(() => {
+                dragRaf = 0;
+                notifyTransformChanged();
+            });
+        };
+        const dragStartObserver = activeGizmo?.onDragStartObservable.add(() => session.binding?.onBeforeChange?.());
+        const dragObserver = activeGizmo?.onDragObservable.add(scheduleTransformRefresh);
+        const dragEndObserver = activeGizmo?.onDragEndObservable.add(() => {
+            notifyTransformChanged();
+            session.binding?.markChanged();
+        });
+        return () => {
+            if (dragRaf !== 0) {
+                cancelAnimationFrame(dragRaf);
+            }
+            if (activeGizmo) {
+                activeGizmo.onDragStartObservable.remove(dragStartObserver ?? null);
+                activeGizmo.onDragObservable.remove(dragObserver ?? null);
+                activeGizmo.onDragEndObservable.remove(dragEndObserver ?? null);
+            }
+        };
+    }, [session, mode]);
+
+    useEffect(() => {
+        if (!paused) {
+            session?.gizmoManager.attachToNode(target);
+        }
+    }, [session, target, paused]);
+}
+
+/**
+ * The floating drawer is opaque, so the scene renders only in the part of the viewport above it:
+ * the view, and every "frame this effect" camera move, re-centres on what is visible. Measured
+ * again when the drawer floats or docks and when the timeline collapses. Returns the pixels the
+ * drawer covers.
+ */
+export function useViewportInset(
+    session: EditorSession | null,
+    canvasRef: React.RefObject<HTMLCanvasElement | null>,
+    areaRef: React.RefObject<HTMLDivElement | null>,
+    drawerFloating: boolean,
+    timelineCollapsed: boolean
+): number {
+    const [inset, setInset] = useState(0);
+    useEffect(() => {
+        const update = () => {
+            const camera = session?.camera;
+            const canvas = canvasRef.current;
+            const area = areaRef.current;
+            if (!camera || !canvas || !area) return;
+            const canvasRect = canvas.getBoundingClientRect();
+            const drawerTop = area.getBoundingClientRect().bottom - DRAWER_HEIGHT;
+            const covered = drawerFloating
+                ? Math.max(0, Math.min(canvasRect.height * 0.8, canvasRect.bottom - drawerTop))
+                : 0;
+            const fraction = canvasRect.height > 0 ? covered / canvasRect.height : 0;
+            camera.viewport = new Viewport(0, fraction, 1, 1 - fraction);
+            setInset(covered);
+        };
+        update();
+        window.addEventListener('resize', update);
+        return () => window.removeEventListener('resize', update);
+    }, [session, canvasRef, areaRef, drawerFloating, timelineCollapsed]);
+    return inset;
+}
+
+/** Asks before the page unloads while `dirty`. */
+export function useUnsavedChangesGuard(dirty: boolean): void {
+    useEffect(() => {
+        if (!dirty) return;
+        const onBeforeUnload = (e: BeforeUnloadEvent) => {
+            e.preventDefault();
+            e.returnValue = '';
+        };
+        window.addEventListener('beforeunload', onBeforeUnload);
+        return () => window.removeEventListener('beforeunload', onBeforeUnload);
+    }, [dirty]);
+}

package/src/react/host/hostStyles.ts

@@ -0,0 +1,65 @@
+import type React from 'react';
+import {buttonStyle, theme} from '../theme.js';
+
+/** Width of the Scene list on the left. */
+export const SCENE_PANEL_WIDTH = 280;
+/** Width of the inspector on the right. */
+export const INSPECTOR_WIDTH = 340;
+/** Height of the timeline dock when expanded. */
+export const TIMELINE_HEIGHT = 200;
+/** Height of the Assets drawer. */
+export const DRAWER_HEIGHT = 280;
+
+/** A square icon button of the viewport toolbars. */
+export const squareButtonStyle: React.CSSProperties = {
+    ...buttonStyle,
+    width: 28,
+    height: 28,
+    padding: 0,
+    display: 'flex',
+    alignItems: 'center',
+    justifyContent: 'center',
+    fontWeight: 700,
+};
+
+/** Added to a toolbar button that is switched on. */
+export const activeSquareButtonStyle: React.CSSProperties = {
+    border: `1px solid ${theme.borderActive}`,
+    background: 'rgba(120, 165, 255, 0.35)',
+};
+
+/** Title of a dock (Assets, Timeline). */
+export const dockTitleStyle: React.CSSProperties = {
+    fontSize: 11,
+    fontWeight: 600,
+    letterSpacing: 0.4,
+    textTransform: 'uppercase',
+    color: theme.text,
+};
+
+/** A small icon button in a dock's header. */
+export const dockIconButtonStyle: React.CSSProperties = {
+    ...buttonStyle,
+    width: 24,
+    height: 22,
+    padding: 0,
+    display: 'inline-flex',
+    alignItems: 'center',
+    justifyContent: 'center',
+};
+
+/** A floating panel over the viewport. */
+export const floatingPanelStyle: React.CSSProperties = {
+    background: theme.panelBg,
+    border: `1px solid ${theme.border}`,
+    borderRadius: 8,
+};
+
+/** A Save button, highlighted while there is something to save. */
+export function saveButtonStyle(pending: boolean, padding: string): React.CSSProperties {
+    return {
+        ...buttonStyle,
+        padding,
+        ...(pending ? {background: theme.accent, color: '#0a1128', border: `1px solid ${theme.accent}`} : {}),
+    };
+}

package/src/react/index.ts

@@ -1,6 +1,7 @@
-export {AssetsPanel} from './AssetsPanel';
-export type {AssetsPanelProps} from './AssetsPanel';
+export {AssetsPanel} from './AssetsPanel.js';
+export type {AssetsPanelProps} from './AssetsPanel.js';
 export {
+    AttractorModule,
     CollisionModule,
     ColorBySpeedModule,
     EmitDirectionModule,
@@ -16,24 +17,24 @@ export {
     TextureSheetModule,
     TurbulenceModule,
     WidthOverTrailModule,
-} from './behaviorModules';
-export {ChoiceDialog} from './ChoiceDialog';
-export type {ChoiceDialogAction, ChoiceDialogProps} from './ChoiceDialog';
-export {ContextMenu} from './ContextMenu';
-export type {ContextMenuItem, ContextMenuProps} from './ContextMenu';
-export {CurveEditor} from './CurveEditor';
-export {EditorWorkspace, QuarksEditorWorkspace} from './EditorWorkspace';
-export type {EditorWorkspaceProps} from './EditorWorkspace';
-export {EffectEditor} from './EffectEditor';
-export type {EffectEditorProps} from './EffectEditor';
-export {EffectEditorHost, QuarksEffectEditor} from './EffectEditorHost';
-export type {EffectEditorHostHandle, EffectEditorHostProps} from './EffectEditorHost';
-export {EffectTreeView} from './EffectTreeView';
-export type {EffectTreeViewProps} from './EffectTreeView';
-export {CheckboxField, NumberField, Row, SelectField} from './fields';
-export {GradientEditor} from './GradientEditor';
-export {MessageDialog} from './MessageDialog';
-export type {MessageDialogProps} from './MessageDialog';
+} from './behaviorModules.js';
+export {ChoiceDialog} from './ChoiceDialog.js';
+export type {ChoiceDialogAction, ChoiceDialogProps} from './ChoiceDialog.js';
+export {ContextMenu} from './ContextMenu.js';
+export type {ContextMenuItem, ContextMenuProps} from './ContextMenu.js';
+export {CurveEditor} from './CurveEditor.js';
+export {EditorWorkspace, QuarksEditorWorkspace} from './EditorWorkspace.js';
+export type {EditorWorkspaceProps} from './EditorWorkspace.js';
+export {EffectEditor} from './EffectEditor.js';
+export type {EffectEditorProps} from './EffectEditor.js';
+export {EffectEditorHost, QuarksEffectEditor} from './EffectEditorHost.js';
+export type {EditorProject, EffectEditorHostHandle, EffectEditorHostProps} from './EffectEditorHost.js';
+export {EffectTreeView} from './EffectTreeView.js';
+export type {EffectTreeViewProps} from './EffectTreeView.js';
+export {CheckboxField, NumberField, Row, SelectField} from './fields.js';
+export {GradientEditor} from './GradientEditor.js';
+export {MessageDialog} from './MessageDialog.js';
+export type {MessageDialogProps} from './MessageDialog.js';
 export {
     ColorOverLifeModule,
     EmissionModule,
@@ -41,21 +42,25 @@ export {
     RendererModule,
     ShapeModule,
     SizeOverLifeModule,
-} from './modules';
-export type {GeometryData, GeometryOption, TextureOption} from './modules';
-export {ModuleSection} from './ModuleSection';
-export {ProjectsPage} from './ProjectsPage';
-export type {ProjectsPageProps} from './ProjectsPage';
-export {PromptDialog} from './PromptDialog';
-export type {PromptDialogProps} from './PromptDialog';
-export {ScenePanel} from './ScenePanel';
-export type {ScenePanelProps} from './ScenePanel';
-export {SubEmittersModule} from './SubEmittersModule';
-export {buttonStyle, inputStyle, labelStyle, rowStyle, theme} from './theme';
-export {TimelinePanel} from './TimelinePanel';
-export type {PlaybackState, TimelinePanelProps} from './TimelinePanel';
-export {TimelineTrackRow} from './TimelineTrackRow';
-export type {TimelineTrackRowProps} from './TimelineTrackRow';
-export {TransportBar} from './TransportBar';
-export type {TransportBarProps} from './TransportBar';
-export {ValueField} from './ValueField';
+} from './modules.js';
+export type {GeometryData, GeometryOption, TextureOption} from './modules.js';
+export {ModuleSection} from './ModuleSection.js';
+export type {ModuleProps} from './ModuleSection.js';
+export {ProjectsPage} from './ProjectsPage.js';
+export type {ProjectsPageProps} from './ProjectsPage.js';
+export {PromptDialog} from './PromptDialog.js';
+export type {PromptDialogProps} from './PromptDialog.js';
+export {ScenePanel} from './ScenePanel.js';
+export type {ScenePanelProps} from './ScenePanel.js';
+export {SubEmittersModule} from './SubEmittersModule.js';
+export {TextureSelect, textureUrlOf} from './TextureSelect.js';
+export {TextureUVField} from './TextureUVField.js';
+export {buttonStyle, inputStyle, labelStyle, rowStyle, theme} from './theme.js';
+export {TimelinePanel} from './TimelinePanel.js';
+export type {PlaybackState, TimelinePanelProps} from './TimelinePanel.js';
+export {TimelineTrackRow} from './TimelineTrackRow.js';
+export type {TimelineTrackRowProps} from './TimelineTrackRow.js';
+export {TransportBar} from './TransportBar.js';
+export type {TransportBarProps} from './TransportBar.js';
+export {ValueField} from './ValueField.js';
+export type {ConstantValueFieldProps, CurveValueFieldProps} from './ValueField.js';

package/src/react/inspectorHints.ts

@@ -13,6 +13,7 @@ const INSPECTOR_HINTS: Record<string, string> = {
     'Velocity over Lifetime': 'Adds linear and orbital velocity each frame in local or world space.',
     'Inherit Velocity': 'Copies the emitter’s movement into new particle velocity.',
     Gravity: 'Applies a constant downward force (Earth-like gravity by default).',
+    Attractor: 'Pulls particles towards a point, harder the nearer they are (a point gravity).',
     'Rotation over Lifetime': 'Spins particles by setting angular velocity over lifetime.',
     Noise: 'Procedural noise that jitters particle position and rotation.',
     Turbulence: '3D turbulent velocity field that swirls particles through space.',
@@ -31,7 +32,11 @@ const INSPECTOR_HINTS: Record<string, string> = {
     Duration: 'How long the particle system runs before stopping (non-looping) or one loop cycle.',
     Looping: 'When enabled, the effect restarts from the beginning after duration ends.',
     'World space': 'Simulates in world coordinates so moving the emitter does not drag existing particles.',
+    'Scaling mode':
+        'What the emitter’s scale does to a world-space system: only the shape and sizes, or speeds and forces too (Unity’s Scaling Mode).',
     Prewarm: 'Simulates the effect once at start so it already looks mid-playback when play begins.',
+    'Warm-up time':
+        'Seconds of the cycle simulated before the first frame of a looping system (Niagara’s Warmup Time); 0 warms up a whole cycle, as Unity does.',
     'Start delay': 'Wait time before emission starts after play or restart.',
     'Start lifetime': 'How long each spawned particle lives before dying.',
     'Start speed': 'Initial speed along the emission direction when a particle is born.',
@@ -70,12 +75,37 @@ const INSPECTOR_HINTS: Record<string, string> = {
     'Render mode': 'Orientation and geometry used to draw each particle.',
     'Trail length': 'Maximum number of trail segments per particle (trail mode).',
     'Follow origin': 'Keeps the trail anchored to the emitter origin instead of the particle head.',
+    'Texture mode':
+        'How the texture runs along the ribbon: once by distance, once with each segment an equal share, repeated per world unit, or once per segment.',
+    'Texture scale': 'Repeats of the texture: per world unit (tile), per segment (repeat), or over the ribbon.',
+    'Min vertex distance':
+        'The particle has to move this far before a new point is fixed; the last point follows it meanwhile. 0: a point every step.',
+    'Trail time':
+        'How long a point is kept, in seconds, within the trail length. 0: until the trail length is reached.',
     'Speed factor': 'How much particle speed stretches the billboard (stretched billboard mode).',
     'Length factor': 'Base stretch multiplier for stretched billboards.',
     Source: 'Material preset loaded from the effect JSON (read-only reference).',
     'Blend mode': 'How particle color is composited over the background.',
     Transparent: 'Enables alpha blending for soft edges and fade-outs.',
     Texture: 'Sprite or flipbook image applied to each particle.',
+    'UV channel':
+        'Which UV set the texture reads: the sprite or mesh UV, or a mesh’s second set / the length of a trail.',
+    Tiling: 'Repeats of the texture across the UV range, U and V (Unity’s material Tiling).',
+    Offset: 'Shift of the texture in UV units after tiling, U and V (Unity’s material Offset).',
+    Scroll: 'UV units per second the texture moves on the renderer’s clock (Unreal’s Panner).',
+    'Flip U/V': 'Fraction of particles mirrored horizontally and vertically, picked at birth (Unity’s renderer Flip).',
+    Ramp: 'Colour ramp read left to right; without one there is no gradient map.',
+    'Ramp channel':
+        'Which value of the map texel picks the colour along the ramp: one channel of a packed texture, or luminance.',
+    Erosion: 'Lets alpha erode the shape through a mask instead of fading it.',
+    'Erosion mask': 'Texture whose red channel orders what goes first; none uses the map’s own alpha.',
+    Softness: 'Width of the soft transition at the erosion cut, in mask units.',
+    'Edge width': 'Width of the glowing band above the erosion cut; 0 draws none.',
+    'Edge color': 'Linear RGB added in the edge band; may exceed 1 for a glow.',
+    'Noise texture': 'Texture whose red and green channels push the map’s UV about; it should repeat.',
+    'Distortion strength': 'How far the map’s UV is pushed at most, in UV units.',
+    'Swept trail': 'Spans the ribbon along a fixed axis of the emitter instead of facing the camera (a weapon trail).',
+    'Side axis': 'Local axis the swept trail spans its width along; give a unit vector.',
     'Alpha test': 'Pixels below this alpha are discarded (cutout/hard edges).',
     'Depth write': 'Writes to the depth buffer — usually off for additive particles.',
     'Depth test': 'Whether particles are occluded by scene geometry.',
@@ -90,6 +120,16 @@ const INSPECTOR_HINTS: Record<string, string> = {
     'Blend tiles': 'Smoothly blends between adjacent atlas tiles during animation.',
     'Start tile': 'Atlas cell index where playback begins (0 = top-left).',
     'Animate frames': 'Enables frame-over-lifetime curve to cycle through atlas tiles.',
+    'Time mode':
+        'Lifetime samples the curve over each particle’s life; FPS plays frames by age from the curve’s frame.',
+    FPS: 'Frames per second in FPS mode.',
+    Loop: 'In FPS mode, wrap back to the first frame of the segment, or hold the last.',
+    'Random frame': 'In FPS mode, show a random frame of the segment every tick instead of the next one.',
+    'Frame count': 'Frames in the segment that plays, from the first frame; 0 means no segment.',
+    'Start frame':
+        'Starts each particle on a random one of the first N frames (Unity’s Start Frame); editing sets a 0…N range.',
+    'attractor.center': 'Point in the system’s space particles are pulled towards.',
+    'attractor.magnitude': 'Pull strength, divided by the squared distance to the center.',
 
     // Sub emitters
     Trigger: 'When the child system is spawned: on particle birth, death, or every frame.',