Planet
navi homePPSaboutscreenshotsdownloaddevelopmentforum

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

Last change on this file since 11881 was 11071, checked in by landauf, 9 years ago

merged branch cpp11_v3 back to trunk

  • Property svn:eol-style set to native
File size: 9.1 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/**
31    @file Script.h
32    @brief Definition of the Script class.
33    @ingroup Objects
34*/
35
36#ifndef _Script_H__
37#define _Script_H__
38
39#include "objects/ObjectsPrereqs.h"
40
41#include <string>
42#include <vector>
43
44#include "core/BaseObject.h"
45#include "network/ClientConnectionListener.h"
46
47namespace orxonox
48{
49
50    /**
51    @brief The mode a specific @ref orxonox::Script "Script" is in.
52    */
53    enum class ScriptMode
54    {
55        normal, //!< The @ref orxonox::Script "Scripts'" code is executed through the @ref orxonox::CommandExecutor "CommandExecutor".
56        lua //!< The @ref orxonox::Script "Scripts'" code is executed through lua.
57    };
58
59    /**
60    @brief
61        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.
62        There are three parameters:
63        - @b code The code that should be executed.
64        - @b mode The mode, specifying whether the set code should be executed the normal way (<em>normal</em>) or in lua (<em>lua</em>). Default is <em>normal</em>.
65        - @b 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 <em>forAll</em>. Default is true.
66        - @b needsGraphics Whether the code needs graphics to be executed or not. Default is false.
67        - @b 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 @ref orxonox::PlayerTrigger "PlayerTrigger".
68
69        Here are two examples illustrating the usage:
70        @code
71        <Script code="showGUI QuestGUI" needsGraphics=true />
72        @endcode
73        This would show the QuestGUI opon creation of the object. The <em>mode</em> is <em>normal</em>, not specified here since that is the default, also <em>onLoad</em> is true, also not specified, since it is the default as well. Also <em>needsGraphics</em> is set to true because showGUI needs graphics to work.
74
75        @code
76        <Script code="hideGUI QuestGUI" mode="normal" onLoad="false" needsGraphics=true >
77            <events>
78                <trigger>
79                    <DistanceTrigger distance=10 target="Pawn" />
80                </trigger>
81            </events>
82        </Script>
83        @endcode
84        This would hide the QuestGUI as soon as a @ref orxonox::Pawn "Pawn" got in range of the @ref orxonox::DistanceTrigger "DistanceTrigger". The mode is <em>normal</em>, it is specified here, but could be ommitted as well, since it is the default. <em>OnLoad</em> is false, that is why it can't be ommitted. Also <em>needsGraphics</em> is set to true because showGUI needs graphics to work.
85
86    @author
87        Benjamin Knecht
88    @author
89        Damian 'Mozork' Frick
90    */
91    class _ObjectsExport Script : public BaseObject, public ClientConnectionListener
92    {
93        public:
94            Script(Context* context);
95            virtual ~Script();
96
97            virtual void XMLPort(Element& xmlelement, XMLPort::Mode mode) override; //!< Method for creating a Script object through XML.
98            virtual void XMLEventPort(Element& xmlelement, XMLPort::Mode mode) override; //!< Creates a port that can be used to channel events and react to them.
99
100            bool trigger(bool triggered, BaseObject* trigger); //!< Is called when an event comes in trough the event port.
101            void execute(unsigned int clientId, bool onLoad = false); //!< Executes the Scripts code for the input client, depending on the mode.
102            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.
103
104            /**
105            @brief Sets the code that is executed by this Script.
106            @param code  The code that is executed by this Script.
107            */
108            inline void setCode(const std::string& code)
109                { code_ = code; }
110            /**
111            @brief Get the code that is executed by this Script.
112            @return Returns the code that is executed by this Script.
113            */
114            inline const std::string& getCode() const
115                { return code_; }
116
117            void setMode(const std::string& mode); //!< Sets the mode of the Script.
118            const std::string& getMode(void); //!< Get the mode of the Script.
119
120            /**
121            @brief Set whether this Script is executed onLoad or not.
122            @param onLoad if true the Script is executed onLoad, if false it's not.
123            */
124            inline void setOnLoad(bool onLoad)
125                { this->onLoad_ = onLoad; }
126            /**
127            @brief Get whether this Script is executed onLoad.
128            @return Returns true if this Script is executed onLoad, false if not.
129            */
130            inline bool isOnLoad(void)
131                { return this->onLoad_; }
132
133            void setTimes(int times); //!< Set the number of times this Script is executed at the most.
134            /**
135            @brief Get the number of times this Script is executed at the most.
136            @return Returns the number of times this Script is executed at the most. -1 denotes infinity.
137            */
138            inline int getTimes(void)
139                { return this->times_; }
140
141            /**
142            @brief Set whether the code to be executed needs graphics to work.
143            @param needsGraphics True if the cde needs graphics to be executed properly.
144            */
145            void setNeedsGraphics(bool needsGraphics)
146                { this->needsGraphics_ = needsGraphics; }
147            /**
148            @brief Get whether the code to be executed needs graphics to work.
149            @return Returns true if the code needs graphic, false if not.
150            */
151            bool getNeedsGraphics(void)
152                { return this->needsGraphics_; }
153
154            /**
155            @brief Set whether the code is executed for all players or just for the player triggering the Script.
156            @param forAll If true the code is executed for all players.
157            */
158            void setForAll(bool forAll)
159                { this->forAll_ = forAll; }
160            /**
161            @brief Get whether the Script executes its code for all players or just for the player triggering the Script.
162            @return Returns true if the code is executed for all players, false if not.
163            */
164            bool isForAll(void)
165                { return this->forAll_; }
166
167            virtual void clientConnected(unsigned int clientId) override; //!< Callback that is called when a new client has connected.
168            virtual void clientDisconnected(unsigned int clientid) override {}
169
170        private:
171            //! Static variables to avoid magic strings.
172            static const std::string NORMAL;
173            static const std::string LUA;
174            static const int INF;
175
176            std::string code_; //!< The code that is executed by this Script.
177            ScriptMode mode_; //!< The mode the Script is in. Determines whether the code is executed the normal way or in lua.
178            std::string modeStr_; //!< The mode the Script is in, as a string. Is used for networking purposes.
179            bool onLoad_; //!< Whether the Scripts code is executed upon loading (creation) of this Script.
180            int times_; //!< The number of times the Scripts code is executed at the most. -1 denotes infinity.
181            bool needsGraphics_; //!< Whether the code to be executed needs graphics.
182            bool forAll_; //!< Whether the code is executed for all players (in a multiplayer setup) or just for the one triggering the Script.
183
184            int remainingExecutions_; //!< The number of remainign executions. -1 denotes infinity.
185
186            void modeChanged(); //!< Sets the mode to the mode specified in this->modeStr_.
187
188            /**
189            @brief Sets the mode of the Script.
190            @param mode The mode of the Script.
191            */
192            inline void setMode(ScriptMode mode)
193                { this->mode_ = mode; }
194    };
195}
196
197#endif /* _Script_H__ */
Note: See TracBrowser for help on using the repository browser.