New Project Structure and Migration Guide

[zachkinstner]

I have just merged the ui-core branch into master. This is a major refactoring of the entire project, and will cause many breaking changes for existing integrations. I'll use this ticket to answer questions and help with the migration process.

This refactor was started to share code/concepts more easily between Hovercast and Hoverboard. This will also make it much easier for me to maintain and extend these projects.

I'll be working on a variety of different documents for the project wiki over the next few days. These will describe the new project structure, the Getting Started process, etc.

[zachkinstner]

I have added an "out-of-date" notice to the existing documentation.

[zachkinstner]

Some initial migration notes...

---

Scripts (OldClass => NewClass)

• HovercastNavItem => HovercastItem
• HovercastNavItemListener => HovercastItemListener
• HovercastNavProvider => HovercastItemHierarchy
• HovercastCustomizationProvider => removed, use individual settings groups below
• HovercastDefaultSegment => HovercastItemVisualSettings
• HovercastDefaultPalm => HovercastItemVisualSettings
• HovercastDefaultCursor => HovercursorVisualSettings
• HovercastCustomInteraction => HovercastInteractionSettings
• HovercastInputProvider => HovercastInput

Items

• NavItem => ISelectableItem (in most cases)
• NavItem.ItemType => SelectableItemType
• NavItemSelector => ISelectorItem
• NavItemParent => IParentItem
• NavItemCheckbox => ICheckboxItem
• NavItemRadio => IRadioItem
• NavItemSticky => IStickyItem
• NavItemSlider => ISliderItem

Setup

Hovercast now requires Hovercursor. Hovercursor is a standalone sub-project which Hovercast and Hoverboard (and others, in the future) use for their various cursor needs (Leap/Look/etc.).

Check the "CastCubes" demo scenes to see how this demo has changed to support the latest project structure. This commit (and a few that follow it) show how it migrated from old to new. Check the "CastTest" scenes to see a minimal integration.

In general, the Hovercast setup process is now simplified. The *Setup classes will search the GameObject hierarchy for most scripts. If a script isn't found, the setup will try to create/use a default version. So, you won't need to manually connect all the "Providers" anymore. Basic steps:

• Create a "Hovercursor" GameObject within the "HandController" GameObject, and attach the HovercursorSetup script to it.
• Create a "Hovercast" GameObject within the "HandController" GameObject, and attach the
  HovercastSetup script to it. Drag the scene's camera into the "Camera Transform" property (this makes the cursors face toward the desired camera).
• Attach the HovercursorLeapInput and HovercastLeapInput scripts to the "HandController" GameObject. This is for typical Leap Motion based input. There are other demo scenes that show how to setup a "Look" cursor mode.
• Create a GameObject for the root of your menu items, and attach the HovercastItemHierarchy script to it.
• Within that menu root, add child GameObjects for the menu items. Attach the HovercastItem script to each item, and configure the item properties as usual.

[zachkinstner]

Overview

The Hover UI code is now all contained within a Visual Studio (or MonoDevelop) solution, located here. The solution contains several projects, which each produce one assembly/DLL that should be placed into Unity's /Assets/Plugins/ directory.

These projects are structured in a way that limits the dependencies required for integration. For example, you can omit the Hover.Cast.Input.Leap DLL to avoid any dependence on Leap Motion input. This becomes more important as additional input modules become available.

As described above, there is now a Hover.Cursor project, which handles cursor-related functionality for all other projects. There is also a Hover.Common project, which all other projects depend upon to provide a variety of shared utilities and functionality.

There are currently two Hover.*.Edit projects, which contain custom Unity editors. These had to be separated out, since references to UnityEditor.dll are not allowed in full Unity builds. These DLLs should reside in an Editor/ directory.

[zachkinstner]

I have excluded the compiled Hover.* assemblies from the repository. I didn't want to commit new versions of those assemblies with each change. The projects in the main Visual Studio solution are configured to deploy their assembly to /Unity/Assets/Plugins/Hover/ or /Unity/Assets/Plugins/Hover/Editor/ upon each successful build. You will likely need to create these empty directories before this deployment process will work.

I'll be packing up "official" versions of these assemblies, so you won't have to build them yourself. You'll only need to build them yourself if you are making changes to the Hover UI code.

[zachkinstner]

New wiki documents:

• Home (and sidebar)
• Hovercursor / [Integration](https://github.com/aestheticinteractive/Hovercast-VR-Menu/wiki/Hovercursor Integration)
• Hovercast / [Integration](https://github.com/aestheticinteractive/Hovercast-VR-Menu/wiki/Hovercast Integration)
• Hoverboard / [Integration](https://github.com/aestheticinteractive/Hovercast-VR-Menu/wiki/Hoverboard Integration)

[ddutchie]

Good Job. Busy integrating into my project, will report any major issues.

[ddutchie]

Does the latest package include the latest Oculus integration?

[ddutchie]

Okay, I didn't manage to get anything working.
I haven't really used Microsoft VS before, but I managed to build what I needed, fixed a missing reference to the UnityEditor.dll and placed all the dll's where they were needed.

None of the prefabs keep their script connections. ( I think this might be because the dll's were not in the Plugins folder the first time I started the project)

Nothing works.
Even after replacing all the missing scripts with the scripts mentioned above and in the integration docs.

Holding out.
Thanks for your efforts.

[zachkinstner]

Does the latest package include the latest Oculus integration?

The core projects do not use/depend upon Oculus. The Unity project included in this repository does still have the Oculus integration, and it is used by most demo scenes. The CastCubes scene is the main Hovercast demo from before this refactoring process.

---

I managed to build what I needed

Sorry, I forgot to upload the pre-built assemblies. In most use cases, you won't need to build them by yourself. You can download them here (480KB).

The contents of this archive:

• /Assets/Plugins/Hover/: All main project assemblies. You may not need them all (for example, the Hover.Board assemblies wouldn't be needed for Hovercast-only usage).
• /Assets/Plugins/Hover/Editor/: The assemblies related to the Unity editors.
• /Assets/Hover/Common/Resources/: The textures, shaders, and fonts used by the Hovercast/Hoverboard (for its default/standard design).

[ddutchie]

You should consider distributing it as a unityasset which can be imported into a project to simplify this process. Will try again now.

[zachkinstner]

None of the prefabs keep their script connections.

Unfortunately, I think this is expected for Unity. The class names and namespaces of the scripts have changed, so I don't think any connections will be maintained. I had to manually update the existing Hovercast/Hoverboard demo scenes to find/use the new script names. Sorry -- I know this is a pain. I can try to describe my general process in a moment.

---

Nothing works.

Oh no! I can help you work through the issues. We can document them here to help anyone else who is trying to perform the same migration process. We'll have to get more specific about the error messages that are appearing, etc.

First step: Are you able to get any of the included demos to run? Please do use the pre-built assemblies (from the download link above) so we can be sure we're using the same files. If I remember correctly, you're using Unity 5, which I haven't tested out yet. Let's try the HovercastTest-VR-LeapMenu-LeapCursor.unity scene (located in /Assets/Hover/Demo/CastTest/).

[ddutchie]

[ddutchie]

this is a screenshot taken from the downloaded github package.

[zachkinstner]

this is a screenshot taken from the downloaded github package.

Are all the Hover.* assemblies in the Plugins directory?

[ddutchie]

What I'm trying now is re-extract the main github zip, extract the assemblies posted above. Add to Assets folder. Open project. Still same issue as above.

[zachkinstner]

I'm downloading the repository fresh to try the same process. Maybe there's some important difference between my local setup and the repository's setup.

[ddutchie]

I've attatched all the scripts as explained in the integration docs. Hands aren't even showing up.

[ddutchie]

none of the demos run. except for the OVR or LEAPOVR demos also included in the download.

[zachkinstner]

What I'm trying now is re-extract the main github zip, extract the assemblies posted above. Add to Assets folder. Open project. Still same issue as above.

I can reproduce this issue. The demo scenes included in the repository are not keeping their connections to the scripts. When I click the script field in Unity, I do see all of the "Hover*" scripts in the list, so I'm not sure why it can't find them.

I'll need to investigate this further. As you suggested, maybe a UnityAsset package is necessary.

[grobm]

I am seeing the same thing. I am assuming we are still working in Unity 4.6 and not Unity 5?

-Mark

On Mar 31, 2015, at 8:26 AM, ddutchie notifications@github.com wrote:

https://cloud.githubusercontent.com/assets/10877426/6918812/d53589ba-d7b1-11e4-84f4-c130dfb0be59.png
I've attatched all the scripts as explained in the integration docs. Hands aren't even showing up.

—
Reply to this email directly or view it on GitHub #21 (comment).

[zachkinstner]

Ah, it's related to the .meta files. Unity is probably finding the assemblies (which contain the scripts) via their ID value in the .meta files. When you drop in new assemblies into the project, however, they get auto-assigned new ID values.

I just copy-pasted the assemblies (with their .meta files) from my local project into the one that I just downloaded fresh from the repository. When I did that, Unity immediately found the "missing" scripts. I'll post a download that includes the .meta files. That's probably not the permanent solution, but it should help in the near term.

[zachkinstner]

Please try the asset download again. It's the same link as before, but the .meta files are now included within the Plugins folder.

[zachkinstner]

I am assuming we are still working in Unity 4.6 and not Unity 5?

Good question. I'm working in Unity 4.6, but I think @ddutchie is using Unity 5.

[ddutchie]

And we're back. That works.

[ddutchie]

and yes. I'll be sticking to Unity5 as I'm hoping Oculus drops some mad optimizations in future versions. The scenes I am exploring are already taxing my monster PC.

[zachkinstner]

And we're back. That works.

That's great news!

---

consider distributing it as a unityasset which can be imported into a project

You can now download this UnityPackage. I tested this out in the same "fresh" repository scenario, and it worked as expected. Including .meta files in the ZIP archive is probably (roughly) equivalent to creating a UnityPackage. The upside of the UnityPackage is that you get the nice dialog for choosing which files to include in the import, etc. Good idea, @ddutchie.

Note: I had to put the UnityPackage into a ZIP file to make it downloadable on my server. Sorry for the extra step.

[ddutchie]

Does this Unity Package include all Hover items or do I still need to download the main Github zip.

Could I import just this package into one of my projects and I would have all the 'hover' dependencies to get it to work. Or do I still need files from the original branch?

Exciting. This project is moving along nicely.

[zachkinstner]

Great question -- the UnityPackage (and the earlier ZIP) includes all the "Hover" dependencies:

• All Hover.* assemblies
• The few textures, shaders, and fonts required for the standard/default design

The assemblies named Hover.*.Input.Leap do have the Leap Motion dependency. If you don't want/need Leap Motion support, you can omit those assemblies from your project. This choose-what-you-need assembly structure will become a more important factor as we introduce additional input modules, which will each create new device-specific dependencies.

None of the assemblies have an Oculus dependency. The "Look" input module just uses a Transform (typically, the one for the "Center Eye" GameObject), so it should be able to work with any kind of VR headset. (It also works with a non-VR Unity camera. The cursor just stays in the center of the screen, and you move your items/menu toward it to make selections.)

[zachkinstner]

Exciting. This project is moving along nicely.

Thanks! I agree :)

Hopefully the handful of early-adopters can get through this migration phase. I know it's time-consuming and a bit painful... I had to do it with the demo scenes. Please let me know if you come up against additional migration issues. If you resolve something that seemed confusing, please also make a note -- it will probably help the next developer.

[ddutchie]

Yay, no more downloading that full 224mb package on our african line.

On 31 March 2015 at 16:07, Zach Kinstner notifications@github.com wrote:

Great question -- the UnityPackage (and the earlier ZIP) includes all the
"Hover" dependencies:

• All Hover.* assemblies
• The few textures, shaders, and fonts required for the
  standard/default design

The assemblies named Hover.*.Input.Leap do have the Leap Motion
dependency. If you don't want/need Leap Motion support, you can omit those
assemblies from your project. This choose-what-you-need assembly structure
will become a more important factor as we introduce additional input
modules, which will each create new device-specific dependencies.

None of the assemblies have an Oculus dependency. The "Look" input module
just uses a Transform (typically, the one for the "Center Eye"
GameObject), so it should be able to work with any kind of VR headset. (It
also works with a standard Unity camera, too. The cursor just stays in the
center of the screen, and you move your menu-hand toward it to make
selections.)

—
Reply to this email directly or view it on GitHub
#21 (comment)
.

Gerard Slee

[zachkinstner]

The current UnityPackage is only about 0.5MB, so yes, that should be a big improvement for your download time ;)

[zachkinstner]

My general migration process for the demo scenes (CastCubes and BoardKeys) looked like this:

1. Open the demo's code in Visual Studio (or MonoDevelop).
   • I used the Visual Studio solution that Unity creates/updates.
2. Find all usages of the old class names, and replace them with the new classes.
   • See my "initial migration notes" above for some class equivalencies.
   • In many cases, I used a project-wide search-and-replace.
   • This also requires many namespaces to be updated in each class's "using" lines.
     • The Visual Studio or MonoDevelop "add usings" tool (usually available when you right-click on a class name) should help here.
   • Continue this process until the project compiles.
3. Update the Unity project.
   • I don't think this process can be automated, but maybe someone has a better way?
   • For each menu item, select the HovercastItem script. The old property values may/not remain intact, so it might require some re-setup of item types, slider values, etc.
   • For the menu root, select the HovercastItemHierarchy script.
   • For the main Hovercast GameObject, select the new HovercastSetup script.
   • For the Leap HandController GameObject, select the HovercastLeapInput script.
   • For any custom settings that were applied, select the HovercastItemVisualSettingsStandard or HovercastIntegrationSettings scripts.
   • The "Customization Provider" concept is gone. The settings scripts are now provided on an individual basis (see the point above).
   • Integrate the Hovercursor project: integration instructions.
   • Please refer to the Hovercast integration instructions for full details.

This commit (and a few that follow it) show the full details of the demo's migration process.

[ddutchie]

I'm getting this error on two custom listener scripts. They are very similar. The only difference is Lights are either enabled or disabled.

using System;
using UnityEngine;
using Hover.Common.Items;
using Hover.Common.Items.Types;

namespace Hover.Demo.CastCubes.Items {

/*================================================================================================*/
public class LightsOff: DemoBaseListener<ISelectorItem> {

    public GameObject LightsOFF;

    ////////////////////////////////////////////////////////////////////////////////////////////////
    /*--------------------------------------------------------------------------------------------*/
    protected override void Setup() {
        base.Setup();
        Item.OnSelected += HandleSelected;
    }

    /*--------------------------------------------------------------------------------------------*/
    protected override void BroadcastInitialValue() {
        //do nothing...

    }


    ////////////////////////////////////////////////////////////////////////////////////////////////
    /*--------------------------------------------------------------------------------------------*/
    private void HandleSelected(ISelectableItem pNavItem) {

        //Enviro.TimeofDay(Item.RangeValue);
        //if (LightsON.SetActive (true)) {  


            //Enviro.LightsOn(pNavItem.Value);
            LightsOFF.SetActive (false);
            //LightsOFF2.SetActive (false);
            //RenderSettings.skybox = sky;
    //  }
    }
    /*--------------------------------------------------------------------------------------------*/


}

}

[ddutchie]

Besides that no errors. Able to get my listeners upgraded with very little effort.

[zachkinstner]

@ddutchie, please try this:

DemoBaseListener<ICheckboxItem>

The DemoMotionTypeListener is a good reference for a Checkbox listener. The idea for the base class's generic T is to match the item type (like Checkbox, Slider, etc.), because it has a property public T Item { get; set; }.

---

After this change, you'll have access to an ICheckboxItem typed Item property. That makes the OnValueChanged event available (via ISelectableItem<bool>), which you could handle like this:

Item.OnValueChanged += HandleValueChanged;
[...]

HandleValueChanged(ISelectableItem<bool> pItem) {
    [...]
    Lights.SetActive(pItem.Value);
    [...]
}

[ddutchie]

And there I've mastered the checkbox. Two birds with one stone as they would say.

[ddutchie]

I hope these noob questions are helping others.

[grobm]

I feel the same. :-)

-Mark

On Apr 1, 2015, at 9:37 AM, ddutchie notifications@github.com wrote:

I hope these noob questions are helping others.

—
Reply to this email directly or view it on GitHub #21 (comment).

[zachkinstner]

I'm sure they will :)

We can start using StackOverflow for general QA. My username is zachkinstner there, also. You can @-mention me on questions and/or use the following tags (I have notifications set up for these):

• hover-vr
• hovercursor-vr
• hovercast-vr
• hoverboard-vr

[zachkinstner]

Working on new per-project animations for the wiki pages:

[zachkinstner]

I have created a "release" here in GitHub:
https://github.com/aestheticinteractive/Hover-VR-Interface-Kit/releases

[grobm]

Nice work!!!

-Mark

On Apr 2, 2015, at 12:37 PM, Zach Kinstner notifications@github.com wrote:

I have created a "release" here in GitHub:
https://github.com/aestheticinteractive/Hover-VR-Interface-Kit/releases/tag/v1.0.0 https://github.com/aestheticinteractive/Hover-VR-Interface-Kit/releases/tag/v1.0.0
—
Reply to this email directly or view it on GitHub #21 (comment).

[zachkinstner]

Thanks! 😄

[zachkinstner]

Some notable new/updated wiki documents:

• Home
• [Hovercursor Input Modules](../wiki/Hovercursor Input Modules)
• [Hovercast Input Modules](../wiki/Hovercast Input Modules)

[grobm]

Finally got the weekend to implement the new/updated modules.

A lot quicker and a lot faster. The issues I was having with the selection and instance of objects is now gone.

Great improvement!!!

-Mark

On Apr 2, 2015, at 2:57 PM, Zach Kinstner notifications@github.com wrote:

Some notable new/updated wiki documents:

Home x-msg://2/wiki
Hovercursor Input Modules x-msg://2/wiki/Hovercursor%20Input%20Modules
Hovercast Input Modules x-msg://2/wiki/Hovercast%20Input%20Modules
—
Reply to this email directly or view it on GitHub #21 (comment).

[zachkinstner]

Thanks, I'm glad to hear it!

A little background for anyone who might be new: the initial version of Hovercast required a few extra scripts in the scene. You then had to drag-and-drop those scripts into the HovercastSetup to "wire" everything up. The *Setup classes now search your scene to find relevant scripts (for the menu items, settings, etc.).

[Slaventsiy]

Currently trying to make Hovercast work in my project. Unity 5.0.1f1 Leap Motion 2.2.5+26752. Hovercast cannot find the LeapCSharp.NET3.5.dll, after replacing it with the one from Git solution - Unity finally has loaded all the scripts from dlls and Hovercast seems to work, but the editor is giving an error "EntryPointNotFoundException: CSharp_Image_DataWithArg ... ".

[zachkinstner]

Hi @Slaventsiy, thanks for the note!

I haven't done extensive testing in Unity 5 yet, but a few of us have been able to get it working. In my Unity 5 integration, I also experienced the LeapCSharp.NET3.5.dll issue. My solution was to move the contents of /Assets/Plugins/Hover/ down one level to /Assets/Plugins/. I'm not sure why this is an issue for Unity 5; I couldn't find any answers with my searches at the time.

I'm not sure about the second error. Since you replaced the Leap DLL with the one from this repository, my guess is that the error is related to a Leap DLL version mismatch. Please try to use your original Leap DLL + the "plugins" folder solution -- hopefully that will resolve it.

[Slaventsiy]

Thank you, @zachkinstner! The fix works and Hover is awesome!

[zachkinstner]

I have included this Plugins folder change in the v1.1.0 release. I'm going to close this issue for now.