feat(dazpy): add dForce simulation control

Add DazDForce modifier proxy (freeze_simulation/freeze/unfreeze, backed
by the "Freeze Simulation" property DAZ exposes on DzDForceModifier),
wire it into DazNode's modifier type discrimination and a new
dforce_modifiers() filter, and add DazScene.run_dforce_simulation()/
is_simulating()/clear_dforce_simulation() driven by DzSimulationMgr.
Long-running simulations use the async execute-and-poll path via
execute_long. Closes daz-script-server-23o.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

Author: ghirpara

.beads/interactions.jsonl

@@ -107,3 +107,4 @@
 {"id":"int-5a43b6c7","kind":"field_change","created_at":"2026-06-25T02:24:17.8197462Z","actor":"G.Hirpara","issue_id":"daz-script-server-017","extra":{"field":"status","new_value":"in_progress","old_value":"open"}}
 {"id":"int-8d6b4894","kind":"field_change","created_at":"2026-06-27T16:13:46.4041403Z","actor":"G.Hirpara","issue_id":"daz-script-server-4kg","extra":{"field":"status","new_value":"closed","old_value":"in_progress","reason":"Updated all four .github/workflows/*.md docs to reflect 6-job DS4+DS6 build matrix, new artifact naming, private SDK repo, and Qt6 caching"}}
 {"id":"int-596487b9","kind":"field_change","created_at":"2026-06-27T16:19:25.0398042Z","actor":"G.Hirpara","issue_id":"daz-script-server-v4b","extra":{"field":"status","new_value":"closed","old_value":"in_progress","reason":"Implemented: build-dazpy now builds wheel+sdist, release-tagged.yml has publish-pypi job using OIDC, artifact renamed to dazpy-dist everywhere, docs updated"}}
+{"id":"int-31bf68ff","kind":"field_change","created_at":"2026-07-13T11:50:35.0064285Z","actor":"G.Hirpara","issue_id":"daz-script-server-23o","extra":{"field":"status","new_value":"closed","old_value":"in_progress","reason":"Added DazDForce modifier class (freeze/unfreeze), DazNode.dforce_modifiers()/find_modifier() type discrimination, and DazScene.run_dforce_simulation()/is_simulating()/clear_dforce_simulation() backed by DzSimulationMgr. Unit + integration tests added."}}

.beads/issues.jsonl

@@ -25,6 +25,7 @@
 from ._material import DazMaterial
 from ._modifier import DazModifier
 from ._morph import DazMorph
+from ._dforce import DazDForce
 from ._geometry import DazGeometry
 from ._render import DazRenderSettings
 from ._viewport import DazViewport
@@ -97,6 +98,7 @@
     "DazMaterial",
     "DazModifier",
     "DazMorph",
+    "DazDForce",
     "DazGeometry",
     "DazRenderSettings",
     "DazViewport",

dazpy/__init__.py

@@ -0,0 +1,54 @@
+from __future__ import annotations
+
+from ._modifier import DazModifier
+from ._script_builder import ScriptBuilder
+
+
+class DazDForce(DazModifier):
+    """Proxy for a ``DzDForceModifier`` (cloth/hair dForce simulation modifier).
+
+    Returned by :meth:`DazNode.modifiers`, :meth:`DazNode.find_modifier`,
+    :meth:`DazNode.find_modifier_by_label`, and :meth:`DazNode.dforce_modifiers`
+    when the underlying DAZ modifier is a ``DzDForceModifier``.
+
+    Simulation tunables not covered by :attr:`freeze_simulation` (e.g.
+    ``"Dynamics Strength"``, ``"Contraction-Expansion Ratio"``, the various
+    stiffness weight maps) are still reachable through the inherited
+    :meth:`~dazpy.DazElement.get_property` / :meth:`~dazpy.DazElement.set_property`,
+    which look properties up by their Parameters-pane label.
+    """
+
+    @property
+    def freeze_simulation(self) -> bool | None:
+        """Whether the simulated result is frozen onto the mesh (read/write).
+
+        Freezing detaches the mesh from the live dForce solve so it holds its
+        current shape without needing to re-simulate — this is DAZ Studio's
+        equivalent of "baking" a dForce result.
+        """
+        script = ScriptBuilder.iife(f"""
+            var m = {self._locator};
+            if (!m) return null;
+            var p = m.findPropertyByLabel("Freeze Simulation");
+            return p ? p.getValue() : null;
+        """)
+        return self._client.execute(script).value
+
+    @freeze_simulation.setter
+    def freeze_simulation(self, value: bool) -> None:
+        flag = "true" if value else "false"
+        script = ScriptBuilder.iife(f"""
+            var m = {self._locator};
+            if (!m) return;
+            var p = m.findPropertyByLabel("Freeze Simulation");
+            if (p) p.setValue({flag});
+        """)
+        self._client.execute(script)
+
+    def freeze(self) -> None:
+        """Bake the current simulated result onto the mesh (sets ``freeze_simulation`` on)."""
+        self.freeze_simulation = True
+
+    def unfreeze(self) -> None:
+        """Release a frozen simulation so it resumes following the dForce solve."""
+        self.freeze_simulation = False

dazpy/_dforce.py

@@ -11,6 +11,7 @@
     from ._material import DazMaterial
     from ._modifier import DazModifier
     from ._morph import DazMorph
+    from ._dforce import DazDForce
 
 
 @dataclass
@@ -167,6 +168,17 @@ def children(self) -> list[DazNode]:
         names = self._client.execute(script).value or []
         return [DazNode(self._client, NodeIdentifier(n)) for n in names]
 
+    @staticmethod
+    def _modifier_class_for(class_name: str):
+        from ._modifier import DazModifier
+        from ._morph import DazMorph
+        from ._dforce import DazDForce
+        if class_name == "DzMorph":
+            return DazMorph
+        if class_name == "DzDForceModifier":
+            return DazDForce
+        return DazModifier
+
     def _modifier_locator(self, modifier_name: str) -> str:
         return (
             f"(function(){{"
@@ -183,8 +195,6 @@ def modifiers(self) -> list["DazModifier"]:
             A list of :class:`~dazpy.DazMorph` and :class:`~dazpy.DazModifier`
             instances.
         """
-        from ._modifier import DazModifier
-        from ._morph import DazMorph
         script = ScriptBuilder.node_body(
             self._identifier,
             """
@@ -202,10 +212,8 @@ def modifiers(self) -> list["DazModifier"]:
         result = []
         for item in items:
             loc = self._modifier_locator(item["name"])
-            if item["className"] == "DzMorph":
-                result.append(DazMorph(self._client, loc))
-            else:
-                result.append(DazModifier(self._client, loc))
+            cls = self._modifier_class_for(item["className"])
+            result.append(cls(self._client, loc))
         return result
 
     def find_modifier(self, name: str) -> "DazModifier | None":
@@ -218,8 +226,6 @@ def find_modifier(self, name: str) -> "DazModifier | None":
             A :class:`~dazpy.DazMorph` or :class:`~dazpy.DazModifier`, or
             ``None`` if not found.
         """
-        from ._modifier import DazModifier
-        from ._morph import DazMorph
         script = ScriptBuilder.node_body(
             self._identifier,
             f"""
@@ -233,9 +239,7 @@ def find_modifier(self, name: str) -> "DazModifier | None":
         if result is None:
             return None
         loc = self._modifier_locator(result["name"])
-        if result["className"] == "DzMorph":
-            return DazMorph(self._client, loc)
-        return DazModifier(self._client, loc)
+        return self._modifier_class_for(result["className"])(self._client, loc)
 
     def _material_locator(self, material_name: str) -> str:
         return (
@@ -309,8 +313,6 @@ def find_modifier_by_label(self, label: str) -> "DazModifier | None":
             A :class:`~dazpy.DazMorph` or :class:`~dazpy.DazModifier`, or
             ``None`` if no modifier with that label exists.
         """
-        from ._modifier import DazModifier
-        from ._morph import DazMorph
         script = ScriptBuilder.node_body(
             self._identifier,
             f"""
@@ -329,9 +331,7 @@ def find_modifier_by_label(self, label: str) -> "DazModifier | None":
         if result is None:
             return None
         loc = self._modifier_locator(result["name"])
-        if result["className"] == "DzMorph":
-            return DazMorph(self._client, loc)
-        return DazModifier(self._client, loc)
+        return self._modifier_class_for(result["className"])(self._client, loc)
 
     def find_property(self, name: str) -> "DazProperty | None":  # noqa: F821
         """Find a node-level property by its internal name.
@@ -389,6 +389,11 @@ def morphs(self) -> list["DazMorph"]:
         from ._morph import DazMorph
         return [m for m in self.modifiers() if isinstance(m, DazMorph)]
 
+    def dforce_modifiers(self) -> list["DazDForce"]:
+        """Return only the dForce simulation modifiers on this node (convenience filter)."""
+        from ._dforce import DazDForce
+        return [m for m in self.modifiers() if isinstance(m, DazDForce)]
+
     def set_rotation(self, x: float, y: float, z: float) -> None:
         """Set the world-space rotation using Euler angles in degrees.
 

dazpy/_node.py

@@ -656,3 +656,75 @@ def redo_last(self) -> None:
         """
         script = ScriptBuilder.iife("App.getUndoStack().redo();")
         self._client.execute(script)
+
+    # ── dForce simulation ──────────────────────────────────────────────────────
+
+    def is_simulating(self) -> bool:
+        """Return ``True`` if a dForce simulation is currently running."""
+        script = ScriptBuilder.iife("return App.getSimulationMgr().isSimulating();")
+        return bool(self._client.execute(script).value)
+
+    def clear_dforce_simulation(self) -> None:
+        """Discard all cached dForce simulation data for the active engine."""
+        script = ScriptBuilder.iife("App.getSimulationMgr().clearSimulation();")
+        self._client.execute(script)
+
+    def run_dforce_simulation(
+        self,
+        nodes: list[DazNode] | None = None,
+        *,
+        wait: bool = True,
+        timeout: float = 300.0,
+    ) -> str | None:
+        """Run a dForce simulation using the active simulation engine.
+
+        Args:
+            nodes: Optional subset of nodes to simulate via
+                ``DzSimulationEngine.customSimulate()``. ``None`` (default)
+                simulates the whole scene via ``DzSimulationMgr.simulate()``,
+                which follows the frame range configured in the Simulation
+                Settings pane.
+            wait: If ``True`` (default), block until the simulation finishes,
+                using the async execute-and-poll endpoint since dForce runs can
+                take minutes. If ``False``, submit the job and return
+                immediately.
+            timeout: Maximum seconds to wait when *wait* is ``True``.
+
+        Returns:
+            ``None`` when *wait* is ``True`` (the simulation already finished
+            by the time this call returns). When *wait* is ``False``, the
+            ``request_id`` of the submitted async job — poll it with
+            :meth:`~dazpy.DazClient.get_request_status` /
+            :meth:`~dazpy.DazClient.get_request_result`.
+
+        Raises:
+            :class:`~dazpy.exceptions.ScriptRuntimeError`: If the simulation
+                engine reports an error.
+        """
+        if nodes:
+            node_exprs = ",".join(ScriptBuilder.find_node_expr(n._identifier) for n in nodes)
+            body = f"""
+                var mgr = App.getSimulationMgr();
+                var engine = mgr.getActiveSimulationEngine();
+                if (!engine) return {{"error": "no_active_engine"}};
+                var err = engine.customSimulate([{node_exprs}]);
+                return {{"error": err ? String(err) : null}};
+            """
+        else:
+            body = """
+                var mgr = App.getSimulationMgr();
+                var err = mgr.simulate();
+                return {"error": err ? String(err) : null};
+            """
+        script = ScriptBuilder.iife(body)
+
+        if not wait:
+            return self._client.execute_async_submit(script)
+
+        from ._polling import execute_long
+        from .exceptions import ScriptRuntimeError
+        result = execute_long(self._client, script, timeout=timeout)
+        data = result.value or {}
+        if data.get("error"):
+            raise ScriptRuntimeError(f"dForce simulation failed: {data['error']}")
+        return None

dazpy/_scene.py

@@ -1640,6 +1640,63 @@ def test_modifier_locator_uses_findModifier(self):
         self.assertIn("MyMorph", loc)
         self.assertIn("getObject", loc)
 
+    def test_find_modifier_returns_daz_dforce_when_class_is_dzdforcemodifier(self):
+        from dazpy._dforce import DazDForce
+        client = _make_client({"name": "MyCloth", "className": "DzDForceModifier"})
+        node = DazNode(client, NodeIdentifier("Genesis9"))
+        mod = node.find_modifier("MyCloth")
+        self.assertIsInstance(mod, DazDForce)
+
+    def test_dforce_modifiers_filters_to_only_dzdforcemodifier(self):
+        from dazpy._dforce import DazDForce
+        client = _make_client([
+            {"name": "SomeMod", "className": "DzSubDivisionModifier"},
+            {"name": "MyMorph", "className": "DzMorph"},
+            {"name": "MyCloth", "className": "DzDForceModifier"},
+        ])
+        node = DazNode(client, NodeIdentifier("Genesis9"))
+        mods = node.dforce_modifiers()
+        self.assertEqual(len(mods), 1)
+        self.assertIsInstance(mods[0], DazDForce)
+
+
+class TestDazDForceScriptGeneration(unittest.TestCase):
+    def _make_dforce(self, return_value=None):
+        from dazpy._dforce import DazDForce
+        client = _make_client(return_value)
+        locator = 'Scene.findNode("Genesis9").getObject().findModifier("MyCloth")'
+        mod = DazDForce(client, locator)
+        return mod, client
+
+    def test_freeze_simulation_getter_calls_findPropertyByLabel(self):
+        mod, client = self._make_dforce(True)
+        val = mod.freeze_simulation
+        self.assertTrue(val)
+        script = client.execute.call_args[0][0]
+        self.assertIn("findPropertyByLabel", script)
+        self.assertIn("Freeze Simulation", script)
+
+    def test_freeze_simulation_setter_calls_setValue(self):
+        mod, client = self._make_dforce(None)
+        mod.freeze_simulation = True
+        script = client.execute.call_args[0][0]
+        self.assertIn("setValue", script)
+        self.assertIn("true", script)
+
+    def test_freeze_sets_freeze_simulation_true(self):
+        mod, client = self._make_dforce(None)
+        mod.freeze()
+        script = client.execute.call_args[0][0]
+        self.assertIn("Freeze Simulation", script)
+        self.assertIn("true", script)
+
+    def test_unfreeze_sets_freeze_simulation_false(self):
+        mod, client = self._make_dforce(None)
+        mod.unfreeze()
+        script = client.execute.call_args[0][0]
+        self.assertIn("Freeze Simulation", script)
+        self.assertIn("false", script)
+
 
 class TestDazMaterialScriptGeneration(unittest.TestCase):
     def _make_material(self, return_value=None):
@@ -2123,6 +2180,72 @@ def test_loop_playback_off(self):
         self.assertIn("false", script)
 
 
+class TestDazSceneDForceSimulation(unittest.TestCase):
+    def _scene(self, return_value=None):
+        return DazScene(_make_client(return_value))
+
+    def test_is_simulating_true(self):
+        scene = self._scene(True)
+        self.assertTrue(scene.is_simulating())
+        script = scene._client.execute.call_args[0][0]
+        self.assertIn("getSimulationMgr", script)
+        self.assertIn("isSimulating", script)
+
+    def test_is_simulating_false(self):
+        scene = self._scene(False)
+        self.assertFalse(scene.is_simulating())
+
+    def test_clear_dforce_simulation_calls_clearSimulation(self):
+        scene = self._scene(None)
+        scene.clear_dforce_simulation()
+        script = scene._client.execute.call_args[0][0]
+        self.assertIn("getSimulationMgr", script)
+        self.assertIn("clearSimulation", script)
+
+    def test_run_dforce_simulation_wait_false_submits_async(self):
+        scene = self._scene()
+        scene._client.execute_async_submit.return_value = "req-123"
+        request_id = scene.run_dforce_simulation(wait=False)
+        self.assertEqual(request_id, "req-123")
+        script = scene._client.execute_async_submit.call_args[0][0]
+        self.assertIn("getSimulationMgr", script)
+        self.assertIn("mgr.simulate()", script)
+
+    def test_run_dforce_simulation_with_nodes_uses_customSimulate(self):
+        scene = self._scene()
+        scene._client.execute_async_submit.return_value = "req-456"
+        node = DazNode(scene._client, NodeIdentifier("Skirt"))
+        scene.run_dforce_simulation(nodes=[node], wait=False)
+        script = scene._client.execute_async_submit.call_args[0][0]
+        self.assertIn("customSimulate", script)
+        self.assertIn("getActiveSimulationEngine", script)
+        self.assertIn("Skirt", script)
+
+    def test_run_dforce_simulation_wait_true_returns_none_on_success(self):
+        scene = self._scene()
+        scene._client.execute_async_submit.return_value = "req-789"
+        scene._client.get_request_result.return_value = {
+            "success": True,
+            "result": {"error": None},
+            "output": [],
+            "duration_ms": 12.0,
+        }
+        result = scene.run_dforce_simulation(wait=True)
+        self.assertIsNone(result)
+
+    def test_run_dforce_simulation_wait_true_raises_on_engine_error(self):
+        scene = self._scene()
+        scene._client.execute_async_submit.return_value = "req-999"
+        scene._client.get_request_result.return_value = {
+            "success": True,
+            "result": {"error": "DZ_ERROR_SOMETHING"},
+            "output": [],
+            "duration_ms": 12.0,
+        }
+        with self.assertRaises(exceptions.ScriptRuntimeError):
+            scene.run_dforce_simulation(wait=True)
+
+
 class TestDazLightScriptGeneration(unittest.TestCase):
     def setUp(self):
         from dazpy._light import DazLight