Output Event Helpers (#58)

* Base Commit

* Moved Files down one folder

* Updated Package Configuration, CHANGELOG and documentation

* Fixed Behavior of ExposedProperty by implementing a simple Drawer / Debug Behaviour

* Small fixes and checks

* Updated Documentation / Renamed Attribute handler RigidBody to RigidBodyVeolcity + Safe check

* Small Fixes

* Added the Execute In Editor Capability + Custom Inspectors in order to handle the capability correctly

* Other custom Editors + Helpbox

* Added CMCameraShake Editor + Capabilities / Fixed Possible Circular Reference in  Prefab Spawn

* Removed Rerouting Helpers as CopyValuesFrom is broken at the moment.

* Fixed ASMDEFs / class accessibility

* Updated Documentation

* Fixed Class Accessibility for ExposedPropertyDrawer

* Updated Changelog (missing entry for Exposed Proeprty Custom Property Drawer)

Co-authored-by: Thomas ICHÉ <[email protected]>

Author: 2 people

com.unity.visualeffectgraph/CHANGELOG.md

@@ -62,6 +62,12 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.
 - Compute culling of particle which have their alive attribute set to false in output
 - Mesh and lit mesh outputs can now have up to 4 differents meshes that can be set per Particle (Experimental)
 - Screen space per particle LOD on mesh and lit mesh outputs (Experimental)
+- Compare operator can take int and uint as inputs
+- New operator : Sample Signed distance field
+- Added Output Event Handler API
+- Added Output Event Handler Samples
+- Added ExposedProperty custom Property Drawer
+
 
 ### Fixed
 - Moved VFX Event Tester Window visibility to Component Play Controls SceneView Window

com.unity.visualeffectgraph/Documentation~/Contexts.md

@@ -37,6 +37,7 @@ For a breakdown of context compatibility, see the table below.
 | **Event**              | **None**                                      | **SpawnEvent** (1+) | **None**                                                     |
 | **Spawn**              | **SpawnEvent** (1+)                           | **SpawnEvent** (1+) | Has two input flow slots which start and stop the **Spawn** context respectively. |
 | **GPU Event**          | **None**                                      | **SpawnEvent**      | Outputs to **Initialize** Context                            |
+| **Output Event** | **SpawnEvent (1+)** |  | Outputs a CPU SpawnEvent back to the Visual Effect component. |
 | **Initialize**         | **SpawnEvent** (1+) or **GPUSpawnEvent** (1+) | **Particle** (1)    | Input types are either **SpawnEvent** or **GPUSpawnEvent**. These input types are mutually exclusive.<br/>Can output to **Particle Update** or **Particle Output**. |
 | **Update**             | **Particle** (1)                              | **Particle** (1+)   | Can output to a **Particle Update** or **Particle Output**.  |
 | **Particle Output**    | **Particle** (1)                              | **None**            | Can either have input from an **Initialize** or **Update** Context.<br/>No output. |

com.unity.visualeffectgraph/Documentation~/OutputEventHandlers.md

@@ -0,0 +1,80 @@
+# Output Event Handlers
+
+A VFXOutputEventHandler is an API helper that hooks into an [Output Event](Contexts.md#output-events) to allow you to execute scripts based on the event.
+
+The Visual Effect Graph includes a set of example scripts as a sample. For information on how to install the sample, see [Installing sample scripts](#installing-sample-scripts).
+
+## Output Event Handler API
+
+To create your own output event handler, write a script that extends the `UnityEngine.VFX.Utility.VFXOutputEventHandler` class.
+
+When you write a MonoBehaviour that extends this class, it reduces the  amount of code required to perform a hook. This is because the base  class does the job of filtering the event and calls the following method :
+
+`override void OnVFXOutputEvent(VFXEventAttribute eventAttribute)`
+
+When you implement this method, Unity calls it every time the event triggers and passes in the event's attributes.
+
+### Example
+
+The following example teleports a Game Object to the Given position when it receives an event.
+
+```c#
+[RequireComponent(typeof(VisualEffect))]
+public class VFXOutputEventTeleportObject : VFXOutputEventHandler
+{
+    public Transform target;
+    
+    static readonly int kPosition = Shader.PropertyToID("position");
+    
+    public override void OnVFXOutputEvent(VFXEventAttribute eventAttribute)
+    {
+        if(target != null)
+            target.position = eventAttribute.GetVector3(kPosition);
+    }
+}
+```
+
+## Installing Sample Scripts
+
+To help you create your own VFXOutputEventHandler, the Visual Effect  Graph package includes a set of example scripts that you can install via the Package Manager. To do this, select the Visual Effect Graph package then, next to **OutputEvent Helpers Sample**, click the **Import** button.
+
+### Using Output Event Helpers
+
+The OutputEvent Helper scripts are deployed into the project as a Sample contained in the folder :  `Assets/Samples/Visual Effect Graph/(version)/OutputEvent Helpers/`. 
+
+These helpers are MonoBehaviour Scripts that you can add to Game Objects that hold a VisualEffect Component. These scripts will listen for OutputEvents of a given name, and will react to these events by performing various actions.
+
+Some of these scripts can be safely previewed in editor, while other aren't. The Inspector shall display a **Execute in Editor** toggle if the script is able to be previewed. Otherwise, you can press the Play button to experience the behavior in play mode.
+
+<u>The Sample Output Event Helpers are the following:</u>
+
+* **VFXOutputEventCMCameraShake** : Upon receiving a given OutputEvent, Triggers a Camera Shake through the Cinemachine Impulse Sources system.
+* **VFXOutputEventPlayAudio** : Upon receiving a given OutputEvent, Plays a sound from an AudioSource
+* **VFXOutputEventPrefabSpawn** : Upon receiving a given OutputEvent, Spawns an invisible prefab game object from a pool of prefabs, at a given position, rotation and angle, and manages its life based on the Event lifetime attribute. Spawned Prefabs can also be customized upon spawn with the help of **VFXOutputEventPrefabAttributeHandler** scripts in order to configure child elements of the prefab (see below).
+* **VFXOutputEventRigidBody** : Upon receiving a given OutputEvent, applies a force to a RigidBody.
+* **VFXOutputEventRigidBody** : Upon receiving a given OutputEvent, triggers a UnityEvent
+
+### Using Output Event Prefab Spawn
+
+The **VFXOutputEventPrefabSpawn** script handles the spawn of hidden prefabs from a pool. These prefabs are instantiated as invisible, and disabled upon enabling this monobehaviour, and destroyed upon disabling the monobehaviour.
+
+Upon receiving a given OutputEvent, the system will look for a free (disabled) prefab, and if any available will :
+
+* enable it
+
+* set its position from the position attribute,  if enabled in the inspector
+
+* set its rotation from the angle attribute, if enabled in the inspector
+
+* set its scale from the scale attribute, if enabled in the inspector
+
+* start a coroutine with a delay (based on the lifetime attribute), that will disable (free) the prefab once elapsed, thus making it available for spawn upon a future OutputEvent
+
+* search for any **VFXOutputEventPrefabAttributeHandler** scripts in the prefab instance in order to perform attribute binding.
+
+  
+
+**VFXOutputEventPrefabAttributeHandler** scripts are used to configure parts of the prefab, based on the event that spawned the prefab. Here are two examples bundled with the samples:
+
+* **VFXOutputEventPrefabAttributeHandler_Light** : this script, upon prefab spawn, will set the color and the brightness of the light, based on the OutputEvent color attribute and a brightnessScale property.
+* **VFXOutputEventPrefabAttributeHandler_RigidBodyVelocity** : this script, upon prefab spawn, will set the current rigid body velocity, based on the OutputEvent velocity attribute.

com.unity.visualeffectgraph/Documentation~/TableOfContents.md

@@ -21,6 +21,7 @@
   * [Using Visual Effects with Timeline](Timeline.md)
   * [Property Binders](PropertyBinders.md)
   * [Event Binders](EventBinders.md)
+  * [Output Event Handlers](OutputEventHandlers.md)
 * Pipeline Tools
   * [ExposedProperty Helper](ExposedPropertyHelper.md)
   * [Vector Fields](VectorFields.md)

com.unity.visualeffectgraph/Editor/Utilities/ExposedProperty.meta

@@ -0,0 +1,23 @@
+using UnityEditor.UIElements;
+using UnityEngine;
+using UnityEngine.UIElements;
+using UnityEngine.VFX.Utility;
+
+namespace UnityEditor.VFX.Utility
+{
+    [CustomPropertyDrawer(typeof(ExposedProperty))]
+    class ExposedPropertyDrawer : PropertyDrawer
+    {
+        const string k_PropertyName = "m_Name";
+
+        public override VisualElement CreatePropertyGUI(SerializedProperty property)
+        {
+            return new PropertyField(property.FindPropertyRelative(k_PropertyName), ObjectNames.NicifyVariableName(property.name));
+        }
+
+        public override void OnGUI(Rect position, SerializedProperty property, GUIContent label)
+        {
+            EditorGUI.PropertyField(position, property.FindPropertyRelative(k_PropertyName), new GUIContent(ObjectNames.NicifyVariableName(property.name)));
+        }
+    }
+}

com.unity.visualeffectgraph/Editor/Utilities/ExposedProperty/ExposedPropertyDrawer.cs

@@ -0,0 +1,46 @@
+namespace UnityEngine.VFX.Utility
+{
+    [ExecuteAlways]
+    [RequireComponent(typeof(VisualEffect))]
+    public abstract class VFXOutputEventHandler : MonoBehaviour
+    {
+        public abstract bool canExecuteInEditor { get; }
+        public bool executeInEditor = true;
+
+        public ExposedProperty outputEvent = "On Received Event";
+
+        protected VisualEffect m_VisualEffect { private set; get; }
+
+        protected virtual void OnEnable()
+        {
+            m_VisualEffect = GetComponent<VisualEffect>();
+            if (m_VisualEffect != null)
+            {
+                m_VisualEffect.outputEventReceived += OnOutputEventRecieved;
+            }
+        }
+
+        protected virtual void OnDisable()
+        {
+            if(m_VisualEffect != null)
+                m_VisualEffect.outputEventReceived -= OnOutputEventRecieved;
+        }
+
+
+        void OnOutputEventRecieved(VFXOutputEventArgs args)
+        {
+            if (Application.isEditor
+                && !Application.isPlaying
+                && (!executeInEditor || !canExecuteInEditor))
+                return;
+
+            if (args.nameId == outputEvent)
+            {
+                OnVFXOutputEvent(args.eventAttribute);
+            }
+        }
+
+        public abstract void OnVFXOutputEvent(VFXEventAttribute eventAttribute);
+
+    }
+}