Planet
navi homePPSaboutscreenshotsdownloaddevelopmentforum

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

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

Adding all classes in modules/objects to Objects module (in doxygen).
Created TriggerBase which is the base class of Trigger and MultiTrigger and now provides the shared functionality and data.
Updated some of the documentation in MultiTrigger and Script.

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