source: nrEngine/include/ScriptEngine.h @ 23

Revision 23, 8.1 KB checked in by art, 13 years ago (diff)
Line 
1/***************************************************************************
2 *                                                                         *
3 *   (c) Art Tevs, MPI Informatik Saarbruecken                             *
4 *       mailto: <tevs@mpi-sb.mpg.de>                                      *
5 *                                                                         *
6 *   This program is free software; you can redistribute it and/or modify  *
7 *   it under the terms of the GNU General Public License as published by  *
8 *   the Free Software Foundation; either version 2 of the License, or     *
9 *   (at your option) any later version.                                   *
10 *                                                                         *
11 ***************************************************************************/
12
13
14#ifndef _NR_SCRIPT_ENGINE_H_
15#define _NR_SCRIPT_ENGINE_H_
16
17
18//----------------------------------------------------------------------------------
19// Includes
20//----------------------------------------------------------------------------------
21#include "Prerequisities.h"
22
23//! Declare a scripting function as static memeber of class (c++ only)  \ingroup script
24#define ScriptFunctionDef(name)\
25        public: static nrEngine::ScriptResult name (const std::vector<std::string>&, const std::vector<nrEngine::ScriptParam>&)
26
27//! Declare a scripting function out of the class class (c++ only)  \ingroup script
28#define ScriptFunctionDec(name, class)\
29        nrEngine::ScriptResult class::name (const std::vector<std::string>& args, const std::vector<nrEngine::ScriptParam>& param)
30
31namespace nrEngine{
32
33
34        //! Each script function can return variable argument as a result \ingroup script
35        typedef VarArg ScriptResult;
36
37        //! The real functions accept this default parameter \ingroup script
38        typedef boost::any ScriptParam;
39
40        //! We define each function that can be called from the scripts as this type \ingroup script
41        typedef boost::function<ScriptResult (const std::vector<std::string>&, const std::vector<ScriptParam>&)> ScriptFunctor;
42
43        //! Script engine is a glue code between the scripts and the engine
44        /**
45         * The script engine is a main class representing the glue code between
46         * the scripting languages (from plugins or whatever) and the game engine.
47         * The game engine will register functions by the script engine, so
48         * you get an access to this functions in your scripts. So the script
49         * engine class is something like an engine's API for the scripts.
50         *
51         * In the future we want to improve the functionality of the scripting
52         * engine, by adding the possibility to use meta classes. So the scripts
53         * could create new classes based on engine's.
54         *
55         * \ingroup script
56        **/
57        class _NRExport ScriptEngine{
58                public:
59
60                        /**
61                         * Cast a script parameter, which is of type "any", to any other type.
62                         * Note: we use here any_cast, so you have to worry about catching the
63                         * error throws
64                         **/
65                        template<class T>
66                        static T parameter_cast(const ScriptParam& p){
67                                return boost::any_cast<T>(p);
68                        }
69
70                        /**
71                        * Register new functions, that can be called from scripts.
72                        * The functions registered here are called through call() method.
73                        *
74                        * You can also specify one default parameter, that will be passed
75                        * to the called function (e.g. pointer to your object). The parameter is
76                        * of the boost type "any". So it does not have certain type.
77                        *
78                        * @param name Name of the function, must be unique
79                        * @param func Function itself (i.e. boost::function)
80                        * @param param Parameters you want to be stored to pass later to the function
81                        *
82                        * @return either OK or an error code if there is some problems
83                        **/
84                        Result add(const std::string& name, ScriptFunctor func, const std::vector<ScriptParam>& param = std::vector<ScriptParam>());
85
86                        /**
87                         * Using variable parameter arguments.
88                         * @see add()
89                         **/
90                        Result add(const std::string& name, ScriptFunctor func, const VarArg& v);
91
92                        /**
93                        * Delete already registered function from the api database.
94                        *
95                        * @param name name of the function to be deregistered
96                        *
97                        * @return either OK or an error code
98                        **/
99                        Result del(const std::string& name);
100
101                        /**
102                        * Call a certain function from the database whithin the given parameters.
103                        * First script engine database will look if there is a function
104                        * whithin the given name. Then if such could be found the functor
105                        * according to the function will be called. As first parameter it sends
106                        * the user predefined parameters, stored in the database. As second
107                        * it will pass the string parameters coming from the script or from
108                        * the subroutine called this method.
109                        *
110                        * @param name Unique name of hte function to be called
111                        * @param args Argument list of arguments given to the function (like in
112                        *                               the console, first must always be the function name)
113                        **/
114                        ScriptResult call(const std::string& name, const std::vector<std::string>& args = std::vector<std::string>());
115
116                        /**
117                         * Load a new script from the given file. The script will be loaded
118                         * by the resource manager, which will try to find the appropriate
119                         * loader for this type of scripts. If there is no such loader could
120                         * be found, so null will be returned. Otherwise you get a resource
121                         * pointer to the script. The resource pointer garanty that the according
122                         * script will be used in the way like all other resources. This means if
123                         * a script is unloaded,so EmptyScript will be used. You do not have
124                         * to care about given pointers, because resource pointers have similar
125                         * behaviours as smart pointers.
126                         *
127                         * The function does load the scripts in the memory, so you do not have
128                         * to carry about the returned pointer, if you do not want to. Loaded scripts
129                         * are still accessable by their names.
130                         *
131                         * @param name Name for the script.
132                         * @param fileName Name of the file containign the script.
133                         *
134                         * @return ResourcePtr<IScript> to the script.
135                         **/
136                        ResourcePtr<IScript> load(const std::string& name, const std::string& fileName);
137
138                        /**
139                         * This method will execute script of a certain name loaded before
140                         * with loadScript() method.
141                         *
142                         * @param name Unique name for the script
143                         * @param runOnce If true the script will be executed only one time
144                         * @param immediate If true the script will be run immediately. If false
145                         * the script will be added as a task into the kernel, and will be started
146                         * in the next execution cycle.
147                         *
148                         * @return Returning code of IScript::execute() method.
149                         **/
150                        Result execute(const std::string& name, bool runOnce = true, bool immediate = false);
151
152                        /**
153                         * Combined method of load() and execute(). See documentation for them
154                         * instead
155                         **/
156                        Result execute(const std::string& name, const std::string& fileName, bool runOnce = true, bool immediate = false);
157
158                        /**
159                         * Get count of functions registered in the database
160                         **/
161                        NR_FORCEINLINE uint32 getFunctionCount() const { return mDatabase.size(); }
162
163                        /**
164                         * Return an functor element of a certain index from the database.
165                         * Any functor element is a pair of the functor and script parameters
166                         * defined by the user.
167                         **/
168                        const std::string& getFunction(uint32 index, ScriptFunctor& functor);
169                                       
170                private:
171
172                        //! Run not by name, but by pointer
173                        Result _execute(const ResourcePtr<IScript>& ptr, bool runOnce = true, bool immediate = false);
174
175                        //! Only engine is allowed to create the instances
176                        friend class Engine;
177
178                        //! Allocate memory and define all default values
179                        ScriptEngine();
180
181                        //! Release used memory and close the scripting engine
182                        ~ScriptEngine();
183
184                        //! This is our database holding the registered functions
185                        typedef std::map<std::string, std::pair<ScriptFunctor, std::vector<ScriptParam> > > FunctionDatabase;
186
187                        //! Here we store our registered functions
188                        FunctionDatabase mDatabase;
189
190                        //! Check whenever a function with the given name is already in the database
191                        bool isRegistered(const std::string& name);
192
193                        //! Get  the function according to the given name
194                        FunctionDatabase::iterator get(const std::string& name);
195
196
197                        ScriptFunctionDef(scriptLoad);
198                        ScriptFunctionDef(scriptRun);
199                        ScriptFunctionDef(scriptLoadAndRun);
200                        ScriptFunctionDef(scriptCall);
201                       
202        };
203
204
205};
206
207#endif
Note: See TracBrowser for help on using the repository browser.