extendrealityltd/zinnia.unity

A collection of design patterns for solving common problems.

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.

zinnia.unity's Issues

Create a highlight for a GameObject by changing it's material colour

The ability to highlight objects as found in current VRTK

Move object around scene based on given Vector2 input

This will form the touchpad walking mechanism but be way more generic

Ability to display a pointer cursor that represents the current play area boundaries

Requires #33 to be done first

Apply physics to the camera rig objects to allow VR playareas to fall, etc

Same as body physics, but just redesign it so it's better :p

Ability to attach a valid object to another object with a joint

The concept of grabbing an object with a controller using a joint but without all the existing baggage,

Again separate the concept of grab with the mechanic of grab,

Allow a Transform to follow an active Transform from a selection in the scene

The ability for a transform to follow an active transform will make it easier for mapping an alias object onto multiple objects in the scene such as the various SDK setups (e.g. map a proxy object to all available SDK HMDs)

This will help separate concerns with SDK specific game objects.

Ensure only one SDK camera rig is active in the scene at one time

It will be possible to have multiple SDK camera rigs in the scene, but only one can be active at any time based on what VR settings are active.

This is similar to the existing SDK Manager in loose concept.

Allow grabbing objects using physics based tracking (track object)

Requires #18 to be done first

Ability to enable/disable the renderers on an object

Show and hide an object (e.g. controllers) in a scene.

Provide Unity Events for all C# Delegates

By default all events in VRTK will be C# delegates, but a Unity Events helper will be provided to allow for Unity Events for any C# delegate.

Ability to grab an object with a secondary controller and initiate a type of action

Requires #18 to be done first

This will lay the ground work for what happens when you grab an object with the second controller when the object is already being grabbed.

Scale an object when grabbing with a secondary grab action

Requires #24 to be done first

Determine if there is an unobstructed line of sight between given objects

This will be the generic implementation of checking if the headset can see the controllers, which helps with preventing cheating like putting your controllers through a wall and teleporting.

Allow grabbing objects based on following angular velocity (rotator tracking)

Requires #18 to be done first

Ability to grab and drag/rotate the world and scale the play area (hulk mode)

Same as the existing feature.

Ability to emit a signal when a controller input is received

The concept of signals will basically be events with extra controls to allow for things like controller input.

e.g. button press, axis changes

These will be agnostic for each SDK and will simply emit an event when a (controller) input is detected. Other scripts will then digest these signals to determine another course of action to occur.

This will decouple the input mechanisms to other scripts (such as turning on or off a pointer).

Pre-defined areas that denote where an object can be dropped and snapped into

Snap Drop Zones

Ability to force drop a grabbed object

Ability to grab objects and pull the character around the scene (i.e. climbing)

Requires the grab mechanics and requires #29 to be done.

largely the same as current climbing mechanic.

Ability to trigger haptics on a peripheral

This will have a mechanism to call a haptics method (both pulse and audio) on a range of given Haptic scripts.

Ability to multiply real world steps into the virtual world (step multiplier)

Same as the existing step multiplier concept,

Apply colour overlay to screen

The ability to provide a colour overlay on the screen cameras to allow fading in and out or to simulate the "blink" action.

This can be useful for teleporting but won't be tied to the teleporter.

Rotate an object based on given input

This will form the rotate camera rig on touchpad/thumbstick concept,

Fade the headset if it is colliding with an invalid object

Same as the headset collision fading script.

Warp object a certain distance in a certain direction based on Vector2 input

The concept of player warping but more generic

Modify a Transform with constraints (e.g. offset) with a potential transition time

The ability to modify a Transform's position, rotation, scale with a given offset Transform and to be able to perform the transition over a given duration.

This will enable movement of the play area using the headset as an offset position. The transition duration will enable the transform to lerp to it's new orientation.

This will enable teleporting and dash teleporting around a scene.

Allow attaching objects with custom joints (custom joint grabbing)

Duplicate of #18

To be able to toggle an action based on any given signal

Rather than build the concept of toggling something on a button press (e.g. toggle pointer on/off)

the Toggle signal is an extension of a signal that will listen for a signal and then activate a toggle on action, then on the second digestion of a signal it will call the toggle off action.

This totally decouples the concept of toggling from all scripts and provide a single signal script for performing this task.

Ability to get points/vertices of the active play area boundaries

Another script that will just hand off to the first available SDK boundary script that can report this data.

Track the velocity of moving objects that don't have a rigidbody

To get the velocity of tracked objects such as the controllers or HMD as the transforms don't have rigidbodies.

Physics based pushable controls

Control the direction of an object via the secondary grab

Requires #24 to be done first

Same as the two handed gun control

Compound AND signal to only emit a signal if a collection of given signals are true

A simple concept that enables a group of signals to be considered true before emitting another signal.

This will act as a proxy if something like: only do action is button 1, 2 and 3 are pressed.

Tooltips that can be linked to specific objects

The concept of object/controller tooltips

A pointer that emits a parabolic curve with a cursor that reacts to other scene objects

Another implementation of the pointer concept outlined in #7

but using a parabolic/bezier curve to draw the pointer tracer.

A pointer cursor that can be rotated to determine a new facing direction

Similar to the existing pointer direction indicator prefab

Allow custom positioning of an object when it is grabbed (i.e snap handles)

Like the snap handles now, you have a transform that determines the orientation of the object to the grabbing object (e.g. controller) when it is grabbed.

Determine when a tracked object (e.g. controller) is touching a valid object

Some concept of the old Interact Touch -> Interactable Objects but without having this level of dependency.

Ability to navigate scene with a simulated VR setup

A version of the VRTK simulator

A pointer that emits a straight visible line with a cursor that reacts to other scene objects

This is the straight pointer but has no connection to teleporters or button input, a simple concept that simply emits a raycast and draws a straight pointer with a cursor that when interacts with objects in the scene will report the items it has entered, is hovering over, has exited and when it is selected.

It will be activatable by a simple method call and no button presses will be coupled to it.

Grab an object with a level of precognition

This allows someone to be initiating the grab action before the grab is valid.

E.g.

If you press the grip button before touching the object (within a second or so) then you still perform the grab. This helps with fast moving objects.

Allow pointers to interact with objects (e.g. grab objects with a pointer)

This should be totally decoupled and not baked in like it currently is.

Policy lists to enable restrictions on certain actions

Just as in current VRTK, the concept of a policy list to restrict certain actions based on things like the existence of a tag, script or layer on another GameObejct

Ability to determine the nearest surface along a given Vector

To determine the nearest surface will be useful to replicate the Snap To Nearest Floor setting but without tying it into any teleport code.

The feature will simply cast a ray in a given direction (e.g. down) and find the nearest surface and report the position of that surface (again with an offset maybe of another object e.g. the headset).

This can then be used to report to move the camera rig down to the nearest surface on teleporting

Create highlight for a GameObject by applying an outline glow around it

Need a better way of providing the outline glow, the current shader is very limited.

Prevent movement of object if it's colliding with another object in certain circumstances

The concept of stopping the play area from moving around if it bumps into a wall unless the player is physically walking in their playspace.

Ability to accurately move a set of colliders to track another GameObject

This will enable the ability of tracking what the VR tracked objects are colliding with (e.g. the controllers).

Allow multiple Transforms to follow a single Transform

This is the opposite of #2

and will allow a collection of transforms to track another given transform, which will be useful for moving the 3rd party camera rigs around at the same time

String Identifier Rule

Environment

Source of VRTK: Github
Version of VRTK: release/3.3.0-alpha (e43089a)
Version of Unity3D (e.g. Unity 2017.3.0f3)
Hardware used (e.g. Vive)
SDK used (e.g. SteamVR)

Steps to reproduce

1. Open "041_Controller_ObjectSnappingToDropZones"
2. See that that "Valid Object List Policy" only supports Tags, Layers and Scripts
3. The scene uses tags to identify correct objects
4. In my game, i got > 100 snap drop zones/objects. Therefore I would need >100 different Tags/Layers/Scripts.

Expected behavior

I propose a forth Option for VRTK_PolicyList: "String Identifier"

If you chose VRTK_PolicyList.CheckType = "String Identifier"
Then VRTK_PolicyList.TypeCheck would check if the GameObject obj got an Script VRTK_PolicyListStringIdentifier. If so, it checks whether the string specified in VRTK_PolicyListStringIdentifier matches one identifier of VRTK_PolicyList.

Basically it's the same system like tags, but it don't mess up a projects tag-structure.

If you like it, I can start an PR immeadiatly, because I already programmed this change.

Determine if a given object is looking at a specified object

This will provide the basis to determine if the headset is looking at a specific controller.