dazscript-framework 1.0.15 → 1.0.17

package/README.md

@@ -501,7 +501,7 @@ The framework ships helpers for common Daz Studio tasks, all importable from `@d
 |---|---|
 | `scene-helper` | `getRoot()`, `getSelectedNode()`, `getNodes()` |
 | `node-helper` | Type checks (`isFigure`, `isBone`), transforms, visibility |
-| `property-helper` | Find, read, and adjust node properties |
+| `property-helper` | Set paths, unlock, cast numeric types, and inspect property inputs/outputs |
 | `array-helper` | `distinct()`, `flatten()`, `groupBy()` |
 | `string-helper` | Case, trimming, splitting |
 | `directory-helper` | File and path operations |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dazscript-framework",
-  "version": "1.0.15",
+  "version": "1.0.17",
   "author": "Freddy Diaz",
   "license": "MPL-2.0",
   "description": "",

package/src/helpers/message-box-helper.test.ts

@@ -0,0 +1,43 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import { confirm, prompt } from './message-box-helper'
+
+vi.mock('@dsf/common/log', () => ({ debug: vi.fn() }))
+
+describe('message-box-helper', () => {
+    const question = vi.fn()
+
+    beforeEach(() => {
+        question.mockReset()
+        vi.stubGlobal('MessageBox', { question })
+    })
+
+    it('treats the first confirm button as ok', () => {
+        question.mockReturnValue(0)
+
+        expect(confirm('Continue?')).toEqual({ ok: true, cancel: false })
+    })
+
+    it('treats the second confirm button as cancel', () => {
+        question.mockReturnValue(1)
+
+        expect(confirm('Continue?')).toEqual({ ok: false, cancel: true })
+    })
+
+    it('treats the first prompt button as cancel so Esc is also cancel', () => {
+        question.mockReturnValue(0)
+
+        expect(prompt('Reset?', 'Reset', 'Zero', 'Default')).toEqual({ cancel: true, selection: -1 })
+    })
+
+    it('maps the second prompt button to the first selection', () => {
+        question.mockReturnValue(1)
+
+        expect(prompt('Reset?', 'Reset', 'Zero', 'Default')).toEqual({ cancel: false, selection: 0 })
+    })
+
+    it('maps the third prompt button to the second selection', () => {
+        question.mockReturnValue(2)
+
+        expect(prompt('Reset?', 'Reset', 'Zero', 'Default')).toEqual({ cancel: false, selection: 1 })
+    })
+})

package/src/helpers/message-box-helper.ts

@@ -20,7 +20,7 @@ export const confirm = (message?: string): { ok: boolean, cancel: boolean } => {
 }
 
 export const prompt = (text: string, title: string, button0: string, button1?: string): { cancel: boolean, selection: number } => {
-    const response = MessageBox.question(text, title, button0, button1 ?? "", "Cancel")
+    const response = MessageBox.question(text, title, "Cancel", button0, button1 ?? "")
 
-    return { cancel: response === 0, selection: response };
-}
+    return { cancel: response === 0, selection: response - 1 };
+}

package/src/helpers/property-helper.test.ts

@@ -0,0 +1,94 @@
+import { describe, expect, it, vi } from 'vitest'
+import { getPropertyInputs, getPropertyOutputs } from './property-helper'
+
+vi.mock('@dsf/core/global', () => ({
+    sceneHelper: {
+        getInternalName: vi.fn(),
+        getNode: vi.fn(),
+        getUniqueMorphName: vi.fn(),
+        setInternalName: vi.fn(),
+        setPropertyPath: vi.fn()
+    }
+}))
+
+describe('property-helper relationships', () => {
+    const property = (name: string, inheritsTypes: string[] = []) => ({
+        name,
+        inherits: (type: string) => inheritsTypes.indexOf(type) >= 0,
+        getNumControllers: () => 0,
+        getController: () => null,
+        getNumSlaveControllers: () => 0,
+        getSlaveController: () => null,
+        getLinkProperty: () => null,
+        getFollowProperty: () => null
+    }) as any
+
+    it('gets input properties from normal and redirected controller properties', () => {
+        const driver = property('driver')
+        const redirectedDriver = property('redirectedDriver')
+        const controller = {
+            getProperty: () => driver,
+            getCurrentProperty: () => redirectedDriver
+        }
+        const driven = {
+            ...property('driven'),
+            getNumControllers: () => 1,
+            getController: () => controller
+        }
+
+        expect(getPropertyInputs(driven as any)).toEqual([
+            { property: driver, controller, source: 'controller' },
+            { property: redirectedDriver, controller, source: 'currentController' }
+        ])
+    })
+
+    it('gets input properties from direct numeric link and follow properties', () => {
+        const link = property('link')
+        const follow = property('follow')
+        const driven = {
+            ...property('driven', ['DzNumericProperty', 'DzFloatProperty']),
+            getLinkProperty: () => link,
+            getFollowProperty: () => follow
+        }
+
+        expect(getPropertyInputs(driven as any)).toEqual([
+            { property: link, controller: null, source: 'link' },
+            { property: follow, controller: null, source: 'follow' }
+        ])
+    })
+
+    it('gets output properties from slave controller owners', () => {
+        const output = property('output')
+        const controller = {
+            getOwner: () => output
+        }
+        const driver = {
+            ...property('driver'),
+            getNumSlaveControllers: () => 1,
+            getSlaveController: () => controller
+        }
+
+        expect(getPropertyOutputs(driver as any)).toEqual([
+            { property: output, controller, source: 'slaveController' }
+        ])
+    })
+
+    it('does not duplicate the same relation', () => {
+        const driver = property('driver')
+        const controller = {
+            getProperty: () => driver,
+            getCurrentProperty: () => driver
+        }
+        const driven = {
+            ...property('driven'),
+            getNumControllers: () => 2,
+            getController: () => controller
+        }
+
+        expect(getPropertyInputs(driven as any)).toEqual([
+            { property: driver, controller, source: 'controller' },
+            { property: driver, controller, source: 'currentController' }
+        ])
+    })
+
+})

package/src/helpers/property-helper.ts

@@ -1,5 +1,19 @@
 import { sceneHelper } from '@dsf/core/global'
 
+export type PropertyRelationSource = 'controller' | 'currentController' | 'link' | 'follow' | 'slaveController'
+
+/**
+ * A property relationship discovered from Daz controller, link, follow, or slave-controller APIs.
+ */
+export type PropertyRelation = {
+    /** The related input or output property. */
+    property: DzProperty
+    /** The controller that exposed the relation, or null for direct numeric property links. */
+    controller: DzController | null
+    /** The Daz API surface that exposed the relation. */
+    source: PropertyRelationSource
+}
+
 /**
  * Sets the DzPropertyGroup path (and appropriate geometryregion_dz) for the given property.
  * @param property  The property to change the path of.
@@ -18,6 +32,11 @@ export const getName = (property: DzProperty): string => {
     return sceneHelper.getInternalName(property).valueOf()
 }
 
+/**
+ * Ensures the property's internal name is unique on its owning node.
+ * @param property The property whose internal name should be checked.
+ * @returns The unique internal name assigned to the property.
+ */
 export const ensureNameIsUnique = (property: DzProperty): string => {
     const name = getName(property)
     const uniqueName = sceneHelper.getUniqueMorphName(sceneHelper.getNode(property), name)
@@ -39,24 +58,122 @@ export const unlock = (property: DzProperty, then: (property: DzProperty) => voi
     if (locked) property.lock(false)
 }
 
+/**
+ * Adds a property relation unless the same property, controller, and source were already collected.
+ * @param relations The relation collection to update.
+ * @param property The related property to add, or null to skip.
+ * @param controller The controller that exposed the relation, or null for direct property links.
+ * @param source The Daz API surface that exposed the relation.
+ */
+const addRelation = (relations: PropertyRelation[], property: DzProperty | null, controller: DzController | null, source: PropertyRelationSource): void => {
+    if (!property) return
+
+    for (let relation of relations) {
+        if (relation.property === property && relation.controller === controller && relation.source === source) return
+    }
+
+    relations.push({ property, controller, source })
+}
+
+/**
+ * Gets the source property referenced by a controller.
+ * @param controller The controller to inspect.
+ * @param current If true, uses getCurrentProperty; otherwise, uses getProperty.
+ * @returns The controller's property, or null when the controller does not expose that method.
+ */
+const getControllerProperty = (controller: DzController, current: boolean): DzProperty | null => {
+    const methodName = current ? 'getCurrentProperty' : 'getProperty'
+    const method = (controller as any)[methodName]
+    if (typeof method !== 'function') return null
+
+    return method.call(controller) as DzProperty | null
+}
+
+/**
+ * Gets properties that drive this property through controllers or direct numeric links.
+ * @param property The property whose input/driving properties should be collected.
+ * @returns Related input properties with the controller/source that exposed each relation.
+ */
+export const getPropertyInputs = (property: DzProperty): PropertyRelation[] => {
+    const relations: PropertyRelation[] = []
+    const controllerCount = property.getNumControllers()
+
+    for (let index = 0; index < controllerCount; index++) {
+        const controller = property.getController(index)
+        addRelation(relations, getControllerProperty(controller, false), controller, 'controller')
+        addRelation(relations, getControllerProperty(controller, true), controller, 'currentController')
+    }
+
+    const numericProperty = cast<DzNumericProperty>(property, 'DzNumericProperty')
+    if (numericProperty) {
+        addRelation(relations, numericProperty.getLinkProperty(), null, 'link')
+        addRelation(relations, numericProperty.getFollowProperty(), null, 'follow')
+    }
+
+    return relations
+}
+
+/**
+ * Gets properties driven by this property through slave controllers.
+ * @param property The property whose output/driven properties should be collected.
+ * @returns Related output properties with the controller/source that exposed each relation.
+ */
+export const getPropertyOutputs = (property: DzProperty): PropertyRelation[] => {
+    const relations: PropertyRelation[] = []
+    const controllerCount = property.getNumSlaveControllers()
+
+    for (let index = 0; index < controllerCount; index++) {
+        const controller = property.getSlaveController(index)
+        addRelation(relations, controller.getOwner(), controller, 'slaveController')
+    }
+
+    return relations
+}
+
+/**
+ * Checks whether a property is a Daz numeric property.
+ * @param property The property to check.
+ * @returns True if the property inherits DzNumericProperty.
+ */
 export const isNumeric = (property: DzProperty): boolean => {
     return property.inherits('DzNumericProperty')
 }
 
+/**
+ * Casts a property to a specific Daz property type when it inherits that type.
+ * @param property The property to cast.
+ * @param type The Daz property class name to test.
+ * @returns The property typed as T, or null when it does not inherit the requested type.
+ */
 export const cast = <T extends DzProperty>(property: DzProperty, type: 'DzNumericProperty' | 'DzFloatProperty' | 'DzIntProperty'): T | null => {
     return property.inherits(type)
         ? property as T
         : null
 }
 
+/**
+ * Casts a property to a numeric float or int property.
+ * @param property The property to cast.
+ * @returns The property as DzFloatProperty or DzIntProperty, or null if it is neither.
+ */
 export const toNumeric = (property: DzProperty): DzFloatProperty | DzIntProperty | null => {
     return toFloat(property) ?? toInt(property)
 }
 
+/**
+ * Casts a property to a float property.
+ * @param property The property to cast.
+ * @returns The property as DzFloatProperty, or null if it is not one.
+ */
 export const toFloat = (property: DzProperty): DzFloatProperty | null => {
     return cast<DzFloatProperty>(property, 'DzFloatProperty')
 }
 
+/**
+ * Casts a property to an int property.
+ * @param property The property to cast.
+ * @returns The property as DzIntProperty, or null if it is not one.
+ */
 export const toInt = (property: DzProperty): DzIntProperty | null => {
     return cast<DzIntProperty>(property, 'DzIntProperty')
-}
+}

package/src/helpers/transform-bake-helper.test.ts

@@ -0,0 +1,122 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+
+vi.mock('./numeric-property-helper', () => ({ adjust: vi.fn() }))
+vi.mock('@dsf/core/global', () => ({
+    sceneHelper: {
+        getInternalName: vi.fn(),
+        getNode: vi.fn(),
+        getUniqueMorphName: vi.fn(),
+        setInternalName: vi.fn(),
+        setPropertyPath: vi.fn()
+    }
+}))
+
+const { adjust } = await import('./numeric-property-helper')
+const { bakeRotations, bakeScale, bakeTranslations, bakeTransforms, collectTransformBakePlan } = await import('./transform-bake-helper')
+
+type TestProperty = {
+    name: string
+    path: string
+    value: number
+    outputs: TestProperty[]
+    getName: () => string
+    getPath: () => string
+    getValue: () => number
+    getNumSlaveControllers: () => number
+    getSlaveController: (index: number) => { getOwner: () => TestProperty }
+    getNumControllers: () => number
+    getController: () => null
+    inherits: (type: string) => boolean
+}
+
+const property = (name: string, path = '/Pose Controls'): TestProperty => {
+    const testProperty: TestProperty = {
+        name,
+        path,
+        value: 7,
+        outputs: [],
+        getName: () => testProperty.name,
+        getPath: () => testProperty.path,
+        getValue: () => testProperty.value,
+        getNumSlaveControllers: () => testProperty.outputs.length,
+        getSlaveController: (index: number) => ({ getOwner: () => testProperty.outputs[index] }),
+        getNumControllers: () => 0,
+        getController: () => null,
+        inherits: (type: string) => type === 'DzNumericProperty' || type === 'DzFloatProperty'
+    }
+
+    return testProperty
+}
+
+const link = (driver: TestProperty, output: TestProperty): void => {
+    driver.outputs.push(output)
+}
+
+beforeEach(() => {
+    vi.clearAllMocks()
+})
+
+describe('transform bake helper', () => {
+    it('plans recursive output reset and selected rotation capture', () => {
+        const master = property('body_ctrl_rHandGrasp')
+        const middle = property('body_ctrl_rFingersGrasp')
+        const rotation = property('ZRotate', '/General/Transforms/Rotation')
+        const corrective = property('Value', '/Hidden/Base Correctives/Hands')
+        link(master, middle)
+        link(middle, rotation)
+        link(rotation, corrective)
+
+        const plan = collectTransformBakePlan(master, { rotations: true })
+
+        expect(plan.resetProperties).toEqual([master, middle, rotation, corrective])
+        expect(plan.capturedProperties).toEqual([rotation])
+    })
+
+    it('bakes selected transforms by capturing final values, zeroing chain, then restoring captures', () => {
+        const master = property('master')
+        const rotation = property('XRotate', '/General/Transforms/Rotation')
+        rotation.value = 45
+        link(master, rotation)
+
+        bakeTransforms(master, { rotations: true })
+
+        expect(adjust).toHaveBeenNthCalledWith(1, master, 0)
+        expect(adjust).toHaveBeenNthCalledWith(2, rotation, 0)
+        expect(adjust).toHaveBeenNthCalledWith(3, rotation, 45)
+    })
+
+    it('filters translations and scale independently', () => {
+        const master = property('master')
+        const translation = property('XTranslate', '/General/Transforms/Translation')
+        const rotation = property('XRotate', '/General/Transforms/Rotation')
+        const scale = property('XScale', '/General/Transforms/Scale')
+        link(master, translation)
+        link(master, rotation)
+        link(master, scale)
+
+        expect(collectTransformBakePlan(master, { translations: true }).capturedProperties).toEqual([translation])
+        expect(collectTransformBakePlan(master, { rotations: true }).capturedProperties).toEqual([rotation])
+        expect(collectTransformBakePlan(master, { scale: true }).capturedProperties).toEqual([scale])
+    })
+
+    it('exposes focused bake helpers', () => {
+        const master = property('master')
+        const translation = property('YTranslate', '/General/Transforms/Translation')
+        const rotation = property('YRotate', '/General/Transforms/Rotation')
+        const scale = property('YScale', '/General/Transforms/Scale')
+        link(master, translation)
+        link(master, rotation)
+        link(master, scale)
+
+        bakeRotations(master)
+        expect(adjust).toHaveBeenLastCalledWith(rotation, 7)
+
+        vi.clearAllMocks()
+        bakeTranslations(master)
+        expect(adjust).toHaveBeenLastCalledWith(translation, 7)
+
+        vi.clearAllMocks()
+        bakeScale(master)
+        expect(adjust).toHaveBeenLastCalledWith(scale, 7)
+    })
+})

package/src/helpers/transform-bake-helper.ts

@@ -0,0 +1,172 @@
+import { adjust } from './numeric-property-helper'
+import { getPropertyOutputs } from './property-helper'
+
+export type TransformBakeOptions = {
+    rotations?: boolean
+    translations?: boolean
+    scale?: boolean
+    maxDepth?: number
+}
+
+export type TransformBakePlan = {
+    resetProperties: DzProperty[]
+    capturedProperties: TransformBakeProperty[]
+}
+
+type TransformBakeProperty = DzFloatProperty | DzIntProperty | DzBoolProperty
+
+type CapturedPropertyValue = {
+    property: TransformBakeProperty
+    value: number
+}
+
+const DEFAULT_MAX_DEPTH = 10
+
+const hasProperty = (properties: DzProperty[], property: DzProperty): boolean => {
+    for (let index = 0; index < properties.length; index++) {
+        if (properties[index] === property) return true
+    }
+
+    return false
+}
+
+const isTransformBakeProperty = (property: DzProperty): property is TransformBakeProperty => {
+    return property.inherits('DzFloatProperty') || property.inherits('DzIntProperty') || property.inherits('DzBoolProperty')
+}
+
+const getPropertyName = (property: DzProperty): string => {
+    const getName = (property as any).getName
+    if (typeof getName === 'function') return String(getName.call(property))
+
+    return String((property as any).name ?? '')
+}
+
+const getPropertyPath = (property: DzProperty): string => {
+    const getPath = (property as any).getPath
+    if (typeof getPath === 'function') return String(getPath.call(property))
+
+    return ''
+}
+
+const isRotationProperty = (property: DzProperty): boolean => {
+    const name = getPropertyName(property)
+    return getPropertyPath(property) === '/General/Transforms/Rotation'
+        || name === 'XRotate'
+        || name === 'YRotate'
+        || name === 'ZRotate'
+}
+
+const isTranslationProperty = (property: DzProperty): boolean => {
+    const name = getPropertyName(property)
+    return getPropertyPath(property) === '/General/Transforms/Translation'
+        || name === 'XTranslate'
+        || name === 'YTranslate'
+        || name === 'ZTranslate'
+}
+
+const isScaleProperty = (property: DzProperty): boolean => {
+    const name = getPropertyName(property)
+    return getPropertyPath(property) === '/General/Transforms/Scale'
+        || name === 'Scale'
+        || name === 'XScale'
+        || name === 'YScale'
+        || name === 'ZScale'
+}
+
+const shouldCaptureProperty = (property: DzProperty, options: TransformBakeOptions): boolean => {
+    return (options.rotations === true && isRotationProperty(property))
+        || (options.translations === true && isTranslationProperty(property))
+        || (options.scale === true && isScaleProperty(property))
+}
+
+const collectRecursiveOutputProperties = (property: DzProperty, maxDepth: number): DzProperty[] => {
+    const outputs: DzProperty[] = []
+    const queue: DzProperty[] = [property]
+    const depths: number[] = [0]
+
+    for (let queueIndex = 0; queueIndex < queue.length; queueIndex++) {
+        const driver = queue[queueIndex]
+        const depth = depths[queueIndex]
+        if (depth >= maxDepth) continue
+
+        const relations = getPropertyOutputs(driver)
+        for (let relationIndex = 0; relationIndex < relations.length; relationIndex++) {
+            const output = relations[relationIndex].property
+            if (!output) continue
+            if (hasProperty(outputs, output)) continue
+
+            outputs.push(output)
+            if (!hasProperty(queue, output)) {
+                queue.push(output)
+                depths.push(depth + 1)
+            }
+        }
+    }
+
+    return outputs
+}
+
+export const collectTransformBakePlan = (property: DzProperty, options: TransformBakeOptions): TransformBakePlan => {
+    const outputs = collectRecursiveOutputProperties(property, options.maxDepth ?? DEFAULT_MAX_DEPTH)
+    const capturedProperties: TransformBakeProperty[] = []
+
+    for (let index = 0; index < outputs.length; index++) {
+        const output = outputs[index]
+        if (!isTransformBakeProperty(output)) continue
+        if (!shouldCaptureProperty(output, options)) continue
+
+        capturedProperties.push(output)
+    }
+
+    return {
+        resetProperties: [property].concat(outputs),
+        capturedProperties
+    }
+}
+
+const captureValues = (properties: TransformBakeProperty[]): CapturedPropertyValue[] => {
+    const values: CapturedPropertyValue[] = []
+
+    for (let index = 0; index < properties.length; index++) {
+        const property = properties[index]
+        values.push({ property, value: (property as any).getValue() })
+    }
+
+    return values
+}
+
+const resetProperties = (properties: DzProperty[]): void => {
+    for (let index = 0; index < properties.length; index++) {
+        const property = properties[index]
+        if (!isTransformBakeProperty(property)) continue
+
+        adjust(property, 0)
+    }
+}
+
+const restoreValues = (values: CapturedPropertyValue[]): void => {
+    for (let index = 0; index < values.length; index++) {
+        const captured = values[index]
+        adjust(captured.property, captured.value)
+    }
+}
+
+export const bakeTransforms = (property: DzProperty, options: TransformBakeOptions): void => {
+    const plan = collectTransformBakePlan(property, options)
+    const capturedValues = captureValues(plan.capturedProperties)
+
+    resetProperties(plan.resetProperties)
+    restoreValues(capturedValues)
+}
+
+export const bakeRotations = (property: DzProperty): void => {
+    bakeTransforms(property, { rotations: true })
+}
+
+export const bakeTranslations = (property: DzProperty): void => {
+    bakeTransforms(property, { translations: true })
+}
+
+export const bakeScale = (property: DzProperty): void => {
+    bakeTransforms(property, { scale: true })
+}