Programming Manual Chap. 12

Creating and using Gizmos
In addition to SceneObjects, the Wild Pockets engine supports another type of 3D object: the Gizmo. Like SceneObjects, Gizmos are drawn in the 3D space. However, unlike SceneObjects, Gizmos never interact with other things in the scene; they are purely visual with no body. They are also much simpler than SceneObjects, allowing only sphere, box, and line shapes to be drawn. Gizmos are primarily intended for creating user interface elements, such as selection boxes, directional indicators, and visual connections between related things in a scene.

To use Gizmos, you must first enable the Gizmo system by doing the following in your onSceneStart method: Gizmo.setActive(true)

Once Gizmos are activated, you can create some by using the Gizmo.create method. You can create Gizmos that are spheres, boxes, and lines. Regardless of what type you create, they all use the same method.

Here is an example of creating a Gizmo. Here, we simply create a yellow box that sits near the origin: myBox = Gizmo.create( "box", {     position=vec(0,0,0),      extents=vec(20,20,2),      color=color(1,1,0,1)  } )

The first argument simply states that we want to create a box gizmo. The second argument is a table that sets the default values of the gizmo: position is the origin of the world, and color is yellow. The 'extents' option is unique to box gizmos: Extents tells the box what its height, width, and depth should be.

Once we have created the gizmo, we are returned a Gizmo object, which acts very much like a table. We can change the properties to change the gizmo's behavior; it will immediately change in the 3D view to reflect its new properties. For example, the following code would turn the box red and position it 5 meters above the scene's origin: ''myBox.color=color(1,0,0,1) myBox.position=vec(0,0,5)''

Gizmos are automatically shown when created; you can hide them by calling their hide method (myBox:hide) and hide all the Gizmos by calling Gizmo.hideAll.

As a more complicated example, here is a gizmo that always floats 5 meters above an object referenced by the variable "selectedObject": myMarker = Gizmo.create( "sphere", {     position=function  return selectedObject:getPosition + vec(0,0,5) end,     radius=2,      color=color(0,1,0,1)  } )

When you set a function as one of a Gizmo's properties, that function is evaluated every frame and the value the function returns is used as the value of the property. In this example, instead of setting position to a specific value, we set it to a function that calculates the position based on the position of selectedObject.

You can also set a SceneObject to be the value of a property. When this is done, the corresponding property of the SceneObject is read every frame and used as the value of the property. For example, here is how to create a purple line gizmo that connects the centers of two objects referenced by object1 and object2: connectingLine = Gizmo.create( "line", {     color=color(1,0,1,1),      endpoint1=object1,      endpoint2=object2  } )

Since endpoint1 and endpoint2 are position properties for a line, the endpoints are decided by calling object1:getPosition and object2:getPosition every frame. So the line always connects the two objects, regardless of where they are.

Here are all the properties that Gizmos understand:

shared by all Gizmos box Gizmos sphere Gizmos line Gizmos
 * position: position of the gizmo. For lines, this is added to endpoint1 and endpoint2
 * rotation: rotation of the gizmo. Spheres ignore this. For lines, the entire line is rotated
 * scale: scale of the gizmo
 * color: color of the gizmo
 * extent: length of the box along the x, y, and z axes, in meters
 * radius: radius of the sphere, in meters
 * endpoint1: position of one end of the line
 * endpoint2: position of the other endpoint of the line
 * color1: Color of endpoint 1. Overrides the color property
 * color2: Color of endpoint 2. Overrides the color property