Add simulation decorator

Author: carson-katri

api/static/simulation.py

@@ -0,0 +1,25 @@
+import inspect
+import typing
+
+class SimulationInput:
+    class DeltaTime: pass
+    class ElapsedTime: pass
+
+def simulation(block: typing.Callable[typing.Any, 'Geometry']):
+    """
+    Create a simulation input/output block.
+
+    > Only available in the `geometry-node-simulation` branch of Blender 3.5.
+    """
+    def wrapped(geometry: 'Geometry', *args, **kwargs):
+        from geometry_script import simulation_input, simulation_output
+        simulation_in = simulation_input(geometry=geometry)
+        signature = inspect.signature(block)
+        for key, value in signature.parameters.items():
+            match value.annotation:
+                case SimulationInput.DeltaTime:
+                    kwargs[key] = simulation_in.delta_time
+                case SimulationInput.ElapsedTime:
+                    kwargs[key] = simulation_in.elapsed_time
+        return simulation_output(geometry=block(simulation_in.geometry, *args, **kwargs)).geometry
+    return wrapped

api/tree.py

@@ -11,6 +11,7 @@
 from .static.expression import *
 from .static.input_group import *
 from .static.sample_mode import *
+from .static.simulation import *
 from .arrange import _arrange
 
 def _as_iterable(x):

book/src/SUMMARY.md

@@ -22,6 +22,7 @@
     - [Attributes](./api/advanced-scripting/attributes.md)
     - [Boolean Math](./api/advanced-scripting/boolean-math.md)
     - [Drivers](./api/advanced-scripting/drivers.md)
+    - [Simulation](./api/advanced-scripting/simulation.md)
 
 # Tutorials
 

book/src/api/advanced-scripting/simulation.md

@@ -0,0 +1,26 @@
+# Simulation
+
+> This API is subject to change as future builds of Blender with simulation nodes are released.
+
+The `geometry-nodes-simulation` branch of Blender 3.5 includes support for "simulation nodes".
+
+Using a *Simulation Input* and *Simulation Output* node, you can create effects that change over time.
+
+As a convenience, the `@simulation` decorator is provided to make simulation node blocks easier to create.
+
+```python
+@simulation
+def move_over_time(
+    geometry: Geometry, # the first input must be `Geometry`
+    speed: Float,
+    dt: SimulationInput.DeltaTime, # Automatically passes the delta time on any argument annotated with `SimulationInput.DeltaTime`.
+    elapsed: SimulationInput.ElapsedTime, # Automatically passes the elapsed time
+) -> Geometry:
+    return geometry.set_position(
+        offset=combine_xyz(x=speed)
+    )
+```
+
+Every frame the argument `geometry` will be set to the geometry from the previous frame. This allows the offset to accumulate over time.
+
+The `SimulationInput.DeltaTime`/`SimulationInput.ElapsedTime` types mark arguments that should be given the outputs from the *Simulation Input* node.