GameTools loadMap

This library loads GameTools level files and provides means to query and modify them at runtime:

class TileObject

A TileObject is a single 3D model (typically a terrain tile) with an identifier and some bounding box data. All TileObjects are are maintained in a global linked list rooted at the global object TileObject *tileList (which is NULL when there are no TileObjects loaded:

 class TileObject
 {
   TileObject ( const char *_name, ssgBranch  *_root ) ;
   float        getOptimumViewDistance () ;
   const sgBox *getBbox        () ;
   const sgBox *getSnappedBbox () ;
   const char  *getName        () ;
   ssgBranch   *getModel       () ;
   TileObject  *getNext        () ;
   int          getIdent       () ;
   int          getNumVertices () ;
   void overrideBbox ( const sgBox *newBox ) ;
   ssgBranch *find ( const char *nm ) ;
 } ;

The constructor function is given the name of an object along with a pointer to its PLIB scene graph - it computes the bounding box and a 'snapped' bounding box that's snapped to the current grid size. It also adds it into the tileList.

Utility Functions

Snap a number to the nearest grid step:

  void gridSnap ( float gridstep, float *value )

These utility functions query the global tileList:

 int         getNumTiles    () ;
 int         findTile       ( const char *name ) ;
 ssgBranch  *findTileModel  ( const char *name ) ;
 ssgBranch  *findTileModel  ( int which ) ;
 const char *findTileName   ( int which ) ;
 TileObject *findTileObject ( int which ) ;
 TileObject *findTileObjectFromIdent ( int ident ) ;

class MapFlag

Certain game features make use of invisible 'flags' that can be planted into the level using the tiled program (or manually entered into the XML level file).

Flags have 'colours' (for ease of identification and classification) - as well as names.

The colours are defined as simple integers: FLAG_RED, FLAG_GREEN, FLAG_BLUE, FLAG_CYAN, FLAG_MAGENTA, FLAG_YELLOW, FLAG_BLACK, FLAG_WHITE, FLAG_ORANGE and FLAG_GREY

 class MapFlag
 {
    MapFlag () ;
   ~MapFlag () ;
   void setPosition ( sgCoord *crd ) ;
   void setColour   ( int col ) ;
   void setName     ( const char *newname ) ;
   float getX () { return x ; }
   float getY () { return y ; }
   float getZ () { return z ; }
   float getH () { return h ; }
   int         getColour () ;
   const char *getName   () ;
   const char *getColourString () ;
   const char *getColourFlagString () ;
 } ;

class Map

The Map class is set up to represent a grid of terrain tiles - plus some number of MapFlags. The constructor function is told the size of the grid (in 'grid cells') and the various static set and get functions allow you to set the size of each grid cell for object placement and display (although the 'showGrid' applies only to the tiled program).

Once constructed, you can call Map::load and Map::save to load and save the map as an XML level file you can add either tiles or maps by giving the TileObject or MapFlag along with its location. You can also remove the TileObject that's at a particular location - or a specific MapFlag.

Finally, there are get functions to convert a grid cell number into a 3D coordinate, to get the MapEntry for the object at a particular 3D position, find the number of MapFlag objects - and the nearest one to any given location. You can also search for MapFlags by name or by a simple consecutive integer enumerator. getMapColour returns the ASCII colour name for a map given a colour number (eg FLAG_RED ==> "Red"),

 class Map
 {
   Map ( int maxGridX, int maxGridY ) ;
   bool remove ( sgVec2 loc ) ;
   bool remove ( MapFlag *mf ) ;
   bool add    ( TileObject *to, sgCoord *loc, ssgBranch *br ) ;
   bool add    ( MapFlag    *mf, sgCoord *loc ) ;
   bool save   ( const char *fname ) ;
   bool load   ( const char *fname, ssgBranch *parent ) ;
   static void  setGridParams ( float _showGridXY , float _showGridZ,
                                float _placeGridXY, float _placeGridZ ) ;
   static float getShowGridXY  () ;
   static float getShowGridZ   () ;
   static float getPlaceGridXY () ;
   static float getPlaceGridZ  () ;
   void getCoordFromMapLoc ( sgCoord *loc, float x, float y, float z, float h ) ;
   MapEntry   *getMapEntry        ( sgVec2 loc ) ;
   int         getNumMapFlags  () { return flagList . getNumEntities () ; }
   MapFlag    *getNearestMapFlag  ( float x, float y, float z,
                                    float maxrange, int colormatch = -1 ) ;
   MapFlag    *getMapFlag         ( const char *name ) ;
   MapFlag    *getMapFlag         ( int i ) ;
   const char *getMapFlagColour   ( int c ) ;
 } ;

class MapEntry

Whilst a TileObject represents a particular terrain tile, that tile may appear at multiple locations within the same map. class MapEntry stores a specific instance of that tile - the TileObject and it's location.

 class MapEntry
 {
   MapEntry ( TileObject *_to, int _x, int _y, int _z, int _h )
   MapEntry ( TileObject *_to, float _x, float _y, float _z, float _h )
   ~MapEntry ()
   float getMapX () ;
   float getMapY () ;
   float getMapZ () ;
   float getMapH () ;
   void addModel ( ssgBranch *_gr ) ;
   TileObject  *getTileObject  () ;
   const sgBox *getSnappedBbox () ;
 } ;

Wikiid Pages relating to gameTools ()

gameTools - Main page

gameTools - Support Tools : plb_to_ac3d, mklevel, mktile, mktree, tiled, autogen_java, mk3dgallery

gameTools - File Formats : title_screen.rgb, ultimate.xml, material.xml, decoration.xml, physics.xml tiled.xml, tiled_autotiles.xml, Level files, Tile naming scheme, PLB files

gameTools - Source Code : Game functions: gameCamera, gameClock, gameChecksum/gameHashTable, gameHTTP, gameIsect, gameJoystick, gameParticleManager, gameScreen/gameMouse, gameSky, gameStarter, gameStrokeFont, gameUtils Material database: MatList/MatEntry Tile map handling: TileObject/MapFlag/MapEntry/Map Java Interfacing: JavaLink Image file loading: liImage/liImageFactory 3D Model file loading: loadPLB, PLB exporter Physics: Sabot, Bullet, gameTools - Use with Blender, PLB exporter Object management: Object