story.h

Go to the documentation of this file.
00001 /*
00002  * story.h
00003  *
00004  * Copyright (C) 2008,2009  Thomas A. Vaughan
00005  * All rights reserved.
00006  *
00007  *
00008  * Redistribution and use in source and binary forms, with or without
00009  * modification, are permitted provided that the following conditions are met:
00010  *     * Redistributions of source code must retain the above copyright
00011  *       notice, this list of conditions and the following disclaimer.
00012  *     * Redistributions in binary form must reproduce the above copyright
00013  *       notice, this list of conditions and the following disclaimer in the
00014  *       documentation and/or other materials provided with the distribution.
00015  *     * Neither the name of the <organization> nor the
00016  *       names of its contributors may be used to endorse or promote products
00017  *       derived from this software without specific prior written permission.
00018  *
00019  * THIS SOFTWARE IS PROVIDED BY THOMAS A. VAUGHAN ''AS IS'' AND ANY
00020  * EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
00021  * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
00022  * DISCLAIMED. IN NO EVENT SHALL THOMAS A. VAUGHAN BE LIABLE FOR ANY
00023  * DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
00024  * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
00025  * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
00026  * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
00027  * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
00028  * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
00029  *
00030  *
00031  */
00032 
00033 #ifndef AESOP_STORY_H__
00034 #define AESOP_STORY_H__
00035 
00036 // includes --------------------------------------------------------------------
00037 #include "common/common.h"
00038 #include "i18n/i18n.h"
00039 #include "threadsafe/smart_ptr.h"
00040 
00041 
00042 // forward decl
00043 class Datahash;
00044 
00045 namespace story {
00046 
00047 ////////////////////////////////////////////////////////////////////////////////
00048 ///
00049 /// \ingroup aesop_core
00050 /// \defgroup story Story Library
00051 ///
00052 /// \n
00053 /// This library defines the Story object, and other helper objects/routines.
00054 /// A Story is a kind of database, containing all information that a generic
00055 /// game engine needs to run.  In particular, \ref aesop_srv and \ref aesop_client
00056 /// libraries use Story objects to determine how to find and load important
00057 /// game data.
00058 ///
00059 ////////////////////////////////////////////////////////////////////////////////
00060 
00061 /*@{*/
00062 
00063 
00064 
00065 ///     This is the high-level story object.
00066 ///
00067 ///     <center><b> DESIGN PRINCIPLES </b></center>
00068 ///
00069 ///\n
00070 ///     Story objects exist to help get IDs and absolute paths to local persisted
00071 ///       objects relevant to the story being told.  The goal is that a story
00072 ///       object is pointed at a local directory (containing the full story files),
00073 ///       and the Story object handles all the details where objects are persisted
00074 ///       within that directory structure.  The Story object also understands (and
00075 ///       exposes) some Story-level concepts.
00076 ///
00077 ///     For instance, a Story object can tell you the ID of the starting map for
00078 ///       the story.  Given a map ID, the Story object can tell you the full path
00079 ///       that map on local disk.
00080 ///
00081 ///     The Story object can NOT:
00082 ///        - load objects or maps.  Other libraries must do that, given the paths.
00083 ///        - handle dynamics.  Stories are there to provide content.  Other libraries
00084 ///             have to handle dynamic state.
00085 ///
00086 /// The story library should never depend on any aesop libraries.  This should
00087 /// be a simple leaf library.
00088 ///
00089 /// All methods must be threadsafe!  This should be no big deal since all
00090 /// methods are typically const anyway.
00091 class Story {
00092 public:
00093         // virtual destructor --------------------------------------------------
00094         virtual ~Story(void) throw();
00095 
00096         // story::Story class interface methods --------------------------------
00097 
00098         /// every story must have a universally unique ID
00099         virtual const char * getUuid(void) const throw() = 0;
00100 
00101         /// short title (preferably 16 characters or less!)
00102         virtual const char * getTitle(void) const throw() = 0;
00103 
00104         /// return the ID of the starting map (game starts here)
00105         virtual const char * getStartingMapId(void) const throw() = 0;
00106 
00107         /// Given an object ID, and type of object, return the path.
00108         /// Examples:
00109         ///  - getObjectPath("map",   "firstGameMap.map")
00110         ///  - getObjectPath("model", "cube.model")
00111         ///  - getObjectPath("type",  "chicken.type")
00112         virtual std::string getObjectPath(IN const char * objectType,
00113                                 IN const char * objectId) const = 0;
00114 
00115         /// given the locale-relative path, return an i18n::Manager object
00116         ///     Example: getI18nManager("converse/system.txt")
00117         virtual smart_ptr<i18n::Manager> getI18nManager(IN const char * path) = 0;
00118 
00119         // static factory methods ----------------------------------------------
00120         static smart_ptr<Story> create(IN const char * locale,
00121                                 IN const char * story_dir);
00122 };
00123 
00124 
00125 };      // story namespace
00126 
00127 #endif  // AESOP_STORY_H__
00128