OLPCities/Sprites: Difference between revisions

From OLPC
Jump to navigation Jump to search
No edit summary
 
 
(35 intermediate revisions by 2 users not shown)
Line 1: Line 1:
This library is part of the <b>Gamelib</b>, created by Scott Porter and updated by Brent Silby. Gamelib is available under the terms of the [http://www.gnu.org/copyleft/lgpl.html GNU Library General Public Licence].
Descriptions of methods
</p>


<table>
<tr>
<th>Method</th>
<th NOWRAP>Parameters</th>
<th>Description</th>
</tr>
<tr> <a name="clearCollisionArea"></a>
<td>clearCollisionArea</td>
<td>(none)</td>
<td> Removes the collision area from a sprite. The sprite will register collisions
around its perimeter (the default behaviour). See the <a href="#setCollisionArea">setCollisionArea()</a>
method for details about setting collision areas. </td>
</tr>
<tr> <a name="clearFrameByDirection"></a>
<td>clearFrameByDirection</td>
<td>(none)</td>
<td> Stops sprite from setting its own frame based on its current direction.
See the <a href="#setFrameByDirection">setFrameByDirection()</a> method
for details about this. </td>
</tr>
<tr> <a name="clearRoute"></a>
<td>clearRoute</td>
<td>(none)</td>
<td> This stops sprite from following a route. See <a href="#setRoute">setRoute()</a>
method for details of how to set a route.</td>
</tr>
<tr> <a name="clearRouteLoop"></a>
<td>clearRouteLoop</td>
<td>(none)</td>
<td> This stops the sprite from looping through a route. It will continue
following its current route until the end. See the <a href="#setRoute">setRoute()</a>
method for details about setting a route. </td>
</tr>
<tr> <a name="destroy"></a>
<td>destroy</td>
<td>(none)</td>
<td> This will "destroy" the sprite object. After calling this method, the
sprite will no longer respond to any methods. In actuality, the sprite object
still exists, and is reused the next time a new sprite is generated. The
reason the destroy method does not actually destroy the sprite (IE, remove
all the properties, methods and DOM objects from the document) is to work
around the memory leak in IE6 (and possibly IE5), whereby the browser never
actually frees up any memory allocated when a DOM object is generated, when
that object is destroyed (unless the browser is minimized and maximized
again for some bizarre reason!) </td>
</tr>
<tr> <a name="setCollisionArea"></a>
<td>setCollisionArea</td>
<td>Numeric, Numeric, Numeric, Numeric</td>
<td> Sets the collision area for a sprite. This is a rectangular region within
the sprite which should be used to register collisions. Any collisions outside
this area will be ignored (think of it as a "soft" area outside the collision
area). Basically this means that you can cause sprites to overlap slightly
before a collision will occur which is handy with oddly shaped sprites.
The parameters passed are the distances from the left, right, top and bottom
(in that order) of the sprite for the collision area rectangle. Setting
this will not affect performance. See the <a href="#clearCollisionArea">clearCollisionArea()</a>
method for details about clearing collision areas. </td>
</tr>
<tr> <a name="setCollisionZTest"></a>
<td>setCollisionZTest</td>
<td>Numeric</td>
<td> Sets the maximum distance another sprite can be within in the Z axis
to be able to collide with this sprite (see the <a href="#setZ">setZ</a>
method for details of how to set the Z index). Eg, If this sprite has a
Z index of 10 and you use <span class="jCode">mySprite.setCollisionZTest(5)</span>
then other sprites with a Z index less than 5 or higher than 15 will not
be able to collide with it! This can be a very useful setting and may help
to speed up your code if used correctly since the Z test is performed before
the normal collision test and is very quick. So, if you don't care whether
certain sprites collide, just set this value so collisions will be ignored!
</td>
</tr>
<tr> <a name="setRoute"></a>
<td>setRoute</td>
<td>Boolean, Numeric, Numeric [...] (or Array)</td>
<td> This sets a route for the sprite to follow. This method can be passed
an array OR a list of arguments to specify the route. If an array were used,
it would contain exactly the same elements that would be passed in the list
and so I will describe the list method here.<br>
<br>
The first argument specifies whether the sprite should loop (true means
loop, false means don't) through the route until cleared (using <a href="#clearRoute">clearRoute()</a>).
After the first argument, any number of numeric x,y values can follow this,
which specify the co-ordinates the sprite should visit during the route.
</td>
</tr>
<tr> <a name="setRouteByCommand"></a>
<td>setRouteByCommand</td>
<td>String, Boolean</td>
<td> This programs a sprite with a set of commands, in order to create a complex
route. The first argument is a string containing the commands, separated
by semi-colons. Any white space is ignored. The second argument specifies
whether the sprite should loop (true means loop, false means don't) through
the route until cleared (using <a href="#clearRoute">clearRoute()</a>).
The commands a sprite understands are all of the form of a character, followed
by either one or two arguments, separated by a comma. The commands follow:
<p> <span class="jcode">mX,Y;</span> will move the sprite to position X,Y
on the screen. So <span class="jcode">m100,50;</span> will move the sprite
to position 100,50. </p>
<p> <span class="jcode">aX,Y;</span> will move turn the sprite anticlockwise
by Y degrees per frame for X frames. So <span class="jcode">a20,2;</span>
will move the sprite 2 degrees anticlockwise per frame, for 20 frames.
</p>
<p> <span class="jcode">cX,Y;</span> will move turn the sprite clockwise
by Y degrees per frame for X frames. So <span class="jcode">c20,2;</span>
will move the sprite 2 degrees clockwise per frame, for 20 frames. </p>
<p> <span class="jcode">sX;</span> will set the sprite's speed to X. </p>
<p> <span class="jcode">dX;</span> will set the sprite's direction to X
degrees (0-359). </p>
<p> <span class="jcode">fX;</span> will move the sprite forward at its current
speed for X frames. </p>
<p> <span class="jcode">AX;</span> turn the sprite anticlockwise by X degrees.
</p>
<p> <span class="jcode">CX;</span> turn the sprite clockwise by X degrees.
</p>
To see an example of the setRouteByCommand in action, take a look at <a href="../examples/sprite_example_3.html">Sprite
example 3</a>. </td>
</tr>
<tr> <a name="getHits"></a>
<td>getHits</td>
<td>(none)</td>
<td> This will return an array containing references to all the sprites this
sprite hit during the last gameloop. If it didn't hit anything, this array
will be empty. It's probably more efficient to test for a hit first by checking
the <a href="#hit">.hit</a> property, which always holds the last sprite
hit during the last gameloop. If nothing was hit, .hit will be false. </td>
</tr>
<tr> <a name="hasHit"></a>
<td>hasHit</td>
<td>Object</td>
<td>Use this to test if the sprite has hit another. This superseeds the old
<a href="#hit">hit</a> property. So if this sprite is called fred and you
want to know if it has hit a sprite called bill, just use <span class="jcode"><br>
<br>
if(fred.hasHit(bill)){<br>
&nbsp;//do something<br>
} <br>
<br>
</span> * Note: In most circumstances, the <a href="#setHitEvent">setHitEvent()</a>
method for sprites is probably an easier way of handling collisions - since
the sprites will then call functions as soon as they've hit a target instead
of you having to check! </td>
</tr>
<tr> <a name="makeStatic"></a>
<td>makeStatic</td>
<td>(none)</td>
<td> This makes sprite static. See <a href="#isstatic">isstatic</a> property
</td>
</tr>
<tr> <a name="makeNormal"></a>
<td>makeNormal</td>
<td>(none)</td>
<td> This makes sprite normal </td>
</tr>
<tr> <a name="moveTo"></a>
<td>moveTo</td>
<td>Numeric, Numeric</td>
<td> This moves sprite to position on screen. * Note: this is relative to
the global offsets, unless the sprite is static, and sprite will only appear
if it's property "on" is true or it's static</td>
</tr>
<tr> <a name="setDir"></a>
<td>setDir</td>
<td>Numeric, Numeric</td>
<td> This sets sprite directions. These are added to the sprite positions
every loop by the sprite engine </td>
</tr>
<tr> <a name="setXlimits"></a>
<td>setXlimits</td>
<td>Numeric, Numeric</td>
<td> This limits the sprite x movement. sprite cannot move left further than
the first argument, or right further than second argument minus its width.
If property "<a href="#bounces">bounces</a>" is true then sprite will bounce
when it hits its limit </td>
</tr>
<tr> <a name="setYlimits"></a>
<td>setYlimits</td>
<td>Numeric, Numeric</td>
<td> This limits the sprite y movement. sprite cannot move up further than
the first argument, or down further than second argument minus its height.
If property "<a href="#bounces">bounces</a>" is true then sprite will bounce
when it hits its limit</td>
</tr>
<tr> <a name="setImage"></a>
<td>setImage</td>
<td>String, Numeric, Numeric, Numeric, Numeric</td>
<td>
<p> * Note: DO NOT use this method for normal image .src changes if the
new image will have the same dimensions, instead use the <a href="#swapImage">swapImage()</a>
method, which is MUCH faster for this! </p>
<p> sets the sprite image. Sprite images can be in "canvas animation" format,
this is a method of animating sprites that radically decreases download
times, and incurs almost no CPU overhead. The image will consist of all
the frames of animation for the sprite. frames (see <a href="#setFrame">setFrame()</a>
below) are in x axis, and animations (set <a href="#setAnimation">setAnimation()</a>,
<a href="#setAnimation">setAnimationSpeed()</a>) are in y axis for each
frame. </p>
<p> The arguments to this method are passed in the following order:<br>
img = the image src (eg "mypicture.gif") x = width of the frames (frames
are the different shapes for the sprite) y = height of the frames x2 =
number of frames in image y2 = number of animations per frame </p>
<p> "frames" are in the X axis of a canvas image and "animations" are in
the Y axis. (See example of sprite animation for clarification on this)
</p>
</td>
</tr>
<tr> <a name="swapImage"></a>
<td>swapImage</td>
<td>String</td>
<td> Swaps the sprite's image to a new passed as the argument. You must use
<a href="#setImage">setImage()</a> to set the sprite's initial image. This
method will not resize the image currently in use, and so should only be
used to swap between images of the same size unless you don't mind the scaling.
On the other hand though, it's very fast! </td>
</tr>
<tr> <a name="setFrame"></a>
<td>setFrame</td>
<td>Numeric</td>
<td>This sets the sprite's frame. Each frame can have a number of animations.
Using this resets the animation position for a sprite to the first animation
for the frame (animation position 0). You must set a frame for a sprite
before it will be displayed at all. If a sprite only has one frame, and
no animation, use <a href="#setFrame">setFrame(0)</a> </td>
</tr>
<tr> <a name="setFrameByDirection"></a>
<td>setFrameByDirection</td>
<td>Numeric, Numeric, Numeric [...]</td>
<td> This method is used to specify which frames the sprite should use when
it's heading in different directions. The arguments are in sets of 3, and
are of the form degree,degree,frame, degree,degree,frame etc etc. So if
you wanted a sprite to use frame 0 when it was moving in the direction between
50 and 70 degrees, and frame 1 when it was moving between 71 and 100 degrees,
you could use something like this:<br>
<br>
<span class="jcode"> mySprite.setFrameByDirection(50,70,0,71,100,1); </span><br>
<br>
Easy huh? :-) You can specify up to 360 degrees for a sprite's frames. Sprites
are intelligent enough to translate between degrees and absolute directions
too, so if you set the direction to (1,-1), the sprite knows to use the
frame that covers 45 degrees! </td>
</tr>
<tr>
<td><a name="setFalling"></a>setFalling</td>
<td>Numeric</td>
<td>
<p>You can use this in any way you feel appropriate. Perhaps set to 1 if
the sprite is falling, then 0 if the sprite is not falling. For example:</p>
<p><span class="jcode">mySprite.setFalling(1); </span></p>
</td>
</tr>
<tr>
<td><a name="setFallingSpeed"></a>setFallingSpeed</td>
<td>Numeric</td>
<td>
<p>This is another useful property. You can use this to keep a record of
the sprite's falling speed.</p>
<p><span class="jcode">mySprite.setFallingSpeed(8); </span></p>
<p>Note: At this time there are no falling functions provided in the sprite
module. You will have to handle this yourself. FallingSpeed, setFalling,
setJumpSpeed etc are simply properties that you can use in whatever way
you choose.</p>
</td>
</tr>
<tr>
<td><a name="setFinishPos"></a>setFinishPos</td>
<td>Numeric</td>
<td>
<p>It is often useful to calculate a finish position for a sprite when it
is falling.</p>
<p><span class="jcode">mySprite.setFinishPos(278); </span></p>
</td>
</tr>
<tr>
<td><a name="setJumping"></a>setJumping</td>
<td>&nbsp;</td>
<td>
<p>You can use this in any way you feel appropriate. Perhaps set to 1 if
the sprite is jumping, then 0 if the sprite is not jumping. For example:</p>
<p><span class="jcode">mySprite.setJumping(1); </span></p>
</td>
</tr>
<tr>
<td><a name="setJumpSpeed"></a>setJumpSpeed</td>
<td>&nbsp;</td>
<td>
<p>This is another useful property. You can use this to keep a record of
the sprite's jumping speed. You can change it in your script if you want
to make the sprite's jump speed slow down to 0 to make it look realistic.
Perhaps once it reaches 0 you can setJumping(0), then setFalling(1) and
define a fallingSpeed (see above).</p>
<p><span class="jcode">mySprite.setFallingSpeed(8); </span></p>
</td>
</tr>
<tr> <a name="setAnimation"></a>
<td>setAnimation</td>
<td>Numeric</td>
<td>This sets the sprite's animation stage for the frame</td>
</tr>
<tr> <a name="setAnimationLoop"></a>
<td>setAnimationLoop</td>
<td>Numeric, Numeric</td>
<td>
<p> This sets the animation limits for a frame between the first and second
arguments. This is used when using a canvas image with animations of varying
lengths (for example, 2 stages of animation for one frame, 5 for another
frame etc) </p>
<p> You cannot set the animation limits below 0, or above the maximum amount
of animations specified when canvas was loaded into the sprite using <a href="#setImage">setImage()</a>.
Also, the first argument cannot be greater than the second. The method
checks for these things and adjusts the values to correct limits. This
is useful if you wish to revert to the default animation limits for a
sprite, just set the first argument to 0 and the second to a large number!
</p>
</td>
</tr>
<tr> <a name="setAnimationRepeat"></a>
<td>setAnimationRepeat</td>
<td>Numeric</td>
<td>When this is set to a value above -1, the sprite will animate x times.
A value of -1 means "keep animating indefinately". Once the sprite stops
animating, you can start it animating again by either using this method
again, or using the <a href="#setAnimationSpeed">setAnimationSpeed()</a>
method </td>
</tr>
<tr> <a name="setAnimationSpeed"></a>
<td>setAnimationSpeed</td>
<td>Numeric [,String]</td>
<td>
<p> The first argument sets the sprites animation speed. A value of 0 means
no animation. Any other value means how many frames between animation
changes. So 1 would mean every frame, 2 would mean every other frame etc.
When animating, the sprite keeps the same <a href="#frame">frame</a> but
loops through the animations for that frame (between the default limits
of animation when the <a href="#setImage">setImage()</a> method was called,
or the limits imposed by <a href="#setAnimationLoop">setAnimationLoop()</a>).
0 is the default speed for animations (no animation). </p>
<p> The optional second argument is either "forward" or "backward" (case
insensitive). "forward" means loop through animation stages from top to
bottom of the image you gave the sprite, "backward" loops up from bottom
to top. "forward" is the default setting. If this argument is omitted,
the sprite will continue to animate in its current direction. </p>
</td>
</tr>
<tr>
<td><a name="setShootDelay"></a>setShootDelay</td>
<td>Numeric</td>
<td>A useful property. The gamelib engine doesn't do anything with this. You
can use it in whatever way you wish. A suggestion is to use it in shooting
games. Only let a sprite fire if it's shoot delay is &lt;0. Then set the
sprite's shoot delay to, say, 5 when it shoots. On every loop reduce the
sprite's shoot delay e.g <span class="jcode">mySprite.setShootDelay(mySprite.shootDelay-1)</span>.</td>
</tr>
<tr> <a name="setSpeed"></a>
<td>setSpeed</td>
<td>Numeric</td>
<td>Sets the sprite speed</td>
</tr>
<tr> <a name="getXYdegs"></a>
<td>getXYdegs</td>
<td>(none)</td>
<td> This method will return the sprite's current direction as degrees of
a circle. So if you had set the direction to (1,0) for example, this method
would return 90. The return value is always an integer between 0 and 359.
</td>
</tr>
<tr> <a name="setValue"></a>
<td>setValue</td>
<td>Numeric</td>
<td> This sets the sprite's value. See the <a href="#value">value</a> property
for details. </td>
</tr>
<tr> <a name="setXYdegs"></a>
<td>setXYdegs</td>
<td>Numeric</td>
<td> This sets the sprite direction between 0 and 359 degrees. wraps so that
360 degs=0, 370 degs=10 etc </td>
</tr>
<tr> <a name="setZ"></a>
<td>setZ</td>
<td>Numeric</td>
<td> This sets the sprite z-index. Sprites with higher values move over those
with lower ones </td>
</tr>
<tr> <a name="switchOn"></a>
<td>switchOn</td>
<td>(none)</td>
<td> This switches the sprite on. When a sprite is created, it is off by default,
and so not visible </td>
</tr>
<tr> <a name="switchOff"></a>
<td>switchOff</td>
<td>(none)</td>
<td>This switches the sprite off (default)</td>
</tr>
<tr> <a name="resize"></a>
<td>resize</td>
<td>Numeric, Numeric</td>
<td>
<p>This resizes the sprite to x,y size. Note: this is not the size of the
canvas, but the size of the individual frames/animations in the canvas.
Any collision area settings are retained. Be aware that Netscape 4 has
difficulties resizing images, so although it will work, there will be
some flickering if sprites are being resized constantly.</p>
</td>
</tr>
<tr> <a name="dragType"></a>
<td>dragType</td>
<td>Numeric/String</td>
<td>
<p> Defines how the sprite can be dragged (see <a href="#makeDraggable">makeDraggable()</a>
method which must be used first). The dragType can be one of the following:
</p>
<p> 0 or "normal" =normal dragging (default).<br>
1 or "vertical" =Sprite can only be dragged in the y axis.<br>
2 or "horizontal" =Sprite can only be dragged in the x axis.<br>
</p>
<p> * Note: sprites cannot be dragged outside their x and y limits (xmin,xmax,ymin,ymax)
</p>
</td>
</tr>
<tr> <a name="follow"></a>
<td>follow</td>
<td>Sprite Object, Numeric, Numeric</td>
<td>As with the layer object (see <a href="layerdoc.html">layer docs</a>),
this causes the sprite to follow another sprite or the mouse object, remaining
at distance x,y (where x is the second argument, y the third) from the object
it's following. A sprite can only follow one object at a time, so you MUST
use the <a href="#stopFollowing">stopFollowing()</a> method before you make
a sprite follow something else! </td>
</tr>
<tr> <a name="groupHit"></a>
<td>groupHit</td>
<td>(none)</td>
<td> This will cause a groupHit event for this sprite's group. If the group
this sprite belongs to has a trigger set, and this hit, added to the current
total of hits in the group has reached the group's trigger value, then the
group's trigger event will fire, and the groups hit count will be reset
to zero. (see <a href="#SPgroupClearTrigger">global group functions section</a>
for more details about sprite groups) </td>
</tr>
<tr> <a name="groupSet"></a>
<td>groupSet</td>
<td>Numeric</td>
<td> This will add the sprite to a group. If a group with the ID passed as
the parameter does not exist, it will be created and the hitCount for the
group set to zero. (see <a href="#SPgroupClearTrigger">global group functions
section</a> for more details about sprite groups) </td>
</tr>
<tr> <a name="makeDraggable"></a>
<td>makeDraggable</td>
<td>(none)</td>
<td> Makes the sprite draggable! * Note: You must have the <a href="mousedoc.html">mouse
module</a> linked in to use this </td>
</tr>
<tr> <a name="makeUndraggable"></a>
<td>makeUndraggable</td>
<td>(none)</td>
<td> Stops the sprite from being draggable! * Note: You must have the <a href="mousedoc.html">mouse
module</a> linked in to use this</td>
</tr>
<tr> <a name="setCollide"></a>
<td>setCollide</td>
<td>Boolean</td>
<td> If true, the sprite will register collisions. If this is false, then
the <a href="#setHitEvent">hit events</a> will not work (default=false)</td>
</tr>
<tr> <a name="stopFollowing"></a>
<td>stopFollowing</td>
<td>(none)</td>
<td> Calling this method causes the sprite to stop following another sprite
or the mouse </td>
</tr>
<tr> <a name="useHitEvents"></a>
<td>useHitEvents</td>
<td>Boolean</td>
<td> If true, then sprite will use hit events (and hard hit events) as defined
below. Using these events does not have much impact upon performance, and
can greatly simplify your own code! Don't enable them unless you're actually
going to use them though... </td>
</tr>
<tr> <a name="setHitEvent"></a>
<td>setHitEvent</td>
<td>Sprite Object,String</td>
<td> String argument is function name (usually, but can be any legitimate
javascript statement) to be called when this sprite hits the Sprite Object.
You cannot set a hit event for the mouse since there are already 4 <a href="#onmouseover">mouse
events</a> for that! </td>
</tr>
<tr> <a name="target"></a>
<td>target</td>
<td>Sprite Object, Numeric, Numeric</td>
<td> The sprite will now move toward the Sprite Object, offset from its top
left corner by x,y pixels (passed as the second and third arguments. Whether
it catches a moving sprite or not depends on the speeds of the two sprites.
A sprite can only target one object at a time, so use the <a href="#stopTargetting">stopTargetting()</a>
method before you make a sprite target a new object. </td>
</tr>
<tr> <a name="stopTargetting"></a>
<td>stopTargetting</td>
<td>String</td>
<td> This stops the sprite from targetting another sprite. If the String 'drift'
is passed (ie <span class="jcode">mySprite.stopTargetting('drift')</span>)
then the sprite will continue moving in the direction it was before it stopped
targetting.</td>
</tr>
<tr> <a name="makeHard"></a>
<td>makeHard</td>
<td>(none)</td>
<td> This makes sprite hard (fnaa fnaa :). See <a href="#hard">hard</a> property
for details </td>
</tr>
<tr> <a name="setHardHitEvent"></a>
<td>setHardHitEvent</td>
<td>String</td>
<td> The string argument is a function (usually, but can be any legitimate
javascript statement) to be called when this sprite hits ANY hard sprite.
You must enable hit events for the sprite to use this (see <a href="#useHitEvents">useHitEvents()</a>
method) </td>
</tr>
<tr> <a name="setOpacity"></a>
<td>setOpacity</td>
<td>Numeric</td>
<td>Sets the opacity of the sprite. Range is from 0 to 100, with 0 being invisible.
It's probably not a good idea to use this too much in a game, as it affects
performance when there are a lot of semi-transparent objects flying around
(looks nice though!) This function has no effect with Netscape 4 (browser
does not support transparency.) </td>
</tr>
</table>


By definition a sprite has "frames" (horizontal frames) and "animations" (vertical frames). It can have only one frame so it will have 1 "frame" and 1 "animation" that are the same.
To understand this better take a look at the many sprites at:
*[[OLPCities/Floors|Floors]]
*[[OLPCities/Avatares|Avatares]]
*[[OLPCities/3D objects|3D objects]]
*[[OLPCities/Hard objects|Hard objects]]
*[[OLPCities/Animated objects|Animated objects]]
*[[OLPCities/Links|Links]]


<p class="subheading">
Descriptions of properties
</p>


To use this library (this Class) add one line to the <HEAD> section of the web page of the Lot.
<table>
<tr>
You need to click this link and "save" the library at the same folder of the web page or put it at another folder at the same server and make a reference:
<th>Property</th>
<th NOWRAP>Data Type</th>
<th NOWRAP>Read/Write</th>
<th>Description</th>
</tr>
<tr> <a name="on"></a>
<td>on</td>
<td>Boolean</td>
<td>R</td>
<td> Use this to determine whether the sprite is on/off. When off, it's not
on screen. </td>
</tr>
<tr> <a name="state"></a>
<td>state</td>
<td>Numeric?</td>
<td>R/W</td>
<td>Not currently used by gamelib. Can be used for anything!</td>
</tr>
<tr> <a name="value"></a>
<td>value</td>
<td>Numeric</td>
<td>R</td>
<td> Sprite's value. This has no effect on the sprite engine itself. It was
added as a convenience property. If for instance your player blows up a
sprite called "alien", we can use something like <span class="jcode">score+=alien.value</span>.
Set the value with the <a href="#setValue">setValue</a> method. </td>
</tr>
<tr> <a name="x"></a>
<td>x</td>
<td>Numeric</td>
<td>R</td>
<td>Sprite's X position (see also Sp_xoffset)</td>
</tr>
<tr> <a name="y"></a>
<td>y</td>
<td>Numeric</td>
<td>R</td>
<td>Sprite's Y position (see also Sp_yoffset)</td>
</tr>
<tr> <a name="z"></a>
<td>z</td>
<td>Numeric</td>
<td>R</td>
<td> Sprite's z position. Sprites with higher value will pass over sprites
with lower, also if a sprite collides with more than one other during a
loop, the sprite with the highest z index will be reported in the <a href="#hit">hit</a>
property. </td>
<tr> <a name="xmin"></a>
<td>xmin</td>
<td>Numeric</td>
<td>R</td>
<td> The minumum allowed x position for sprite. Sprite will either stop or
bounce (see <a href="#bounces">bounces</a>) if it hits this limit. </td>
<tr> <a name="ymin"></a>
<td>ymin</td>
<td>Numeric</td>
<td>R</td>
<td> The minimum allowed y position for sprite. Sprite will either stop or
bounce (see <a href="#bounces">bounces</a>) if it hits this limit. </td>
</tr>
<tr> <a name="xmax"></a>
<td>xmax</td>
<td>Numeric</td>
<td>R</td>
<td> The maximum allowed x position for sprite. Sprite will either stop or
bounce (see <a href="#bounces">bounces</a>) if it hits this limit. </td>
</tr>
<tr> <a name="ymax"></a>
<td>ymax</td>
<td>Numeric</td>
<td>R</td>
<td> The maximum allowed y position for sprite. Sprite will either stop or
bounce (see <a href="#bounces">bounces</a>) if it hits this limit. </td>
</tr>
<tr> <a name="bounces"></a>
<td>bounces</td>
<td>Boolean</td>
<td>R/W</td>
<td> If sprite hits boundary this decides whether it bounces or stops. </td>
</tr>
<tr> <a name="width"></a>
<td>width</td>
<td>Numeric</td>
<td>R</td>
<td>The width of sprite</td>
</tr>
<tr> <a name="height"></a>
<td>height</td>
<td>Numeric</td>
<td>R</td>
<td>The height of sprite</td>
</tr>
<tr> <a name="xdir"></a>
<td>xdir</td>
<td>Numeric</td>
<td>R</td>
<td>The direction of sprite in x axis</td>
</tr>
<tr> <a name="ydir"></a>
<td>ydir</td>
<td>Numeric</td>
<td>R</td>
<td>The direction of sprite in y axis</td>
</tr>
<tr> <a name="xydegs"></a>
<td>xydegs</td>
<td>Numeric</td>
<td>R</td>
<td>The current direction of sprite as 0-359 degrees</td>
</tr>
<tr> <a name="speed"></a>
<td>speed</td>
<td>Numeric</td>
<td>R</td>
<td> The speed of sprite. the x and y directions are multiplied by this figure
</td>
</tr>
<tr> <a name="collides"></a>
<td>collides</td>
<td>Boolean</td>
<td>R/W</td>
<td> This decides whether the sprite should check for a collision each loop.
Note: If this sprite collides with more than one other sprite during a loop,
the sprite with the highest z value will be returned in the <a href="#hit">hit</a>
property. You can and should now set this property using <a href="#setCollide">setCollide()</a>
detailed in the method section </td>
</tr>
<tr> <a name="hard"></a>
<td>hard</td>
<td>Boolean</td>
<td>R</td>
<td> If a sprite is hard, other sprites that detect collisions will not be
able to pass through it unless they are moving so quickly that they "jump"
the hard sprite. The other sprite will register a collision, and be stopped
at the point at which it was about to pass through the hard sprite. If the
other sprite is not moving, the hard sprite will push it along. The hard
sprite itself will generally act like any other sprite apart from its hardness.
Hard sprites are ideal as walls/barriers/platforms in a game! </td>
</tr>
<tr> <a name="frame"></a>
<td>frame</td>
<td>Numeric</td>
<td>R</td>
<td> The current frame being used by an animated sprite. Use <a href="#setFrame">setFrame()</a>
to change. </td>
</tr>
<tr> <a name="animpos"></a>
<td>animpos</td>
<td>Numeric</td>
<td>R</td>
<td> The current animation position for a frame. Use <a href="#setAnimation">setAnimation()</a>
to change. </td>
</tr>
<tr> <a name="animdir"></a>
<td>animdir</td>
<td>String</td>
<td>R</td>
<td> The direction of animation, either "forward" or "backward". Use <a href="#setAnimationType">setAnimationType()</a>
to change</td>
</tr>
<tr> <a name="animspd"></a>
<td>animspd</td>
<td>Numeric</td>
<td>R</td>
<td> The number of frames between animation changes. 0 means no animation.
Use <a href="#setAnimationSpeed">setAnimationSpeed()</a> to change</td>
</tr>
<tr> <a name="hit"></a>
<td>hit</td>
<td>Object</td>
<td>R</td>
<td> If not null, the object it holds is the last sprite this sprite has collided
with. <a href="#collides">collides</a> must be set to true for this to work.
* Note: This property is deprecated. Please use the <a href="#hasHit">hasHit()</a>
method or create <a href="#setHitEvent">hit events</a> instead of this,
which can report multiple collisions. </td>
</tr>
<tr>
<td><a name="falling"></a>falling</td>
<td>Numeric</td>
<td>&nbsp;</td>
<td>This is used to signify that the sprite is falling. I usually set to 1
if falling, 0 otherwise.</td>
</tr>
<tr>
<td><a name="fallingSpeed"></a>fallingSpeed</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
<td>This can be used to store a falling speed for a sprite. This is handy
if you want to increase a sprite's speed as it falls to simulate gravity.</td>
</tr>
<tr>
<td><a name="finishPos"></a>finishPos</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
<td>This is the sprite's finish position which you can use to tell it when
to stop falling.</td>
</tr>
<tr> <a name="image"></a>
<td>image</td>
<td>String</td>
<td>R</td>
<td> The image canvas the sprite is using. Its dimensions must be (width*frames)
wide and (height*animations) of the sprite shape. </td>
</tr>
<tr> <a name="isstatic"></a>
<td>isstatic</td>
<td>Boolean</td>
<td>R</td>
<td> Whether sprite is static. If static, sprite does not detect or cause
collisions, does not have speed, dirrection or move relative to global positions.
These are ideally used for screen elements that are not part of the gameplay
(lives left displays, timers, bonus displays, non-moving backgrounds etc).
It can only be moved by <a href="#moveTo">moveTo(x,y)</a> </td>
</tr>
<tr>
<td><a name="jumping"></a>jumping</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
<td>This has the same purpose as falling (see above).</td>
</tr>
<tr>
<td><a name="shootDelay"></a>shootDelay</td>
<td>Numeric</td>
<td>&nbsp;</td>
<td>Contains the sprite's shoot delay. See <a href="#setShootDelay">setShootDelay
</a>for more info.</td>
</tr>
<tr>
<td><a name="jumpSpeed"></a>jumpSpeed</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
<td>This has the same purpose as fallingSpeed (see above). But for jumping
of course :)</td>
</tr>
<tr> <a name="onmouseover"></a>
<td>onmouseover</td>
<td>String</td>
<td>R/W</td>
<td> The string is the function name to be called when the mouse pointer has
moved over the sprite. This CAN include arguments so <span class="jcode">mySprite.onmouseover="dosomething(x,y,z)"</span>
would pass the variables x,y,z to the function dosomething </td>
</tr>
<tr> <a name="onmouseout"></a>
<td>onmouseout</td>
<td>String</td>
<td>R/W</td>
<td> The string is the function name to be called when the mouse pointer has
moved away from the sprite </td>
</tr>
<tr> <a name="onclickdown"></a>
<td>onclickdown</td>
<td>String</td>
<td>R/W</td>
<td> The string is the function name to be called when the mouse button has
been pressed while over the sprite </td>
</tr>
<tr> <a name="onclickup"></a>
<td>onclickup</td>
<td>String</td>
<td>R/W</td>
<td> The string is the function name to be called when the mouse button has
been released while over the sprite </td>
</tr>
<tr> <a name="draggable"></a>
<td>draggable</td>
<td>Boolean</td>
<td>R/W</td>
<td> Whether the sprite is draggable or not. You should now use the new <a href="#makeDraggable">makeDraggable()</a>
and <a href="#makeUndraggable">makeUndraggable()</a> methods rather than
setting this "by hand". See also <a href="#dragType">dragType()</a> method.
Note: sprites cannot be dragged outside their x and y limits (xmin,xmax,ymin,ymax)</td>
</tr>
<tr> <a name="hitevents"></a>
<td>hitevents</td>
<td>Boolean</td>
<td>R</td>
<td> Whether this sprite is using hit events (see <a href="#setHitEvent">setHitEvent()</a>
method </td>
</tr>
<tr> <a name="beingfollowed"></a>
<td>beingfollowed</td>
<td>Boolean</td>
<td>R</td>
<td> True if sprite is being followed by another object (sprite or layer)
</td>
</tr>
<tr> <a name="followedby"></a>
<td>followedby</td>
<td>(array of Objects)</td>
<td>R</td>
<td> Which objects are following this sprite (see <a href="#follow">follow()</a>
method) </td>
</tr>
<tr> <a name="following"></a>
<td>following</td>
<td>Object</td>
<td>R</td>
<td>The sprite this sprite is following</td>
</tr>
<tr> <a name="followingx"></a>
<td>followingx</td>
<td>Numeric</td>
<td>R</td>
<td>The x offset to sprite this sprite is following</td>
</tr>
<tr> <a name="followingy"></a>
<td>followingy</td>
<td>Numeric</td>
<td>R</td>
<td>The y offset to sprite this sprite is following</td>
</tr>
<tr> <a name="opacity"></a>
<td>opacity</td>
<td>Numeric</td>
<td>R</td>
<td> The opacity level of sprite (0-100) Using opacity will obviously impact
performance </td>
</tr>
</table>


[http://www.dmu.com/olpc/gamelib_sprites.js gamelib_sprites.js ]
<p class="subheading">
Descriptions of Global functions for sprite library
</p>


If you put it at the same folder, the line would be:
<table>
<tr>
<pre>
<script language="Javascript" src="gamelib_sprites.js"></script>
<th>Function</th><th NOWRAP>Parameters</th><th>Description</th>
</tr>
</pre>


To create an "object" of the Class:
<tr>
<a name="SPgroupClearTrigger"></a>
<td>Sp_groupClearTrigger</td><td>Numeric</td>
<td>
This will clear the trigger for the group passed as the parameter to this function.
See the <a href="#SPgroupSetTrigger">Sp_groupSetTrigger</a> function for details
about group triggers.
</tr>


<tr>
<pre>
someName = new Sp_Sprite();
<a name="SPgroupGetMembers"></a>
</pre>
<td>Sp_groupGetMembers</td><td>Numeric</td>
<td>
This will return an array of references to all the sprites that belong to the group passed as the
parameter to the function. If there are no members, the array will be empty.
</tr>


Due to the continuing rendering problems under Linux platforms, add the following statement to your script before creating the sprites:
<tr>
<pre>
<a name="SPgroupReset"></a>
Sp_linuxcompatible=true;
<td>Sp_groupReset</td><td>Numeric</td>
<td>
</pre>
This will reset the trigger counter for the group passed as the parameter to this function.
See the <a href="#SPgroupSetTrigger">Sp_groupSetTrigger</a> function for details
about group triggers.
</tr>


==Methods==
<tr>
<pre>
<a name="SPgroupSetTrigger"></a>
<td>Sp_groupSetTrigger</td><td>Numeric, Numeric, String</td>
<td>
This will set a trigger for a group. The parameters to pass to this function are the groupID, then the
number of sprite <a href="#groupHit">groupHits</a> that will cause the group to trigger, and finally
a string containing the function or instructions to execute when the trigger value is reached. When used
properly, groups and group triggers can be very powerful tools. The most obvious use is to create Boss
type sprites which comprise of many sprites all working together. A hit on any one of the sprites will
affect the group, and by using the Sp_groupGetMembers function, you can easily control a whole group of
sprites as one entity if you wish!
</tr>


clearCollisionArea() Removes the collision area from a sprite. See the setCollisionArea().


clearRoute() Stops sprite from following a route. See setRoute().
</table>


clearRouteLoop() Stops the sprite from looping through a route. It will continue following its
<p class="subheading">
current route until the end.
Descriptions of Global properties for sprite library
</p>
destroy() Will "destroy" the sprite object.


setCollisionArea(n,n,n,n) Setsa the collision area for a sprite. The parameters passed are the distances
<table>
from the left, right, top and bottom .
<tr>

<th>Property</th><th NOWRAP>Data Type</th><th NOWRAP>Read/Write<th>Description</th>
setCollisionZTest(n) Sets the maximum distance another sprite can be within in the Z axis to be
</tr>
able to collide with this sprite. See the setZ(n).
<tr>

<a name="SPlinuxcompatible"></a>
setRoute (Boolean,n,n,...) sets a route for the sprite to follow. The first argument specifies whether
<td>Sp_linuxcompatible</td>
the sprite should loop (true means loop, false means don't) through the route.
<td>Boolean</td><td>R/W</td>
After the first argument, any number of numeric x,y values
<td>If this is set to true, linux compatibility mode is enabled for the sprite engine. Setting this
which specify the co-ordinates the sprite should visit during the route.
to true will enable a workaround to a bug in the Mozilla rendering engine (at the time of writing,
the most recent version of Mozilla is 1.1).</td>
getHits() Will return an array containing references to all the sprites this sprite hit
</tr>
during the last gameloop.
<tr>

<a name="SPxoffset"></a>
hasHit(Object) Test if the sprite has hit another.
<td>Sp_xoffset</td><td>Numeric</td><td>R/W</td><td>

(default=0) The origin of the sprites in the x axis. A sprite x position is
moveTo(n,n) Moves sprite to position on screen.
relative to this unless the sprite is <a href="#isstatic">static</a>. This

variable is also the x origin for the mouse object (see <a href="mousedoc.html">mouse docs</a>)
setDir(n,n) Sets sprite directions.
</td>

</tr>
setXlimits(n,n) Limits the sprite x movement.
<tr>

<a name="SPyoffset"></a>
setYlimits(n,n) Limits the sprite y movement.
<td>Sp_yoffset</td><td>Numeric</td><td>R/W</td><td>
(default=0) the origin of the sprites in the y axis. A sprite y position is relative
setImage(String,n,n,n,n) Sets the sprite image. The arguments to this method are passed in the
to this unless the sprite is <a href="#isstatic">static</a>. This variable is also the
following order: the image src (eg "mypicture.gif"); width of each frame;
y origin for the mouse object (see <a href="mousedoc.html">mouse docs</a>)
height of each frame; number of "frames"; number of "animations".
</td>

</tr>
setFrame(n) Sets the sprite's frame (horizontal). Each frame can have a number
<tr>
of animations (vertical). Using this resets to the first animation for
<a name="SPtotalsprites"></a>
the frame (animation position 0). You must set a frame for a sprite before it
<td>Sp_totalsprites</td><td>Numeric</td><td>R</td><td>The number of sprites you've created</td>
will be displayed at all. If a sprite only has one frame/animation,
</tr>
use setFrame(0).
<tr>

<a name="SPspritesonscreen"></a>
setFrameByDirection (n,n,n...) This method is used to specify which frames the sprite should use when it's
<td>Sp_spritesonscreen</td><td>Numeric</td><td>R</td><td>
heading in different directions. The arguments are in sets of 3, and are of
The number of sprites currently on screen. This does not include <a href="#isstatic">static</a> sprites
the form degree,degree,frame, degree,degree,frame etc etc. So if you wanted
</td>
a sprite to use frame 0 when it was moving in the direction between 50 and
</tr>
70 degrees, and frame 1 when it was moving between 71 and 100 degrees, you
</table>
could use something like this:
mySprite.setFrameByDirection(50,70,0,71,100,1);

setAnimation(n) Sets one of the sprite's animations

setAnimationLoop(n,n) Sets the animation limits for a frame between the first and second arguments.
This is used when using a canvas image with animations of varying lengths
(for example, 2 stages of animation for one frame, 5 for another frame etc)
setAnimationRepeat(n) When this is set to a value above -1, the sprite will animate x times.
A value of -1 means "keep animating indefinately".

setAnimationSpeed(n [,String]) The first argument sets the sprites animation speed (number of frames
between animation changes) A value of 0 means
no animation. The optional second argument is either "forward"
or "backward" (case insensitive). 3 is the usual for avatares walking.
2 is faster than 3.

setSpeed(n) Sets the sprite speed.
getXYdegs() This method will return the sprite's current direction as degrees, an
integer between 0 and 359.
setXYdegs(n) Sets the sprite direction between 0 and 359 degrees.

setZ(n) Sets the sprite z-index. Sprites with higher values move over
those with lower ones
switchOn() Switches the sprite on. When a sprite is created, it is off by
default, and so not visible.
switchOff() Switches the sprite off

dragType (n) Defines how the sprite can be dragged (see makeDraggable() method
which must be used first). The dragType can be one of the following:
0 = normal dragging (default).
1 = Sprite can only be dragged in the y axis.
2 = Sprite can only be dragged in the x axis.

follow(Object,n,n) Causes the sprite to follow another sprite or the mouse object, remaining
at distance n,n from the object it's following. A sprite can only follow one
object at a time, so you MUST use the stopFollowing() method before you make
a sprite follow something else! Good to be used for a bullet of
an avatar's gun. At the shoot you liberate it and change it's speed.

makeDraggable() Makes the sprite draggable! * Note: You must have the mouse module
linked in to use this

makeUndraggable() Stops the sprite from being draggable!

setCollide(Boolean) If true, the sprite will register collisions. If this is false, then the
hit events will not work (default=false)

stopFollowing() Causes the sprite to stop following another sprite or the mouse

useHitEvents(Boolean) If true, then sprite will use hit events (and hard hit events) as defined below.

setHitEvent(Object,String) String argument is function name or any legitimate JavaScript statement)
to be called when this sprite hits another.

target (Object,n,n) The sprite will now move toward the Sprite Object, offset from its top left
corner by x,y pixels (passed as the second and third arguments. Whether it
catches a moving sprite or not depends on the speeds of the two sprites.
A sprite can only target one object at a time, so use the stopTargetting()
method before you make a sprite target a new object.
stopTargetting(String) Stops the sprite from targetting another sprite. If the String 'drift' is
passed (ie mySprite.stopTargetting('drift')) then the sprite will continue
moving in the direction it was before it stopped targetting.

makeHard () Makes the sprite "hard" for collisons.

setHardHitEvent(String) The string argument is a function or JavaScript statement to be called when this
sprite hits ANY hard sprite. You must enable hit events for the sprite to use
this (see useHitEvents() method)

</pre>

==Properties==

Read only if not especified differently

<pre>
on Use this to determine whether the sprite is on/off.
When off, it's not on screen.

x Sprite's X position
y Sprite's Y position
z Sprite's z position. Sprites with higher value will pass over sprites with lower.

xmin The minumum allowed x position for sprite.

ymin The minimum allowed y position for sprite.
xmax The maximum allowed x position for sprite.

ymax The maximum allowed y position for sprite.

width The width of sprite

height The height of sprite

xdir The direction of sprite in x axis

ydir The direction of sprite in y axis

xydegs The current direction of sprite as 0-359 degrees

speed The speed of sprite.

hard True if an sprite is hard

frame The current frame being used by an animated sprite.

animpos The current animation position for a frame.
animdir The direction of animation, either "forward" or "backward".

animspd The number of frames between animation changes. 0 means no animation.

onmouseover [=String] Is R/W The string is the function name to be called when the mouse
pointer has moved over the sprite. This CAN include arguments so
mySprite.onmouseover="dosomething(x,y,z)" would pass the variables x,y,z
to the function dosomething

onmouseout [=String} Is R/W. The string is the function name to be called

onclickdown [=String] Is R/W The string is the function name to be called

onclickup [=String] Is R/W The string is the function name to be called
</pre>

<b>***IMPORTANT: To use the last four properties you need to create an object of the Class [[OLPCities/Mouse|Mouse]] </b>
<pre>

bounces [=Boolean] Is R/W The sprite will collide and do not stops, reverting the direction

draggable Whether the sprite is draggable or not.

hitevents Whether this sprite is using hit events (see setHitEvent() method

beingfollowed True if sprite is being followed by another object
following The sprite this sprite is following

followingx The x offset to sprite this sprite is following

followingy The y offset to sprite this sprite is following

</pre>

[[Category:OLPCities_JavaScript_Libraries]]

Latest revision as of 06:51, 2 June 2009

This library is part of the Gamelib, created by Scott Porter and updated by Brent Silby. Gamelib is available under the terms of the GNU Library General Public Licence.


By definition a sprite has "frames" (horizontal frames) and "animations" (vertical frames). It can have only one frame so it will have 1 "frame" and 1 "animation" that are the same. To understand this better take a look at the many sprites at:


To use this library (this Class) add one line to the <HEAD> section of the web page of the Lot.

You need to click this link and "save" the library at the same folder of the web page or put it at another folder at the same server and make a reference:

gamelib_sprites.js

If you put it at the same folder, the line would be:

<script language="Javascript" src="gamelib_sprites.js"></script> 

To create an "object" of the Class:

someName = new Sp_Sprite(); 

Due to the continuing rendering problems under Linux platforms, add the following statement to your script before creating the sprites:

Sp_linuxcompatible=true; 

Methods


clearCollisionArea()         Removes the collision area from a sprite.  See the setCollisionArea().

clearRoute()                 Stops sprite from following a route. See setRoute().

clearRouteLoop()             Stops the sprite from looping through a route. It will continue following its
                             current route until the end.   
 
destroy()                    Will "destroy" the sprite object.   

setCollisionArea(n,n,n,n)    Setsa the collision area for a sprite. The parameters passed are the distances
                             from the left, right, top and bottom .

setCollisionZTest(n)         Sets the maximum  distance another sprite can be within in the Z axis to be
                             able to collide with this sprite. See the setZ(n).  

setRoute (Boolean,n,n,...)    sets a route for the sprite to follow. The first argument specifies whether
                              the sprite should loop (true means loop, false means don't) through the route.
                              After the first argument, any number of numeric x,y values
                              which specify the co-ordinates the sprite should visit during the route.
  
getHits()                     Will return an array containing references to all the sprites this sprite hit
                              during the last gameloop.   

hasHit(Object)                Test if the sprite has hit another.  

moveTo(n,n)                   Moves sprite to position on screen.  

setDir(n,n)                   Sets sprite directions.   

setXlimits(n,n)               Limits the sprite x movement.  

setYlimits(n,n)               Limits the sprite y movement.   
 
setImage(String,n,n,n,n)       Sets the sprite image.  The arguments to this method are passed in the 
                              following order: the image src (eg "mypicture.gif"); width of each frame;  
                              height of each  frame; number of "frames"; number of "animations".  

setFrame(n)                   Sets the sprite's frame (horizontal). Each frame can have a number 
                             of animations (vertical). Using this resets  to the first animation for 
                             the frame (animation position 0). You must set a frame for a sprite before it
                             will be displayed at all. If a sprite only has one frame/animation,
                             use setFrame(0).  

setFrameByDirection (n,n,n...) This method is used to specify which frames the sprite should use when it's
                               heading in different directions. The arguments are in sets of 3, and are of
                               the form degree,degree,frame, degree,degree,frame etc etc. So if you wanted 
                               a sprite to use frame 0 when it was moving in the direction between 50 and
                               70 degrees, and frame 1 when it was moving between 71 and 100 degrees, you
                               could use something like this:
                                        mySprite.setFrameByDirection(50,70,0,71,100,1); 

setAnimation(n)                Sets one of the sprite's animations  

setAnimationLoop(n,n)         Sets the animation limits for a frame between the first and second arguments.
                              This is used when using a canvas image with animations of varying lengths 
                              (for example, 2 stages of animation for one frame, 5 for another frame etc) 
  
setAnimationRepeat(n)         When this is set to a value above -1, the sprite will animate x times. 
                              A value of -1 means "keep animating indefinately".  

setAnimationSpeed(n [,String]) The first argument sets the sprites animation  speed (number of frames
                               between animation changes) A value of 0 means
                               no animation.  The optional second argument is either "forward" 
                               or "backward" (case insensitive). 3 is the usual for avatares walking.
                               2 is faster than 3. 

setSpeed(n)                  Sets the sprite speed.
 
getXYdegs()                  This method will return the sprite's current direction as degrees, an
                             integer between 0 and 359.   
 
setXYdegs(n)                  Sets the sprite direction between 0 and 359 degrees.  

setZ(n)                       Sets the sprite z-index. Sprites with higher values move over 
                             those with lower ones 
 
switchOn()                   Switches the sprite on. When a sprite is created, it is off by 
                             default, and so not visible.
  
switchOff()                  Switches the sprite off  

dragType (n)                Defines how the sprite can be dragged (see makeDraggable() method 
                               which must be used first). The dragType can be one of the following: 
                                   0   = normal dragging (default).
                                   1   = Sprite can only be dragged in the y axis.
                                   2  = Sprite can only be dragged in the x axis.

  
follow(Object,n,n)         Causes the sprite to follow another sprite or the mouse object, remaining 
                            at distance n,n   from the object it's following. A sprite can only follow one
                            object at a time, so you MUST use the stopFollowing() method before you make 
                            a sprite follow something else!  Good to be used for a bullet of 
                             an avatar's gun. At the shoot you liberate it and change it's speed.

makeDraggable()            Makes the sprite draggable! * Note: You must have the mouse module 
                            linked in to use this  

makeUndraggable()          Stops the sprite from being draggable!  

setCollide(Boolean)         If true, the sprite will register collisions. If this is false, then the 
                            hit events will not work (default=false) 

stopFollowing()            Causes the sprite to stop following another sprite or the mouse  

useHitEvents(Boolean)      If true, then sprite will use hit events (and hard hit events) as defined below.   

setHitEvent(Object,String)  String argument is function name or any legitimate JavaScript statement) 
                            to be called when this sprite hits another. 

 target (Object,n,n)        The sprite will now move toward the Sprite Object, offset from its top left 
                          corner by x,y pixels (passed as the second and third arguments. Whether it 
                          catches a moving sprite or not depends on the speeds of the two sprites. 
                          A sprite can only target one object at a time, so use the stopTargetting() 
                          method before you make a sprite target a new object.
  
stopTargetting(String)     Stops the sprite from targetting another sprite. If the String 'drift' is
                            passed (ie mySprite.stopTargetting('drift')) then the sprite will continue 
                            moving in the direction it was before it stopped targetting. 

makeHard ()               Makes the sprite "hard" for collisons.

  
setHardHitEvent(String)  The string argument is a function or JavaScript statement  to be called when this
                         sprite hits ANY hard sprite. You must enable hit events for the sprite to use 
                         this (see useHitEvents() method)  

 

Properties

Read only if not especified differently

on                        Use this to determine whether the sprite is on/off. 
                          When off, it's not on screen.  

x                         Sprite's X position  
 
y                         Sprite's Y position
  
z                         Sprite's z position. Sprites with higher value will pass over sprites with                      lower.  

xmin                      The minumum allowed x position for sprite. 

 
ymin                       The minimum allowed y position for sprite.  
 
xmax                       The maximum allowed x position for sprite.  

ymax                      The maximum allowed y position for sprite.     

width                     The width of sprite 

height                    The height of sprite 

xdir                      The direction of sprite in x axis 

ydir                       The direction of sprite in y axis 

xydegs                     The current direction of sprite as 0-359 degrees 

speed                      The speed of sprite.  

  
hard                       True if an sprite is hard  

frame                      The current frame being used by an animated sprite.  

animpos                     The current animation position for a frame. 
 
animdir                     The direction of animation, either "forward" or "backward".  

animspd                     The number of frames between animation changes. 0 means no animation. 

   
onmouseover [=String]        Is  R/W    The string is the function name to be called when the mouse
                              pointer has moved over the sprite. This CAN include arguments so
                              mySprite.onmouseover="dosomething(x,y,z)" would pass the variables x,y,z 
                              to the function dosomething  

onmouseout [=String}          Is R/W.  The string is the function name to be called   

onclickdown [=String]         Is R/W  The string is the function name to be called  

onclickup [=String]            Is  R/W The string is the function name to be called

***IMPORTANT: To use the last four properties you need to create an object of the Class Mouse

 

bounces [=Boolean]             Is R/W The sprite will collide and do not stops, reverting the direction

draggable                      Whether the sprite is draggable or not.  

hitevents                       Whether this sprite is using hit events (see setHitEvent() method  

beingfollowed                   True if sprite is being followed by another object    
 
following                      The sprite this sprite is following 

followingx                         The x offset to sprite this sprite is following 

followingy                          The y offset to sprite this sprite is following