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.

Script Define Symbols

There are a collection of custom script define symbols that are included that can affect functionalities provided within Zinnia:

• ZINNIA_IGNORE_CUSTOM_COLLAPSIBLE_DRAWER - Disables the collapsible event drawer functionality in the inspector windows.
• ZINNIA_IGNORE_CUSTOM_INSPECTOR_EDITOR - Disables the custom zinnia inspector that handles automatically updating property values when changed in the inspector.
• ZINNIA_IGNORE_CUSTOM_LIST_EDITOR - Disables the custom observable list editor in any version of Unity.
• ZINNIA_IGNORE_PIPELINE_MATERIALS - Prevents the PipelineMaterialApplier from updating materials to match the current render pipeline mode.
• ZINNIA_USE_CUSTOM_LIST_EDITOR - Force the custom observable list editor in the version of Unity 2020.3 or above.
• ZINNIA_USE_ISACTIVEANDENABLED - Determines whether to use the behaviour.isActiveAndEnabled property on a behvaiour when calling the CheckIsActiveAndEnabled method instead of using the more robust behaviour.gameObject.activeInHierarchy && behaviour.enabled.

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

2.16.0 (2024-04-17)

Features

• Cast: add raycast hit validity rule for points cast (170a241)

  The PointsCast now has a RaycastHitValidity rule that will allow any data within the cast RaycastHit to be used within a rule for any custom.

• Cast: make drag curve offset a vector3 (f90f1e8)

  The Drag Curve Offset is now a Vector3 allowing the curve offset to be applied to any axis rather than just the back axis.

  To replicate the orignal setting, just change the Z axis to a negative value and this will replicate the same as the Vector3.back * offset.

• Data: add script define to disable collapsible drawer (36f978b)

  The custom collapisble drawer editor modification can now be disabled by setting a scripting define symbol of ZINNIA_IGNORE_CUSTOM_COLLAPSIBLE_DRAWER.

• README.md: add section describing custom script define symbols (3238142)

  The various script define symbols that are added by Zinnia are now documented to make it easier to know when to use them.

• Tracking: apply distance offset on position difference rotation (208570d)

  The TransformPositionDifferenceRotation logic now has a source to offset maximum distance setting that will be activated if the Apply Offset is to true. This will ensure the rotation will only be applied when the source and offset are within the given distances and anything outside of those distances will be ignored.

Bug Fixes

• Data: prevent null exception in collapsible drawer in 2022.3 (2ce9cef)

  Due to a change in Unity 2022.3, there is now no actual need to do the reflection for replacing a default drawer and in fact the attempt to get DrawerKeySet will return a null, thus causing the existing error.

  The fix is to simply do a null check to prevent the error and the reflection will simply be ignored on versions of Unity of 2022.3 and above.