io.extendreality.zinnia.unity

Zinnia

A collection of design patterns for solving common problems.

[zin-ee-uh]

Introduction

Zinnia is a collection of design patterns for the Unity software that can be beneficial in (but not limited to) spatial computing development.

Requires the Unity software version 2018.3.10f1 (or above).

Getting Started

Setting up a project

• Using the Unity software version 2018.3.10f1 (or above), create a new project using the 3D Template or open an existing project.
• Ensure the project Scripting Runtime Version is set to .NET 4.x Equivalent.
  • In the Unity software select Main Menu -> Edit -> Project Settings to open the Project Settings inspector.
  • Select Player from the left hand menu in the Project Settings window.
  • In the Player settings panel expand Other Settings.
  • Ensure the Scripting Runtime Version is set to .NET 4.x Equivalent.

Adding the package to the Unity project manifest

• Navigate to the Packages directory of your project.

• Adjust the project manifest file manifest.json in a text editor.

  • Ensure https://registry.npmjs.org/ is part of scopedRegistries.
    • Ensure io.extendreality is part of scopes.
  • Add io.extendreality.zinnia.unity to dependencies, stating the latest version.

  A minimal example ends up looking like this. Please note that the version X.Y.Z stated here is to be replaced with the latest released version which is currently .

  {
    "scopedRegistries": [
      {
        "name": "npmjs",
        "url": "https://registry.npmjs.org/",
        "scopes": [
          "io.extendreality"
        ]
      }
    ],
    "dependencies": {
      "io.extendreality.zinnia.unity": "X.Y.Z",
      ...
    }
  }
  

• Switch back to the Unity software and wait for it to finish importing the added package.

Running the tests

If you want to run the tests that come with Zinnia please follow these steps.

Because Zinnia is a package tests have to be explicitly enabled for this package, before the Test Runner can pick them up.

• Navigate to the Packages directory of your project.

• Adjust the project manifest file manifest.json in a text editor.

  • Ensure io.extendreality.zinnia.unity is part of testables.

  A minimal example ends up looking like this.

  {
    "scopedRegistries": [
      ...
    ],
    "testables": [
      "io.extendreality.zinnia.unity"
    ],
    "dependencies": {
      ...
    }
  }
  

• As noted in the official Unity documentation:

  NOTE: You may need to re-import the package, because the test framework doesn't always immediately pick up changes to the testables attribute.

  • Within the Unity software's Project window expand the Packages node.
  • Right-click on the Zinnia.Unity child node and choose Reimport.
  • Wait for the Unity software to finish re-importing the package.

• In the Unity software select Main Menu -> Window -> Test Runner.

• Within the Test Runner window click on the PlayMode tab and the click Run All button.

• If all the tests pass then the installation was successful.

Note: The tests are not compatible with the Run all in player option.

Updating to the latest version

The package will show up in the Unity Package Manager UI once the above steps have been carried out. From then on the package can be updated by selecting the package in the Unity Package Manager and clicking on the Update button or using the version selection UI.

Naming

Inspired by the Zinnia genus of plants known for their colorful, long lasting flower heads and their great ease to grow from seeds. This repository, much like the Zinnia flower aims to be easy to use and allow your projects to grow and flourish into long lasting, easy to maintain solutions.

Fun Fact: Zinnias have been grown aboard the International Space Station and have demonstrated the capability to blossom in a weightless environment.

Contributing

Please refer to the Extend Reality Contributing guidelines and the Unity project coding conventions.

Code of Conduct

Please refer to the Extend Reality Code of Conduct.

License

Code released under the MIT License.

Disclaimer

These materials are not sponsored by or affiliated with Unity Technologies or its affiliates. "Unity" is a trademark or registered trademark of Unity Technologies or its affiliates in the U.S. and elsewhere.

Changelog

1.20.0 (2020-07-11)

Features

• Action: add ability to set initial value of an Action (bbc8ee0)

  The new InitialValue property allows an Action to have the starting value set in the Unity Editor at edit time. Once the script is started then the InitialValue will be used to set the default state of the Action (but no events will be emitted to denote an action change as technically the state hasn't changed if it is moving to the initial state).

  This new InitialValue property is only for use in the UnityEditor at Edit time and cannot be changed at runtime nor can it be set via script. If an initial value is required via creation of an Action by script then simply just need to create the Action and call Receive(<your-initial-value>) prior to any event listeners being hooked up. This will simply call the Receive method and will emit the relevant events, but as no event listeners should have been registered then this won't make any difference.

  An extra method of ReceiveInitialValue has also been added that will allow the Receive method to be called with the initial set value. Again, this is only useful for when creating the Action via the Unity Inspector as the InitialValue cannot be changed via script.

  The DefaultValue help text has also been updated to make it more clearer what this property is for as it's not the starting value of the Action, but the value the Action needs to be at to be considered disabled.

• Extension: add enum extension/helper methods (33463ce)

  A couple of new Enum helper methods have been added that make getting an enum easier by either being able to provide the index of the enum to return or by getting the enum by string name.

  The PointerElementPropertyMutator has been updated to take advantage of this new method.

• Extension: add new data type extensions for common calculations (816dc97)

  A common calculation is finding a fine grain distance between two points (either Vector2 or Vector3) where the tolerance is also given in the same type as opposed to just a simple float.

  The new Vector2.WithinDistance and Vector3.WithinDistance offer this via the relevant extensions.

  Another common calculation is converting euler degrees to signed degrees, such as 270' is actually equivalent to -90'. This helps when doing greater than or less than comparisons as a negative rotation of -90' is less than a rotation of 0' whereas 270' as a number would be greater than 0'.

  The Vector3.UnsignedEulerToSignedEuler will convert the current Vector3 of euler angles into a Signed Euler (-180' to 180f) using the new float.GetSignedDegree which simply converts a Euler angle into the -180' to 180' range.

  These are then used to provide new Transform extensions for:

  • Transform.SignedEulerAngles * Transform.SignedLocalEulerAngles

  Which simply return the respective Euler or Local Euler angle for the Transform but in this signed format.

• structure: provide mechanism to change properties via UnityEvents (98ae181)

  Some property types cannot be changed via UnityEvents as they are not supported in the UnityEvent inspector, such as Enums, Vectors and Vector3State.

  This has been fixed by adding custom setter methods that can be called via the UnityEvent inspector using primitive types that are supported to allow this data to still be set.

• Tracking: add divergable property modifier types (8538d3f)

  A new Property Modifier type known as a Divergable Property Modifier has been added that allows a property modifier to know when the target has become diverged from the source in whatever property it is tracking.

  Only certain types of modifier can actually ever cause a divergence, such as the RigidbodyVelocity and RigidbodyAngularVelocity because they can make it so the target is not keeping exactly up to date with the source and become diverged somewhat.

  So now both RigidbodyVelocity and RigidbodyAngularVelocity have become extensions of the DivergablePropertyModifier and now emit events when the source/target diverge and converge again.

  It is also possible to turn off this divergence tracking and it is turned off by default as it adds an additional overhead, which should not be automatically implemented unless the overhead is warranted for the benefits of using the functionality.

• Tracking: add proxy emitter for ObjectFollower.EventData (0da6d51)

  The ObjectFollower.EventData can now be proxied via the new ObjectFollowerEventProxyEmitter and this data can also now be used as an input to the PropertyModifier Modify method as this makes it easy to chain Property Modifiers together to have one modifier use its data to call another Property Modifier.

• Yield: add ability to emit an event after a yield instruction (f1e70c8)

  The new Yield events provide the ability to trigger some action after a yield instruction has completed such as seconds passed or at end of frame.

  This can be used in conjunction with the Proxy events to first store the payload in the Proxy then trigger the emit after the yield instruction has completed.

Bug Fixes

• Attribute: record MinMaxRange value changes on prefab instance (4617d6c)

  There is an issue where the MinMaxRange control will reset the value back to the previous value when it is used within a prefab.

  The solution seems to be to record the prefab instance property modification after the custom FloatRange value has been set through the Supyrb SetValue extension, which doesn't set the value via the SerializedProperty because that is not supported in Unity on custom data types.

  The issue only seems to present itself when changing the value between varying negative values:

  • -0.5 * -0.2 * -0.5 (reverts to 0)

Code Refactoring

• guidelines: apply coding guidelines to empty classes (fea537b)

  The coding guidelines state that empty classes should have the brackets on the same line as such:

  class { }

  and not

  class { }

  This has now been applied to the relevant offending files.