Planet
navi homePPSaboutscreenshotsdownloaddevelopmentforum

source: code/trunk/src/modules/objects/Script.h @ 7486

Last change on this file since 7486 was 7486, checked in by dafrick, 14 years ago

Cleanup in Script. Some more documenting in Notifications module.

  • Property svn:eol-style set to native
File size: 8.7 KB
Line 
1
2/*
3 *   ORXONOX - the hottest 3D action shooter ever to exist
4 *                    > www.orxonox.net <
5 *
6 *
7 *   License notice:
8 *
9 *   This program is free software; you can redistribute it and/or
10 *   modify it under the terms of the GNU General Public License
11 *   as published by the Free Software Foundation; either version 2
12 *   of the License, or (at your option) any later version.
13 *
14 *   This program is distributed in the hope that it will be useful,
15 *   but WITHOUT ANY WARRANTY; without even the implied warranty of
16 *   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
17 *   GNU General Public License for more details.
18 *
19 *   You should have received a copy of the GNU General Public License
20 *   along with this program; if not, write to the Free Software
21 *   Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
22 *
23 *   Author:
24 *      Benjamin Knecht
25 *   Co-authors:
26 *      Damian 'Mozork' Frick
27 *
28 */
29
30#ifndef _Script_H__
31#define _Script_H__
32
33#include "objects/ObjectsPrereqs.h"
34
35#include <string>
36#include <vector>
37
38#include "core/BaseObject.h"
39#include "network/ClientConnectionListener.h"
40
41namespace orxonox
42{
43
44    namespace ScriptMode
45    {
46        //! Modes of the Script class.
47        enum Value
48        {
49            normal,
50            lua
51        };
52    }
53
54    /**
55    @brief
56        The Script class lets you execute a piece of code, either the normal way or in lua, through XML. It can be specified whether the code is executed upon loading (creation) of the object. Additionally the code is executed each time a trigger event comes in.
57        There are three parameters:
58        'code': The code that should be executed.
59        'mode': The mode, specifying whether the set code should be executed the normal way ('normal') or in lua ('lua'). Default is 'normal'.
60        'onLoad': Whether the code is executed upon loading (creation) of this object. If this is set the code is executed ofr all players, regardless of the value of parameter 'forAll'. Default is true.
61        'needsGraphics': Whether the code needs graphics to be executed or not. Default is false.
62        'forAll': Whether the code is executed for all players each time the Script is triggered or jut for the player triggering the Script. If forAll is false, which is default, the event that triggers the Script must come from a PlayerTrigger.
63
64        Here are two examples illustrating the usage:
65        @code
66        <Script code="showGUI QuestGUI" needsGraphics=true />
67        @endcode
68        This would show the QuestGUI opon creation of the object. The mode is 'normal', not specified here since that is the default, also onLoad is true, also not specified, since it is the default as well. Also needsGraphics is set to true because showGUI needs graphics to work.
69
70        @code
71        <Script code="hideGUI QuestGUI" mode="normal" onLoad="false" needsGraphics=true >
72            <events>
73                <trigger>
74                    <DistanceTrigger distance=10 target="Pawn" />
75                </trigger>
76            </events>
77        </Script>
78        @endcode
79        This would hide the QuestGUI as soon as a Pawn got in range of the DistanceTrigger. The mode is 'normal', it is specified here, but could be ommitted as well, since it is the default. OnLoad is false, that is why it can't be ommitted. Also needsGraphics is set to true because showGUI needs graphics to work.
80    @author
81        Benjamin Knecht
82    @author
83        Damian 'Mozork' Frick
84    */
85    class _ObjectsExport Script : public BaseObject, public ClientConnectionListener
86    {
87        public:
88            Script(BaseObject* creator);
89            virtual ~Script();
90
91            virtual void XMLPort(Element& xmlelement, XMLPort::Mode mode); //!< Method for creating a Script object through XML.
92            virtual void XMLEventPort(Element& xmlelement, XMLPort::Mode mode); //!< Creates a port that can be used to channel events and react to them.
93
94            bool trigger(bool triggered, BaseObject* trigger); //!< Is called when an event comes in trough the event port.
95            void execute(unsigned int clientId, bool onLoad = false); //!< Executes the Scripts code for the input client, depending on the mode.
96            static void executeHelper(const std::string& code, const std::string& mode, bool needsGraphics); //!< Helper method that is used to reach this Script object on other clients.
97
98            /**
99            @brief Sets the code that is executed by this Script.
100            @param code  The code that is executed by this Script.
101            */
102            inline void setCode(const std::string& code)
103                { code_ = code; }
104            /**
105            @brief Get the code that is executed by this Script.
106            @return Returns the code that is executed by this Script.
107            */
108            inline const std::string& getCode() const
109                { return code_; }
110
111            void setMode(const std::string& mode); //!< Sets the mode of the Script.
112            const std::string& getMode(void); //!< Get the mode of the Script.
113
114            /**
115            @brief Set whether this Script is executed onLoad or not.
116            @param onLoad if true the Script is executed onLoad, if false it's not.
117            */
118            inline void setOnLoad(bool onLoad)
119                { this->onLoad_ = onLoad; }
120            /**
121            @brief Get whether this Script is executed onLoad.
122            @return Returns true if this Script is executed onLoad, false if not.
123            */
124            inline bool isOnLoad(void)
125                { return this->onLoad_; }
126
127            void setTimes(int times); //!< Set the number of times this Script is executed at the most.
128            /**
129            @brief Get the number of times this Script is executed at the most.
130            @return Returns the number of times this Script is executed at the most. -1 denotes infinity.
131            */
132            inline int getTimes(void)
133                { return this->times_; }
134
135            /**
136            @brief Set whether the code to be executed needs graphics to work.
137            @param needsGraphics True if the cde needs graphics to be executed properly.
138            */
139            void setNeedsGraphics(bool needsGraphics)
140                { this->needsGraphics_ = needsGraphics; }
141            /**
142            @brief Get whether the code to be executed needs graphics to work.
143            @return Returns true if the code needs graphic, false if not.
144            */
145            bool getNeedsGraphics(void)
146                { return this->needsGraphics_; }
147
148            /**
149            @brief Set whether the code is executed for all players or just for the player triggering the Script.
150            @param forAll If true the code is executed for all players.
151            */
152            void setForAll(bool forAll)
153                { this->forAll_ = forAll; }
154            /**
155            @brief Get whether the Script executes its code for all players or just for the player triggering the Script.
156            @return Returns true if the code is executed for all players, false if not.
157            */
158            bool isForAll(void)
159                { return this->forAll_; }
160
161            virtual void clientConnected(unsigned int clientId); //!< Callback that is called when a new client has connected.
162            virtual void clientDisconnected(unsigned int clientid) {}
163
164        private:
165            //! Static variables to avoid magic strings.
166            static const std::string NORMAL;
167            static const std::string LUA;
168            static const int INF;
169
170            std::string code_; //!< The code that is executed by this Script.
171            ScriptMode::Value mode_; //!< The mode the Script is in. Determines whether the code is executed the normal way or in lua.
172            std::string modeStr_; //!< The mode the Script is in, as a string. Is used for networking purposes.
173            bool onLoad_; //!< Whether the Scripts code is executed upon loading (creation) of this Script.
174            int times_; //!< The number of times the Scripts code is executed at the most. -1 denotes infinity.
175            bool needsGraphics_; //!< Whether the code to be executed needs graphics.
176            bool forAll_; //!< Whether the code is executed for all players (in a multiplayer setup) or just for the one triggering the Script.
177
178            int remainingExecutions_; //!< The number of remainign executions. -1 denotes infinity.
179
180            void modeChanged(); //!< Sets the mode to the mode specified in this->modeStr_.
181
182            /**
183            @brief Sets the mode of the Script.
184            @param mode The mode of the Script.
185            */
186            inline void setMode(ScriptMode::Value mode)
187                { this->mode_ = mode; }
188    };
189}
190
191#endif /* _Script_H__ */
Note: See TracBrowser for help on using the repository browser.