PDG engine v0.9.5
 All Classes Namespaces Functions Variables Groups Pages
Public Member Functions | List of all members
TileLayer Class Reference

efficiently handles large tile datasets, useful for backgrounds, terrains, etc... More...

Inheritance diagram for TileLayer:
Inheritance graph
[legend]
Collaboration diagram for TileLayer:
Collaboration graph
[legend]

Public Member Functions

number checkCollision (Sprite movingSprite, uint alphaThreshold=128, boolean shortCircuit=true)
 see if a sprite has collided with tiles in a layer
 
 defineTileSet (int tileWidth, int tileHeight, Image tiles, boolean hasTransparency=true, boolean flipTiles=false)
 define image and dimensions for the tiles used by this layer
 
MemBlock getMapData (int mapWidth=0, int mapHeight=0, int srcX, int srcY)
 
Image getTileSetImage ()
 get the Image currently being used as a tile set
 
Point getTileSize ()
 get size of a tile in the image
 
object getTileTypeAndFacingAt (int x, int y)
 get the tile type and the facing/flipped state of the tile
 
number getTileTypeAt (int x, int y)
 get the tile type at a particular spot on the map
 
Rect getWorldBounds ()
 get the size in layer coordinates of the world map
 
Rect getWorldSize ()
 get the number of tiles in the map
 
 loadMapData (BinaryString data, int mapWidth=0, int mapHeight=0, int dstX, int dstY)
 
 loadMapData (MemBlock data, int mapWidth=0, int mapHeight=0, int dstX, int dstY)
 
 setTileTypeAt (int x, int y, uint t, uint facing=facing_Ignore)
 sets the type of tile at a given location on the map
 
 setWorldSize (int width, int height, boolean repeatingX=false, boolean repeatingY=false)
 sets the number of tiles in the world map
 
- Public Member Functions inherited from SpriteLayer
 addSprite (Sprite newSprite)
 add an existing sprite to the layer
 
Sprite createSprite ()
 create a sprite that belongs to this layer
 
Sprite createSpriteFromSCML (string inSCML, string inEntityName=null)
 create a single sprite from SCML data
 
Sprite createSpriteFromSCMLEntity (string inEntityName)
 create a sprite from SCML data that was previously loaded
 
Sprite createSpriteFromSCMLFile (string inFileName, string inEntityName=null)
 create a sprite from an SCML data file
 
 deserialize (Deserializer deserializer)
 deserialize a sprite layer
 
 disableCollisions ()
 stop checking for collisions between objects in this layer
 
 disableCollisionsWithLayer (SpriteLayer otherLayer)
 remove layer from list of layers that do collisions between layers
 
 enableCollisions ()
 allow collision checking for sprites in this layer
 
 enableCollisionsWithLayer (SpriteLayer otherLayer)
 start collision checking with sprites in another layer
 
 fadeIn (int msDuration, int easing=linearTween)
 fade entire layer to full opacity over time
 
 fadeOut (int msDuration, int easing=linearTween)
 fade out the entire layer to full transparency over time
 
Sprite findSprite (int id)
 find a sprite in this layer by user assigned id
 
number getMyClassTag ()
 returns class tag for SpriteLayer, used for serialization
 
Sprite getNthSprite (int index)
 get a sprite by z-order
 
Point getOrigin ()
 get the point in the layer that is drawn at 0,0 in the port
 
uint getSerializedSize (Serializer serializer)
 get the bytes needed to serialize the layer
 
CpSpace getSpace ()
 get the Chipmunk Physics CpSpace for the layer
 
Port getSpritePort ()
 get the Port the layer renders into
 
int getSpriteZOrder (Sprite sprite)
 get the z-order of a sprite in this layer
 
number getZoom ()
 get the current zoom factor
 
int getZOrder ()
 get the z-order of this layer compared to all others
 
boolean hasSprite (Sprite sprite)
 see if a particular sprite belongs to this layer
 
 hide ()
 stop rendering this layer.
 
boolean isHidden ()
 true if layer is hidden, false if it is visible
 
boolean isSpriteBehind (Sprite sprite, Sprite otherSprite)
 returns true if sprite will be drawn before otherSprite
 
Offset layerToPortOffset (Offset o)
 adjust the offset to account for layer transformations
 
Point layerToPortPoint (Point p)
 translate the point to account for layer transformations
 
Quad layerToPortQuad (Quad q)
 translate the Quad to account for layer transformations
 
RotatedRect layerToPortRect (Rect r)
 translate the rectangle (or RotatedRect) to account for layer transformations
 
Vector layerToPortVector (Vector v)
 translate the point to account for layer transformations
 
 moveBehind (SpriteLayer layer)
 change the z-order of this layer to draw it before the given layer
 
 moveInFrontOf (SpriteLayer layer)
 change the z-order of this layer to draw it after the given layer
 
 moveToBack ()
 move this layer behind all other layers
 
 moveToFront ()
 move this layer in front of all other layers
 
 moveWith (SpriteLayer layer, number moveRatio=1.0, number zoomRatio=1.0)
 link this layer to follow another layer's movements
 
IEventHandler on (int eventCode, function func)
 set event handler for all different sprite and spritelayer events
 
IEventHandler onAnimationComplete (function func)
 set event handler for layer animation complete events
 
IEventHandler onAnimationEnd (function func)
 set event handler for sprite animation end events
 
IEventHandler onAnimationLoop (function func)
 set event handler for sprite animation loop events
 
IEventHandler onAnimationStart (function func)
 set event handler for layer animation complete events
 
IEventHandler onCollideSprite (function func)
 set event handler for sprite-to-sprite collision events
 
IEventHandler onCollideWall (function func)
 set event handler for sprite-wall collision events
 
IEventHandler onDrawPortComplete (function func)
 set event handler for rendering complete events
 
IEventHandler onErasePort (function func)
 set event handler for rendering starting events
 
IEventHandler onExitLayer (function func)
 set event handler for sprite out of bounds event
 
IEventHandler onFadeComplete (function func)
 set event handler for sprite fade event
 
IEventHandler onFadeInComplete (function func)
 set event handler for sprite fade in event
 
IEventHandler onFadeOutComplete (function func)
 set event handler for sprite fade out event
 
IEventHandler onLayerFadeInComplete (function func)
 set event handler for layer fade in event
 
IEventHandler onLayerFadeOutComplete (function func)
 set event handler for layer fade out event
 
IEventHandler onMouseClick (function func)
 set event handler for tap or mouse click in a sprite
 
IEventHandler onMouseDown (function func)
 set event handler for finger down or mouse down in a sprite
 
IEventHandler onMouseEnter (function func)
 set event handler for mouse pointer over a sprite
 
IEventHandler onMouseLeave (function func)
 set event handler for mouse pointer leaving a sprite it was over
 
IEventHandler onMouseUp (function func)
 set event handler for finger up or mouse up in a sprite
 
IEventHandler onOffscreen (function func)
 set event handler for sprite offscreen event
 
IEventHandler onOnscreen (function func)
 set event handler for sprite onscreen event
 
IEventHandler onPostAnimateLayer (function func)
 set event handler for layer animation finished events
 
IEventHandler onPostDrawLayer (function func)
 set event handler for layer rendering complete events
 
IEventHandler onPreAnimateLayer (function func)
 set event handler for layer animation start events
 
IEventHandler onPreDrawLayer (function func)
 set event handler for layer rendering start events
 
IEventHandler onZoomComplete (function func)
 set event handler for this layer finishing zoom animation
 
Offset portToLayerOffset (Offset o)
 adjust the offset to account for layer transformations
 
Point portToLayerPoint (Point p)
 adjust the point to account for layer transformations
 
Quad portToLayerQuad (Quad q)
 adjust the quad to account for layer transformations
 
RotatedRect portToLayerRect (Rect r)
 adjust the rectangle to account for layer transformations
 
Vector portToLayerVector (Vector v)
 adjust the vector to account for layer transformations
 
 removeAllSprites ()
 remove all sprites in the layer
 
 removeSprite (Sprite oldSprite)
 remove a particular sprite from the layer
 
 serialize (Serializer serializer)
 serialize the sprite layer and all the sprites in it
 
 setAutoCenter (boolean autoCenter=true)
 keep the center of the layer at the center of the port
 
 setDamping (number damping)
 set the overall resistance to motion over time (Chipmunk Physics Only)
 
 setFixedMoveAxis (boolean fixedAxis=true)
 make movement of the layer relative to the port axis
 
 setGravity (number gravity, boolean keepItDownward=true)
 set the force of gravity pulling everything downward (Chipmunk Physics Only)
 
 setKeepGravityDownward (boolean keepItDownward=true)
 keep gravity relative to the port when the layer is rotated (Chipmunk Physics Only)
 
 setOrigin (Point origin)
 set the point in the layer that is drawn at 0,0 in the port
 
SpriteLayer setSerializationFlags (uint flags)
 set the mode for sprite layer serialization
 
 setSpritePort (Port port)
 set the port this layer is rendered into
 
 setStaticLayer (boolean isStatic=true)
 make objects in this layer not subject to physics forces (Chipmunk Physics Only)
 
 setUseChipmunkPhysics (boolean useIt=true)
 enable or disable use of Chipmunk Physics for a particular layer
 
 setZoom (number zoomLevel)
 immediately set the zoom level for this layer
 
 show ()
 start rendering this layer if it was previously hidden
 
 startAnimations ()
 restart doing animation calculations for this layer if they were stopped
 
 stopAnimations ()
 stop doing animation calculations for this layer
 
 zoom (number deltaZoomLevel, int msDuration, int easing=easeInOutQuad, Rect keepInRect=Rect(0, 0), Point centerOn=Point(0, 0))
 animated zoom by a particular factor over time
 
 zoomTo (number zoomLevel, int msDuration, int easing=easeInOutQuad, Rect keepInRect=Rect(0, 0), Point centerOn=Point(0, 0))
 animated zoom to a particular zoom level over time
 
- Public Member Functions inherited from Animated
 accelerate (number deltaSpeed, int msDuration=duration_Instantaneous, int easing=linearTween)
 change the object's speed over time
 
 accelerateTo (number speed, int msDuration=duration_Instantaneous, int easing=linearTween)
 change the object's speed to a particular value over time
 
 addAnimationHelper (IAnimationHelper helper)
 setup a helper to handle custom animation
 
boolean animate (int msElapsed)
 animate based on the passage of time
 
 applyForce (Vector force, int msDuration=duration_Instantaneous)
 apply a force to the object over time
 
 applyTorque (number forceSpin, int msDuration=duration_Instantaneous)
 apply torque to the object over time
 
 changeCenter (Offset offset, int msDuration=duration_Instantaneous, int easing=easeInOutQuad)
 shift the center point of the object over time
 
 changeCenterTo (Offset offset, int msDuration=duration_Instantaneous, int easing=easeInOutQuad)
 shift the center point of the object to a particular offset from true center over time
 
 clearAnimationHelpers ()
 remove all previously added animation helpers
 
Rect getBoundingBox ()
 get the rectangle that completely encloses the object
 
Offset getCenterOffset ()
 get the current offset of the center relative to the true center point
 
number getHeight ()
 get height of the object
 
Point getLocation ()
 get the position of the object
 
number getMass ()
 get the mass of the object
 
number getMoveFriction ()
 get the amount of friction for movement
 
number getMovementDirectionInRadians ()
 get the direction the object is moving
 
RotatedRect getRotatedBounds ()
 get the bounds with rotation
 
number getRotation ()
 get how much the object is rotated
 
number getSizeFriction ()
 get the friction applied to size changes (growing or shrinking)
 
number getSpeed ()
 get how fast the object is moving in pixels/sec
 
number getSpin ()
 get how fast the object is spinning in radians per second
 
number getSpinFriction ()
 get the friction applied toward spinning
 
Vector getVelocity ()
 get the vector that expresses magnitude and direction of the object's movement in pixels/sec
 
number getWidth ()
 get the width of the object
 
 grow (number factor, int msDuration=duration_Instantaneous, int easing=easeInOutQuad)
 change size of the object by a factor over time
 
 move (Offset delta, int msDuration=duration_Instantaneous, int easing=easeInOutQuad)
 move the object by a certain amount over time
 
 moveTo (Point where, int msDuration=duration_Instantaneous, int easing=easeInOutQuad)
 move the object to a particular location over time
 
 removeAnimationHelper (IAnimationHelper helper)
 remove a specific animation helper
 
 resize (number deltaWidth, number deltaHeight, int msDuration=duration_Instantaneous, int easing=easeInOutQuad)
 change the size of an object by a given amount over time
 
 resizeTo (number width, number height, int msDuration=duration_Instantaneous, int easing=easeInOutQuad)
 resize the object to a specific size over time
 
 rotate (number radians, int msDuration=duration_Instantaneous, int easing=easeInOutQuad)
 rotate the object by a specific amount over time
 
 rotateTo (number radiansRotation, int msDuration=duration_Instantaneous, int easing=easeInOutQuad)
 rotate the object to face a particular direction over time
 
Animated setCenterOffset (Offset inCenterOffset)
 set the offset of the center point relative to the true center
 
Animated setFriction (number frictionCoefficient)
 set friction for movement, rotation and resizing all at once
 
Animated setHeight (number inHeight)
 set the object's height
 
Animated setLocation (Point inLocation)
 place the object at a particular location
 
Animated setMass (number inMass)
 set the object's mass, used when forces are applied
 
Animated setMoveFriction (number inMoveFriction)
 set the object's friction for movement
 
Animated setRotation (number inRotation)
 set the direction the object is facing in radians
 
Animated setSize (number width, number height)
 set the size of the object
 
Animated setSizeFriction (number inSizeFriction)
 set the friction applied for object resizing
 
Animated setSpeed (number inSpeed)
 set the speed the object is moving in its current direction of motion
 
Animated setSpin (number inSpin)
 set the rate at which the object is spinning, in radians/sec
 
Animated setSpinFriction (number inSpinFriction)
 set the friction the object faces for spinning
 
Animated setVelocity (Vector deltaPerSec)
 set the speed and direction the object is moving
 
Animated setVelocity (number deltaXPerSec, number deltaYPerSec)
 set the speed and direction the object is moving
 
Animated setVelocityInRadians (number speed, number direction)
 set the speed and direction the object is moving
 
Animated setWidth (number inWidth)
 set the width of the object
 
 startGrowing (number amountPerSecond)
 set the growth rate of the object in pixels/sec
 
 startStretching (number widthPerSecond, number heightPerSecond)
 set the growth rate of the object in pixels/sec, with varied rates for width and height
 
 stopAllForces ()
 remove all forces that were acting on the object (except friction)
 
 stopGrowing ()
 stop any size change
 
 stopMoving ()
 stop any movement the object was doing (except spinning)
 
 stopSpinning ()
 stop any spinning the object was doing
 
 stopStretching ()
 stop any stretching the object was doing
 
 stretch (number widthFactor, number heightFactor, int msDuration=duration_Instantaneous, int easing=easeInOutQuad)
 change the dimensions of the object over time
 
Animated wait (int msDuration)
 wait before beginning the next animation call that operates over time
 
- Public Member Functions inherited from EventEmitter
 addHandler (IEventHandler inHandler, int inEventType=all_events)
 add a new handler for some event type, or for all events if no type specified.
 
 blockEvent (int inEventType)
 temporarily ignore all events of a particular type.
 
 clear ()
 remove all handlers
 
 removeHandler (IEventHandler inHandler, int inEventType=all_events)
 remove a handler for some event type, or for all events (see note) if no type specified.
 
 unblockEvent (int inEventType)
 stop ignoring events of a particular type
 

Additional Inherited Members

Detailed Description

efficiently handles large tile datasets, useful for backgrounds, terrains, etc...

Note
API Stability: 2 - Unstable. The API is in the process of settling, but has not yet had sufficient real-world testing to be considered stable. Backwards-compatibility will be maintained if reasonable.

Capabilities

Each TileLayer has a tile set, a set of equal size tiles taken from a single image. There can be at most 256 tiles in an image.

Tile sets can contain transparency, either through a transparent color or via an alpha channel. If a tile set does not contain transparency, then the entire tile world will be filled in solid, there is no way to leave out a tile. In tile sets with transparency, tile type 0 is considered empty, even if the there is no transparency in the actual image.

Tile sets can support tile rotation (facing) or tile flipping (vertical, horizontal, or both). You cannot use both rotation and flipping in the same layer.

Warning
While individual tiles can be rotated, the TileLayer itself cannot. This is a departure from the expected capabilities of SpriteLayers in general, and will be addressed in a future release.

Getting the Results you Want

For truly impressive maps, you will rarely use just a single TileLayer. Because TileLayers are highly optimized for large areas of transparent/empty tiles, you can use a number of linked TileLayers that each focus on different details: water, terrain, ground cover, flowers and shrubs, trees, etc...

You can intersperse regular SpriteLayers in between TileLayers to provided animated effects to make your characters move at the right layer (underneath the tree-tops, for example).

Be sure to link together all your layers using SpriteLayer.moveWith().

See Also
defineTileSet
Image.setTransparentColor
SpriteLayer.moveWith

Member Function Documentation

checkCollision ( Sprite  movingSprite,
uint  alphaThreshold = 128,
boolean  shortCircuit = true 
)

see if a sprite has collided with tiles in a layer

defineTileSet ( int  tileWidth,
int  tileHeight,
Image  tiles,
boolean  hasTransparency = true,
boolean  flipTiles = false 
)

define image and dimensions for the tiles used by this layer

Each TileLayer has a set of equal size tiles taken from a single image. The tileWidth and tileHeight specify the size of each individual tile in the image, and the image should divide evenly into tiles with no left-over space. There can be at most 256 tiles in an image.

Tile sets can contain transparency, either through a transparent color or via an alpha channel (See Image for more details on transparency).

Tile sets can support tile rotation (facing) or tile flipping (vertical, horizontal, or both). You cannot use both rotation and flipping in the same layer.

To support rotation, you must have a maximum of 64 tiles in your tile set. Typically the tiles would be arranged in an 8x8 grid, with the top left corner tile being considered tile 0 and then counting left to right, top to bottom.

To support flipping in both directions, your tile set should be laid out just like for rotation, 64 tiles in an 8x8 grid. For horizontal flipping only, you should have 128 tiles in an 8x16 grid, and for vertical flipping only you should have 128 tile in a 16x8 grid. For all kinds of flipping you must pass true for the flipTiles parameter when you call defineTileSet().

MemBlock getMapData ( int  mapWidth = 0,
int  mapHeight = 0,
int  srcX,
int  srcY 
)
getTileSetImage ( )

get the Image currently being used as a tile set

getTileSize ( )

get size of a tile in the image

Returns
Point with x (width) and y (height) values
getTileTypeAndFacingAt ( int  x,
int  y 
)

get the tile type and the facing/flipped state of the tile

Parameters
xcomponent of x,y coordinates on the map
ycomponent of x,y coordinates on the map
Returns
a JavaScript object with tileType and facing. Unlike getTileTypeAt(), this separates the facing/flipping information from the raw tile type, so the tile type is the actual index into your tile set.
> console.log(myTileLayer.getTileTypeAndFacingAt(0,0);
{ tileType: 61, facing: 128 }
See Also
setTileTypeAt
getTileTypeAt
getTileTypeAt ( int  x,
int  y 
)

get the tile type at a particular spot on the map

Parameters
xcomponent of x,y coordinates on the map
ycomponent of x,y coordinates on the map
Returns
the tile type. This is the raw data as stored in the TileLayer, so it includes rotation/flipping information in the high bits. It can only be used directly as the index into your tile set on TileLayers that aren't using tile rotation or flipping.
See Also
getTileTypeAndFacingAt
setTileTypeAt
getWorldBounds ( )

get the size in layer coordinates of the world map

Returns
the layer coordinates of the boundaries of the world map
Warning
this is not necessarily the pixel location for drawing, since it doesn't account for layer movement, rotation or zoom. You need to call layerToPortRect() on this to get pixel drawing coordinates.
getWorldSize ( )

get the number of tiles in the map

Returns
a rectangle with the dimensions of the world map in number of tiles. If you want to get the pixel size for drawing use getWorldBounds() instead.
See Also
getWorldBounds
setWorldSize
loadMapData ( BinaryString  data,
int  mapWidth = 0,
int  mapHeight = 0,
int  dstX,
int  dstY 
)
loadMapData ( MemBlock  data,
int  mapWidth = 0,
int  mapHeight = 0,
int  dstX,
int  dstY 
)
setTileTypeAt ( int  x,
int  y,
uint  t,
uint  facing = facing_Ignore 
)

sets the type of tile at a given location on the map

Parameters
xthe horizontal tile position on the map (not pixels)
ythe vertical tile position on the map (not pixels)
tthe type of tile (the tile index in the tile set image)
facingthe rotation (or flipping) to use for this tile, defaults to none, ignored on layers that aren't using facing or flipping
setWorldSize ( int  width,
int  height,
boolean  repeatingX = false,
boolean  repeatingY = false 
)

sets the number of tiles in the world map

Parameters
widthhow many tiles wide the world should be
heighthow many tiles high the world should be
repeatingXtrue if the map should wrap around horizontally to appear infinite, defaults to false
repeatingYtrue if the map should wrap around vertically to appear infinite, defaults to false

User Comments