Before I begin explaining the use of pivot entities, please ensure that you familiarise yourself with the use of object grouping and entity creation from within Cartography Shop. These techniques are required for creating and using Pivot entities.
When creating your maps, it will become obvious that a means for manipulating grouped objects in DarkBASIC Professional is needed. It is also cumbersome and inefficient when trying to rotate or translate a set of meshes in your map that must be done each frame. A typical example would be an elevator or a set of doors. These types of non-static objects may consist of several individual meshes. The elevator contains the main cabin, a panel textured with buttons, and finally, two sliding doors.
So, would it be more effective if all these objects were somehow grouped together, and when you want to move the group, all you use is the pivot entity identifier instead of referencing each mesh in the group.
Using Pivot Entities
When a CSM map is loaded into DarkBASIC Professional, all meshes are normally positioned relative to the world origin, (x0, y0, z0). The problem with this is that any rotations performed on CSM geometry would result in the geometry being rotated about the world origin. This is not acceptable for objects such as ceiling fans or turnstiles because they must rotate about their centre. So, how can we do this?
Examine the following image:
In the room, I've placed a ceiling fan that consists of 5 meshes. The five meshes have been grouped together to form a single object which can be selected and moved independently. The next stage is to create an entity which has at least two single properties:
ClassName = Pivot
Name = Ceiling Fan
The entity must be placed at the centre of the group which will act as the local origin for the group. Once the entity has been created and placed, you must now add this entity to the group of meshes. At present, the only way this can be done in Cartography Shop is to ungroup the meshes, reselect all meshes including the pivot entity, and then re-group again.
When the map file is loaded into DarkBASIC Professional using the LOAD CSM command, all groups that contain pivot entities will be logged and stored for use by the pivot commands which are explained further in.
Controlling your pivot entities in DarkBASIC Professional
Provided with the plugin is an example program that demonstrates how to find and use a pivot entity. Typically, you would use the CSM PROPERTY function to find the entity index that matches a specific property name. In this case, I've used the following code to find the entity index for the ceiling fan:
nEntity = -1
The next step is to convert the entity index into a pivot index. To do this, you use the CSM PIVOT ID function. This function returns a pivot index based on what entity index you specify. This pivot index can now be used with any of the Pivot functions (See function list).
(C) Paul S. J. Millard 2006