Class Mappy

java.lang.Object
  |
  +--Mappy

public class Mappy

extends java.lang.Object

Mappy Playback Library for Java Release 6

Based on MappyJV Release1 14/07/99 (C)1999 Robin Burrows.

This class allows the playback of Mappy .FMP files. Current limitations are:

• Pillars are not supported.
• Animation Blocks are not fully supported.

After constructing a Mappy class, you must load a Map into it before it can be used. If any of your image blocks are transparent then be sure to set the transparent colour key via setTransparentColour() before you call a loadMap() method. It is also important that you set the screen area that the Map is to be drawn into (via setScreenDimensions() ) before any drawing functions are called.

As a Map can have up to 8 layers, the Mappy class introduces the concept of a current layer. This current layer is used implicity (i.e. without you specifing)in most of the map operations (e.g. drawForeground()), therefore you must set the current Map layer before calling any Map layer methods.

Despite the source for the Mappy Playback being quite large I have kept it in a single source (.java) file to ease portability. For the same reason, Mappy has been moved out of it's default package of com.alienfactory.gaming. Future releases may well begin to spread accross several classes (over 2000 lines, I mean, come on!).

See the readme.txt file for more info

See Also:

setTransparentColour(int), loadMap(File, Component), setScreenDimensions(Rectangle), Mappy.Block

Nested Class Summary

class

Mappy.Block Mappy Block v1.10 This class represents a Block as used by Mappy.

Constructor Summary

Mappy()
Constructs a new Mappy Playback Library.

Method Summary

void	addX(int intIncX) Increments the X coordinate of the current Map layer by the given amount (in pixels).
void	addY(int intIncY) Increments the Y coordinate of the current Map layer by the given amount (in pixels).
void	animateBlocks() Animates all the animation block structures.
boolean	collisionDetection(int intX, int intY) Performs a collision detection test at the given pixel coordinates using the Block's collision flags.
void	drawBackground(java.awt.Graphics gfx, boolean blnTransparency) Draws the Blocks' background of the current Map layer.
void	drawForeground(java.awt.Graphics gfx, int intBlockLayer) Draws the Blocks' foreground of the current Map layer.
Mappy.Block	getBlock(int intBlockX, int intBlockY) Returns the Block used at the given Block coordinates, in the current Map layer.
int	getBlockHeight() Returns the height of a Block, in pixels.
int	getBlockWidth() Returns the width of a Block, in pixels.
int	getBlockX() Returns the X coordinate of the current Map layer, in Blocks.
int	getBlockY() Returns the Y coordinate of the current Map layer, in Blocks.
int	getCurrentMapLayer() Returns the current Map layer.
java.lang.String	getMapDescription() Returns a description of the Map.
int	getMapHeight() Returns the total height of the Map, in pixels.
int	getMapHeightBlocks() Returns the total height of the Map, in blocks.
int	getMapWidth() Returns the total width of the Map, in pixels.
int	getMapWidthBlocks() Returns the total width of the Map, in blocks.
java.awt.Rectangle	getScreenDimensions() Returns the screen dimensions.
int	getTransparentColour() Returns the transparent colour used for Block Images in RGB format.
int	getX() Returns the X coordinate of the current Map layer, in pixels.
int	getY() Returns the Y coordinate of the current Map layer, in pixels.
void	loadMap(java.io.File file, java.awt.Component component) Loads a .FMP Map from a given File.
void	loadMap(java.io.InputStream stream, java.awt.Component component) Loads a .FMP Map from a given InputStream.
void	loadMap(java.lang.String strFileName, java.awt.Component component) Loads a .FMP Map from a given filename.
void	loadMAR(java.lang.String strFileName, int marlyr) Loads a .MAR map array file called strFileName.
void	setBlock(int intBlockX, int intBlockY, int intIndex) Puts the block structure value in the map at the given block coords.
void	setCurrentMapLayer(int intMapLayer) Sets the current Map layer.
void	setScreenDimensions(int intX, int intY, int intWidth, int intHeight) A helper method that sets the screen dimensions.
void	setScreenDimensions(java.awt.Rectangle rectangle) Sets the screen dimensions.
void	setTransparentColour(int intNewTransparentColour) Sets the transparent colour for Block Images.
void	setX(int intNewX) Sets the X coordinate of the current Map layer, in pixels.
void	setY(int intNewY) Sets the Y coordinate of the current Map layer, in pixels.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

Mappy

public Mappy()

Constructs a new Mappy Playback Library.

Method Detail

setTransparentColour

public void setTransparentColour(int intNewTransparentColour)

Sets the transparent colour for Block Images. This is used to denote the transparent colour of block images when a Map is loaded. Hence this method need only be used before a loadMap() method is called.

The default transparent colour is Color.black.

Thinking about it, if I can't find another use for the transparent colour then I may make it a parameter in loadMap().

Parameters:

intNewTransparentColour - the blocks transparent colour in RGB.

See Also:

getTransparentColour(), loadMap(File, Component), loadMap(String, Component)

getTransparentColour

public int getTransparentColour()

Returns the transparent colour used for Block Images in RGB format.

Returns:

the transparent colour used for Block Images.

See Also:

setTransparentColour(int)

loadMap

public void loadMap(java.lang.String strFileName,
                    java.awt.Component component)

Loads a .FMP Map from a given filename. The Mappy class is rather useless until you load a Map into it!

Parameters:

strFileName - the filename of the Mappy .FMP file.

component - this is required to create a compatible image, it can be a Window or an Applet or any component really!

See Also:

loadMap(File, Component)

loadMap

public void loadMap(java.io.File file,
                    java.awt.Component component)

Loads a .FMP Map from a given File. The Mappy class is rather useless until you load a Map into it!

Parameters:

file - the file of the Mappy .FMP file.

component - this is required to create a compatible image, it can be a Window or an Applet or any component really!

See Also:

loadMap(InputStream, Component)

loadMap

public void loadMap(java.io.InputStream stream,
                    java.awt.Component component)

Loads a .FMP Map from a given InputStream. The Mappy class is rather useless until you load a Map into it!

Parameters:

stream - the InputStream where the .FMP file can be found.

component - this is required to create a compatible image, it can be a Window or an Applet or any component really!

loadMAR

public void loadMAR(java.lang.String strFileName,
                    int marlyr)

Loads a .MAR map array file called strFileName. The corresponding FMP map must be loaded first.

Parameters:

strFileName - the name of the .MAR file to load

marlyr - the number of the layer you want to load to

getMapDescription

public java.lang.String getMapDescription()

Returns a description of the Map. The description is a concatonation of the strings found in the ATHR chunk of the map, seperated by new-line ("\n") characters.

Returns:

a description of the Map.

getMapWidthBlocks

public int getMapWidthBlocks()

Returns the total width of the Map, in blocks.

Returns:

the width of the Map.

See Also:

getMapHeightBlocks()

getMapHeightBlocks

public int getMapHeightBlocks()

Returns the total height of the Map, in blocks.

Returns:

the width of the Map.

See Also:

getMapWidthBlocks()

getMapWidth

public int getMapWidth()

Returns the total width of the Map, in pixels.

Returns:

the width of the Map.

See Also:

getMapHeight()

getMapHeight

public int getMapHeight()

Returns the total height of the Map, in pixels.

Returns:

the height of the Map.

See Also:

getMapWidth()

getBlockWidth

public int getBlockWidth()

Returns the width of a Block, in pixels.

Returns:

the width of a Block.

See Also:

getBlockHeight()

getBlockHeight

public int getBlockHeight()

Returns the height of a Block, in pixels.

Returns:

the height of a Block.

See Also:

getBlockWidth()

setScreenDimensions

public void setScreenDimensions(java.awt.Rectangle rectangle)

Sets the screen dimensions. The rectangle denotes the area of the screen where the map is drawn.

The default dimensions equivalent to new Rectangle(0, 0, 640, 480) .

Parameters:

rectangle - the new screen dimensions.

See Also:

getScreenDimensions()

setScreenDimensions

public void setScreenDimensions(int intX,
                                int intY,
                                int intWidth,
                                int intHeight)

A helper method that sets the screen dimensions. The parameters denote the area of the screen where the map is drawn.

The default dimensions are equivalent to new Rectangle(0, 0, 640, 480) .

Parameters:

intX - the X coordinate of the screen drawing area

intY - the Y coordinate of the screen drawing area

intWidth - the width of the screen drawing area

intHeight - the height of the screen drawing area

See Also:

getScreenDimensions()

getScreenDimensions

public java.awt.Rectangle getScreenDimensions()

Returns the screen dimensions. The rectangle denotes the area of the screen where the map is drawn.

The rectangle returned is an independant object, e.g. altering the rectangle does not affect the Mappy class.

Returns:

the screen dimensions.

setCurrentMapLayer

public void setCurrentMapLayer(int intMapLayer)

Sets the current Map layer. This layer is used implicitly in all the map specific functions (e.g. drawBackground()), so it is important that this is set first.

A valid Map always has layer "0" and may have up to 7 more. If you try to set the Map layer to a layer that doesn't exist then the current Map layer remains unchanged.

Parameters:

intMapLayer - the new current Map layer.

See Also:

getCurrentMapLayer(), setX(int), addX(int), getX(), setY(int), addY(int), getY(), getBlockX(), getBlockY()

getCurrentMapLayer

public int getCurrentMapLayer()

Returns the current Map layer. This layer is used implicitly in all the map specific functions (e.g. drawBackground()), so it is important that this is set first.

A valid Map always has layer "0" and may have up to 7 more.

Returns:

the current Map layer.

See Also:

setCurrentMapLayer(int), setX(int), addX(int), getX(), setY(int), addY(int), getY(), getBlockX(), getBlockY()

setX

public void setX(int intNewX)

Sets the X coordinate of the current Map layer, in pixels.

The new X coordinate is clipped, so that it is always greater than zero and less than the Map's pixel width minus the current screenwidth. This ensures that whatever the X coordinate is set to, a complete portion of the Map can be displayed.

Parameters:

intNewX - the new X coordinate of the current Map layer in pixels.

See Also:

addX(int), getX()

addX

public void addX(int intIncX)

Increments the X coordinate of the current Map layer by the given amount (in pixels).

This helper method effectivly just calls setX() so the same clipping rules apply.

Parameters:

intIncX - what to increment the X coordinate of the current Map layer by, in pixels (may be negative).

See Also:

setX(int), getX()

getX

public int getX()

Returns the X coordinate of the current Map layer, in pixels.

I'm thinking of renaming this method to getPixelX() to be more in line with getBlockX().

Returns:

the X coordinate of the current Map layer, in pixels.

See Also:

addX(int), setX(int), getBlockX()

setY

public void setY(int intNewY)

Sets the Y coordinate of the current Map layer, in pixels.

The new Y coordinate is clipped, so that it is always greater than zero and less than the Map's pixel height minus the current screenheight. This ensures that whatever the Y coordinate is set to, a complete portion of the Map can be displayed.

Parameters:

intNewY - the new Y coordinate of the current Map layer in pixels.

See Also:

addY(int), getY()

addY

public void addY(int intIncY)

Increments the Y coordinate of the current Map layer by the given amount (in pixels).

This helper method effectivly just calls setY() so the same clipping rules apply.

Parameters:

intIncY - what to increment the Y coordinate of the current Map layer by, in pixels (may be negative).

See Also:

setY(int), getY()

getY

public int getY()

Returns the Y coordinate of the current Map layer, in pixels.

I'm thinking of renaming this method to getPixelY() to be more in line with getBlockY().

Returns:

the Y coordinate of the current Map layer, in pixels.

See Also:

addY(int), setY(int)

getBlockX

public int getBlockX()

Returns the X coordinate of the current Map layer, in Blocks.

This is effectively getX() / getBlockWidth().

Returns:

the X coordinate of the current Map layer, in Blocks.

See Also:

getX(), getBlockWidth(), getBlock(int, int)

getBlockY

public int getBlockY()

Returns the Y coordinate of the current Map layer, in Blocks.

This is effectively getY() / getBlockHeight().

Returns:

the Y coordinate of the current Map layer, in Blocks.

See Also:

getY(), getBlockHeight(), getBlock(int, int)

animateBlocks

public void animateBlocks()

Animates all the animation block structures.

drawBackground

public void drawBackground(java.awt.Graphics gfx,
                           boolean blnTransparency)

Draws the Blocks' background of the current Map layer.

Parameters:

gfx - the Graphics object that the Map is to drawn on.

blnTransparency - whether or not the background is to be drawn with transparency or not.

See Also:

drawForeground(Graphics, int), setCurrentMapLayer(int), setScreenDimensions(Rectangle), getX(), getY()

drawForeground

public void drawForeground(java.awt.Graphics gfx,
                           int intBlockLayer)

Draws the Blocks' foreground of the current Map layer.

If intBlockLayer is unknown then an error is logged (not thrown).

Parameters:

gfx - the Graphics object that the Map is to drawn on.

intBlockLayer - the Block's foreground layer to be drawn.

See Also:

drawBackground(Graphics, boolean), setCurrentMapLayer(int), setScreenDimensions(Rectangle), getX(), getY()

getBlock

public Mappy.Block getBlock(int intBlockX,
                            int intBlockY)

Returns the Block used at the given Block coordinates, in the current Map layer.

The returned Block is not independant of the Map, so any changes made to the block are immediatly reflected in the Map. Also remember that there is not one Block for each given coordinate but that each coordinate points to a Block. i.e. Blocks are reused throughout the Map.

If any of the Block coordinates given are out of range then an error is logged (not thrown) and null returned.

Returns:

the Block used at the given coordinate.

See Also:

setCurrentMapLayer(int), getBlockX(), getBlockY()

setBlock

public void setBlock(int intBlockX,
                     int intBlockY,
                     int intIndex)

Puts the block structure value in the map at the given block coords. negative values are animations (-1 is the first anim).

collisionDetection

public boolean collisionDetection(int intX,
                                  int intY)

Performs a collision detection test at the given pixel coordinates using the Block's collision flags.

If any of the pixel coordinates are out of range of the map then false is automatically returned.

Parameters:

intX - the pixel X coordinate.

intY - the pixel Y coordinate.