OLPCities/Sprites: Difference between revisions

From OLPC
Jump to navigation Jump to search
No edit summary
 
(33 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].
By definition the sprite has "frames" (vertical frames) and "animations" (horizontal frames). It can have only one frame so we will have 1 "frame" and 1 "animation" that are the same.


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]]


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:

[http://www.dmu.com/olpc/gamelib_sprites.js gamelib_sprites.js ]

If you put it at the same folder, the line would be:
<pre>
<script language="Javascript" src="gamelib_sprites.js"></script>
</pre>

To create an "object" of the Class:

<pre>
someName = new Sp_Sprite();
</pre>

Due to the continuing rendering problems under Linux platforms, add the following statement to your script before creating the sprites:
<pre>
Sp_linuxcompatible=true;
</pre>

==Methods==
<pre>

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)

</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
Retrieved from "http://wiki.laptop.org/mediawiki/index.php?title=OLPCities/Sprites&oldid=209499"