babylon.quarks-editor 0.26.0 → 0.28.0

package/src/react/behaviorModules.tsx

@@ -12,8 +12,8 @@ import {
     EulerGenerator,
     ForceOverLife,
     FrameOverLife,
-    getPhysicsResolver,
     Gradient,
+    GravityForce,
     InheritVelocity,
     IntervalValue,
     LimitSpeedOverLife,
@@ -33,21 +33,17 @@ import {
     WidthOverLength,
 } from 'babylon.quarks';
 import React from 'react';
-import {EffectBinding} from '../core/binding';
-import {buildGradient, DEFAULT_GRADIENT_STOPS, findBehavior, readGradientStops} from '../core/colors';
-import {buildCurve, buildScalar, readPieces, readScalar} from '../core/values';
-import {CurveEditor} from './CurveEditor';
-import {CheckboxField, NumberField, Row, SelectField} from './fields';
-import {GradientEditor} from './GradientEditor';
-import {iconStyle} from './icons';
-import type {TextureOption} from './modules';
-import {ModuleSection} from './ModuleSection';
-import {theme} from './theme';
-import {ValueField} from './ValueField';
-
-interface ModuleProps {
-    binding: EffectBinding;
-}
+import {EffectBinding} from '../core/binding.js';
+import {buildGradient, DEFAULT_GRADIENT_STOPS, findBehavior, readGradientStops} from '../core/colors.js';
+import {buildCurve, buildScalar, readPieces, readScalar} from '../core/values.js';
+import {CurveEditor} from './CurveEditor.js';
+import {CheckboxField, NumberField, Row, SelectField} from './fields.js';
+import {GradientEditor} from './GradientEditor.js';
+import {iconStyle} from './icons.js';
+import type {TextureOption} from './modules.js';
+import {ModuleSection, type ModuleProps} from './ModuleSection.js';
+import {theme} from './theme.js';
+import {ValueField} from './ValueField.js';
 
 function removeBehaviorOfType(behaviors: Behavior[], type: string): void {
     for (let i = behaviors.length - 1; i >= 0; i--) {
@@ -85,6 +81,7 @@ function BehaviorModule<T extends Behavior>(props: {
     );
 }
 
+/** The Speed over Lifetime module (Unity's Speed Modifier): scales speed by a curve over the particle's life. */
 export function SpeedOverLifeModule({binding}: ModuleProps) {
     return (
         <BehaviorModule<SpeedOverLife>
@@ -92,9 +89,7 @@ export function SpeedOverLifeModule({binding}: ModuleProps) {
             title="Speed over Lifetime"
             type="SpeedOverLife"
             create={() =>
-                new SpeedOverLife(
-                    buildScalar({mode: 'curve', value: 1, min: 0, max: 1, curve: [1, 0.75, 0.5, 0]}) as never
-                )
+                new SpeedOverLife(buildScalar({mode: 'curve', value: 1, min: 0, max: 1, curve: [1, 0.75, 0.5, 0]}))
             }
         >
             {(behavior) => (
@@ -102,7 +97,7 @@ export function SpeedOverLifeModule({binding}: ModuleProps) {
                     <CurveEditor
                         pieces={readPieces(behavior.speed)}
                         maxValue={2}
-                        onChange={(pieces) => binding.apply(() => (behavior.speed = buildCurve(pieces) as never))}
+                        onChange={(pieces) => binding.apply(() => (behavior.speed = buildCurve(pieces)))}
                     />
                 </div>
             )}
@@ -110,6 +105,7 @@ export function SpeedOverLifeModule({binding}: ModuleProps) {
     );
 }
 
+/** The Limit Speed over Lifetime module (Unity's Limit Velocity over Lifetime): caps speed by a curve, with dampening. */
 export function LimitSpeedOverLifeModule({binding}: ModuleProps) {
     return (
         <BehaviorModule<LimitSpeedOverLife>
@@ -117,10 +113,7 @@ export function LimitSpeedOverLifeModule({binding}: ModuleProps) {
             title="Limit Speed over Lifetime"
             type="LimitSpeedOverLife"
             create={() =>
-                new LimitSpeedOverLife(
-                    buildScalar({mode: 'curve', value: 1, min: 0, max: 1, curve: [4, 2, 1, 1]}) as never,
-                    0.5
-                )
+                new LimitSpeedOverLife(buildScalar({mode: 'curve', value: 1, min: 0, max: 1, curve: [4, 2, 1, 1]}), 0.5)
             }
         >
             {(behavior) => (
@@ -129,7 +122,7 @@ export function LimitSpeedOverLifeModule({binding}: ModuleProps) {
                         <CurveEditor
                             pieces={readPieces(behavior.speed)}
                             maxValue={8}
-                            onChange={(pieces) => binding.apply(() => (behavior.speed = buildCurve(pieces) as never))}
+                            onChange={(pieces) => binding.apply(() => (behavior.speed = buildCurve(pieces)))}
                         />
                     </div>
                     <Row label="Dampen">
@@ -146,6 +139,7 @@ export function LimitSpeedOverLifeModule({binding}: ModuleProps) {
     );
 }
 
+/** The Force over Lifetime module (Unity's Force over Lifetime): a constant push per axis. */
 export function ForceOverLifeModule({binding}: ModuleProps) {
     return (
         <BehaviorModule<ForceOverLife>
@@ -156,6 +150,16 @@ export function ForceOverLifeModule({binding}: ModuleProps) {
         >
             {(behavior) => (
                 <>
+                    <Row label="Space">
+                        <SelectField
+                            value={behavior.space}
+                            options={[
+                                {value: 'world', label: 'World'},
+                                {value: 'local', label: 'Local'},
+                            ]}
+                            onChange={(v) => binding.apply(() => (behavior.space = v))}
+                        />
+                    </Row>
                     <ValueField
                         hintKey="force.x"
                         label="X"
@@ -288,6 +292,43 @@ export function InheritVelocityModule({binding}: ModuleProps) {
     );
 }
 
+/** A point attractor (`GravityForce`): particles fall towards a point, harder the nearer they are. */
+export function AttractorModule({binding}: ModuleProps) {
+    return (
+        <BehaviorModule<GravityForce>
+            binding={binding}
+            title="Attractor"
+            type="GravityForce"
+            create={() => new GravityForce(new Vector3(0, 0, 0), 1)}
+        >
+            {(behavior) => (
+                <>
+                    <Row label="Center" hintKey="attractor.center">
+                        <div style={{display: 'flex', gap: 6}}>
+                            {(['x', 'y', 'z'] as const).map((axis) => (
+                                <NumberField
+                                    key={axis}
+                                    value={behavior.center[axis]}
+                                    step={0.1}
+                                    onChange={(v) => binding.apply(() => (behavior.center[axis] = v))}
+                                />
+                            ))}
+                        </div>
+                    </Row>
+                    <Row label="Strength" hintKey="attractor.magnitude">
+                        <NumberField
+                            value={behavior.magnitude}
+                            step={0.1}
+                            onChange={(v) => binding.apply(() => (behavior.magnitude = v))}
+                        />
+                    </Row>
+                </>
+            )}
+        </BehaviorModule>
+    );
+}
+
+/** The Gravity module: pulls particles towards a point. */
 export function GravityModule({binding}: ModuleProps) {
     return (
         <BehaviorModule<ApplyForce>
@@ -297,18 +338,31 @@ export function GravityModule({binding}: ModuleProps) {
             create={() => new ApplyForce(new Vector3(0, -1, 0), new ConstantValue(9.81))}
         >
             {(behavior) => (
-                <Row label="Strength" hintKey="gravity.strength">
-                    <NumberField
-                        value={readScalar(behavior.magnitude).value}
-                        step={0.5}
-                        onChange={(v) => binding.apply(() => (behavior.magnitude = new ConstantValue(v)))}
-                    />
-                </Row>
+                <>
+                    <Row label="Strength" hintKey="gravity.strength">
+                        <NumberField
+                            value={readScalar(behavior.magnitude).value}
+                            step={0.5}
+                            onChange={(v) => binding.apply(() => (behavior.magnitude = new ConstantValue(v)))}
+                        />
+                    </Row>
+                    <Row label="Space">
+                        <SelectField
+                            value={behavior.space}
+                            options={[
+                                {value: 'world', label: 'World'},
+                                {value: 'local', label: 'Local'},
+                            ]}
+                            onChange={(v) => binding.apply(() => (behavior.space = v))}
+                        />
+                    </Row>
+                </>
             )}
         </BehaviorModule>
     );
 }
 
+/** The Rotation over Lifetime module (Unity's Rotation over Lifetime): spin rate over the particle's life. */
 export function RotationOverLifeModule({binding}: ModuleProps) {
     return (
         <BehaviorModule<RotationOverLife>
@@ -595,6 +649,7 @@ export function SequencesModule({binding, textureOptions}: ModuleProps & {textur
     );
 }
 
+/** The Noise module (Unity's Noise): moves and turns particles by a noise field. */
 export function NoiseModule({binding}: ModuleProps) {
     return (
         <BehaviorModule<Noise>
@@ -695,6 +750,7 @@ function Vector3Row(props: {
     );
 }
 
+/** The Turbulence module: a curl noise force field. */
 export function TurbulenceModule({binding}: ModuleProps) {
     return (
         <BehaviorModule<TurbulenceField>
@@ -735,12 +791,36 @@ export function TurbulenceModule({binding}: ModuleProps) {
                         step={0.1}
                         onChange={(v) => binding.apply(() => (behavior.timeScale = v))}
                     />
+                    {/* The field is built from the seed, so a different seed is a different swirl. */}
+                    <Row label="Seed">
+                        <NumberField
+                            value={behavior.seed}
+                            step={1}
+                            onChange={(v) =>
+                                binding.apply(() => {
+                                    const seed = Math.round(v);
+                                    const next = new TurbulenceField(
+                                        behavior.scale,
+                                        behavior.octaves,
+                                        behavior.velocityMultiplier,
+                                        behavior.timeScale,
+                                        seed
+                                    );
+                                    behavior.seed = seed;
+                                    behavior.generator = next.generator;
+                                    behavior.initialOffset.copy(next.initialOffset);
+                                    behavior.timeOffset.copy(next.initialOffset);
+                                })
+                            }
+                        />
+                    </Row>
                 </>
             )}
         </BehaviorModule>
     );
 }
 
+/** The Randomize Direction module: tilts each particle's start direction by a random angle. */
 export function EmitDirectionModule({binding}: ModuleProps) {
     return (
         <BehaviorModule<ChangeEmitDirection>
@@ -752,25 +832,26 @@ export function EmitDirectionModule({binding}: ModuleProps) {
             {(behavior) => (
                 <ValueField
                     label="Angle (rad)"
-                    generator={behavior.angle as never}
+                    generator={behavior.angle}
+                    curve={false}
                     min={0}
-                    curveMax={Math.PI}
-                    onChange={(g) => binding.apply(() => (behavior.angle = g as never))}
+                    onChange={(g) => binding.apply(() => (behavior.angle = g))}
                 />
             )}
         </BehaviorModule>
     );
 }
 
+/** The Collision module (Unity's Collision): particles bounce off or die on a ground plane. */
 export function CollisionModule({binding}: ModuleProps) {
     // Like Unity: Collision stores bounce only. Colliders are host-provided via
-    // setPhysicsResolver — the editor never invents a ground plane.
+    // setPhysicsResolver, asked when a particle is tested — the editor never invents a ground plane.
     return (
         <BehaviorModule<ApplyCollision>
             binding={binding}
             title="Collision"
             type="ApplyCollision"
-            create={() => new ApplyCollision(getPhysicsResolver(), 0.5)}
+            create={() => new ApplyCollision(undefined, 0.5)}
         >
             {(behavior) => (
                 <>
@@ -816,6 +897,7 @@ function SpeedRangeRows({binding, behavior}: {binding: EffectBinding; behavior:
     );
 }
 
+/** The Color by Speed module (Unity's Color by Speed): a gradient over a speed range. */
 export function ColorBySpeedModule({binding}: ModuleProps) {
     return (
         <BehaviorModule<ColorBySpeed>
@@ -843,6 +925,7 @@ export function ColorBySpeedModule({binding}: ModuleProps) {
     );
 }
 
+/** The Size by Speed module (Unity's Size by Speed): size over a speed range. */
 export function SizeBySpeedModule({binding}: ModuleProps) {
     return (
         <BehaviorModule<SizeBySpeed>
@@ -851,7 +934,7 @@ export function SizeBySpeedModule({binding}: ModuleProps) {
             type="SizeBySpeed"
             create={() =>
                 new SizeBySpeed(
-                    buildScalar({mode: 'curve', value: 1, min: 0, max: 1, curve: [0.5, 0.8, 1.2, 1.5]}) as never,
+                    buildScalar({mode: 'curve', value: 1, min: 0, max: 1, curve: [0.5, 0.8, 1.2, 1.5]}),
                     new IntervalValue(0, 5)
                 )
             }
@@ -860,9 +943,9 @@ export function SizeBySpeedModule({binding}: ModuleProps) {
                 <>
                     <div style={{marginTop: 6}}>
                         <CurveEditor
-                            pieces={readPieces(behavior.size as never)}
+                            pieces={readPieces(behavior.size)}
                             maxValue={2}
-                            onChange={(pieces) => binding.apply(() => (behavior.size = buildCurve(pieces) as never))}
+                            onChange={(pieces) => binding.apply(() => (behavior.size = buildCurve(pieces)))}
                         />
                     </div>
                     <SpeedRangeRows binding={binding} behavior={behavior} />
@@ -872,6 +955,7 @@ export function SizeBySpeedModule({binding}: ModuleProps) {
     );
 }
 
+/** The Rotation by Speed module (Unity's Rotation by Speed): spin rate over a speed range. */
 export function RotationBySpeedModule({binding}: ModuleProps) {
     return (
         <BehaviorModule<RotationBySpeed>
@@ -896,6 +980,7 @@ export function RotationBySpeedModule({binding}: ModuleProps) {
     );
 }
 
+/** The Orbit over Lifetime module (Unity's Velocity over Lifetime orbital): turns particles about an axis. */
 export function OrbitOverLifeModule({binding}: ModuleProps) {
     return (
         <BehaviorModule<OrbitOverLife>
@@ -916,6 +1001,7 @@ export function OrbitOverLifeModule({binding}: ModuleProps) {
     );
 }
 
+/** The Width over Trail module (Unity's Trails width over trail): a trail's width along its length. */
 export function WidthOverTrailModule({binding}: ModuleProps) {
     return (
         <BehaviorModule<WidthOverLength>
@@ -923,18 +1009,16 @@ export function WidthOverTrailModule({binding}: ModuleProps) {
             title="Width over Trail"
             type="WidthOverLength"
             create={() =>
-                new WidthOverLength(
-                    buildScalar({mode: 'curve', value: 1, min: 0, max: 1, curve: [1, 0.75, 0.4, 0]}) as never
-                )
+                new WidthOverLength(buildScalar({mode: 'curve', value: 1, min: 0, max: 1, curve: [1, 0.75, 0.4, 0]}))
             }
         >
             {(behavior) => (
                 <>
                     <div style={{marginTop: 6}}>
                         <CurveEditor
-                            pieces={readPieces(behavior.width as never)}
+                            pieces={readPieces(behavior.width)}
                             maxValue={2}
-                            onChange={(pieces) => binding.apply(() => (behavior.width = buildCurve(pieces) as never))}
+                            onChange={(pieces) => binding.apply(() => (behavior.width = buildCurve(pieces)))}
                         />
                     </div>
                     {/* Off: the curve multiplies the particle size. On: it is the width in world units (files from 0.21 and earlier). */}
@@ -950,6 +1034,13 @@ export function WidthOverTrailModule({binding}: ModuleProps) {
     );
 }
 
+/** How many of the first frames a start-frame generator picks from: its exclusive upper bound. */
+function startFrameCount(startFrame: FrameOverLife['startFrame']): number {
+    const state = readScalar(startFrame);
+    return Math.round(state.mode === 'random' ? state.max : state.value);
+}
+
+/** The Texture Sheet Animation module (Unity's Texture Sheet Animation): plays the sheet's frames by life or by frame rate. */
 export function TextureSheetModule({binding}: ModuleProps) {
     const system = binding.system;
     const frameBehavior = findBehavior<FrameOverLife>(system.behaviors, 'FrameOverLife');
@@ -958,7 +1049,7 @@ export function TextureSheetModule({binding}: ModuleProps) {
     const u = Math.max(1, system.uTileCount);
     const v = Math.max(1, system.vTileCount);
     // Start tile → cell (row-major, top-left origin — matches the shader's tile UV mapping).
-    const startIdx = Math.min(Math.max(0, Math.round(readScalar(system.startTileIndex as never).value)), tiles - 1);
+    const startIdx = Math.min(Math.max(0, Math.round(readScalar(system.startTileIndex).value)), tiles - 1);
     const startCol = startIdx % u;
     const startRow = Math.floor(startIdx / u);
     return (
@@ -1047,7 +1138,7 @@ export function TextureSheetModule({binding}: ModuleProps) {
             </Row>
             <Row label="Start tile">
                 <NumberField
-                    value={readScalar(system.startTileIndex as never).value}
+                    value={readScalar(system.startTileIndex).value}
                     min={0}
                     step={1}
                     onChange={(v) => binding.apply((s) => (s.startTileIndex = new ConstantValue(Math.round(v))))}
@@ -1071,7 +1162,7 @@ export function TextureSheetModule({binding}: ModuleProps) {
                                             min: 0,
                                             max: tiles - 1,
                                             curve: [0, (tiles - 1) / 3, (2 * (tiles - 1)) / 3, tiles - 1],
-                                        }) as never
+                                        })
                                     )
                                 );
                             }
@@ -1080,13 +1171,107 @@ export function TextureSheetModule({binding}: ModuleProps) {
                 />
             </Row>
             {frameBehavior && (
-                <div style={{marginTop: 6}}>
-                    <CurveEditor
-                        pieces={readPieces(frameBehavior.frame)}
-                        maxValue={Math.max(1, tiles - 1)}
-                        onChange={(pieces) => binding.apply(() => (frameBehavior.frame = buildCurve(pieces) as never))}
-                    />
-                </div>
+                <>
+                    <Row label="Time mode">
+                        <SelectField<'life' | 'fps'>
+                            value={frameBehavior.fps > 0 ? 'fps' : 'life'}
+                            options={[
+                                {value: 'life', label: 'Lifetime (curve over life)'},
+                                {value: 'fps', label: 'FPS (frame from curve, then by age)'},
+                            ]}
+                            onChange={(mode) =>
+                                binding.apply(() => {
+                                    frameBehavior.fps = mode === 'fps' ? 12 : 0;
+                                    if (mode === 'fps' && frameBehavior.frameCount <= 0) {
+                                        frameBehavior.frameCount = tiles;
+                                    }
+                                })
+                            }
+                        />
+                    </Row>
+                    {frameBehavior.fps > 0 ? (
+                        <>
+                            <Row label="FPS">
+                                <NumberField
+                                    value={frameBehavior.fps}
+                                    min={0.01}
+                                    step={1}
+                                    onChange={(v) => binding.apply(() => (frameBehavior.fps = v))}
+                                />
+                            </Row>
+                            <Row label="Loop">
+                                <CheckboxField
+                                    value={frameBehavior.loop}
+                                    onChange={(v) => binding.apply(() => (frameBehavior.loop = v))}
+                                />
+                            </Row>
+                            <Row label="Random frame">
+                                <CheckboxField
+                                    value={frameBehavior.random}
+                                    onChange={(v) => binding.apply(() => (frameBehavior.random = v))}
+                                />
+                            </Row>
+                        </>
+                    ) : (
+                        <Row label="Cycles">
+                            <NumberField
+                                value={frameBehavior.cycles}
+                                min={0.01}
+                                step={1}
+                                onChange={(v) => binding.apply(() => (frameBehavior.cycles = v))}
+                            />
+                        </Row>
+                    )}
+                    <Row label="Frame count">
+                        <NumberField
+                            value={frameBehavior.frameCount}
+                            min={frameBehavior.fps > 0 || frameBehavior.startFrame ? 1 : 0}
+                            max={tiles}
+                            step={1}
+                            onChange={(v) =>
+                                binding.apply(() => (frameBehavior.frameCount = Math.max(0, Math.round(v))))
+                            }
+                        />
+                    </Row>
+                    <Row label="Start frame">
+                        <CheckboxField
+                            value={!!frameBehavior.startFrame}
+                            onChange={(v) =>
+                                binding.apply(() => {
+                                    frameBehavior.startFrame = v ? new IntervalValue(0, tiles) : undefined;
+                                    // The offset only wraps into a segment; without one it runs off the sheet.
+                                    if (v && frameBehavior.frameCount <= 0) {
+                                        frameBehavior.frameCount = tiles;
+                                    }
+                                })
+                            }
+                        />
+                        {frameBehavior.startFrame && (
+                            <NumberField
+                                value={startFrameCount(frameBehavior.startFrame)}
+                                min={1}
+                                max={tiles}
+                                step={1}
+                                onChange={(v) =>
+                                    binding.apply(
+                                        () =>
+                                            (frameBehavior.startFrame = new IntervalValue(
+                                                0,
+                                                Math.max(1, Math.round(v))
+                                            ))
+                                    )
+                                }
+                            />
+                        )}
+                    </Row>
+                    <div style={{marginTop: 6}}>
+                        <CurveEditor
+                            pieces={readPieces(frameBehavior.frame)}
+                            maxValue={Math.max(1, tiles - 1)}
+                            onChange={(pieces) => binding.apply(() => (frameBehavior.frame = buildCurve(pieces)))}
+                        />
+                    </div>
+                </>
             )}
         </ModuleSection>
     );

package/src/react/fields.tsx

@@ -1,7 +1,8 @@
 import React, {useEffect, useState} from 'react';
-import {InspectorLabel} from './InspectorLabel';
-import {inputStyle, rowStyle} from './theme';
+import {InspectorLabel} from './InspectorLabel.js';
+import {inputStyle, rowStyle} from './theme.js';
 
+/** An inspector row: a label, with an optional hint, and its controls. */
 export function Row(props: {label: string; hint?: string; hintKey?: string; children: React.ReactNode}) {
     return (
         <div style={rowStyle}>
@@ -12,7 +13,13 @@ export function Row(props: {label: string; hint?: string; hintKey?: string; chil
 }
 
 /** Number input that keeps focus-friendly local text state and commits parsed values. */
-export function NumberField(props: {value: number; onChange: (value: number) => void; step?: number; min?: number}) {
+export function NumberField(props: {
+    value: number;
+    onChange: (value: number) => void;
+    step?: number;
+    min?: number;
+    max?: number;
+}) {
     const [text, setText] = useState(String(round(props.value)));
     const focusedRef = React.useRef(false);
     useEffect(() => {
@@ -28,6 +35,7 @@ export function NumberField(props: {value: number; onChange: (value: number) =>
             value={text}
             step={props.step ?? 0.1}
             min={props.min}
+            max={props.max}
             onFocus={() => {
                 focusedRef.current = true;
             }}
@@ -46,6 +54,7 @@ export function NumberField(props: {value: number; onChange: (value: number) =>
     );
 }
 
+/** A checkbox bound to a boolean. */
 export function CheckboxField(props: {value: boolean; onChange: (value: boolean) => void}) {
     return (
         <input
@@ -58,9 +67,18 @@ export function CheckboxField(props: {value: boolean; onChange: (value: boolean)
     );
 }
 
+/** A select bound to a value, from a list of options. */
 export function SelectField<T extends string | number>(props: {
+    /** The selected value. */
     value: T;
-    options: Array<{value: T; label: string}>;
+    /** The options, in menu order. */
+    options: Array<{
+        /** The option's value. */
+        value: T;
+        /** Its text. */
+        label: string;
+    }>;
+    /** Receives the picked value, a number when the values are numbers. */
     onChange: (value: T) => void;
 }) {
     const numeric = typeof props.value === 'number';