BlitzCoder - Blitz Basic Game Development Resources

Blitz2D Newbies: Basic Map File Loading & Scrolling by Krylar

UPDATE!

I have updated this article to include more dynamic tile/map loading. Also the Map_ShowMap function now can be called with more specific detail, including the specific map cells to begin drawing from. This means you can do scrolling and such. Look at the example file downloads to see it in action.

Introduction:

There've been a lot of people asking about how to go about loading a map from a file. The primary reason is because most all 2D side-scrollers or tile-games use some type of map to display the appropriate tiles at appropriate locations.

The method described here is just one of many, and it is a simple method. But it should be good enough to get you started. After seeing how this works, I would recommend that you expand upon this and make it much more robust.

Loading Tiles

Before doing anything with the map, we need to have something to display. Generally folks put a bunch of fixed-sized tiles (though they can be varied in size if your code permits) in a single image file. Sometimes all of the tiles run together, such as shown here:

Other times, the artist puts a block around each image to keep them visibly seperated, shown here:

This is an important distinction because you don't want to end up loading the blocks with the images, you just want the actual images. Because of this, you'll not only need to know how tall and wide each image is, but also how much space is between each of your images.

For example, let's say that you have images that are 32x32. That is they are 32 pixels wide by 32 pixels high. And let's say that you've put a 2x2 box around each image. When you go to use the GrabImage function in BB, you'll not want to grab from 0,0 (the top left of the image), rather you'll want to grab from the inside-top-left edge of the box at 2,2. See below for an example:

In an effort to make this entire process easier on the caller, I've set up a group of functions for a map loading/displaying library. I named it "maplib.bb". You can call it whatever you want.

At the very top of the map library, I have set a number of global variables and arrays. Here they are:

Next I put together a function that will call all of the loading functions, clear any old arrays/types, and re-dimension new ones based on map information. Here is the code:

;******************************************************************
; This function is a wrapper that clears out old
; arrays/types, loads up a tile file and a map file and sets
; everything up for processing.
;
; Arguments: 
;    Tile_Full_Path$ = Tile Image file, including the full path
;    TileWidth = Width of the tiles being loaded
;    TileHeight = Height of the tiles being loaded
;    XSpacer = If there are boxes around the tiles, set this to
;              the number of pixels that the boxes are wide.
;    YSpacer = If there are boxes around the tiles, set this to
;              the number of pixels that the boxes are high.
;    TotalColumns = How many tiles are there across?
;    TotalRows = How many tiles are there high?
;    Map_Full_Path$ = Map filename, including the full path
;******************************************************************

Function Map_LoadMap(Tile_Full_Path$,TileWidth,TileHeight,XSpacer,
                     YSpacer,TotalColumns,TotalRows,Map_Full_Path$)

; clear out any old tiles, to conserve memory
  For TileCounter = 0 To TotalTiles - 1
      If Tile.Tiles(TileCounter) <> Null
         FreeImage Tile(TileCounter)\Image
         Delete Tile(TileCounter)
      EndIf
  Next

; re-dimension the Tile array
  Dim Tile.Tiles(TotalRows * TotalColumns)

; call the Map_LoadTiles function with the proper vars (see function)
Map_LoadTiles(Tile_Full_Path$,TileWidth,TileHeight,XSpacer,YSpacer,TotalRows,TotalColumns)

; clear out any old maps, to conserve memory
  For Rows = 0 To MapHeight - 1
      For Columns = 0 To MapWidth - 1
          If Map.MapData(Columns,Rows) <> Null
             Delete Map.MapData(Columns,Rows)
          EndIf
      Next
  Next

; call the Map_ReadDimensions to get the proper rows/columns
  Map_ReadDimensions(Map_Full_Path$)

; re-dimension the Map array
  Dim Map.MapData(MapWidth,MapHeight)

; Now read the actual data from that map file
  Map_ReadData(Map_Full_Path$)

End Function

We will have to load the actual image tiles each time a new map is loaded. There are a number of arguments that the caller must send to the Map_LoadTiles(...) function. They specify the following:

The Filename that the tiles are in (the image file), including the full path.
The Width, in pixels, of each tile
The Height, in pixels, of each tile
The offset (for boxes around the images) from the X, or horizontal, perspective...in pixels
The offset (for boxes around the images) from the Y, or verticle, perspective...in pixels
The total number of columns of tiles to be loaded in from each row
The total number of rows of tiles to be loaded in from the file

Now, the following source is fully commented so study it carefully!

;******************************************************************
;  This function loads in the actual tiles to be used
;  with the map.  It takes into account any boxes that may have 
;  been placed around each image by allowing the caller to specify
;  the box widths and heights.
;
; Arguments: 
;    Tile_Full_Path$ = Tile Image file, including the full path
;    TileWidth = Width of the tiles being loaded
;    TileHeight = Height of the tiles being loaded
;    XSpacer = If there are boxes around the tiles, set this to
;              the number of pixels that the boxes are wide.
;    YSpacer = If there are boxes around the tiles, set this to
;              the number of pixels that the boxes are high.
;    TotalColumns = How many tiles are there across?
;    TotalRows = How many tiles are there high?
;****************************************************************** 
Function Map_LoadTiles(Tile_Full_Path$,TileWidth,TileHeight,XSpacer,
                       YSpacer,TotalColumns,TotalRows)
  
  ; first off let's load the full image containing all the tiles
  ; into a temporary space
  Temp_Image=LoadImage(Tile_Full_Path$)

; get the current buffer so we can restore to it
  CurrentBuffer = GraphicsBuffer()

; next make that image the current buffer
  SetBuffer ImageBuffer(Temp_Image)

; setup our basic vars.  The X and Y values will be whatever the XSpacer
  ; and YSpacer values are. If they are 0, then it's assumed that there is
  ; no space between the tiles. If you look at the sample images included
  ; with this demo you'll see a white box around each image...that's why
  ; I have these spacers...we don't wanna load the boxes, just the images.
  X = XSpacer
  Y = YSpacer

; keep track of the number of images
  ImageNumber = 0

; run through the total number of rows (minus 1, of course)
  For Rows=0 To TotalRows-1
      ; and run through all the columns per row (minus 1 again)
      For Columns=0 To TotalColumns-1
          ; create a new TileList element and assign it the current
          ; ImageNumber.  Then populate the TileList element with
          ; the TileWidth, TileHeight, and the actual Tile_Image
          Tile.Tiles(ImageNumber) = New Tiles
          Tile(ImageNumber)\Width = TileWidth
          Tile(ImageNumber)\Height = TileHeight

; to get the image, we first use CreateImage(...) to make sure
          ; BB allocates enough space in the TileList field Tile_Image 
          Tile(ImageNumber)\Image=CreateImage(TileWidth,TileHeight)

; then we grab the image based off the size setup in CreateImage(...)
          ; from our X,Y location
          GrabImage(Tile(ImageNumber)\Image,X,Y)
         
          ; now we add X to the TileWidth and the XSpacer to get the new X position.
          ; So, if our current X = 2, and the TileWidth = 32 and the XSpacer = 2, we'd
          ; have X = 2 + 32 + 2, or 36.  This means that the next time we call         
          ; GrabImage(...) it will start grabbing from the X position 36 (or the 36th pixel 
          ; from the left).         
          X=X + TileWidth + XSpacer

; increment our tile counter (for the array positioning)
          ImageNumber = ImageNumber + 1
      Next
      ; we've finished with that row, so reset X back to the spacer position
      X = XSpacer

; now we add Y to the TileHeight and the YSpacer to get the new Y position.
      ; So, if our current Y = 2, and the TileHeight = 32 and the YSpacer = 2, we'd
      ; have Y = 2 + 32 + 2, or 36.  This means that the next time we call  
      ; GrabImage(...) it will start grabbing from the Y position 36 (or the 36th pixel 
      ; from the top).         
      Y = Y + TileHeight + YSpacer
  Next
  
  ; restore the buffer
  SetBuffer CurrentBuffer

; free the image from memory, so we don't hold memory for no reason
  FreeImage Temp_Image

; reset our global tile tracker
  TotalTiles = ImageNumber
End Function

There is a lot to that function, but if you go over it a few times it should become clear how it works.

Map File Format

There are many ways to layout a map file. Some folks use numbers seperated by spaces or commas, others use various methods of encryption, some just go straight across with the numbers and parse appropriately. Additionally, some map generators and files take into consideration Z-Ordering. That is, the level on which a tile sits when compared to other tiles. (For more information on Z-Ordering, please refer to the BlitzBasic Intermediates: Z-Ordering article.

For ease of understanding, I've decided to go with numbers seperated by commas.

The first line of my map file will have two numbers: The Width, or columns on the map, and the Height, or rows on the map. Immediately following that will be the appropriate number of rows of data mixed with the appropriate number of columns. Here is an example:

This map basically says that there are 3 columns and 2 rows. The first row contains 3 images and they are: Image 10, Image 1, and Image 5. The second row's images are: Image 4, Image 15, and Image 6. If you recall, when we loaded in the Tiles each tile was assigned a place in the array. So, when we go to call DrawImage we can pass the Tile(ImageNumber) and it will display the appropriate tile!

Loading Map Dimensions

In order to load this data in, we must first determine the number of elements we'll need to store within our MapData array. In order to make this easier on the caller, I have created two functions to handle reading in the map data. The first is called Map_ReadDimensions(...) and it's sole purpose is to open a map data file, read in the first line, and parse that line so it knows how many columns and rows are in the map.

Take a look at the function and study the comments closely:

;******************************************************************
; This function loads in the actual dimensions of
;  the map file and stores the values in MapWidth and MapHeight.
; Arguments: 
;    Map_Full_Path$ = Map file, including the full path
;****************************************************************** 
Function Map_ReadDimensions(Map_Full_Path$)

; first thing we do is open the file using a Pointer Variable (which
  ; is "File" in this case)
  File=ReadFile(Map_Full_Path$);

; Then we read the first line of the file...it *should* contain the
  ; width/height data.  If it doesn't, somebody goofed up on the layout
  ; of the file
  MapDimensions$ = ReadLine$(File);

; we need to set up some variables to parse the line.  We could just
  ; set this up to have the x,y on two lines and save some trouble from
  ; a coding perspective, but this method makes the map creation more
  ; intuitive for the user...and that's our job ;)
  EndOfString = 0
  Offset = 0

; while we haven't reached the end of the string
  While EndOfString = 0
        ; let's first put the current position in the string into Temp$
        ; this is just 1 character from the string cause we use the Mid$(...)
        ; command to yank out that value
        Temp$ = Mid$(MapDimensions$,Offset+1,1)

; if that character is not a comma we haven't gone past the length
        ; of the string
        If Temp$ <> "," And (Offset <= Len(MapDimensions$))
          ; then it must be a number, so we save it in the HoldString$
          HoldString$ = HoldString$ + Temp$
        ; otherwise, it's either gone too far or it's the comma seperator
        Else
           ; if we've gone too far, then we know that the MapHeight is done
           If Offset > Len(MapDimensions$)
              ; so we convert the current HoldString$ to an Int and assign it
              MapHeight = Int(HoldString$)
              ; and make sure the While loop breaks
              EndOfString = 1
          ; it must be a comma, so that means our MapWidth value is loaded
          Else
             ; convert the current HoldString$ to an int and assign it
             MapWidth = Int(HoldString$)
             ; reset the HoldString$ to blank so we can start loading MapHeight
             HoldString$ = ""
          EndIf
        EndIf
        ; increase the string position offset by 1 (to move to the next character)
        Offset = Offset + 1
   Wend
   ; we're done, so close the file!
   CloseFile(File)
End Function

Now you may consider this overkill for just determining the Cols,Rows...and, frankly, you may be right. But my goal is to make it brain-dead simple for the person calling these functions to use the map and the function, so I don't mind overkill in my code.

Loading the Map Data

The second function is called Map_ReadData(...) and it's job is to take the information it knows for the number of columns and rows (which it gets from Map_ReadDimensions(...)) and load in all of the image numbers into the MapData array. Again, study this carefully:

;******************************************************************
; This function loads in the actual map information.
; Arguments: 
;    Map_Full_Path$ = Map file, including the full path
;****************************************************************** 
Function Map_ReadData(Map_Full_Path$)

; first thing we do is open the file using a Pointer Variable (which
  ; is "File" in this case)
  File=ReadFile(Map_Full_Path$);
  ; read the Map dimensions line, but don't do anything with it...this
  ; is just to move to the map data line.  Use the Map_ReadDimensions(...)
  ; function for getting the actual MapWidth/MapHeight, so you can DIM
  ; the MapData array appropriately
  MapDimensions$ = ReadLine$(File);

; set up our vars for array placements.  The X will be for columns, and
  ; the Y will be for rows.  The EndOfFile just let's us keep track of how
  ; far into the file we've gone.
  X=0
  Y=0
  EndOfFile = 0

; do this until we reach the end of the file
  While EndOfFile = 0

; read a line of data from the file and put it in the MapLine$ string
        MapLine$ = ReadLine$(File);

; make sure that the lenght of the line is more than 1 character
        If Len(MapLine$) > 1

; set up our EndOfString var to be 0...this will help us keep
           ; track of the current MapLine$ string position
           EndOfString = 0
           ; This Offset var will let us keep track of our current position
           ; in the MapLine$ string
           Offset = 0

; until we reach the end of the MapLine$ string
           While EndOfString = 0
                
                 ; let's first put the current position in the string into Temp$
                 ; this is just 1 character from the string cause we use the Mid$(...)
                 ; command to yank out that value
                 Temp$ = Mid$(MapLine$,Offset+1,1)

; if that character is not a comma we haven't gone past the length
                 ; of the string
                 If Temp$ <> "," And (Offset <= Len(MapLine$)) 
                    ; then it must be a number, so we save it in the HoldString$
                    HoldString$ = HoldString$ + Temp$
                 ; otherwise, it's either gone too far or it's the comma seperator
                 Else
                    ; if we've gone too far, then we know that this line is done
                    If Offset > Len(MapLine$)
                       ; so we make a new MapData element in our Map(x,y) array
                       Map.MapData(X,Y) = New MapData
                       ; fill in the number of the HoldString$ by converting it to an Int
                       Map(X,Y)\TileNumber = Int(HoldString$)
                       ; reset the HoldString$ to a blank
                       HoldString$ = ""
                       ; exit the loop for *this* line (so we can read the next one)
                       EndOfString = 1
                    ; it must be a comma, so that means this column's value is loaded
                    Else
                       ; so we make a new MapData element in our Map(x,y) array
                       Map.MapData(X,Y) = New MapData
                       ; fill in the number of the HoldString$ by converting it to an Int
                       Map(X,Y)\TileNumber = Int(HoldString$)
                       ; reset the HoldString$ to a blank
                       HoldString$ = ""
                       ; Increase the X (or Column) location for the Array
                       X=X+1
                    EndIf
                 EndIf
                 ; add one to our string position offset
                 Offset = Offset + 1
            Wend
            ; set X back to 0 (so we're back to column 0)
            X=0
            ; add 1 to Y (so we move down 1 row in the array)
            Y=Y+1
        ; if we've gone past the length of the file
        Else
            ; then tell the loop to stop cause we're done!
            EndOfFile = 1
        EndIf
   Wend
   ; make sure to close the file!
   CloseFile(File)
End Function

Showing a Loaded Map

After calling this function you should have all the data loaded into your MapData Array of Type. Now it's just a matter of calling the Map_ShowMap(...) function. This function simply runs through the MapData Array Type, grabs the image number to show, and then calls BB's DrawImage function with the TileList Array Type's image for that image number. Here's the code:

;****************************************************************** 
; This function displays a map starting at a certain
;  X,Y offset, at a certain point within the map, and showing a
;  certain number of rows and columns.
; Arguments: 
;    XOffset = The X position to begin displaying the tiles.
;    YOffset = The Y position to begin displaying the tiles.
;    MapCollumnStart = The column of the map to display from
;    MapRowStart = The Row of the map to display from
;    ShowWidth = How many columns to show
;    ShowHeight = How many rows to show
;****************************************************************** 
Function Map_ShowMap(XOffset,YOffset,MapColumnStart,MapRowStart,
                     ShowWidth,ShowHeight)
    ; initialize X and Y to the arguments.  It's easier to
    ; type X,Y in code, but it's easier for the caller to 
    ; understand what's expected by using XOffset,YOffset.
    ; Personal preference
    X=XOffset
    Y=YOffset

; make sure we're not going beyond the map when displaying rows
    If (MapRowStart + (ShowHeight - 1)) >= MapHeight
       MapRowStart = MapHeight - ShowHeight
       ; also make sure that we're not going less than 0!
       If MapRowStart < 0
          MapRowStart = 0
          ShowHeight = MapHeight
       EndIf
    EndIf

; make sure we're not going beyond the map when displaying columns
    If (MapColumnStart + (ShowWidth - 1)) >= MapWidth
       MapColumnStart = MapWidth - ShowWidth
       ; also make sure that we're not going less than 0!
       If MapColumnStart < 0
          MapColumnStart = 0
          ShowWidth = MapWidth
       EndIf
    EndIf

; for all of the rows (minus 1)
    For Rows = MapRowStart To (ShowHeight+MapRowStart)-1
        ; and for all the columns (minus 1)
        For Columns = MapColumnStart To (ShowWidth+MapColumnStart)-1
            TileNumber = Map(Columns,Rows)\TileNumber
            DrawImage Tile(TileNumber)\Image,X,Y
            X = X + Tile(TileNumber)\Width
        Next
        ; reset X to the beginning of the next row
        X = XOffset
        ; increase our Y drawing position by the Tile's Height
        Y = Y + Tile(TileNumber)\Height
    Next
End Function

By changing the values in MapColumnStart and MapRowStart you can scroll the map.

Calling the Functions

From the caller's perspective, this library simple to use. Just call that Map_LoadMap function with the appropriate arguments and you're set for loading. Then call Map_ShowMap with the appropriate arguments to display. If you need to change maps, just call Map_LoadMap again and it will clear out the old images and map data and load in the new.

The caller just needs to create a map file in the format described above, draw up some tiles, setup the TileList and MapData Types, and then put the Map function callers in at some point where they want to show the map. Here's an idea of it:

Conclusion

Hopefully this tutorial will give you some insight on a very simple map file. I also hope that you'll expand on this method and go for a much more heavyweight version!

You can grab a lame little demo of this and all the source code: Click Here. Note that the tiles used are from Ari Feldman's SpriteLib. Ari no longer makes this available on the web, but he has a book out that has these tiles on the CD. His site is: http://www.arifeldman.com.

Until next time...cya!

-Krylar

For a printable copy of this article, please click HERE.