Getting Started

IMPORTANT

If you're having trouble, be sure to see the Troubleshooting section, as well as the relevant topic pages. If you still have an unresolved issue, be sure to visit the forum at forum.anbsoft.com.

Installation

  1. Open your Unity project and click Assets->Import Package->Custom Package...

  2. Locate the core EZ GUI unityPackage file which came with the EZ GUI distribution. Select it and click “Open”. Import all files.

IMPORTANT

For better performance, EZ GUI uses generics. If you receive a parsing error upon importing and are using Unity iPhone 1.7, make sure your project is set to use .NET 2.1. In Unity iPhone, click Edit->Project Settings->Player and change "Api Compatability Level" to .NET 2.1.
NOTE: There are multiple .unityPackage files included with a distribution: a “core” package which includes all necessary files, and one or more “sample” packages which include sample assets and demonstrates some of the features.

All scripts will be imported under the "Editor" and "Plugins" folders. The main scripts you will be accessing directly are found under:

Plugins/EZ/GUI

Inside the GUI folder, are the Controls and Management folders. Controls is where you will find most of the scripts you will use to create controls. And Management contains the UIManager class which must exist in any scene that contains EZ GUI controls.

Basic Setup

  1. Attach a UIManager script to a GameObject in the scene and set its various options. (See UIManager for more details.)

  2. Add an empty GameObject to the scene and drag one of the many control scripts onto it (such as UIButton).

Note

Every scene that contains EZ GUI controls must have a single GameObject with a UIManager script attached.

Creating a control

This section will step you through the process of adding a simple control to the scene. For this example, we'll be adding a Button control.
  1. Create an empty GameObject.

  2. Click Component > EZ GUI > Controls > Button.

  3. You'll now see lots of settings listed in the inspector that are inherited from the various sprite base classes as well as a few settings that are specific to this control. We will cover these later. For now, open the UI Control Editor window and we will proceed to define our button's visual appearance. To do this, click Window > UI Control Editor.

  4. In the UI Control Editor you will find a selection of "states" that are supported by the selected control. Drag textures onto the texture slots to define the appearance the button will have when in each state. The states for the Button control are:
    • Normal
    • Over
    • Active
    • Disabled

  5. Now select a material for the control (if not managed) and build its graphics to an atlas (see Building Atlases for details). Now you should be able to check Pixel Perfect or manually set a width/height. You may now need to press play briefly and the button should appear.

  6. Now that we have defined the appearance of our button, we want our button to cause something to happen (call into our code) when clicked. We can register a delegate in-code by calling the button's SetValueChangedDelegate() method, but the easiest way to get up and running quickly is to make the member in the inspector labeled Script With Method To Invoke point to a GameObject containing the script that will serve as our input handler. We then fill in the Method To Invoke with the name of the method we want to receive input from our button. NOTE: This is case-sensitive and does not include the function/method's "()".

  7. Finally, we set When To Invoke to match the type of event we want our code to respond to. This defaults to TAP. This means that when the button is tapped (pressed and then released), our code will get called.

The button should now function normally. If clicked, your input handling script should be called. Note that a box collider was added automatically. If you want, you can assign your own colliders.

You will find that, for the most part, the process to setup every control is largely the same as the above. To learn more about each control type, see Controls.

Note

EZ GUI controls are drawn in world space rather than screen space. To make a control stationary relative to a moving camera, make it a child of the camera object.





Note

Use the UI Control Editor to configure the visual appearance of a control's various states.

Additional Notes

Making Changes

Always remember, whenever you make changes to a control's textures, you must rebuild your atlases for the changes to take effect.

IMPORTANT NOTE: If your game consists of more than one scene that contain identical controls, or you have any sprite-based control prefabs, it is recommended that every control you create be associated with a prefab, and then as you make design changes to your controls (such as changing their textures), only make these changes to the prefabs and let the instances of those prefabs in your scene(s) be automatically updated. Making changes directly to controls in a scene which are linked to a prefab will cause the properties you change to "override" the same properties in the prefab. The problem with this is that the atlas builder will skip prefab instances and only look at the "source" prefab, meaning a prefab instance that has a different set of textures than its original prefab will not get updated with the correct UVs and will not have its differing source textures included on the atlas. This is by design so that controls in a non-open scene do not get "left behind" when a new atlas is generated.
The rule of thumb is to manage and keep all your control types in prefabs and only modify the properties of the prefabs themselves and not the prefab instances in a scene.

Note

Controls in a scene which are marked as inactive cannot be included when the atlas is rebuilt. In such cases, make any inactive controls into prefabs and use the Scan Project Folder setting when building your atlases.
Texture Sharpness

Even when using Pixel Perfect, the Unity renderer may generate somewhat blurry results depending on what settings you use for mip mapping and texture filtering. If you desire pixel-perfect rendering, it is recommended that you disable mip map generation for the generated texture atlas and change the texture filtering mode to "Point", as well as disable compression. Disabling mip map generation will also save memory and would not be used anyway if the sprite is always displayed pixel-perfect.
Destroying sprite-based controls (Unity 3.1 and earlier only)

If you destroy sprite-based controls at runtime using Destroy(), be sure that you call Delete() on the sprite script before doing so. Otherwise, you may experience a memory leak as the sprite's mesh does not get freed. This is a result of a peculiarity in how Unity handles meshes. Calling Delete(), however, ensures that the mesh gets freed properly.