Units Customization: the GameObjectAnimator component

The WMSK_MoveTo method will return a reference to a GameObjectAnimator component which will be attached to your game object. This component is the link between your gameobject and the asset itself. We recommend you to take a look at the code sample behind the MapPopulation demo.

The GameObjectAnimator component contains some useful properties that allows more precise control over the movement of the game object over the map. The following properties can be changed although they will use default values if not used:

• uniqueId: optional user-defined integer that identifies uniquely this game object.

• type: this is an integer, a user-defined value, that can be used to identify the type of unit.

• group: this is an integer, a user-defined value, that can be used to group units.

• player: this is an integer, a user-defined value, that can refer to the player to which the unit belongs to.

• duration: the duration of the current move.

• easeType: type of easing for the movement: it can be one of the following types: EaseIn, EaseOut, Exponential, Linear, Smooth and Smoother.

• height: the current height from the ground.

• heightMode: changed the height parameter semantic. Accepts Absolute_Height, Absolute_Clamped (never position below ground level) or Relative_To_Ground.

• autoScale: toogles changing the scale automatically when user zooms in/out.

• follow: toggles camera following during current movement.

• followZoomLevel: the zoom level for the camera follow.

• autoRotation: set it to true to make the game object rotate automatically then routing to the destination as well as adapt to the ground. Set this to false for static objects, like buildings (default value).

• rotationSpeed: the speed factor for the autorotation property.

• preserveOriginalRotation: when set to true, game object will retain its current rotation when added to the viewport. Note that autoRotation will override this property so if autoRotation = true, preserveOriginalRotation will be ignored.

• terrainCapability: sets whether the game object can pass through only water, only ground, is an aerial unity or ignores terrain costs (default is Any). This is an important property of your game object and if set to a value different than Any, the game object will not move in a straight line but along a calculated route from current position to end position considering custom costs assigned to the terrain. The “Air” terrain capability let the unit fly over the ocean.

• enableBuoyancyEffect: if this unit can be affected by buoyancy effects (subtle animation due to sea waves). Is true by default.
  

• pivotY: specifies the Y position of the pivot (0..1). If the model is designed so the pivot is at bottom the you don’t need to specify this value. Most ground units should be designed this way so when you put a tank unit for instance over the ground at (0,0,0), the tank will appear entirely over the ground. However, if your model is not designed this way, you can specify a value for pivotY. A 0.5 value will mean that the pivot is at the center of the mesh, while a value of 1 means that the pivot is at the top of the mesh.

• minAltitude/maxAltitude: these values (0..1) define the altitude range across the game object can move. Default values are 0 to minAltutude and 1 to maxAltitude, so there’s no limitation. You may want to lower the maxAltitude to prevent ground-level game objects cross very high mountains.

• maxSearchCost: the maximum allowed cost for the route. A value of -1 will use the global setting defined by pathFindingMaxCost.

• maxSearchSteps: the maximum allowed steps for the route. A value of -1 will use the global setting defined by pathFindingMaxSteps.

• attrib: JSON object that stores user-defined Custom Attributes (see Custom Attributes section for more details)

• BlockRayCast: when set to true, other map click events won’t be fired when the pointer is on this unit.

• visible: (default value=true). When set to false, unit will be invisible regardless of its position on the screen or map. For a visible unit, use isVisibleInViewport to determine if the unit is currently visible on the screen.

• updateWhenOffScreen: (default value=false). By default, units not visible in the viewport are not updated in world space (position/rotation is not updated to improve performance when using many units). Set this value to true to keep units updating their transform even when they’re out of the viewport. Note that when units move, their GameObjectAnimator properties still are updated regardless of their visibility (for example, units moving will have their currentMap2DLocation field updated).

• minZoomLevel / maxZoomLevel: let you define a zoom level range where the unit is visible (the current map zoom level can be obtained calling map.lastKnownZoomLevel or map.GetZoomLevel() and is a value in the 0-1 range, where 1 is fully zoomed out and 0 is zoomed in or when the camera is really near the surface). For example, if you set maxZoomLevel to 0.4, the unit will be visible only when you zoom in at the unit position.

The GameObjectAnimator also exposes a few useful direct functions that you can call once you have a GameObjectAnimator reference to interrogate the unit status or to send direct commands to them:

• isOnWater: returns true if the unit is currently on water (always true for naval units and false for ground units). Some units can move either over ground and water (air and hybrid units) and should have terrainCapability set to Any.

• isNear: returns true if the unit is near given coordinate (optionally passing a max distance value).

• isVisibleInViewport: returns true when the gameobject is visible in the current viewport view. Remember that you can zoom in and scroll the viewport, so the asset will automatically hide game objects that fall outside the current view.

• MoveTo: similar to WMSK_MoveTo() method extensions. In fact, WMSK_MoveTo() calls this function internally. WMSK_* methods are available for convenience if you don’t have a reference to the GameObjectAnimator (which you can get using GameObjectAnimator anim = yourUnit.GetComponent<GameObjectAnimator>()).

• FindRoute: same than WMSK_FindRoute.

• isMoving: returns true if the gameobject is currently moving across the map.

• ChangeDuration: adds/substract time to the path duration while unit is moving effectively changing the unit speed.

• currentMap2DLocation: the current location of the game object in map coordinates (-0.5 .. 0.5).

• endingMap2DLocation: the final location of the game object in the map when it finish entire movement.

• destination: the destination ff the current movement. If the unit moves along a path, destination marks the end position of current step. If the unit does not follow a path (ie. called with MoveTo(destination), then destination equals to endingMap2DLocation).

• Stop: makes the unit stop at current position.

• Fire: similar to WMSK_Fire() method extension.

• GetCellNeighbours: gets a list of hexagonal cells where the unit can move (if grid is enabled).

In addition to the above properties and methods, each GameObjectAnimator exposes the following events which you may subscribe by adding your own function to this properties (eg. OnMoveStart += myfunction):

• OnMoveStart(GameObjectAnimator): fired when the game object starts a movement.

• OnMove(GameObjectAnimator): fired when the game object moves over the map.

• OnMoveEnd(GameObjectAnimator): fired when the game object stops.

• OnCountryEnter(GameObjectAnimator): fired when the unit enters a country.

• OnCountryRegionEnter(GameObjectAnimator): fired when the unit enters a country region.

• OnProvinceEnter(GameObjectAnimator): fired when the unit enters a province.

• OnProvinceRegionEnter(GameObjectAnimator): fired when the unit enters a province region.

• OnPointerXXXX: see Unit selection events on next sections.

• OnKilled: fired when unit gameObject is destroyed

map.VGOToggleGroupVisibility(group, visible): toggles visibility of a group of registered game objects in the viewport.

map.VGOGet(uniqueId): returns the registered game object in the viewport by its unique identifier (optionally set as a property).

map.VGOGet(position, distance): returns the registered game object in the viewport located near position.

map.VGOGet(rect): returns a list of registered game objects contained in a given rect.

map.VGOGet(rect, List<GameObjectAnimator> results, AttribPredicate predicate): returns a list of registered game objects contained in a given rect which optionally satisfy a predicate function.

map.VGOGet(List<GameObjectAnimator> gos): fills user supplied list with all registered gameobjects.

map.VGOBuoyancyAmplitude: rotation amount for the buoyancy effect of naval units. Set to zero to deactivate.

map.VGOBuoyancyMaxZoomLevel: maximum zoom level where the buoyancy effect is enabled.

map.VGOLastClicked: returns last clicked unit.