Ult Events Manual
UltEvents%20Manual
User Manual:
Open the PDF directly: View PDF 
.
Page Count: 7
| Download | |
| Open PDF In Browser | View PDF |
v1.1 Created by Kybernetik Contents 1. Quick Start........................................................................................................................................... 2 2. UnityEvents vs. UltEvents ................................................................................................................... 2 3. Creating and Triggering an Event ........................................................................................................ 3 3.1. Declaring an Event in a Script ...................................................................................................... 3 3.2. Invocation Exceptions .................................................................................................................. 3 3.3. Premade Event Scripts ................................................................................................................. 3 3.4. UltEventHolder............................................................................................................................. 4 4. Configuring an Event ........................................................................................................................... 4 4.1. Configuring a Function Call .......................................................................................................... 5 5. Advanced............................................................................................................................................. 5 5.1. Event Parameters ......................................................................................................................... 5 5.2. Linked Return Values ................................................................................................................... 6 5.3. Configuring Events Using Code .................................................................................................... 6 5.4. Configuring Persistent Listeners Using Code ............................................................................... 7 UltEvents v1.1 Kybernetik kybernetikgames@gmail.com 1. Quick Start public UltEvents.UltEvent myEvent; [SerializeField] private UltEvents.UltEvent myEvent; To create an UltEvent: declare a serializable field in your script as shown above. Once you have declared your event it will show up in the inspector for your script like a regular field so you can configure it to run code. To trigger the execution of the event, simply call myEvent.Invoke(). There are also various Premade Event Scripts which expose MonoBehaviour events like Awake, Update, etc. A scene with some example events can be found in Assets/Plugins/Ult Events/Example. 2. UnityEvents vs. UltEvents UnityEvents allow users to easily setup and configure persistent event callbacks via the Inspector. UltEvents serve the same purpose, but with more features and less restrictions. Serializable Event System Feature Comparison Persistent listeners (serialized) Dynamic listeners (non-serialized) Reorderable function list Parameter types: bool, int, float, string, UnityEngine.Object Parameter types: Enum (regular and flags), Vector (2, 3, 4), Quaternion, Rect, Color, Color32 Maximum parameter count Method parameters Allows methods with non-void return types Use values returned from earlier calls as parameters Public methods Non-public methods Static methods Compact and collapsible GUI Displays dynamic (non-serialized) listeners in the GUI Context menu commands (Invoke, Clear, Copy, Paste) Select a specific component when there are multiple of the same type Back to Contents UnityEvent UltEvent 1 Strict Unlimited Flexible Page 2 of 7 UltEvents v1.1 Kybernetik kybernetikgames@gmail.com 3. Creating and Triggering an Event You can either declare and invoke an UltEvent in your own script or use a Premade Event Script. 3.1. Declaring an Event in a Script You can declare an UltEvent like any other serialized field you want to show in the inspector: public UltEvents.UltEvent myEvent; [SerializeField] private UltEvents.UltEvent myEvent; You will also need to call myEvent.Invoke() to trigger the event when you want it to execute. 3.2. Invocation Exceptions The regular Invoke method contains no exception handling. Any exceptions will be passed out to the caller like normal. The InvokeSafe method will automatically catch and log any exceptions. If you have using UltEvents; declared at the top of your script, you can make use of the UltEventUtils.InvokeX extension method which does nothing if the event is null to avoid throwing a NullReferenceException. This is useful in case you call AddComponent at runtime since your event field will be null unlike when you add a component using the Unity Editor which will automatically create a new event object. 3.3. Premade Event Scripts This plugin includes several scripts which have UltEvents triggered by various MonoBehaviour events: Script CollisionEvents2D CollisionEvents3D LifeCycleEvents TriggerEvents2D TriggerEvents3D UpdateEvents Back to Contents Events OnCollisionEnter2D, OnCollisionStay2D, OnCollisionExit2D OnCollisionEnter, OnCollisionStay, OnCollisionExit Awake, Start, OnEnable, OnDisable, OnDestroy OnTriggerEnter2D, OnTriggerStay2D, OnTriggerExit2D OnTriggerEnter, OnTriggerStay, OnTriggerExit Update, LateUpdate, FixedUpdate Page 3 of 7 UltEvents v1.1 Kybernetik kybernetikgames@gmail.com 3.4. UltEventHolder The UltEventHolder script is similar to the Premade Event Scripts, except that it only has a single event which isn't triggered by anything. One use for this script is to receive a redirected UnityEvent from a UI element so that you can make use of the improved features of the UltEvent. The DelayedUltEventHolder script can be used similarly to impose a delay before the event is actually executed. 4. Configuring an Event Event Name and Parameters Persistent Listener Count Add / Remove Listener An UltEvent has two sets of listeners; persistent (configured in the Unity Editor using the Inspector) and dynamic (added using code at runtime). You can add a persistent listener using the [+] button or by dragging and dropping an object from the Hierarchy Window or Project Window onto the event. If you have multiple calls, you can drag them around to change their execution order. Execution starts at the top and travels down the list. You can Right Click on an event header to open a context menu with functions to Invoke, Copy, Paste, Clear, or Log a description of its contents. Back to Contents Page 4 of 7 UltEvents v1.1 Kybernetik kybernetikgames@gmail.com 4.1. Configuring a Function Call The left field determines the target; either a UnityEngine.Object (such as a GameObject or Component) on which an instance method will be called, or a System.Type in which a static method will be called. The right button opens the method selection menu. When a new call is added, it will be given the component containing the event as its default target. To set a static method, you can either click on the target field and press the Delete key, or open the method selection menu and select “Static Method”. Then the target field will show a type picker which allows you to specify the type where the method you want to call is declared. Once you have selected a type, the method selection menu will show all of the supported methods in that type. The sub-menus near the top of the method selection menu allow you to select methods from any other components on the same GameObject. Doing so will automatically change the target object accordingly. If a method name you selected previously no longer exists (such as if you select a method then rename or remove it from your code), it will be highlighted in red. It will also show a [?] button which will assign another existing method with the most similar name according to a metric known as Levenshtein Distance. The method selection menu also allows you to select properties. Doing so will default to the property's Setter if it has one and is a supported argument type. It will also show a [Get] button which can be used to toggle to the Getter so you can use its return value as a parameter in subsequent methods (see Linked Return Values for more details). 5. Advanced 5.1. Event Parameters The standard UltEvent class allows you to register methods with predefined values, but doesn't let you pass in custom parameters when the event is invoked. For example, you could have an event that instantiates a prefab at a specific location you set in the event's inspector, but you couldn't use the information from an OnCollisionEnter message to have your event instantiate the prefab at the point where the collision occurs. To do this, you need to use the generic versions of UltEvent instead. To use a generic event type you must first create a serializable class that inherits from the desired event type. For example, if you want an event that takes a Vector3 parameter, you would write the following: [Serializable] public sealed class Vector3Event : UltEvents.UltEvent{ } Then you can use that event type instead of the regular UltEvent when declaring your event field: public Vector3Event myEvent; And when you want to invoke the event you will need to pass in the required parameters: myEvent.Invoke(transform.position); Back to Contents Page 5 of 7 UltEvents v1.1 Kybernetik kybernetikgames@gmail.com When using the inspector to configure an event with parameters, any method parameters with the appropriate type will show a [∞] button which toggles that parameter between linked (so it receives the value you pass into the Invoke call) and unlinked (so you can use the inspector to specify its value normally). If you specify a parameter type that isn't normally supported by UltEvents such as UltEvent or UltEvent , you will be able to select methods with that parameter type which would not normally appear in the list. Such parameters are automatically linked and can't be unlinked. 5.2. Linked Return Values If you register a method with a non-void return type, you can use the value it returns as a parameter in later methods. Any parameter that matches the return type of a previous method will show the same [∞] button used to link Event Parameters. The “Parameter Constructors ->” sub-menu contains various methods for constructing simple values to use as parameters in subsequent functions. For example, ReturnVector3 takes its X/Y/Z values as separate float parameters so you can link them individually. 5.3. Configuring Events Using Code You can easily register delegates to an event using the += operator like a standard C# delegate: myEvent += SomeMethod;// Existing Method. myEvent += () => ...;// Lambda Expression. Normally this will register the delegate as a dynamic listener (non-serialized), however if you are currently in Edit Mode (in the Unity Editor but not in Play Mode) it will register as a persistent listener instead. To specifically add a dynamic listener, you can either access the dynamicCalls field directly or use the static AddDynamicCall method which will automatically null-check the event: myEvent.dynamicCalls += SomeMethod; Back to Contents Page 6 of 7 UltEvents v1.1 Kybernetik kybernetikgames@gmail.com UltEvent.AddDynamicCall(ref myEvent, SomeMethod); 5.4. Configuring Persistent Listeners Using Code To specifically add a persistent listener, you can either create a new PersistentCall and add it to the PersistentCalls list or you can call AddPersistentCall which returns a PersistentCall. var call = new PersistentCall((Action )SomeMethod); myEvent.PersistentCalls.Add(call); var call = myEvent.AddPersistentCall((Action )SomeMethod); You can then configure the call using SetArguments or by accessing the PersistentArguments array directly. call.SetArguments(2); call.PersistentArguments[0].Float = 2; All of these + operators and Add methods have corresponding - operators and Remove methods. Questions, feedback, feature requests, etc: kybernetikgames@gmail.com. Back to Contents Page 7 of 7
Source Exif Data:
File Type : PDF File Type Extension : pdf MIME Type : application/pdf PDF Version : 1.5 Linearized : No Page Count : 7 Language : en-AU Tagged PDF : Yes Author : Kailas Dierk Creator : Microsoft® Word 2016 Create Date : 2018:07:19 21:47:18+10:00 Modify Date : 2018:07:19 21:47:18+10:00 Producer : Microsoft® Word 2016EXIF Metadata provided by EXIF.tools