The 'ObjectTransformGizmo' class exposes 2 functions which allow you to specify the objects that the gizmo should transform. Those are the SetTargetObject and SetTargetObjects functions (singular and plural).

The 'SetTargetObject' (Singular) Function

The following code creates a move gizmo and then it calls the SetTargetObject function to tell the gizmo about the object that it should be transforming.

// Create a move gizmo and then set its target object.
// Note: The code assumes the scene contains a game object called "TargetObject".
ObjectTransformGizmo objectMoveGizmo = RTGizmosEngine.Get.CreateObjectMoveGizmo();
objectMoveGizmo.SetTargetObject(GameObject.Find("TargetObject"));

This method is really simple to use but it has the disadvantage that only one object can be transformed at a time. However, for simple purposes such as picking a game object in the scene and then assigning it to a gizmo, it works really well. It all depends on your app's needs.

The 'SetTargetObjects' (Plural) Function

When you would like to transform a collection of objects, you need to use the SetTargetObjects function instead (notice the plural in 'objects'). This might be useful when implementing an object selection system like the ones that are common in 3D editors. For example, a selection system such as the one inside the Unity Editor would be implemented with the help of this function.

The following example, assumes we are working on a selection system and we store the selected objects inside a list. Inside the Start function we inform our gizmos about the objects that they will be transforming:

class ObjectSelection
{
    // The list of selected objects
    private List<GameObject> _selectedObjects = new List<GameObject>();

    // Declare gizmo variables
    private ObjectTransformGizmo _objectMoveGizmo;
    // ... declare the rest of the gizmos

    private void Start()
    {
        // Create the gizmos
        _objectMoveGizmo = RTGizmosEngine.Get.CreateObjectMoveGizmo();
        // ... create the rest of the gizmos

        // Link the gizmos to the selected objects list.
        // Note: After 'SetTargetObjects' is called, the gizmo will store a direct reference
        //       to the object list. This means that you don't need to call 'SetTargetObjects'
        //       every time the list changes (elements added or removed). You only call it once
        //       at initialization time.
        _objectMoveGizmo.SetTargetObjects(_selectedObjects);
        // ... do the same for all other gizmos.
    }
}

Note

It is important to remember that the call to SetTargetObjects will store a direct reference to the original list. This means that you only need to call this function once at app startup. When objects are added or removed from the list, the gizmos will still have acccess to the updated list.

The Target Pivot Object

When using plural version SetTargetObjects, you must also supply a so called target pivot object. The reason why this is necessary is because transform gizmos have 2 properties associated with them: TransformSpace and TransformPivot.

To give you an example of why this object is necessary, imagine that the transform space has been set to Local via a call to SetTransformSpace(GizmoSpace.Local). When the local transform space is used, the gizmo will inherit the rotation of one of the target objects. However, it needs to know which one. The target pivot object is used for this purpose. The pivot object is also used to calculate the position of the gizmo.

You set the target pivot object via a call to SetTargetPivotObject:

_objectMoveGizmo.SetTargetPivotObject(_targetPivot);

Note

You need to call the SetTargetPivotObject function every time the target object collection has changed. Going bakck to our simple object selection class, you would need to call this function every time obejcts are selected or deselected (i.e. when elements are added or removed from the _selectedObjects list.

The target pivot object can be anything you like as long as it belongs to the target object collection. For example, you could set the target pivot object to be the last selected game object like so:

_objectMoveGizmo.SetTargetPivotObject(_selectedObjects[_selectedObjects.Count - 1]);

It is not mandatory to specify a target pivot object. However, if you don't, please keep in mind the following:

  • when using a transform pivot other than CustomWorldPivot, the gizmo will always sit at the center of the entire object collection;
  • the gizmo's rotation will always be set to identity (i.e. gizmos will be aligned to the world axes) even if the transform space is set to Local.

Refreshing the Position and Rotation

Note

The following section only applies if you DO NOT call SetTargetPivotObject.

When using plural version SetTargetObjects, you must instruct the gizmo to update its position and rotation whenever the object collection has changed. For example, using the simple object selection class from earlier, you would have to write the following code every time elements are added or removed from the _selectedObjects list:

_objectMoveGizmo.RefreshPositionAndRotation();
// Do the same for all other gizmos