Gamelib

Introduction

The deals with "maps" or "levels" and mapping from map descriptions to graphical tiles to display. In and of itself, the maps do not generate any graphics, they only specify what sort of tile is where.

Defining tile types

There are two different ways of defining a tile, depending on if the tile has "in-game self-action" or not. A tile that acts within the game (other than as an obstacle) is called a generator.

One tile-mapping is pre-defined. The character "S" signifies both a tile of type :floor and a starting-position for the map. This is at the moment pre-coded and not likely to change.

A normal tile only needs a character that defines it and a tile type. They are declared using the define-tile macro:
(define-tile character tile-type)

A generator is like a normal tile, but it also has a generator class associated with it (one of the classes exported from the GAMES-2D package) that takes care of its in-game action. Generators are declared using the define-generator macro:
(define-generator character tile-type generator-type)

Map definitions

Maps are defined in text files, with a fairly simple format. The first line has the map level number, the width and the height of the map, as numbers. Then, the map follows, using characters mapped to tile types (designated by CL keywords) in the code. The type keywords are used in the graphics library to map to bitmaps.

An example from Gatlopp (the first level) looks like:

1 10 8
##########
#    S   #
#  $     #
#   $$ # #
#  #  ## #
# ###    #
# >#     #
##########

Connecting tiles

If tiles (like, say, door and wall tiles) don't naturally extend all the way to the edges of the tile, the maps library has built-in functionality to help that happen.

The functionality is exposed via the define-type-from-map macro:
(define-type-from-map tile-type &rest character)

Doing this means that when tile-from-map finds a tile-type tile, it will know to look in all four cardinal directions and see if any of the specified characters are there. If so, it will return a "derived" tile type (essentially another keyword like :base-ensw). The keywords for the connecting types will have one or more of the letters "ensw" (in that order), signifying in what directions the tile joins up to other tiles.

If the tile doesn't join up, the base type is returned.

As an example, in Gatlopp, the wall tile doesn't extend to the edge and without using the multi-tile approach, a section of wall from the map file above might've looked like:

If we had declared a multi-tiled type:

(define-tile-from-map wall #\# #\+) ; we want to join to walls and doors

Exported symbols

*current-map*

Bound to a representation of the currently active map

*mapcount*

Number of maps loaded

activate-map

(activate-map seq#)
Activate a new map. Will set *current-map* and go through the new map, checking for generators. Checks that seq# is positive and less than *mapcount*.

define-generator

(define-generator character tile-type generator-type)
Define a tile type for a generator and associates it with a game-object class.

define-tile

define-type-from-map

find-starting-position

(find-starting-position map)
Find the starting position of the map (if any). Return (x y) or NIL, depending on.

height

Accessor for map class. Returns the height (in tiles) of a specific map.

mapdata

Accessor for map class. Returns the array (WxH) of characters taht is the underlying map storage.

read-all-maps

(read-all-maps &optional spec)
Read all map. Will default using a wildcarded pathname merged from *file-path* (defined in the games-2d package) and "*.map". If spec is provided, this will be used instead.

seq

Accessor for map class. Returns the map sequence number.

tile-from-map

(tile-from-map x y &optional actual-type)
Return tile-type for tile x,y (if that tile is a generator, return the generator-type, unless actual-type is non-NIL).

width

Accessor for map class. Return the width of the map.