Class MacaoObject

The class MacaoObject in the package dynamic extends the MacaoObject of the package kernel with fields and methods for dynamic functionality. This includes walking, building nets, talking and others.

For more see the package description of dynamic.

This is the quasi-constant defining the bunch type SAY.

To use this constant call MacaoObject.prototype.BUNCH_TYPE_SAY.
See also addLookBunch().

This is the quasi-constant defining the bunch type STAND.

To use this constant call MacaoObject.prototype.BUNCH_TYPE_STAND.
See also addLookBunch().

This is the quasi-constant defining the bunch type WALK.

To use this constant call MacaoObject.prototype.BUNCH_TYPE_WALK.
See also addLookBunch().

Call this method to change the current velocity by the given value.

The velocity is automatically limited between zero and the maximum velocity defined for the object.
See also setVelocity() and setWalkCharacteristics().

Parameters

acceleration: Provide the difference of the velocity in pixels per step. The value may be positive or negative.

Use this method to add a number of looks, which are building a bunch.

What is a Look Bunch?

HTML is not able to rotate an image to show e.g. a car driving in different directions. Instead you have to add a number of images, showing the car in several directions. The images have to be added as MacaoLook objects. Such a set of images I call a bunch.

One call to the method addLookBunch() creates and adds such a set of looks to the object. A bunch has a special naming convention for the look names. When you use this method, you also have to follow the naming convention for the filenames of the images. The name of a look in the bunch consists of the bunch type and a binary like string encoding the direction.

The bunch type defines the purpose, for which the look is displayed. There are three bunch types. They are defined as constant properties of the class: BUNCH_TYPE_STAND, BUNCH_TYPE_SAY and BUNCH_TYPE_WALK. The constants contain the strings "Stand", "Say" and "Walk".
A look of a bunch type Walk is displayed, when the velocity of the object is not zero (see also setVelocity(), walkToPos() and setApproachClick()). If the objekt is not walking or there is no look of the type Walk, a look of the type Say or Stand is displayed. A look of the bunch type Say is displayed, while a bubble is displayed for the object (see also say() and addTalkItem()). If there is no look of type Say, then there is a look of type Stand displayed. The look will automatically be adjusted, when you use the functionality of the package dynamic.

The direction is encoded by a binary like string consisting of the characters "0" and "1". North is the "0". South is the "1". East is the "01" and west is the "11". Each subdivision of the directions extends the number by a digit. This has the advantage, that each direction keeps its name, even if you increase or reduce the number of subdivisions. You only need to change the depth, not the names of the files.

Here is a list of the encoding for a depth of 5 (=32 directions) in clock wise order:
0 (= north), 00001, 0001, 00011, 001, 00101, 0011, 00111,
01 (= east), 01001, 0101, 01011, 011, 01101, 0111, 01111,
1 (= south), 10001, 1001, 10011, 101, 10101, 1011, 10111,
11 (= west), 11001, 1101, 11011, 111, 11101, 1111, 11111
See the tutorial for a better presentation.

The depth defines the number of directions, which is the number of images for a bunch. A bunch has 2 to the power of depth directions. For example, a bunch of depth 3 has 8 looks, which are 8 images. If you call the method addLookBunch() with a depth of 3, all the 8 looks will be created and added.

The images, which are added using the method addLookBunch() must also follow the naming conventions. For Example:

myObject.addLookBunch(myObject.BUNCH_TYPE_STAND, "optional/cars/blue/carBlue", 1, ".gif", 20, 20)

The example adds two looks to the object, because 2 to the power of 1 is 2. The first look has the name "Stand0" and its image has the URL "optional/cars/blue/carBlueStand0.gif". It shows the car looking north. The second look has the name "Stand1" and its image has the URL "optional/cars/blue/carBlueStand1.gif". It shows the car looking south. If you want more directions, just increase the depth. Set the depth to 5 to load looks for 32 directions. Of course 32 images need to be there.

What are Phases?

You can use phases, to define the animation of walking objects like characters or to switch between bunches. The use of phases is optional.

To animate a character, you use for example three different images for each direction. You may call the phases a, b and c. First you have to create three images for each direction. You have to insert the name of the phase between the direction part and the extension of the filename of the images. So the images for the direction north may have the filenames arnoldWalk1a.gif, arnoldWalk1b.gif, and arnoldWalk1c.gif. To add a bunch containing all the phases, you provide the parameter phases like in the following example.

myObject.addLookBunch(myObject.BUNCH_TYPE_WALK, "optional/characters/arnold/arnold", 1, ".gif", 20, 20, 0, 0, "a,b,c")

Now you have to use the method setWalkPhases() to tell the object the sequence of phases, which is used to animate the object during walking. In the example the image b has to be used twice in the animation. So you get the sequence a-b-c-b-a-b- and so on. Each phase-image in the sequence is displayed for the duration of a walk interval (see MacaoPage.setWalkInterval()). The walk interval is by default 150ms plus the time the computer needs to calculate the next step and to repaint the object. You can display a phase-image for a longer time by repeating the name of the phase in the sequence. A typical walking sequence can be defined like this:

myObject.setWalkPhases("a,b,c,b")

The other purpose of phases is to have loaded several bunches for the same bunch type and switch between the bunches. For example you want to display a dumper in loaded and in unloaded state. First you have to create the images for all states and all directions. Again the name of the phase has to be inserted after the direction part and before the extension of the filenames. You can use one call of the method addLookBunch() to add both phases.

myObject.addLookBunch(myObject.BUNCH_TYPE_STAND, "optional/cars/dumper/dumper", 1, ".gif", 20, 20, 0, 0, "loaded,unloaded")

Then you can use the method setBunchPhase() to switch between the phases, when the dumper is loaded or unloaded.

myObject.setBunchPhase(myObject.BUNCH_TYPE_STAND, "loaded")

You can mix up both techniques. So you can display a character, which for example is carrying a book or carrying nothing. Use the method setWalkPhases() to switch between the phases.

Creating the images

To add a bunch of looks with your own images, you first need to crate the bunch images. There is the tool rotate.hta respective rotate.html contained in the distribution of Macao. It helps you to rotate images, which are showing objects in the birds view.

Rotate is using the freeware toolset Image Magick to rotate the images. You need to download Image Magick from the web (www.imagemagick.org) and install it on your computer. You should also download Image Magicks separate library for gif compression.

If you are on a MS Windows system (others see below), start rotate.hta. It is an HTML-application and runs on windows systems without installation. The application consists of a handful of little HTML- and Java Script files. When you start the application, it offers a dialog like window. Fill out the fields: Select the location of the convert.exe file of the Image Magick installation. Select the source image, which you want to rotate. Enter the size of the source image.

The source image has to be of square format. It may be much larger than the resulting bunch images. It has to show the object in the direction north (= up). It's recommended to use a gif image with transparent background. You need to know the transparent colour. Enter the colour like using the pattern of the example, which is displayed by default. The object, which is shown in the image, should be a little smaller than the image, because when it is rotated, the corners will be cut.

Enter the path, where the bunch images are to be created. Add the beginning of the filename to the path. Select the bunch type. Enter the file extension. Enter the width of the image. Select the bunch depth. That sets the number of images for the full rotation. Click "Rotate" to start the generation of the images. The created images will automatically appear in the preview. The DOS commands, which are used to create the images, are shown in the field "Generated Shell Commands".

When you are not on MS Windows, you can't start rotate.hta, because it is M$ specific. But you can open the web page rotate.html with the browser. Fill out the fields as described above. Click "Rotate", to generate the shell commands. Copy the shell commands to the clipboard and paste them to a shell script file. Execute the shell script file, to generate the images.

Parameters

bunchType: Provide the bunch type. This has to be one of BUNCH_TYPE_STAND, BUNCH_TYPE_WALK or BUNCH_TYPE_SAY.
imageBase: Provide the URL of the path where the images are located. Append the beginning of the filename of the images.
depth: Provide the depth. The depth defines the number of looks, which are created (= 2 to the power of depth). the depth usually is between 0 and 5.
extension: Provide the extension of the file names. This is usually ".gif".
baseWidth: Provide the width of the images in pixels. You can provide a different value than the images' real width to resize the image by default.
baseHeight: Provide the height of the images in pixels. You can provide a different value than the images' real height to resize the image by default.
deltaLeft: Provide the shift of the object in x-direction. Provide null or 0, if the object doesn't need to be shifted relative to the standard object left position.
deltaTop: Provide the shift of the object in y-direction. Provide null or 0, if the object doesn't need to be shifted relative to the standard object top position.
phases: Provide the names of the phases, which have to be loaded. Provide the names as a comma separated string. Put no spaces around the commas. The empty string is also a legal phase name. Provide null or an empty string, if you don't want to use phases.

Call this method to add a talk item to the object.

See the description of the class MacaoTalkItem for a detailed description on how to use talk items.

Parameters

talkItem: Provide the talk item, which you want to add.


Returns

The method returns the talk item, which is added by the call.

Call this method to adjust the objects z-index according to the object's current position.

If staggering is set active for the object (see setStaggering()), the method calls calculateStaggeringIndex(), to get the fitting z-index for the object's current position, and sets it to the object. See also setZIndex().

This method lets the object walk to a target object. When arrived, it lets the target object hear a trigger event, which may cause the execution of a talk item.

This method uses the method approachObject() to walk to the target object. You may use the method addTalkItem() to add a talk item to the target object, which reacts to the given event name.

Controllers primarily use this method.

Parameters

targetObjectName: Provide the name of the target object to which this object has to walk and to tell the event to.
eventName: Provide the name of an event, which will be heard by the target object, when the object arrives. If the target object has a talk item, which uses this event name as a trigger event, then the talk item will be executed. See also addTalkItem().
controllerName: If you provide a controller name, the described functionality of the method is only executed, if the controller is registered to this object. See addController(). If you provide null, the functionality is ever executed.

Call this method to let the object walk near another object.

If the target object is assigned to a node, the position of the node is used as the target position (see setAssignedNode()). If the target object is not assigned to a node, the target position is calculated by the method caclulateApproachPos() of the target object.

If the object is bound to a net, the object walks along the net to the node, which is next to the position. If the object is not bound to a net, the object walks to the position. See also bindToNet() and MacaoNet. See also approachObject().

Parameters

objectName: Provide the name of the target object, to which this object has to walk. The target object needs to be in the same frame as this object.
autoAcceleration: Set this parameter to true, if you want the object to accelerate automatically. Set it to false, if you want to accelerate the object by other method calls. See also setAutoAcceleration().
stopAtEnd: Set this parameter to true, if you want the object to stop, when it reaches the target position. Set this parameter to false, if you want the object to continue walking.
eventType: Provide an event type, if you want the object to send an event to it self, when it reaches the target position. Set the event type to null, if you don't need an event.
params: Provide an array of parameters for the event you defined with the previous parameter. Set this parameter to null, if you don't define an event or the event needs no parameters.


Returns

The method will return false, if the target object is not found or this object is bound to a net and there is no path found between the node next this object and the node next to the position. In this case the object will not start walking. The method returns true, if the object is bound to a net and there is a path found or if the object is not bound to a net.

Call this method to let the object walk to a defined position.

If the object is bound to a net, the object walks along the net to that node, which is next to the position. If the object is not bound to a net, the object walks to the provided position. See also bindToNet() and MacaoNet. See also approachObject().

Parameters

xPos: Provide the x-coordinate of the position in pixels relative to the page.
yPos: Provide the y-coordinate of the position in pixels relative to the page.
autoAcceleration: Set this parameter to true, if you want the object to accelerate automatically. Set it to false, if you want to accelerate the object by other method calls. See also setAutoAcceleration().
stopAtEnd: Set this parameter to true, if you want the object to stop, when it reaches the target position. Set this parameter to false, if you want the object to continue walking.
eventType: Provide an event type, if you want the object to send an event to it self, when it reaches the target position. Set the event type to null, if you don't need an event.
params: Provide an array of parameters for the event you defined with the previous parameter. Set this parameter to null, if you don't define an event or the event needs no parameters.


Returns

The method will return false, if the object is bound to a net and there is no path found between the node next to object and the node next to the position. In this case the object will not start walking. The method returns true, if the object is bound to a net and there is a path found or if the object is not bound to a net.

Use this method to assign the object to a node, which is part of a road element.

This method does the same as setAssignedNode(), but it gets the node for the assignment by the name of the road element and the index of its node.

Parameters

roadName: Provide the name of the road element to which the node belongs to. See MacaoRoad.setName().
nodeIndex: Each road element can have a number of nodes. The nodes are indexed beginning with 0. Provide the index of the node, to which you want to assign the object. If the index is not a valid index of a node, an error message will be displayed.

Call this method to bind the object to a net or unbind it from a net.

An object can only be bound to one net at a time. See also MacaoNet.

Parameters

netType: Provide the name of the net, which is the same as the net type, to bind the object to the net. Provide null, if you want to unbind it from the net.

This method calculates the object's approach position, which is used by other objects to walk to.

By default the method calculates a position, which is in the centre of the objects width and below the bottom of the object. The distance below the object is dependent of the object that wants to approach. If the approaching object is available, the position will be 1/3 of the height of the approaching object below the approached object. If the approaching object is not available, the distance is calculated by the approached object's height.

You may override this method, to calculate another approach position. The following example calculates a position in the centre of the object.

// create object
var house = new MacaoObject("house", "House", 200, 200)
house.setImage("house.gif")

// override method
house.calculateApproachPos = new function(approachingObjectName) {
	
	// create array with coordinates
	return new Array(
		(this.getLeft() + this.getWidth()) / 2,
		(this.getTop() + this.getHeight()) / 2
	)
}

See also setApprochable().

Parameters

approachingObjectName: Provide the name of the object, which wants to approach. The method looks up the object and uses it's height to calculate the approach position. Provide null, if you have no information about an approaching object.


Returns

The method returns an array with two numeric elements. The first element is the x-coordinate of the approach position in pixels, relative to the page. The second element is the y-coordinate.

This method is called internally, to calculate the z-index for stacking.

By default, this method returns the y-coordinate of the bottom edge of the object. You may override this method, if you want another value to be used for stacking. See also setStacking().

Returns

This method returns the z-index, which has to be used for the object's current position. By default, this value is the y-coordinate of the bottom edge of the object.

Call this method to change the direction of the object by an angle.

See also setDirection() and getDirection().

Parameters

angle: Provide the angle to change the direction at the base of PI. The angle can be positive or negative.

Call this method to create a talk item and add it to the object.

This method is provided for convenience, because it creates and adds a talk item in one call. The method returns the talk item, which is created. So you can use the returned item to specify further properties of the talk item. See the description of the class MacaoTalkItem for a detailed description on how to use talk items.

Parameters

itemName: Provide a unique name for the talk item. The name of the talk item is automatically used to handle the text resource of the message (See also MacaoPage.getResource() and MacaoPage.defResource()). This name can also be used as trigger event for other talk items (see next parameter). It is recommended to start the name of the talk item with the name of the MacaoObject, which is using the talk item.
triggerEvents: Provide the name of one or more events, which will cause the execution of this event. You can provide one event as single String. You can provide a number of trigger events as an Array of Strings. See the description of the class MacaoTalkItem for useful trigger events. If you want this talk item to be triggered by keywords (see parameter keywords), you can set this parameter to null.
message: Provide the message, which is to be displayed in the bubble.
The message may contain the placeholder %sender%. This placeholder will be replaced by the title of the object, whose event caused the execution of this talk item. So this object can for example say "Hello title !" to another object. This placeholder currently does not work with inventory items.
The message, which you provide here, is automatically added to the resources and received from the resources. The item name is used as the resource name. See also MacaoPage.getResource().
Set this parameter to null, if you don't want a message to be displayed or if you want the bubble to display HTML or an image. See MacaoTalkItem.setHTML() and MacaoTalkItem.setImage().
keywords: Provide keywords, if you want the talk item to be triggered by the entering of a keyword. See the description of the class MacaoTalkItem for a detailed description how to use keywords. You can provide a single keyword as String. You can provide a list of keywords as a String, separated by commas or as an Array of Strings. Set this parameter to null, if you don't want this talk item to be triggered by keywords.
onceAtTalk: Set this parameter to true, if you want this talk item to be executed only once at a talk. Once it is executed, its name is added to a list of executed talk items. That makes it unavailable for execution until the list is cleared. You can mark another talk item by calling MacaoTalkItem.setClearTalk(), so that it will clear this list. Set this parameter to false, if you don't want to restrict the availability of this talk item.


Returns

Returns the talk item, which was just created and added by the method call.

Call this method to get the anchor's x-position of the object relative to the page.

This method calculates the anchor position of the object. By default that position is in the centre of the object. The anchor is used to walk the object along a net or to a click. For Example, if the object is not bound to a net but has the property approach click activated, and the user clicks on the page, the object will walk to the click position, so that its anchor (centre) is placed on the click position. See also getAnchorYPos().

If you want another position for the anchor of your object, you need to call setAnchorAtBottom() or override the methods getAnchorXPos() and/or getAnchorYPos(). You can use the methods getLeft(), getTop(), getWidth() and getHeight() to calculate your own anchor position. The following example overrides the method getAnchorYPos(), to place the anchor at the bottom of the object.

var car = new MacaoObject("Car", "Car", 200, 200)

car.getAnchorYPos = function() {
	return this.getTop() + this.getHeight()
}

Returns

Returns the x-position anchor of the object relative to the page in pixels.

Call this method to get the anchor's y-position of the object relative to the page.

See also getAnchorXPos() and setAnchorAtBottom().

Returns

Returns the y-position anchor of the object relative to the page in pixels.

Call this method to get the info, if this object is approachable.

See also setApproachable().

Returns

Returns true, if the object is activated as approachable. Otherwise returns false. See setApproachable().

Call this method to get the node, to which the object is assigned.

See also setAssignedNode().

Returns

Returns the node, to which the object is assigned. Returns null, if the object is not assigned to a node.

Call this method to get the phase, which is currently used to display a bunch look.

See addLookBunch() for a description of phases.

Parameters

bunchType: Provide the bunch type, which phase you want to get. This needs to be one of the values BUNCH_TYPE_STAND, BUNCH_TYPE_WALK and BUNCH_TYPE_SAY.


Returns

The method returns the name of the phase, which is currently used to display a look of the bunch type. The method returns an empty string, if no phase is defined.

Call this method to get the direction, to which the object walks.

See also getLookDirection(), setDirection(), setReverseGear() and changeDirection().

Returns

The direction is returned as an array with two elements. The first element contains the x-component of the vector. The second element contains the y-component of the vector. The resulting vector has the length of 1.0.

Call this method to get the direction of the look.

If the reverse gear is not active, this method returns the same direction as the method getDirection(). If the reverse gear is active, this method returns the opposite direction. See also setReverseGear() and addLookBunch().

Returns

The method returns an array with two numeric elements. The first element contains the x-component of the direction. The second element contains the y-component of the direction. The resulting vector of both components has the length of 1.

Call this method to get the maximum velocity of the object.

See also setWalkCharacteristics().

Returns

Returns the maximum velocity of the object in pixels per step.

Call this method to get an array with the names of all objects, which this object is currently meeting.

See also meet(), leave() and isMeetingObject().

Returns

Returns an array that contains the names of the objects, which this object is currently meeting.

Call this method to get the nearest node of the net, to which the object is bound, relative to the objects current position.

To get a node, the object needs to be bound to a net. See also MacaoNet and bindToNet().

This method is used internally, when the object starts to walk along a net. It is used to find the start node of the walk. The object will walk to the nearest node and than along the net to a target node.

Returns

Returns the node of the net, which is nearest to the object's current anchor position. The method returns null, if the object is not bound to a net or the net has no nodes.

Call this method to get the net type of the net, to which the object is bound.

See also MacaoNet.

Returns

Returns the netType of the net, the object is bound to. The method returns null, if the object is not bound to a net. By default the object is not bound to a net.

Call this method to get the name of the sender of the current response talk items.

See hearResponseTalkItems().

Returns

The method returns the name of the sender object. It returns null, if there is no sender object defined.

Call this method to get the response talk items, which are currently to be displayed for this object.

See also hearResponseTalkItems().

Returns

The method returns an array of MacaoTalkItem objects, if there are responses defined. It returns null, if no response talk items are to be displayed.

Call this method to check, if the reverse gear is active.

See also setReverseGear().

Returns

This method returns true, if the reverse gear is active. Else it returns false.

Call this method to get the current velocity of the object.

See also getVelocity().

Returns

Returns the current velocity of the object in pixels per step.

Call this method to send the object a trigger event, which may cause the execution of a valid fitting talk item.

If the object has one or more valid talk items, which are fitting to the trigger event, one of them will be executed. The validity of a talk item may be restricted by game events or by the property onceAtTalk. This method is called internally for every event, which the object receives. See also MacaoTalkItem and hearFreeText().

Parameters

eventName: Provide the name of the event, which is used as trigger event to find a fitting talk item.
senderName: Provide the name of object that sent the event, which caused the execution of the talk item. If the message of the talk item contains the placeholder %sender%, the method uses this parameter to get the sender object's title.

Call this method to send a keyword to the object, which may cause the execution of a valid fitting talk item.

If the object has one or more valid talk items, which are fitting the keyword, one of them will be executed. The validity of a talk item may be restricted by game events or by the property onceAtTalk. This method is called internally to provide the input text, which was entered by the user in a response talk item, which was originated by this object. See also MacaoTalkItem and hearEvent().

You may use this method to trigger the execution of a talk item, even if this free text was not caused by a response talk item.

Parameters

freeText: Provide free text, which will be used to find a talk item with a fitting keyword. If there is no fitting keyword, the text will be split into words to find a fitting keyword. If there is also no fitting keyword found, the provided responseItemName is used as trigger event, to find a fitting talk item by a trigger event.
senderName: Provide the name of the object, which said this text. If the message of the talk item contains the placeholder %sender%, the method uses this parameter to get the sender object's title. Provide null, if the name of the sender object is unknown.
responseItemName: Provide the name of the response talk item, which was used to enter the text. If there is no fitting talk item found for the free text, the name of the response talk item is used as a trigger event to find a fitting talk item to respond. Provide null, if the free text was not caused by a response talk item.

Call this method to test, if this object is currently meeting another object.

See also meet(), leave(), getMeetingObjectNames() and isMeetingObject().

Parameters

objectName: Provide the name of the other object, which you want to test.


Returns

Returns true, if this object currently meets the other object. Otherwise returns false.

Call this method to test, if the object is currently walking.

Returns

Returns true, if the object is currently walking.

Call this method to remove an object from the list of objects, which this object is currently meeting.

See also meet(), getMeetingObjectNames() and isMeetingObject().

Parameters

objectName: Provide the name of the object, which is to be removed from the list.
mutual: Provide true, if you also want this object to be removed from the list of the other object. Provide false or null, if you only want the other object to be removed from the list of this object.

This method is called internally, before the object leaves a node.

This functionally is used for example, to determine, if a traffic light prevents the continuation of the walking. Actually this method forwards the request to the method mayILeave() of the actual node.

You may override this method to change the objects behaviour.

Parameters

actualNode: The call of the method provides the node, at which the object is.
toNode: The call provides the next node, to which the object wants to walk. This may be null, if the object is not walking on the net any longer. You may use this information, if you want to allow the object only to walk to a specific direction.


Returns

Return true, if you allow the object to leave the node. Return false, if you want the object to stay on the node.

Call this method to add an object to the list of objects, which this object is currently meeting.

One object can for example meet another object, when it enters a node, which is assigned to the other object (see setAssignedNode()). You can restrict talk items to send trigger events only to nodes, which the object is currently meeting (see MacaoTalkItem.setBroadcast()). See also leave(), getMeetingObjectNames() and isMeetingObject().

Parameters

objectName: Provide the name of the object, which this object is meeting.
mutual: Provide true, if you also want to register this object to the other object as meeting object. Provide false or null, if you only want to register the other object to this object.

Call this method to move the object giving the new coordinates for the anchor of the object.

While calling moveTo() sets the new left and top coordinates of the object, moveAnchorTo() sets the new anchor position of the object. By default, the anchor position is in the centre of the object. You can set it to the center of the bottom calling setAnchorAtBottom(). See also getAnchorXPos().

Parameters

xPos: Provide the new x-coordinate of the anchor, relative to the page in pixels.
yPos: Provide the new y-coordinate of the anchor, relative to the page in pixels.

Call this method to position the object on a node immediately. You can also set the direction of the object.

This method also sets the provided node as the actual node. This sends the trigger event enteringNode_NodeName and eventually the leavingNode_NodeName to the object. The trigger events may trigger talk items. You can prevent the events by setting the parameter noTriggerEvents. See also MacaoTalkItem.

For positioning the object the object's anchor position is used. See getAnchorXPos(). This method is useful to place an object on a node, after the page is loaded. See also MacaoNet and getNodeByName().

Parameters

node: Provide the node, you want to position the object on.
directionX: Provide a new x-component for the direction of the object. If you don't want to change the direction of the object, set directionX and directionY to null. See also setDirection().
directionY: Provide a new y-component for the direction of the object. If you don't want to change the direction of the object, set directionX and directionY to null.
noTriggerEvents: Set this parameter to true to prevent the trigger events enteringNode_NodeName and leavingNode_NodeName being send. Set this parameter to false to enable the events. See also MacaoTalkItem.

This event handler is called, when the user clicks on another object.

The default implementation of this event handler checks, if the property "approach click" is activated (see setApproachClick(), and initiates the walking of the object to the clicked object.

You may override this event handler to implement another functionality.

Parameters

event: Provide the browser's ui-event, that caused this event.
mouseX: Provide the x-coordinate of the mouse relative to the object.
mouseY: Provide the y-coordinate of the mouse relative to the object.
objectName: Provide the name of the object, which is clicked.

This event handler is called, when the user clicks the window.

The default implementation of this event handler checks, if the property "approach click" is activated (see setApproachClick(), and initiates the walking of the object to the clicked position.

You may override this event handler to implement another functionality.

Parameters

event: The browser's ui-event, which caused this event.
mouseX: Provide the x-coordinate of the mouse relative to the page.
mouseY: Provide the y-coordinate of the mouse relative to the page.
frameName: Provide the name of the frame, in which the event was raised.

This method is called to restore the objects visibility, zoom, position, velocity, direction and walk target for this page, after the page is opened.

These values need to be stored before by the method store().

Call this method to set the anchor to the bottom of the object.

By default the anchor is at the center of the object. See also getAnchorYPos() and moveAnchorTo().

Parameters

activate: Set this parameter to true, to set the anchor to the center of the bottom of the object. Set it to false to set the anchor to the center of the object.

Call this method to set the object as approachable or not approachable.

When an object is set as approachable and the user clicks on the object, other objects which have the property approach click activated (see setApproachClick()) will start walking to the clicked object's approach position. If the object is not set as approachable and the user clicks on the object, the other objects will walk to the position of the click. So the difference is in the target position, to which the objects will walk.

If the object is assigned to the node of a net, the node position is the object's approach position. Otherwise the approach position of an object is calculated by its method calculateApprochPos().

Set this property for foreground objects. Don't set this property for background objects. Because clicking on the background should tell the walking objects: Walk to the click position.

Parameters

approachable: Set this parameter to true, if you want other walking objects to walk to a specified position, when this object is clicked. Set this parameter to false, if you want the other objects walk to the click position.

Call this method to activate or deactivate the behaviour of the object, which tells it to walk to the position where the user clicks.

If the object is bound to a net, the object will walk along the net to that node, which is next to the clicked position. If the object is not bound to a net, the object will walk to the clicked position. See also bindToNet() and MacaoNet.

When the user clicks on a target object, the position to which this object walks depends on the target object's properties and methods. If the target object is not set as approachable (See setApproachable()), this object walks to the clicked position.
If the target object is set as approachable and it is assigned to a node (see setAssignedNode()), this object walks to the position of the node. If the target object is not assigned to a node, the target position is calculated by the target objects method calculateApproachPos().

Parameters

activate: Set this parameter to true to activate the behaviour. Set the parameter to false to deactivate the behavior.

Call this method, in order to assign or de-assign the object to a node.

If the object is assigned to a node and the user clicks on the object, all objects that have the property approach to click (See setApporachClick()) activated and which are bound to the net of the node, will walk to the specified node. When the walking object reaches the node, the object will "hear" the event, which is telling that the walking object meets it (See hearEvent()). It may respond with executing a talk item. See addTalkItem().
If the object, on which the user clicks, is not assigned to a node, the walking object approaches the clicked object. But it is walking to a node near the click coordinates and not to a specific node. The clicked object will hear no event about that the walking object has arrived.

An object can only be assigned to one node at a time. See also getNodeByName().

Parameters

node: Provide the node to which you want to assign the object. Provide null in order to remove the assignment from the object.

Call this method to set the acceleration of the object, for it's automatic acceleration.

To start the automatic acceleration, you have to call the method startAutoAcceleration() or setApproachClick().

Parameters

autoAcceleration: Provide the acceleration in pixels per step. If the auto acceleration is set to 0, the maximum acceleration is used for auto acceleration. By default the auto acceleration is 0.

Use this method to activate or deactivate the automatic storage of the objects dynamic values, before the page is closed.

The values will be restored, when the page is loaded again. See also store() and restore().

Parameters

autoRestore: Set this parameter to true to activate auto storage of the dynamic parameters. Set this parameter to false to deactivate auto storage.

Sets the maximum depth of a bunch type.

Use this method, if you are defining a bunch by adding looks one by one. You don't have to add all looks for a bunch. For example, you can have only three images for a bunch. So you can't call addLookBunch(), because it defines two to the power of n looks. But you can add each look using the method createLook(), providing the right bunch look name. But in this case you have to set the depth of the bunch. The object uses the depth to find a fitting look for a direction. In the case you added three looks, this would be 2, because 2 to the power of 2 is greater equal 3.
If you use addLookBunch(), the depth is set automatically.

Parameters

bunchType: Provide the bunch type, for which you want to define the depth.
depth: Provide the depth of the bunch type.

Call this method to set the current phase for a bunch type.

See addLookBunch() for a description of phases.

Parameters

bunchType: Provide the bunch type, for which the phase is to be set. This has to be one of the values BUNCH_TYPE_STAND, BUNCH_TYPE_WALK and BUNCH_TYPE_SAY.
phase: Provide the name of the phase, which is to be set. Provide null or an empty string, if you don't want a phase to be used.

Call this method to activate and deactivate collision break.

If you activate collision break, the object will stop immediately, when it approaches from behind too near to another object, which also has collision break switched on. The collision break does not work, when the two objects are approaching frontal, because this would cause a dead lock.

Activate collision break for cars. The default value is off.

Parameters

activate: Set this parameter to true, to activate collision break. Set it to false, to deactivate collision break.

Call this method to set the direction, to wich the object walks. This will also switch to the object to a look, which fits the direction.

The parameters are building a vector. When set, the components of the vector are automatically recalculated to build a vector of the length of 1.0.
One of the parameters must not be zero. Otherwise the direction of the object will not be changed.
See also setReverseGear(), getDirection(), getLookDirection() and changeDirection().

Parameters

dX: Provide the x-component of the vector.
dY: Provide the y-component of the vector.

Call this method to temporary disable the approach functionality of the object.

This is useful, when for example a character has to stay sitting on a chair while it tries actions. The actions, which are sent by the sentence controller, will be tried from remote, while the object stays in its place.

Parameters

activate: Provide true to disable the approach functionality. Provide false to permit the approach functionality.

Use this method, to set a look, which has precedence over all bunch looks.

Use the method, if you have added bunch looks to the object, but you temporary want to display a specific look. If you set the preferred look, it will be displayed, even if there are fitting bunch looks. Use this method to set and clear the preferred look. Keep in mind, that you first have to add the look using the method createLook().

If you want to display a specific look, while the object is saying something, you better use the method MacaoTalkItem.setLookName().

Parameters

lookName: Provide the name of the look, which you want to be displayed by the object. Set this parameter to null, if you want to clear the preferred look.

Call this method to start or stop the random execution of talk items, which are added to the object.

The talk items, which are executed randomly, have to be added to the object using the methods addTalkItem() or createTalkItem(). They also must have an equal trigger event. You must provide this event name as parameter. There can only be one random execution of talk items at a time. So when you call this method again to set another event name, the prior random execution will be stopped. Call this method without event name to stop the execution of random talk events. See also MacaoTalkItem.

Parameters

eventName: Provide the event name, which is used as trigger event, to get the random talk items out of the talk items, which are added to this object. If there is more than one valid talk item, which fits to this trigger event, one of the talk items will be selected randomly for execution. Provide null, if you want to stop the random execution of talk items.
baseDuration: Provide the base duration, which is used to calculate the random duration between the executions of the talk items. For the relation between base duration and the resulting random duration see MacaoPage.calculateRandomDuration(). Provide 0 or null, if you call this method to stop the random execution of talk items.
executeNow: Provide true, if you want to execute the first talk item immediately. Provide false, if you want to start with a pause of random duration until the execution of the first talk item.

Call this method, to activate or deactivate the reverse gear.

When the reverse gear is active, the object walks in the opposite direction of its look. But it still only walks in the direction of the connections of a net. So you can't use the reverse gear to walk against a one way. See also getDirection(), getLookDirection() and getReverseGear().

Parameters

activate: Set this parameter to true, to activate the reverse gear. Set it to false to deactivate the reverse gear.

Call this method to activate or deactivate the stacking of the object. Stacking adjusts the objects z-index dependent on its position.

What is Stacking?

When your page shows the objects in a side view rather than in a birds view, it is necessary to adjust their z-index to show their layers in the correct order. A layer with a larger z-index shows the object more on top of the stack of layers. A layer with a lower z-index appears more in the background and may be buried partially or completely by other objects.

Stacking automatically adjusts an object's z-index dependent on its position. By default, it sets the object's z-index to the y-coordinate of the object's bottom edge. So objects, which are more at the bottom of the page, are appearing in front of objects, which are more at the top of the page. When for example a character walks around a table, it appears in front of the table, when the characters feet appear lower then the table-legs. It appears behind the table, when its feet are higher than the table's legs.
Hint: You should build the MacaoNet for the character so, that it walks around the table but not through the table.

All you have to do is to activate the stacking for the objects, which are walking or which can be walked around. Don't activate stacking for background objects like the road grid. By default, the objects z-index is adjusted, when the object is moved. You can force the adjustment by calling adjustStacking(). You can change the calculation of the z-index by override calculateStackingIndex(). See also setZIndex().

Parameters

active: Set this parameter to true to activate stacking. Set it to false to deactivate stacking.

Call this method to preselect the connection, which is to be used at the next node of a net and to start the walking of the object.

How does Steering work?

Steering is a special way to control the walking of an object through a net. Steering means to preselect the connection, which the object will choose at the next node to continue its walking. This preselection works with an index, which can be 0, positive or negative. 0 tells the object to select the most straight ahead connection in the view of the object. An index of -1 means the next connection to the left of the straight-ahead one. An index of 1 means the next right one, and so on. Normally indexes between -2 and 2 are useful.

The index will be maintained across the nodes. For example, if you set the index to -2 and there is only one connection to the left of the most straight ahead connection, the object will use this connection and will change the index to -1. At the following node the index of -1 will cause the object to select one connection to the left, if there is one. If there is such connection, the index will change to 0. Now with an index of 0 the object will walk through the net, ever taking the most straight ahead connection. Of course you can call this method at any time to change the index again.

The call of the method setSteeringIndex() will only initiate the walk to the node after the next node. To get a continuous walking, you have to use or to implement a steering controller. A controller is an object, which is registered as a controller to this object by calling addController(). Every controller will receive the event (= method call) steeredEnteringNode(steeringIndex), when the object is entering the next node. The steering controller has to respond to this call by sending the next setSteeringIndex event, to set the path for the following node. This ping-pong play between the object and its steering controller makes it possible to the steering controller to display a steering wheel, which reflects the current value of the steering index. The class MacaoSteeringController is an implementation of a steering controller, which you can use. Every registered controller will also get the event steeredVelocityChanged(), when the velocity of the object changes.

A steering controller can use the following methods to control the object: Call setSteeringIndex() to adjust the steering index and to start the walking. Call getSteeringIndex() to get the actual steering index. Call stopWalking() to stop the objects walking. See also MacaoNet.

Parameters

steeringIndex: Set the steering index to 0, to let the object choose the most straight ahead connection at the next node. Set an index lower than 0, to let the object choose a more left connection. Set an index greater than 0, to let the object choose a more right connection. When the object passes the next node, the steering index will be automatically adjusted.
autoAcceleration: Set this parameter to true to let the object accelerate automatically. Set this parameter to false to don't initiate the objects acceleration. This parameter does the same as startAutoAcceleration().
stopAtEnd: Set this parameter to true, if you want the object to stop at the node behind the next node. Set this parameter to false, if you want the object to continue walking.
eventType: Set the type of event, which the object has to send itself, when it reaches the node after the next node. Set the parameter to null, if you don't want an event to be sent.
params: Set the parameters of the event you defined in the previous parameter. Set this parameter to null, if you don't define an event or the event needs no parameters.
controllerName: Provide the name of the controller object, which is calling this method. If you provide a name, the method will only execute the described functionality, if the object is registered as a controller to this object. If it is not registered as a controller, the method call will do nothing. See also addController(). Set this parameter to null, if you want the method be executed independent to the registration of a controller.

Call this method to set a special cascading style sheet class, which will be used to display the bubble, when the object talks.

Parameters

cssClassName: Provide the name of the CSS class, if you want a special class to be used to display the bubble. Provide null, if you want the default class to be used. The default value is null.

Call this method to change the velocity of the object.

To accelerate a car, you should better call startAutoAcceleration(). See also getVelocity(), accelerate() and setWalkCharacteristics().

This value is set in pixels per step. But this is only true for the default step duration. If you change the step duration (setMoveInterval()) the value is automatically recalculated where used. When the object is zoomed, the velocity is also recalculated when used. So smaller zoomed objects automatically move slower than larger objects.
The velocity is automatically limited between zero and the maximum velocity defined for the object.

Parameters

velocity: Provide the velocity for the object in pixels per step. A value of zero will stop the object. A velocity unequal to zero will start the object. If the object is bound to a net, the object will follow the paths of the net. If the object is not bound to a net, the object will walk straight ahead.
Negative values are not supported.

Call this method to set the walk characteristics of the object.

For example increase the maximum velocity and the maximum acceleration for larger objects.

Some values are set in pixels per step. But this is only true for the default step duration. If you change the step duration (setMoveInterval()) the values are automatically recalculated where used.

Parameters

maxVelocity: Provide the maximum velocity in pixels per step. The default value is 20. Set this parameter to null, if you don't want to change this value.
maxAcceleration: Provide the maximum acceleration in pixels per step. The default value is 4. Set this parameter to null, if you don't want to change this value.
maxAngularVelocity: Provide the maximum rotation of the object per step. The value should be between 0 and PI. The default value is set to 0.63. The lower this value is, the larger is the turn radius of the object. Set this parameter to null, if you don't want to change this value.
curveBreak: Provide the curve break factor. The default value is 8.0. A curve break factor greater than 0 lets the object decelerate, when it changes its direction. This will reduce the turn radius of the object. Reducing the turn radius is required to better reach a node. Otherwise the object would circle around the target node and could never reach it. It also looks more natural for cars. Set this parameter to null, if you don't want to change this value.

Call this method to set the phases, which are used to animate the object while it is walking.

See addLookBunch() for a description of phases.

Parameters

phases: Provide the names of the phases as a comma separated string. The names of the phases are used as a sequence, one for each step of walking. Put no spaces around the commas. You can provide an empty string between the commas to use a phase with no name. A phase may occur more than once. Repeat the same phase name to extend the duration of the phase's display. Provide null to switch off the animation.

Call this method to start the automatic acceleration of the object.

The object will accelerate, until it reaches its maximum velocity. See also setWalkCharacteristics() and setAutoAcceleration().

This event handler will be called, when this object is registered as a controller of another object and the velocity of the other object changes.

You can implement this event handler, to display the velocity of an object. See also addController(). There is no default implementation of this event handler.

Parameters

velocity: Provide the velocity of the other object in pixels per step. The real distance per step may differ from this value, dependent on the walk interval.

Call this method to stop the walking of the object.

See also walkToPos(), walkToNode(), wanderAround() and MacaoNet.

Parameters

clearTarget: Set this parameter to true, if you want the object to clear its target position and target node, to which it was walking. Set this parameter to false, if you later want to accelerate the object again to the previous target. See also walkToPos() and walkToNode().
controllerName: If you provide a controller name, the stopping is only executed, if the controller is set as a controller of the object (see addController()). Set a controller name, if you call this method from a controller. Set null, if you call this method from elsewhere.

This method is called to store the objects visibility, zoom, position, velocity, direction and walk target, before the page is left.

The values are stored, if the property auto restore is set or if the parameter force is set to true. The method stores the values using the storage manager. See also setAutoRestore(), restore() and the class MacaoPage in the package storageManager.

Parameters

force: Set this parameter to true, if you want the object's properties to be stored, even if the property auto restore is not activated. Set this parameter to false, if you want the properties to be stored only, if the property auto restore is activated.

This method lets a target object hear an event. That event may cause the execution of a talk item.

You may use the method addTalkItem(), to add a talk item to the target object, which reacts to the given event name.

Controllers primarily use this method.

Parameters

targetObjectName: Provide the name of the target object, which will hear the event.
eventName: Provide the name of an event, which will be heard by the target object. If the target object has a talk item, which uses this event name as a trigger event, then the talk item will be executed. See also addTalkItem().
controllerName: If you provide a controller name, the described functionality of the method is only executed, if the controller is registered to this object. See addController(). If you provide null, the functionality is ever executed.

Call this method to start the object walking along a net to a target node.

The object needs to be bound to a net and the target node needs to be part of that net. The start node also needs to be connected to the target node via the net. The start node is the actual node, or the next node from the last walk or the nearest node, if the others are not defined. See also MacaoNet and getNearestNode().

Call stopWalking() to stop the object before reaching the target node. You can also define another walk target before it reaches the target node. See also walkToPos().

Parameters

targetNode: Provide the target node, to which the object has to walk.
autoAcceleration: Set this parameter to true, to start the auto acceleration of the object. The object will accelerate automatically, until it reaches its maximum velocity. Set this parameter to false, if you want to accelerate the object with separate method calls. See also setAutoAcceleration() and accelerate().
stopAtEnd: Set this parameter to true, if you want the object to stop, when it reaches the target node. Set this parameter to false, if you want the object to continue walking.
eventType: Provide an eventType, if you want the object to receive an event when it reaches the target node. Set this parameter to null, if you don't need an event. See also sendEvent().
params: Provide an array with the parameters for the event. Set this parameter to null, if you don't define an event type or your event type needs no parameters.

Call this method to start the object to walk to given position on the page and to turn to a given direction.

If you call this method, the object is walking independent from a net, even if it is bound to a net. See also MacaoNet and bindToNet().

Call stopWalking() to stop the object before it reaches the target position. You can also define another walk target. See also walkToNode().

Parameters

xPos: Provide the target x-position of the object in pixels relative to the page.
yPos: Provide the target y-position of the object in pixels relative to the page.
autoAcceleration: Set this parameter to true, to start the auto acceleration of the object. The object will accelerate automatically, until it reaches its maximum velocity. Set this parameter to false, if you want to accelerate the object with separate method calls. See also setAutoAcceleration() and accelerate().
stopAtEnd: Set this parameter to true, if you want the object to stop, when it reaches the target position. Set this parameter to false, if you want the object to continue walking.
eventType: Provide an eventType, if you want the object to receive an event, when it reaches the target position. Set this parameter to null, if you don't need an event. See also sendEvent().
params: Provide an array with the parameters for the event. Set this parameter to null, if you don't define an event type or your event type needs no parameters.
endDirectionX: Provide the x-component of the direction, to which the object has to turn at the end of the walk. Provide null, if the object doesn't need a specific direction at the end of the walk.
endDirectionY: Provide the y-component of the direction, to which the object has to turn at the end of the walk. Provide null, if the object doesn't need a specific direction at the end of the walk.

Call this method to tell the object to wander around on a net.

The object needs to be bound to a net. See also MacaoNet and bindToNet().

Call stopWalking() to stop the object wander around. You can also stop it wandering around by setting another walk target. See walkToPos() and walkToNode().

Parameters

basePauseDuration: Provide a base duration for a pause between the walks in milliseconds. The object will stop for that duration, when it reaches a target node, before it starts to the next target node. Provide 0, if you don't want the object to have a break. How the actual duration is calculated from the base duration see calculateRandomDuration().
targetNodes: Provide an array of MacaoNode objects, if you want the object to wander between defined target nodes. The nodes will be targeted in random order. Provide null, if you want the object to wander between any nodes of the net, to which the object is bound.