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.15.0 (2020-04-14)

Features

• Cache: provide cache operations for common data types (f1ef2f0)

  The Cache operation allows a data type value to be stored in a cache and then an appropriate event is raised when the value is updated.

  If the value is considered equal then the Unmodified event is emitted. However, if the values are not equal then the Modified event is emitted.

• Extraction: add extractors for SurfaceData and RaycastHit (dcab0ef)

  A collection of extractors that firstly extract the RaycastHit data from a SurfaceData and then a collection of extractors that can extract specific data from the RaycastHit.

  This new collection means the existing SurfaceDataCollisionPointExtractor becomes obsolete as it is too specific for the extractor pattern and can be achieved by first extracting the RaycastHit from the SurfaceData and then extracting the RaycastHit.point from the RaycastHit output.

• Extraction: consolidate all extractors into 1 base class (77e6f97)

  (Nearly) all of the extractors now all inherit from a single ValueExtractor class which contains most of the logic ensuring extractors all have a standard API.

  There are a couple of extractors that have multiple events for extraction and these don't fit into this model yet so have been left out. These are:

  • ObjectDistanceComparatorEventDataExtractor * TransformPropertyApplierEventDataExtractor

  These will be updated in the future to provide individual extrators that can then follow the standard Extractor pattern.

  All Extractors now also implement iProcessable so can all be used with a MomentProcessor.

  All Extractors also invoke a Failed event which is raised when the extractor has failed to extract the value. This is to ensure the PlayAreaDimensionExtractor still has the relevant events required and can fit in the standard Extractor pattern. Plus, having a Failed event is useful to know when an Extractor has failed.

  The TransformPropertyExtractor has been renamed to TransformVector3PropertyExtractor which originally existed within the same file but now it can simply extend the Vector3Extrator but the old extractor had a separate property for storing the result of the extraction called LastExtractedValue. This property is still available but it has been deprecated and the Result field should now be used to get the extracted value.

• Extraction: deprecate Vector2ComponentExtractor (4103c15)

  The Zinnia.Data.Type.Transformation.Conversion.Vector2ToFloat component does the same job as the Vector2ComponentExtractor so there is no need to have both.

Bug Fixes

• Extraction: ensure extraction cannot be mutated if disabled (bf6ceef)

  The main Extract() method should do a check to see if the component is active and enabled and if its not then it should force set the Result to null across all Extractors.

  Also, the RequiresBehaviourState attribute has been added to the Extract methods that allow the data to be passed in via a parameter as they were allowing mutation to the source even when the component was inactive.

  Finally, any extractors that didn't have the Extract methods that allowed a parameter have been updated to include these methods too.

• Extraction: ensure extraction logic order is consistent (4f77a78)

  The TransformPropertyExtractor worked in the opposite way from other extrators where the Extract method does all the work and the DoExtract method just calls the Extract method without any return.

  This has now been updated so it follows this standard logic.

• Extraction: flip extraction logic for local direction (2cb589c)

  The TransformDirectionExtractor had the UseLocal logic the wrong way round. It was returning the global Vector3.<direction> if UseLocal was true and returning the direction of the Source if UseLocal was false.

  This doesn't make sense because Vector3.<direction> is the global direction whereas the direction of the Source is technically local to the Source.

  This is also technically a change that can cause breaks because the logic is now flipped. But rather than do a clever deprecation or anything, it's probably just better to handle complaints as its just fixed by checking (or unchecking) the UseLocal property.

• structure: apply coding conventions (008723a)

  The coding conventions in regards to namespace order has now been applied so the default VisualStudio namespace order is applied to all scripts.

  Any missing code comments have also been added to any non-test related script.

Code Refactoring

• Extraction: simplify the InvokeResult method (441b7c9)

  The ValueExtractor now has a way of dealing with the differences between the TResultElement and TEventElement when the InvokeResult method is called by piping the actual logic into a generic InvokeEvent method meaning each of the concrete classes don't have to repeat the logic.