/* $Id: mapstuffset.hpp,v 1.8 2005/06/28 13:55:20 chfreund Exp $ */

#ifndef  _MAPSTUFFSET_HPP_
#define  _MAPSTUFFSET_HPP_

/**********************************************************/

#include  "spriteset.hpp"
#include  "sprite.hpp"
#include  "weightedrandom.hpp"

/**********************************************************/

//! one set of map stuff

/*! This class represents one set of map stuff.
 *  Basically it is a class SpriteSet<Sprite> with the following
 *  augmentations:
 *   - a material constant, that takes the values defined as public
 *     enumeration constants in class MapStuffSet:
 *     DIGGABLE, UNDIGGABLE, INDESTRUCTIBLE. Whenever you refere
 *     directly to these constants (inside the namespace of MapStuffSet),
 *     you should specify them including their namespace MapStuffSet::,
 *     to prevent ambiguous interpretations due to eventually present
 *     global constants with the same name.
 *   - an integer array of length [getSize()], whereby getSize() is
 *     PointerVector<>::getSize() and returns the number of sprite
 *     sequences in this sprite set. If \f$ w_i \f$ is the probability
 *     weight given for set sequence [i], m_UsageWeights[i] has the
 *     value \f$ \sum_{k=0}^i w_k \f$ and therefore marks the boundary
 *     in a subinterval of [0,getSize()-1]. See also getRandomItem().
 *  <br>
 *  <b>Configuration File</b><br>
 *  The configuration file is the one of a SpriteSet, augmented by a
 *  special section (see class SettingDataBase) with name "MapStuffSet",
 *  which contains the settings, that are specific for a map stuff set:
 *   - <b>odds</b> (optional, integer): integer weights, that specify
 *     the probability for the selection of a sprite sequence. The
 *     probability is defined similarly to the so called "odds". So
 *     "1,5,6" defines odds 1:5:6. The number of weights must exactly
 *     match the number of sequences in the sprite set. If \f$ w_i \f$
 *     is the weight for sequence i, this sequence i is selected with
 *     probability \f$ \frac{w_i}{\sum_{k=0}^n w_i} \f$, whereby n ==
 *     getSize().
 *   - <b>material</b> (mandatory, string): One string of "DIGGABLE",
 *     "UNDIGGABLE", "INDESTRUCTIBLE", specifying the material type
 *     of all items in the set.
 */
class MapStuffSet : public SpriteSet<Sprite>
{
	public:

		//! constructor
		MapStuffSet( const int randomseed = 42 );
		//! destructor
		~MapStuffSet();

		//! returns a randomly chosen map stuff item

		/*! If weights for the random selection of map stuff were
		 *  specified in the configuration file, using the setting
		 *  "usageweights", the selection of the sequence is a weighted
		 *  random selection. Otherwise simply a uniform distribution
		 *  is used. If the sequence contains more than one sprite,
		 *  one of these sprites is selected based on a uniform
		 *  distribution in any case.
		 */
		const Sprite* getRandomItem();

		//! returns the material as enumeration constant
		int getMaterial() const { return m_Material; }
		//! returns the material string
		const char* getMaterialString() const {
			return m_MaterialString[m_Material]; }
		//! maps the material enumeration constant to its string
		static const char* getMaterialString( const int material ) {
			DBG(1) {
				if( !CHECK(material > UNDEFINED     &&
			               material < NUM_MATERIALS   ,
			               "MapStuffSet::getMaterialString: %d is not a "
			               "valid material constant -> returning NULL\n",
			               material) ) {
				return NULL; }
			}
			return m_MaterialString[material];
		}

		//! load the map stuff set

		/*! Loads the map stuff set defined in the configuration
		 *  file "filename", which is placed in the directory "path".
		 *  \return number of sprite sequences loaded as different
		 *          item sets. -1, if the loading did not succeed.
		 */
		int load( const char* const path,
		          const char* const filename );

		//! resets class to state after construction
		void reset();

		//! enumeration constants for material specification
		enum { UNDEFINED = -1,   //!< not defined, not valid, ...
		       DIGGABLE  =  0,   //!< diggable map stuff
		       UNDIGGABLE,       //!< undiggable map stuff
		       INDESTRUCTIBLE,   //!< indestructible map stuff
		       NUM_MATERIALS };
		
	protected:

		//! load settings specific for map stuff
		bool loadMapStuffSettings( const char* const fullpath );
		//! check the consistency of settings
		bool processSettings( const SettingDataBase& settings );

		//! enumaration constants for access to the setting definitions
		enum { ODDS_SETTING_DEFS = 0,
		       MATERIAL_SETTING_DEFS,
		       NUM_SETTING_DEFS };

		int             m_Material; //!< material
		WeightedRandom  m_Random;   //!< random number generator
		
		//! setting definitions
		static const SettingDef   m_SettingDef[NUM_SETTING_DEFS+1];
		static const char* const  m_SectionName;
		//! material strings
		static const char* const  m_MaterialString[NUM_MATERIALS+1];
};

/**********************************************************/

#endif // _MAPSTUFFSET_HPP_