Installation

Coherent UI for Unity3D is distributed in a unitypackage file. You can import this package in your project by either double-clicking on it, or by importing it through Unity in the Project window.

Note

Versions 1.5.3 and prior: After importing the package, you have to install the assets provided. This is done by the Assets → Coherent UI → Install Coherent UI menu entry.

Versions 1.5.4 and later: The install step required for previous versions was removed in Coherent UI 1.5.4. The new structure places the UI Resources inside the WebPlayerTemplates folder since it's the only one that Unity ignores when compiling scripts. The files placed there are not actual web player templates but a collection of HTML/CSS/JS files that are used by the samples. These files won't interfere with actual Web Player Templates as long as there is no file named index.html. The default UI Resources path is no longer set (the installation step in previous versions did that) and the default file handler will try to find the assets in the WebPlayerTemplates folder when ran in the Editor. For built games you must set the UI Resources path using the Edit → Project Settings → Coherent UI → Select UI Folder entry.

Versions 2.4.4 and later: CoherentUI 2.4.0.0 and later versions have support for Unity 4.x and 5 versions, but will no longer support Unity3D 3.5.7. In order to support the new Unity 5, the Coherent UI package has been reorganized. So if you are upgrading to version 2.4.0.0 or later, it is recommended that you take the following steps before importing the new Coherent UI unitypackage in your project:

1. Delete CoherentUI_Native.dll, CoherentUI_Native.pdb, libCoherentUI_Native.so and their meta files from the Assets/Plugins folder of your project.
2. Delete CoherentUINet.dll64, CoherentUI64_Native.dll and their meta files from the Assets/CoherentUI/Binaries folder of the project. Now you are ready to import the new CoherentUI package.

Prerequisites

• Unity3D 4 or later is required
• Only Pro version of Unity is supported
• Coherent UI Mobile supports iOS 5.1 and above.
• Coherent UI Mobile supports Android 3.0 and above (API level 11).
• Mobile versions of Coherent UI SDK for Unity3D work with the free version, but the Preview feature will not work.
• Java Development Kit (JDK) is required for exporting to Android. Referring to the folder you installed JDK in as <JDK>, you need to have the <JDK>/bin folder in your PATH environment variable and set the JAVA_HOME environment variable to <JDK>.

Note

Coherent UI SDK has different requirements than the requirements for Unity3D. Unity supports older hardware via fallbacks, which may prevent Coherent UI SDK from running on older graphics cards. Please make sure that the requirements of Coherent UI SDK match your client requirements for the project.

Package contents and structure

The package has the following structure:

• CoherentUI - contains the UI debugger, samples, and documentation.
• CoherentUI/Editor - contains editor classes for displaying the properties of Coherent UI components plus a post-build step class. These classes provide utility functionality.
• Plugins - contains the Coherent UI libraries. These are automatically copied when building.
• Standard Assets/Scripts/CoherentUI - contains the Coherent UI integration classes. You'll find a Detail folder inside which contains classes that are internal for the implementation and are used by the "public" classes. The interface you should be using is outside the Detail folder.
• StreamingAssets - contains assets that need to be copied as-is in the build directory. These include the Coherent UI host process executable, the libraries it needs, locales and UI resources.

Usage of the package

After importing the CoherentUI.unitypackage in your project, the two main scripts you'll be using are Standard Assets/Scripts/CoherentUI/CoherentUISystem and Standard Assets/Scripts/CoherentUI/CoherentUIView. The easiest way to use Coherent UI is to drag the CoherentUIView component onto an object and hitting Play - that's it! Everything will be up and running. Actually, you can do the same for most of the usage scenarios - just drag the component and then configure it in the inspector. Here's a bit more detail about the two scripts.

The first script, CoherentUISystem, defines initialization parameters of the Coherent UI System and should be placed no more than once in your project. The UI system is meant to be initialized in the first scene and live throughout the game's lifetime. You need to add this component to your scene only if you need custom initialization of the Coherent UI System. For the most cases, using only CoherentUIViews is enough - they will automatically create an instance of the Coherent UI System for you with reasonable default parameters. Check CoherentUISystem Lifetime for details.

CoherentUISystem properties

The second script, CoherentUIView, will represent a single HTML page. This is the component that renders your CSS and JavaScript animations and makes your game alive. This component can be placed on any object that is renderable and serves as its material. When placing it on an object all the needed components are automatically created, hidden from you, and the rendered output is bound to the mainTexture of a new material that is created at runtime. This material is set as the gameObject's renderer material so that you see the page rendered on your object.

CoherentUIView properties

You can also place views on cameras. When doing so, you get your page rendered on the whole viewport of the camera. This way you can easily add a heads-up display for your game. Don't forget to mark your HUD as transparent and make your HTML page transparent! There's even an option for drawing the HUD after the post-effects if you like (The option is available for non-HUDs, too, but it results in a no-op because it doesn't make sense).

Switching between build targets

Coherent UI Mobile has different properties and a restricted subset of features compared to the desktop versions. To switch between the desktop features and the mobile ones you must switch the current active target in Unity. This is done by clicking on File->Build Settings selecting the target platform and clicking "Switch Platform". After doing so the properties of the Views will change to reflect their capabilities specific to the selected platform. Even if the current target is iOS or Android and hence you'll build with Coherent UI Mobile you can still preview your game in the Editor. The preview will use the desktop version of Coherent UI. Keep in mind that in this case you might see some differences compared to the the mobile device after the build as the desktop version has more features. You should check often how your UI behaves and looks on the device itself (or the simulator).

Trial version registration

The trial version of Coherent UI for Unity3D requires a simple registration. The registration requires:

• the email you used for downloading Coherent UI
• internet connection
• outgoing connections to port 3000 to be allowed in your firewall

The registration is started automatically when you run the game. It shows a simple form that asks for your email.

You can register Coherent UI on multiple machines, provided that they run different operating systems.

Games exported with the trial version of Coherent UI also require registration. This means if you want to run your built game on a different computer, you'll have to register Coherent UI on that computer, too. When building a game using the trial version of Coherent UI the activator is packaged as well and ran when the game is started. For manual activation, copy the CoherentUI/Activator folder from your Unity3D project to the machine and run:

Activator.exe --unity3d --host \
        "<FULL PATH TO GAME DATA FOLDER>/StreamingAssets/CoherentUI_Host/windows"

on Windows and:

Activator.app/Contents/MacOS/Activator --unity3d --host \
        "<FULL PATH TO GAME APP>/Contents/Data/StreamingAssets/CoherentUI_Host/macosx"

on Mac OS X.