Board game engine - is the community interested?

BlitzMax Forums/BlitzMax Programming/Board game engine - is the community interested?
SpaceAce
(Posted 2006) [#1]
In developing my first serious BlitzMax project, I decided to build a set of types for developing board games. I refer to it as a board game engine, but maybe that is too grandiose. Anyway, at the very least, it is a useful toolkit with all the elements (a game board, cells, tiles, etc) required to build square-board based games. You can see it in action here: http://www.blitzmax.com/Community/posts.php?topic=63017

What I am trying to figure out is if the BlitzMax community is interested in something like this or if it would just be duplicating existing available libraries. I know there are a ton of code collections out there, but if my fellow Blitzers are interested, I would be willing to release the code for public consumption as-is or possibly polish it up and add support/features for a nominal fee.

An overview of the code is available in the codebox below or here: http://www.tripsixes.com/tempfiles/SA_GameMod_CommentDocs.txt
' ================================================================
' SA_GameMod - Types and methods for building board games.
' All types include a COMPLETE set of methods for manipulating 
' the data fields. In most cases, you should use the SetXXX()
' GetXXX() methods instead of accessing data fields directly,
' as some of the methods include error checking and other 
' code that can help reduce human error when using the 
' SA_GameMod types.
' ================================================================
Include "SA_GameObject.bmx"
Include "SA_GameObject_Cell.bmx"
Include "SA_GameObject_Tile.bmx"
Include "SA_GameObject_GameBoard.bmx"
Include "SA_GameObject_ProgressBar.bmx"
Include "SA_GameObject_Mouse.bmx"

' This type provides methods for simple interaction with
' files. This type is mainly intended to allow the reading
' and writing of INI-style files.
Type SA_GameMod_INI Extends TList
  ' Filename to be associated with this instance of the the
  ' SA_GameMod_INI type. Do not include an extension when
  ' setting this field.
	Field FilePath$ = ".", FileName$ = "Default"
  Field FileExtension$ = "ini"
  
  ' Sets the path in which the file operations will take
  ' place. Simply, this is the place where the INI file
  ' will be written to and read from. This method strips
  ' trailign slashes from the path automatically.
  Method SetFilePath(_FilePath$)
  End Method

  ' Returns the path to the INI file, not including the
  ' filename.
  Method GetFilePath$()
  End Method

  ' Set the name of the INI file. Do not include an extension
  ' in the filename.
  Method SetFileName(_FileName$)
  End Method

  ' Returns the filename of the INI file.
  Method GetFileName$()
  End Method

  ' Set the extension for the INI file. You can supply the 
  ' extension with our without a leading '.', as leading
  ' periods will be removed when this method is used to set
  ' the file extension.
  Method SetFileExtension(_FileExtension$)
  End Method

  ' Returns the INI file extension.
  Method GetFileExtension$()
  End Method

  ' This method inserts an entry into the current INI instance.
  ' Simple call this method with the name of the INI entry and  
  ' the value you wish it to have, thus:
  ' MyINI.Insert("Volume", 100)
	Method Insert(ItemName$, ItemValue$)
	End Method
	
  ' Lookup the INI entry specified by _Name and return its value.
  ' The value is returned as  string, so you may have to cast it
  ' to a numerical type if you are expecting a number.
  Method Fetch$(_Name$)
  End Method
	
  ' Save all of the entries currently stored in the INI object.
  ' The file they entries are saved to depends on the values
  ' you set for FilePath, FileName and FileExtension.
	Method Save()		
	End Method
	
	' Read the INI file associated with this instance 
	' of SA_GameObject_INI and store it in the instance.
	Method Load()
	End Method
	
  ' Help Function to remove unwnted punctuation from
  ' a string.
	Method StripTrailingCharacters(TheString$ var, Char$ = "/")
	End Method

  ' Help Function to remove unwnted punctuation from
  ' a string.
	Method StripLeadingCharacters(TheString$ var, Char$ = ".")
	End Method
End Type

' A data structure representing lines in an INI file.
Type SA_GameMod_INILine
  ' The name, value and raw (Whole) data associated
  ' with this SA_GameObject_INILine object.
	Field Name$, Value$, Whole$
	
  ' Set the name of the INILine. For instance, if the 
  ' line currently contains "bob=sexy" and you use
  ' SetName("Tony") on the object, the line will change
  ' to "tony=sexy". All names are converted to lower case.
	Method SetName(_Name$)
	End Method

  ' Retrieve the name field of the INILine.
	Method GetName$()
	End Method

  ' Set the value of the current line.BreakLine If the line
  ' currently contains the data "volume=10" and you call
  ' SetValue(80) on the line, the new data will be 
  ' "volume=80".
	Method SetValue(_Value$)
	End Method

  ' Retrieve the current line's value.
	Method GetValue$()
	End Method
	
  ' Set both the name and value of this SA_GameObject_INI
  ' line instance.
  Method SetNameValue(_Name$, _Value$)
	End Method
	
  ' Retrieve the name and value associated with this line.
  ' The data is returned in a String array.
	Method GetNameValue:String[]()
	End Method
	
  ' Return the entire line in the form of "Name=Value".
	Method GetWhole$()
	End Method
	
  ' Seperates a raw line into Name and Value by splitting the
  ' line at the first "=". Sets the Name and Value fields of
  ' the invoking object.
	Method BreakLine(Line$)
	End Method
End Type


' ================================================================
' ================================================================
' ================================================================
' ================================================================
' The SA_GameObject is a base type that provides basic properties
' and functionality that are likely to be used by most if not all
' of your game's objects.
' ================================================================
' ================================================================
' ================================================================
' ================================================================
Type SA_GameObject
  ' Fields to be shared by all derived types
  
  ' Object's screen position
  Field x#, y#
  
  ' Object's width and height
  Field Width#, Height#
  
  ' The right-hand and bottom boundries of the SA_GameObject_GameBoard
  Field Xbound#, Ybound#

  ' A Name to identify this object. Useful for debuggin and/or
  ' differentiating objects of the same type from one another.
  Field Name$ = Null
  
  ' Parents and Children can be very useful. A "Parent" can be
  ' considered the object's owner, and a "Child" as being owned
  ' by the Parent. This can be very useful in many circumstances.
  ' For instance, if you have a tile-based game, you can set each
  ' tile's Parent to be the cell the tile occupies on the gameboard,
  ' as well as making the tile the Child of the cell the tile is
  ' in.Close In this way, you can access information and methods
  ' of the cell through the tile and vice-versa.
  Field Parent:Object, Child:Object
  
  ' Flags are used to set properties for objects. For instance, you
  ' may wish to set an object as "inactive" or "hidden" or some such.
  ' Flags are a somewhat advanced topic which I will not attempt to 
  ' explain in detail here, but here is some pseudo-code showing how
  ' flags might be used in your program(s).
  '
  ' Include "SA_GameMod.bmx"
  ' Create a variable to serve as a flag
  ' Call an SA_GameObject's SetFlags() method with your new flag
  ' Use an SA_GameObject's GetFlags() method to retrieve the flag(s)
  ' Use the returned flags to decide what to do.
  Field Flags%


  ' ============
  '  Methods
  ' ============

  ' Initializes an existimg SA_GameObject instance with the values
  ' passed to it.
  Method Create(_x# = 0, _y# = 0, _width# = 0, _height# = 0, _Name$ = Null, _Parent:Object = Null, _Child:Object = Null)
  End Method
  
  ' Sets the pixel positions of the outside x and y boundries of
  ' the object. This is for convenience, so you can access the
  ' bottom-right coordinates the same as you can access the 
  ' upper-left (x, y) coordinates.
  Method SetBounds()
  End Method

  ' All of the "Set" methods return the difference between the old
  ' value and the new one you set by calling the method. If the old 
  ' value was 0 or Null, the number returned will be the same as the
  ' number you passed to the method.
  
  ' Check whether x, y lies within the SA_GameObject (or derived type)
  ' that calls the method.
  Method IsIn%(_x#, _y#)
  End Method
  
  ' Set the x property of the object
  Method SetX#(_x#)
  End Method

  ' Return the x property of the object
  Method GetX#()
  End Method

  ' Set the y property of the object
  Method SetY#(_y#)
  End Method

  ' Return the y property of the object
  Method GetY#()
  End Method

  ' Set the x and y properties of the object simultaneously. This method returns
  ' the differences between the old x and y properties and the new x and y
  ' properties. These are returned in a single-dimension array.
  Method SetXY:Float[](_x# = 0, _y# = 0)
  End Method

  ' Returns a single-dimension array containing the x and y properties of the
  ' object.
  Method GetXY:Float[]()
  End Method

  ' Set the width property of the object
  Method SetWidth#(_width#)
  End Method

  ' Return the width property of the object
  Method GetWidth#()
  End Method

  ' Set the height property of the object
  Method SetHeight#(_height#)
  End Method

  ' Return the height property of the object
  Method GetHeight#()
  End Method

  ' Set the width and height properties of the object simultaneously.
  Method SetWH:Float[](_width# = 0, _height# = 0)
  End Method

  ' Returns a single-dimension array containing the width and height 
  ' properties of the object.
  Method GetWH:Float[]()
  End Method

  ' Set the Xbound property of the object. Returns the differnce
  ' between the new and old value.
  Method SetXbound#(_x#)
  End Method

  ' Return the Xbound property of the object
  Method GetXbound#()
  End Method

  ' Set the Ybound property of the object
  Method SetYbound#(_y#)
  End Method

  ' Return the Ybound property of the object
  Method GetYbound#()
  End Method

  ' Set the Xbound and Ybound properties simultaneously. Returns
  ' the differences between the new and old values in an array.
  Method SetXYbound:Float[](_x# = 0, _y# = 0)
  End Method

  ' Returns a single-dimension array containing the Xbound and
  ' Ybound properties of the object.
  Method GetXYbound:Float[]()
  End Method

  ' Set the Name property of the object
  Method SetName(_Name$)
  End Method

  ' Return the Name property of the object
  Method GetName$()
  End Method

  ' Set the Parent object of this instance of SA_GameObject
  Method SetParent(_Parent:Object)
  End Method

  ' Return the Parent object of this instance of SA_GameObject
  Method GetParent:Object()
  End Method

  ' Set the Child object of this instance of SA_GameObject
  Method SetChild(_Child:Object)
  End Method

  ' Return the Child object of this instance of SA_GameObject
  Method GetChild:Object()
  End Method
  
  ' Set flags for this object
  Method SetFlags(_Flags%)
  End Method

  ' Retrieve the flags associated with this object.
  Method GetFlags%()
  End Method
End Type




' ================================================================
' ================================================================
' ================================================================
' Progress bar object - exactly what it sounds like,
' a progress bar.
' ================================================================
' ================================================================
' ================================================================
' Flags for use with the progress bar. These are 
' explained later in this document.
Const SAGP_HORIZONTAL% = 1
Const SAGP_VERTICAL% = 2
Const SAGP_REVERSE% = 4
Const SAGP_FORWARD% = 8
Const SAGP_EMPTY% = 16
Const SAGP_FILLED% = 32
Const SAGP_NOBORDER% = 64

Type SA_GameObject_ProgressBar Extends SA_GameObject
  ' RGB colors for bar background
  Field ColorR%, ColorG%, ColorB%
  
  ' RGB for progress color
  Field ProgColorR%, ProgColorG%, ProgColorB%
  
  ' Internal, you probably don't need to mess with these.
  Field Progress#, Flags%

  ' Because the Draw() method could easily be called 
  ' hundreds of times per second, while the Update()
  ' method is likely to be called much less frequently
  ' than that, we're going to do all the math in the 
  ' Update() method. In order for the Draw() method
  ' to access the data, we need to store it in variables
  ' that can be accessed inside Draw()
  ' ProgX and ProgY are the x and y coordinates of the
  ' actual colored filling/emptying progress bar. The
  ' absolute position of the bar (which would be the
  ' upper-left corner of the background or border of
  ' the bar) is set using the x and y fields derived
  ' from the SA_GameObject type.
  Field ProgX%, ProgY%, BarLength%, BarHeight%  
  
  ' The "step" is how much is added to the current progress
  ' at each update. A higher number will fill or empty the 
  ' bar faster.
  Field pStep# = 1

  ' 0 = Draw an unfilled background, > 0 = fill in the background.
  Field Fill% = 0
  
  ' The "goal" for the progress bar. When the bar is Update()ed, 
  ' the pStep field will be added to the Progress field and 
  ' then compared to this value to determine how to draw the bar.
  ' When the Progress field reaches this value, the progress bar
  ' will stop filling or emptying.
  Field MaxOut# = 1000
  
  ' The line thickness for drawing the progress bar background.
  Field Thickness# = 2
  

  ' ============
  ' Methods
  ' ============
  
  ''''''''''''''''''''''''''''''''''''''
  ' Note: When the comments below refer to the 
  ' "progress bar", they are really referring
  ' to the colored internal part that does the
  ' visible counting.
  ''''''''''''''''''''''''''''''''''''''
    
  ' Updates the bar's progress toward its "MaxOut" point. This
  ' method does all of the calculations necessary to draw the bar.
  ' In general, you will probably wish to a set a timer in your
  ' code that calls this function whenever it fires.
  Method Update()
  End Method
  
  ' Sets the color for the background rect (if any) that will
  ' make up the background of the progress bar.
  Method SetBGColor(_r%, _g%, _b%)
  End Method
  
  ' Sets the RGB color for the actual progress bar.
  Method SetProgColor(_r%, _g%, _b%)
  End Method
  
  ' Set the orientation of the progress bar. Possible values
  ' are:
  ' SAGP_VERTICAL - The progress bar will fill from bottom to top
  ' SAGP_HORIZONTAL - The progress bar will fill from left to right
  ' SAGP_REVERSE - The bar will start fully filled and run in reverse.
  ' SAGP_FORWARD - The bar will fill instead of emptying
  ' SAGP_EMPTY - The background will be an unfilled rect
  ' SAGP_FILLED - The background will be a solid rect
  ' SAGP_NOBORDER - There is no outline drawn around the progress bar.
  ' You can specify multiple flags using the or operator, like this:
  ' SAGP_HORIZONTAL|SAGP_REVERSE
  ' If no flags are specified, the progress bar will default to 
  ' SAGP_HORIZONTAL|SAGP_FORWARD|SAGP_FILLED
  Method SetOrientation(_Flags%)
  End Method
  
  ' Reset the bar's progress to 0.
  Method Reset()
  End Method

  ' Set the ProgX property. Returns the difference 
  ' between the old and new values.
  Method SetProgX%(_x%)
  End Method

  ' Return the ProgX property of the object
  Method GetProgX%()
  End Method

  ' Set the ProgY property. Returns the difference 
  ' between the old and new values.
  Method SetProgY%(_y%)
  End Method

  ' Return the ProgY property of the object
  Method GetProgY%()
  End Method

  ' Set the ProgX and ProgY values at the same time. Returns
  ' an array containing the differences between the old and
  ' new values.
  Method SetProgXY:Int[](_x% = 0, _y% = 0)
  End Method

  ' Returns a single-dimension array containing the ProgX and 
  ' ProgY properties of the object.
  Method GetProgXY:Int[]()
  End Method

  ' Set the length of the progress bar. Returns the difference
  ' between the old length and the new length. Usually, this will
  ' only be called internally by other SA_GameObject_ProgressBar
  ' methods.
  Method SetBarLength%(_Length%)
  End Method
  
  ' Get the length of the progress bar.
  Method GetBarLength%()
  End Method
  
  ' Set the height of the progress bar. Returns the difference
  ' between the old height and the new height. As with the
  ' SetLength() method, this method probably shouldn't need
  ' to be called from your code.
  Method SetBarHeight%(_Height%)
  End Method
  
  ' Get the Height of the progress bar.
  Method GetBarHeight%()
  End Method
  
  ' Simultaneously set the length and height of the progress
  ' bar/ Returns an array containing the differences between
  ' the old and new values.
  Method SetBarLH:Int[](_x% = 0, _y% = 0)
  End Method

  ' Returns a single-dimension array containing the length and
  ' height of the progress bar.
  Method GetBarLH:Int[]()
  End Method

  ' Using the metrics set by the Update() method, draws the
  ' progress bar and progress bar background.
  Method Draw()
  End Method
End Type



' ================================================================
' ================================================================
' ================================================================
' SA_GameObject_Tile - Tiles, like Dominoes or scrabble tiles,
' impart some sort of value to game cells.
' ================================================================
' ================================================================
' ================================================================
' Notes:
' Remember to call the Drop() method for a tile when you want to 
' remove it from your game.

' Pre-defined flag for use in locking and unlocking a tile.
' Lock()ing the tile has no effect other than setting the
' SAGT_LOCKED flag. Likewise, Unlock() only removes the flag.
' The intention of this flag and those functions is to mark
' a tile as "locked" to make it easy to make sure a tile stays
' where it is.
' Update() ignores the SAGT_LOCKED flag and will move a tile
' whether or not it is locked.
Const SAGT_LOCKED% = 1

Type SA_GameObject_Tile Extends SA_GameObject
  ' Every time you call Create() from a SA_GameObject_Tile object,
  ' it is added to this list for use in the DrawAll() function.
  ' It is important that you call the Drop() method whenever you 
  ' want to remove a tile from your game.
  Global SAGT_TileList:TList = CreateList()
  
  ' You will often want to assign some sort of value to to the
  ' tiles you use in your game. This field is for that purpose.
  Field Value#
  
  ' The TImage object to be associated with this tile.
  Field Sprite:TImage
  
  ' These fields are intended to help you automatically move
  ' tiles around the screen. DestinationX and DestinationY are 
  ' the x and y screen coordinates where you want to tile to 
  ' end up. SpeedX and SpeedY are the horizontal and vertical
  ' speed you want the tiles to move at. If both speeds are set 
  ' to 0, the tile will not be moved no matter what the destination
  ' coordinates are.
  ' The Update() method must be called in order for the tile to
  ' be automatically moved.
  ' BE SURE TO READ THE DESCRIPTION OF the SetDockingFunction 
  ' method described below.
  Field DestinationX#, DestinationY#, SpeedX#, SpeedY#
  
  ' Holds a pointer to a function that will be called when a tile
  ' reaches its destination IF you set one using SetDockingFunction.
  Field DockingFunction(Tile:SA_GameObject_Tile)
  

  ' ============
  ' Methods
  ' ============
  
  ' Overrides the base class Create() method to initialize a 
  ' tile and add it to the global tile list which is used to
  ' allow some mass operations to be performed on all existing
  ' tiles.
  Method Create(_x# = 0, _y# = 0, _width# = 0, _height# = 0, _name$ = Null, _parent:Object = Null, _child:Object = Null)
  End Method
  

  ' Removes the tile from the global tile list.
  Method Drop()
  End Method

  ' This allows you to specify a function to be called whenever a tile
  ' that is being moved automatically via Update() reaches its final
  ' destination. Here's how to implement this:
  '
  ' First, create a function in your program to do whatever you want
  ' done when a tile reaches its destination. You can give the function
  ' any Blitzmax-legal name you wish, but it must have an SA_GameObject_Tile
  ' as its only function parameter. Exmple:
  '
  ' Function HandleDocking(tile:SA_GameObject_Tile)
  '   Do some stuff here...
  ' End Function
  '
  ' When the function is called, the tile that initiated the function call
  ' will be passed to the function as the tile:SA_GameObject_Tile.
  '
  ' Next, Create an SA_GameObject_tile and then call the SetDockingFunction
  ' method like this:
  ' YourTile.SetDockingFunction(HandleDocking)
  '
  ' Once you've done that, the function HandleDocking will be called whenever
  ' Update() determines that a tile that was previously in motion has reached
  ' its destination.
  Method SetDockingFunction(_DockingFunction(Tile:SA_GameObject_Tile))
  End Method
  
  ' Updates the positional information of tiles that are in motion due to 
  ' DestinationX and DestinationY settings. Also calls the DockingFunction
  ' if one is set.
  Method Update()
  End Method

  ' Set the Value field of the tile. Returns the difference
  ' between the old and new values.
  Method SetValue#(_value#)
  End Method

  ' Return the value of this tile's Value field.
  Method GetValue#()
  End Method

  ' ==========
  ' Some of the following are FUNCTIONS as opposed to METHODS.
  ' Therefore, they are not invoked using aTile.MethodName().
  ' Instead, you call them using SA_GameObject_Tile.FunctionName()
  ' ==========
  
  ' Update all the tiles that have been created but not Drop()ped.
  Function UpdateAll()
  End Function
  
  ' Draw all the tiles that have been created but not Drop()ped.
  Function DrawAll()
  End Function
  
  ' This is a combination function that both Update()s and
  ' Draw()s all the existing tiles. This function exists
  ' so you can both Update() and Draw() all the tiles while
  ' only traversing the tile list one time.
  Function ProcessAll()
  End Function
  
  ' Draw the individual tile that is invoking this method.
  Method Draw()
  End Method
  
  ' Attach an existing image to this tile.
  Method SetSprite(_Sprite:TImage)
  End Method
  
  ' Returns the TImage object associated with this tile
  Method GetSprite:TImage()
  End Method
  
  ' Set the width of the cell. If no width is specified, the tile will
  ' try to determine its own width based on the width of its Sprite.
  Method SetWidth#(_width#)
  End Method
  
  ' Set the height of the cell. If no height is specified, the tile will
  ' try to determine its own height based on the height of its Sprite.
  Method SetHeight#(_height#)
  End Method
  
  ' Set the width and height of the cell. If either width or height is
  ' not specified, the tile will attempt to determine its own width
  ' and/or height by reading the size of its Sprite.
  Method SetWH:Float[](_width# = Null, _height# = Null)
  End Method

  ' Set the DestinationX property of the object.
  Method SetDestinationX#(_x#)
  End Method

  ' Return the DestinationX property of the object
  Method GetDestinationX#()
  End Method

  ' Set the DestinationY property of the object
  Method SetDestinationY#(_y#)
  End Method

  ' Return the DestinationY property of the object
  Method GetDestinationY#()
  End Method

  ' Set the DestinationX and DestinationY properties of the object simultaneously. 
  ' This Method returns the differences between the old DestinationX and 
  ' DestinationY properties and the new DestinationX and DestinationY properties. 
  ' These are returned in a single-dimension array.
  Method SetDestinationXY:Float[](_x# = 0, _y# = 0)
  End Method

  ' Returns a single-dimension array containing the DestinationX and 
  ' DestinationY properties of the object.
  Method GetDestinationXY:Float[]()
  End Method

  ' Set the SpeedX property of the object.
  Method SetSpeedX#(_x#)
  End Method

  ' Return the SpeedX property of the object
  Method GetSpeedX#()
  End Method

  ' Set the SpeedY property of the object.
  Method SetSpeedY#(_y#)
  End Method

  ' Return the SpeedY property of the object
  Method GetSpeedY#()
  End Method

  ' Set the SpeedX and SpeedY properties of the object simultaneously. 
  ' This Method returns the differences between the old values and the
  ' new values via a single-dimension array.
  Method SetSpeedXY:Float[](_x# = 0, _y# = 0)
  End Method

  ' Returns a single-dimension array containing the SpeedX and 
  ' SpeedY properties of the object.
  Method GetSpeedXY:Float[]()
  End Method

  ' Make and return an exact copy of the object that calls the method
  Method Clone:SA_GameObject_Tile()
  End Method
  
  ' Set the SAGT_LOCKED flag
  Method Lock()
  End Method

  ' Remove the SAGT_LOCKED flag
  Method Unlock()
  End Method
  
  ' Returns True if the SAGT_LOCKED flag is set; false, otherwise.
  Method IsLocked%()
  End Method
End Type



' ================================================================
' ================================================================
' ================================================================
' SA_GameObject_Cell - just like on a Scrabble
' or Monopoly board, a cell represents a 
' location on the gameboard.
' ================================================================
' ================================================================
' ================================================================
Type SA_GameObject_Cell Extends SA_GameObject
  ' The column is an x-coordinate, the row is a y-coordinate.
  ' For example, the upper-lefthand corner of a gameboard is
  ' a column of 0 and a row of 0. The third cell over in the
  ' top row has a column of 2 and a row of 0. If you start at
  ' 0,0 and move two over to the right and down four, you end
  ' up at column 2, row 4.
  ' Remember that columns and rows start at 0, not 1. So, the 
  ' first cell on any given axis is 0, the second cell is 1
  ' and so on.
  Field Column#, Row#


  ' ============
  ' Methods
  ' ============

  ' Set the Cell's column
  Method SetColumn(_column#)
  End Method

  ' Return the Cell's column number
  Method GetColumn#()
  End Method

  ' Set the Cell's row
  Method SetRow(_row#)
  End Method

  ' Return the Cell's row number
  Method GetRow#()
  End Method

  ' Set the column (x) and row (y) that this cell occupies in
  ' the gameboard grid. This function returns an array holding
  ' the differences between the old column, cell and the new
  ' column, cell.
  Method SetColRow:Float[](_column# = 0, _row# = 0)
  End Method

  ' Returns a single-dimension array containing the 
  ' object's column and row.
  Method GetColRow:Float[]()
  End Method
End Type



' ================================================================
' ================================================================
' ================================================================
' The SA_GameObject_GameBoard's primary attribute is the Grid[,],
' which is an array of SA_GameObject_Cells that make up the board.
' Imagine a Scrabble board with no spaces marked on it, just a
' blank surface. That's the SA_GameObject_Gameboard. Now, imagine
' a Scrabble board with all the spaces outlined and marked as they
' are on a real Scrabble board. That's the Grid[,] laid on top of
' the GameBoard. Now, imagine a game of Scrabble in progress; the
' board (SA_GameObject_Gameboard) is covered with cells (the 
' SA_GameObject_GameBoard Grid[,] field), some of which have 
' additional information associated with them, such as Triple Word
' Score (Flags you set for the SA_GameObject_Cells) and in the
' cells are tiles (SA_GameObject_Tile) with different values
' (SA_GameObject_Tile.Value field).
' ================================================================
' ================================================================
' ================================================================


' Constants for use as flags with the AutoXY() method.
Const SAGG_TOP% = 2
Const SAGG_BOTTOM% = 4
Const SAGG_LEFT% = 8
Const SAGG_RIGHT% = 16
Const SAGG_CENTER% = 32


Type SA_GameObject_GameBoard Extends SA_GameObject
  ' Number of columns (x) and rows (y) in the gameboard grid
  Field Columns%, Rows%
  
  ' The width and height of the gameboard cells
  Field CellWidth#, CellHeight#
  
  ' The width and height of the border around each cell
  Field BorderWidth#, BorderHeight#
  
  ' A TImage object that is used as the GameBoard's background image
  Field Sprite:TImage
   
  ' The heart of the beast. This is the real reason the GameBoard
  ' exists. The Grid is an array of SA_GameObject_Cell objects that
  ' can be easily accessed via Grid[x, y]
  Field Grid:SA_GameObject_Cell[,]
  
  ' Sometimes we don't want the game grid to take up the entire
  ' gameboard. These fields allow us to adjust the position of
  ' the grid within the gameboard.
  Field GridXOffset# = 0, GridYOffset# = 0
  
  ' These are to convenience fields containing the absolute position
  ' the the top-left corner of the game board grid. You could get
  ' this information through simple addition (adding the gameboard
  ' x or y to the grid offset x or y), but setting these fields will
  ' eliminate the need to do so.
  Field GridX#, GridY#
  
  ' With the two groups of fields above, allows for easy reference
  ' to the grid dimensions, position, etc.
  Field GridXbound#, GridYbound#
  
  ' TileList holds all the tiles currently on or associated with the
  ' SA_GameObject_GameBoard. TilePool is a list of SA_GameBoardObject
  ' tiles from which your program can select to populate the board.
  ' Think of the tile pool as the alphabet - you select letters to
  ' use when building words. When you use a letter, it does not come
  ' out of the alphabet and can be used over and over. That is the
  ' concept of the tile pool.
  Field TileList:TList = CreateList(), TilePool:TList = CreateList()

  
  ' ============
  ' Methods
  ' ============

  ' Draws the board's background image if it has one.
  Method Draw()
  End Method
  
  ' Set the number of columns (x) in the gameboard grid. If no number
  ' is specified, this method will attmept to automatically calculate
  ' the number of columns. Returns null if successful or a detailed
  ' error message if not successful.
  Method SetColumns:String(_Columns% = Null)
  End Method
  
  ' Returns the number of columns in the gameboard Grid.
  Method GetColumns#()
  End Method
  
  ' Set the number of rows (y) in the gameboard grid. If no number
  ' is specified, this method will attmept to automatically calculate
  ' the number of rows. Returns null if successful or a detailed
  ' error message if not successful.
  Method SetRows:String(_Rows% = Null)
  End Method

  ' Returns the number of rows in the gameboard Grid.
  Method GetRows#()
  End Method
  
  ' Set the number of rows (y) and columns (y) in the gameboard. If
  ' either _Columns or _Rows are omitted, attempts to calculate
  ' them automatically. Returns a string containing all error
  ' messages generated or Null if successful.
  Method SetColRow:String(_Columns% = Null, _Rows% = Null)
  End Method

  ' Returns an array with the number of columns and the number
  ' of rows in the SA_GameObject_GameBoard instance's Grid.
  Method GetColRow:Float[]()
  End Method
  
  ' Set the width of the cells in the gameboard. If no width is 
  ' specified, the method attempts to calculate the width based
  ' on the available information.
  Method SetCellWidth:String(_cellwidth# = Null)
  End Method

  ' Returns the width of the gameboard Grid's cells.
  Method GetCellWidth#()
  End Method
  
  ' Set the height of the cells in the gameboard. If no height is 
  ' specified, the method attempts to calculate the height based
  ' on the available information.
  Method SetCellHeight:String(_cellheight# = Null)
  End Method
  
  ' Returns the height of the gameboard cells.
  Method GetCellHeight#()
  End Method
  
  ' Set both the width and height of the board's cells. Returns
  ' an error string or Null if no errors occur.
  Method SetCellWH:String(_cellwidth# = null, _cellheight# = Null)
  End Method
  
  ' Returns an array with the width and height of the cells
  ' in the gameboard.
  Method GetCellWH:Float[]()
  End Method
  
  ' Set the border width for cells in this gameboard instance.
  Method SetBorderWidth(_borderwidth#)
  End Method

  ' Return the border width for cells in this gameboard instance.
  Method GetBorderWidth#()
  End Method

  ' Set the border Height for cells in this gameboard instance.
  Method SetBorderHeight(_borderheight#)
  End Method

  ' Return the border width for cells in this gameboard instance.
  Method GetBorderHeight#()
  End Method

  Method SetBorderWH(_borderwidth#, _borderheight#)
  End Method

  ' Automatically calculates the x and y positions of the gameboard
  ' based on its dimensions and the size of the area it is to be
  ' placed in (_width and _height)
  '
  ' Flags:
  ' SAGG_TOP = Place the top of the board at the top of the defined 
  ' area
  '
  ' SAGG_BOTTOM = Place the bottom of the board at the bottom of the 
  ' defined area
  '
  ' SAGG_LEFT = Place the left edge of the board at the left edge of 
  ' the defined area
  '
  ' SAGG_RIGHT = Place the right edge of the board at the right edge
  ' of the defined area.
  '
  ' SAGG_CENTER = Center the board in the defined area
  Method AutoXY(_width#, _height#, gbpos% = Null)
  End Method
  
  ' Possibly the most important method in the SA_GameObject_GameBoard
  ' type. This method fills the gameboard's grid with SA_GameObject_Cells.
  ' This method also calls several convenience functions that set various
  ' values representing the dimensions and position of the grid. You 
  ' probably should not call this method until all of the main grid values 
  ' (CellWidth, CellHeight, BorderWidth, BorderHeight, GridOffsetX,
  ' GridOffsetY) as well as the properties for the gameboard the cell is in
  ' have been properly set.
  Method BuildGrid()
  End Method
  
  ' ToDo: Make it possible to pull tiles from TilePool in order.
  '
  ' Populate the gameboard with tiles drawn from the board's TilePool.
  ' This method can accept two arguments: the number of tiles to place
  ' on the board and whether to fill the board randomly (1) or in
  ' left-to-right order (< 1). The tiles are always selected randomly
  ' from the pool, but the cells they are inserted into can be selected
  ' in order. 
  Method Populate:TList(numTiles% = 10, Random% = 1)
  End Method

  ' Add a tile to the gameboard's tile pool. Tiles can be selected from
  ' the pool multiple times, so the only reason to add a tile to this
  ' list more than once is to increase its chance of being selected 
  ' when tiles are drawn randomly from the pool.
  Method AddToPool(tile:SA_GameObject_Tile)
  End Method
  
  ' Alright! Everybody, out of the pool!
  Method EmptyPool()
  End Method


  ' ToDo: Extend function to return diagonal neighbors
  '
  ' Returns a TList containing the north, south, east
  ' and west neighbors of the cell specified in the
  ' method's argument list.
  Method GetNeighbors:TList(acell:SA_GameObject_Cell)
  End Method

  ' Set an existing image as the gameboard background.
  Method SetSprite(_Sprite:TImage)
  End Method
  
  ' Returns the TImage object associated with this gameboard.
  Method GetSprite:TImage()
  End Method
  
  ' Sets the X and Y boundaries of the gameboard grid. This should not
  ' be called until the width and height of the grid as well as the 
  ' border sizes of the grid have been set! If you change the width,
  ' height or border sizes of the grid and you reference the GridXBound
  ' and/or GridYBound fields in your program, be sure to call this
  ' function again to update the boundaries.
  Method SetGridBounds()
  End Method

  ' Set the Xbound property of the Grid. Returns the differnce
  ' between the new and old value.
  Method SetGridXbound#(_x#)
  End Method

  ' Return the GridXbound property of this SA_GameObject_GameBoard
  ' instance.
  Method GetGridXbound#()
  End Method

  ' Set the Ybound property of the Grid.
  Method SetGridYbound#(_y#)
  End Method

  ' Return the GridYbound property of this SA_GameObject_GameBoard
  ' instance.
  Method GetGridYbound#()
  End Method

  ' Set the GridXbound and GridYbound properties simultaneously.
  ' Returns the differences between the new and old values in 
  ' an array.
  Method SetGridXYbound:Float[](_x# = 0, _y# = 0)
  End Method

  ' Returns a single-dimension array containing the Xbound and
  ' Ybound properties of the grid.
  Method GetGridXYbound:Float[]()
  End Method

  ' Check whether x, y lies within the gameboard grid.
  Method IsInGrid%(_x#, _y#)
  End Method
  
  ' Set the x offset property of the gameboard grid
  Method SetGridXOffset#(_x#)
  End Method

  ' Return the x property of the gameboard grid
  Method GetGridXOffset#()
  End Method

  ' Set the y property of the object
  Method SetGridYOffset#(_y#)
  End Method

  ' Return the y property of the object
  Method GetGridYOffset#()
  End Method

  ' Set the x and y properties of the grid simultaneously. This method returns
  ' the differences between the old x and y properties and the new x and y
  ' properties. These are returned in a single-dimension array.
  Method SetGridXYOffset:Float[](_x# = 0, _y# = 0)
  End Method

  ' Returns a single-dimension array containing the x and y properties of the
  ' grid.
  Method GetGridXYOffset:Float[]()
  End Method

  ' Set the x property of the gameboard grid
  Method SetGridX#(_x#)
  End Method

  ' Return the x property of the gameboard grid
  Method GetGridX#()
  End Method

  ' Set the y property of the object
  Method SetGridY#(_y#)
  End Method

  ' Return the y property of the object
  Method GetGridY#()
  End Method

  ' Set the x and y properties of the grid simultaneously. This method returns
  ' the differences between the old x and y properties and the new x and y
  ' properties. These are returned in a single-dimension array.
  Method SetGridXY:Float[](_x# = 0, _y# = 0)
  End Method

  ' Returns a single-dimension array containing the x and y properties of the
  ' grid.
  Method GetGridXY:Float[]()
  End Method
  
  ' Unlinks all the parents and children of the gameboard,
  ' it's cells and those cells' tiles. Also removes tiles
  ' from the SA_GameObject_Tile global tile list.
  Method FreeUp()
  End Method
End Type



' ================================================================
' ================================================================
' ================================================================
' SA_GameObject_Mouse - fields and methods
' to help interact with the mouse.
' ================================================================
' ================================================================
' ================================================================

' A flag to easily identify whether your mouse object is
' dragging something. An example of when you might use
' this flag is when a user clicks on an object in your
' game; you turn this flag on using the SetFlags()
' method or the shortcut DragOn() method and whenever
' the mouse moves, you can easily check this flag
' (IsDragging() or GetFlags()) to see whether you should
' also be moving some object(s) with the mouse pointer.
' When the user releases the mouse button or completes 
' an action that frees the object from the mouse, you
' turn off this flag using DragOff() or SetFlags()
' This works well in conjunction with the objList field.
Const SAGM_DRAGGING% = 1

Type SA_GameObject_Mouse Extends SA_GameObject
  ' The last x, y position occupied by the mouse pointer.
  Field LastX#, LastY#
  
  ' The speed the mouse is moving on the x and y planes.
  Field VelocityX#, VelocityY#
  
  ' The relative position of the mouse pointer to some object.
  ' These fields make it easy to keep an object at the same
  ' position relative to the mouse pointer.
  Field RelX#, RelY#

  ' It is occasionally useful to attach an object to the
  ' mouse pointer, for instance objects that you want to
  ' drag around. This list is for that purpose.
  '
  ' There are no special methods to manipulate this list;
  ' just use the standard Blitzmax TList methods.
  Field objList:TList = CreateList()
  

  ' ============
  ' Methods
  ' ============
  
  ' Updates the mouse object's current x and y velocities.
  Method Update()
  End Method

  ' Set the RelX property of the object. Returns the
  ' difference between the old value and the new one.
  Method SetRelX#(_x#)
  End Method

  ' Return the RelX property of the object
  Method GetRelX#()
  End Method

  ' Set the RelY property of the object. Returns the
  ' difference between the old value and the new one.
  Method SetRelY#(_y#)
  End Method

  ' Return the RelY property of the object
  Method GetRelY#()
  End Method

  ' Simultaneously set both the RelX and RelY positions of
  ' the mouse pointer object. Returns an array containing
  ' the differences between the old and new values.
  Method SetRelXY:Float[](_x# = 0, _y# = 0)
  End Method

  ' Returns a single-dimension array containing the RelX and 
  ' RelY properties of the object.
  Method GetRelXY:Float[]()
  End Method

  ' Set the SAGM_DRAGGING flag to true.
  Method DragOn()
  End Method
  
  ' Set the SAGM_DRAGGING flag to false.
  Method DragOff()
  End Method
  
  ' Return True if the SAGM_DRAGGING flag is on, false otherwise.
  Method IsDragging%()
  End Method
  
  ' Set the LastX property for this object
  Method SetLastX#(_x#)
  End Method

  ' Return the LastX property of the object
  Method GetLastX#()
  End Method

  ' Set the LastY property of the object
  Method SetLastY#(_y#)
  End Method

  ' Return the LastY property of the object
  Method GetLastY#()
  End Method
  
  ' Set the LastX and LastY properties of the object simultaneously. 
  ' This Method returns the differences between the old LastX and LastY 
  ' properties and the new LastX and LastY properties. These are returned in 
  ' a single-dimension array.
  Method SetLastXY:Float[](_x# = 0, _y# = 0)
  End Method

  ' Returns a single-dimension array containing the LastX and LastY
  ' properties of the object.
  Method GetLastXY:Float[]()
  End Method
End Type
SpaceAce
dynaman
(Posted 2006) [#2]
I've been wanting to do a boardgame for ages (strategy board games mostly). If I ever get back to blitz programming I would give this a look, but I've been doing a lot of contract work lately - in boring old Oracle forms and reports no less. (not as much fun as blitz!)
SpaceAce
(Posted 2006) [#3]
Right now, the board type only supports X by Y grids with square cells. If there is interest, I may add support for point-based shapes instead of just squares.

SpaceAce