Planet
navi homePPSaboutscreenshotsdownloaddevelopmentforum

source: code/branches/portals/src/modules/pickup/PickupManager.h @ 8192

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

Documenting and cleanup.

  • Property svn:eol-style set to native
File size: 14.1 KB
Line 
1/*
2 *   ORXONOX - the hottest 3D action shooter ever to exist
3 *                    > www.orxonox.net <
4 *
5 *
6 *   License notice:
7 *
8 *   This program is free software; you can redistribute it and/or
9 *   modify it under the terms of the GNU General Public License
10 *   as published by the Free Software Foundation; either version 2
11 *   of the License, or (at your option) any later version.
12 *
13 *   This program is distributed in the hope that it will be useful,
14 *   but WITHOUT ANY WARRANTY; without even the implied warranty of
15 *   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
16 *   GNU General Public License for more details.
17 *
18 *   You should have received a copy of the GNU General Public License
19 *   along with this program; if not, write to the Free Software
20 *   Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
21 *
22 *   Author:
23 *      Damian 'Mozork' Frick
24 *   Co-authors:
25 *      ...
26 *
27*/
28
29/**
30    @file PickupManager.h
31    @brief Definition of the PickupManager class.
32    @ingroup Pickup
33*/
34
35#ifndef _PickupManager_H__
36#define _PickupManager_H__
37
38#include "PickupPrereqs.h"
39
40#include <map>
41#include "core/WeakPtr.h"
42
43#include "pickup/PickupIdentifier.h"
44
45#include "PickupRepresentation.h"
46
47#include "util/Singleton.h"
48#include "interfaces/PickupListener.h"
49
50namespace orxonox // tolua_export
51{ // tolua_export
52
53    // tolua_begin
54    /**
55    @brief
56        Data structure to store collected data for one specific @ref orxonox::Pickupable "Pickupable".
57        This is used to not have to synchronise @ref orxonox::Pickupable "Pickupable" just to have the needed information for the PickupInventory available on all clients. Instead the information is sent over the network and stored in a PickupInventoryContainer.
58
59    @ingroup Pickup
60    */
61    struct PickupInventoryContainer
62    {
63        uint32_t pickup; //!< An indentifier for the @ref orxonox::Pickupable "Pickupable" that is associated with the information stored here.
64        bool inUse; //!< Whether the @ref orxonox::Pickupable "Pickupable" is currently in use.
65        bool pickedUp; //!< Whether the @ref orxonox::Pickupable "Pickupable" is currently picked up.
66        bool usable; //!< Whether the @ref orxonox::Pickupable "Pickupable" is usable.
67        bool unusable; //!< Whether the @ref orxonox::Pickupable "Pickupable" is droppable.
68        uint32_t representationObjectId; //!< The objectId of the @ref orxonox::PickupRepresentation "PickupRepresentation" that represents the @ref orxonox::Pickupable "Pickupable".
69    };
70    // tolua_end
71
72    /**
73    @brief
74        The PickupManager class manages @ref orxonox::Pickupable "Pickupables".
75
76        It has in essence two tasks to fulfill. Firstly it must link @ref orxonox::Pickupable "Pickupables" (through their @ref orxonox::PickupIdentifier "PickupIdentifiers") to their respective @ref orxonox::PickupRepresentation "PickupRepresentations". Secondly it manages the PickupInventory. (The PickupInventory is the GUI that displays @ref orxonox::Pickupable "Pickupables" for the covenience of the user.)
77
78        @section PickupManagerTechnicalDetails Technical details
79        Unfortunately <em>under the hood</em> it isn't just as easy. At least the PickupInventory part isn't. To grasp why this is we need to have a brief look at how the pickups module works over the network:
80
81        The pickups module essentially just exists on the @ref orxonox::Server "Server", since it's all game logic. That means, a @ref orxonox::PickupSpawner "PickupSpawner" is always triggered on the server, the @ref orxonox::Pickupable "Pickupable" is then picked up (and maybe used already) on the server. The effects the pickup has are synchronised over the network, if they have to be, but this is the responsibility of the entities that are affected, not the pickups module, and normally this is already implemented. The only two things that need to be communicated over the network are the graphical component of the @ref orxonox::PickupSpawner "PickupSpawner", since it needs to be displayed on the @ref orxonox::Client "Clients" as well, and anything that is needed for the PickupInventory, since it exists for each @ref orxonox::Host "Host" seperatly.
82
83        Fortunately synchronising the @ref orxonox::PickupSpawner "PickupSpawner" is already being taken care of by the synchronisation of the @ref orxonox::StaticEntity "StaticEntity" (or parents thereof).
84
85        This leaves us with the PickupInventory component (and this is really the source of all the complexity).
86
87        Firstly there are a number of lists (where by list I really mean any kind of ordered data structure) kept.
88        - The @ref orxonox::PickupManager::representations_ "representations_" list links @ref orxonox::PickupRepresentation "PickupRepresentations" with @ref orxonox::PickupIdentifier "PickupIdentifiers" and can be used to get the @ref orxonox::PickupRepresentation "PickupRepresentation" for a given @ref orxonox::Pickupable "Pickupable". It is only populated on the server (or in standalone mode). Each @ref orxonox::PickupRepresentation "PickupRepresentation" that is generated through XML registers itself with the PickupManager and is thereby added to the list.
89        - The @ref orxonox::PickupManager::representationsNetworked_ "representationsNetworked_" list is the networked (hence the name) equivalent to the @ref orxonox::PickupManager::representations_ "representations_" list. It links an objectId of a @ref orxonox::PickupRepresentation "PickupRepresentation" to a @ref orxonox::PickupRepresentation "PickupRepresentation". This list is maintained on all hosts, each representation registers itself (in its constructor) with the PickupManager. Since the representations are synchronised they are created on each host. The "same" instance on each host is identified by the same objectId and that is why we store the representations with the objectId as key. We can then use this list to get a @ref orxonox::PickupRepresentation "PickupRepresentation" for a specific @ref orxonox::Pickupable "Pickupable" (or more precisely a number identifiying that particular pickup, but we'll see that, when we look at the next list) on a client to be used in the PickupInventory.
90        - The @ref orxonox::PickupManager::pickupInventoryContainers_ "pickupInventoryContainers_" list links a number identifying a @ref orxonox::Pickupable "Pickupable" to a data structure (the @ref orxonox::PickupInventoryContainer "PickupInventoryContainer"), which contains all necessary information about that @ref orxonox::Pickupable "Pickupable". This list is maintained on all hosts, a new container is inserted when a @ref orxonox::Pickupable "Pickupable" is picked up, but only if it has been picked up by the repsective host. This list is then used by the PickupInventory to access the required information and to get the correct @ref orxonox::PickupRepresentation "PickupRepresentation".
91        - The @ref orxonox::PickupManager::pickups_ "pickups_" list links a number identifiying a @ref orxonox::Pickupable "Pickupable" to a (weak pointer to a) @ref orxonox::Pickupable "Pickupable". It is only maintained by the server (or in standalone mode), to be able to use, unuse and drop @ref orxonox::Pickupable "Pickupables" through the PickupInventory. Since @ref orxonox::Pickupable "Pickupables" only exist on the server a client that wants to change a pickups status has so send a request over the network (with the number identifying the pickup) to the server and then the server facilitates the change, using this list to map from the identifyer to the actual @ref orxonox::Pickupable "Pickupable".
92        - The @ref orxonox::PickupManager::indexes_ "indexes_" list links a @ref orxonox::Pickupable "Pickupable" to the number identifying it. This is only maintained on the server (or in standalone mode), and is used for the inverse mapping of the previous list, which means the server uses it identify pickups on clients when it communicates changes in pickups to clients.
93
94        There is communication in both directions. From server to client, when the server informs the client that the state of some @ref orxonox::Pickupable "Pickupable" has changed, during which all necessary information to create or update the PickupInventoryContainer for that pickup on the client is sent as well. Or from client to server, when the client wants the server to change the state of some @ref orxonox::Pickupable "Pickupable".
95
96    @author
97        Damian 'Mozork' Frick
98
99    @ingroup Pickup
100    */
101    class _PickupExport PickupManager // tolua_export
102        : public Singleton<PickupManager>, public PickupListener
103    { // tolua_export
104        friend class Singleton<PickupManager>;
105
106        public:
107            PickupManager(); //!< Constructor.
108            virtual ~PickupManager(); //!< Destructor.
109
110            /**
111            @brief Get the instance of the PickupManager singleton.
112            @return Returns the instance of the PickupManager singleton.
113            */
114            static PickupManager& getInstance() { return Singleton<PickupManager>::getInstance(); } // tolua_export
115
116            bool registerRepresentation(const PickupIdentifier* identifier, PickupRepresentation* representation); //!< Registers a PickupRepresentation together with the PickupIdentifier of the Pickupable the PickupRepresentation represents.
117            bool unregisterRepresentation(const PickupIdentifier* identifier, PickupRepresentation* representation); //!< Unegisters a PickupRepresentation together with the PickupIdentifier of the Pickupable the PickupRepresentation represents.
118
119            bool registerRepresentation(PickupRepresentation* representation); //!< Registers a PickupRepresentation on the host it was created.
120            bool unregisterRepresentation(PickupRepresentation* representation); //!< Unregisters a PickupRepresentation on the host it is being destroyed.
121
122            PickupRepresentation* getRepresentation(const PickupIdentifier* identifier); //!< Get the PickupRepresentation representing the Pickupable with the input PickupIdentifier.
123
124            virtual void pickupChangedUsed(Pickupable* pickup, bool used); //!< Is called by the PickupListener to notify the PickupManager, that the input Pickupable has transited to the input used state.
125            static void pickupChangedUsedNetwork(uint32_t pickup, bool inUse, bool usable, bool unusable); //!< Helper method to react to the change in the used status of a Pickupable.
126            virtual void pickupChangedPickedUp(Pickupable* pickup, bool pickedUp); //!< Is called by the PickupListener to notify the PickupManager, that the input Pickupable has transited to the input pickedUp state.
127            static void pickupChangedPickedUpNetwork(uint32_t pickup, bool usable, uint32_t representationObjectId, bool pickedUp); //!< Helper method to react to the change in the pickedUp status of a Pickupable.
128
129        // Methods to be used by the PickupInventory.
130        public:
131            // tolua_begin
132            orxonox::PickupRepresentation* getPickupRepresentation(uint32_t pickup); //!< Get the PickupRepresentation of an input indentifier for Pickupable.
133
134            int getNumPickups(void); //!< Get the number of pickups currently picked up by the player.
135            /**
136            @brief Get the next PickupInventoryContainer in the list.
137                   Use this, after having called getNumPickups() to access all the PickupInventoryContainers individually and in succession.
138            @return Returns the next PickupInventoryContainer in the list.
139            */
140            const orxonox::PickupInventoryContainer* popPickup(void)
141                { return (this->pickupsIterator_++)->second; }
142
143            void dropPickup(uint32_t pickup); //!< Drop the input Pickupable.
144            void usePickup(uint32_t pickup, bool use); //!< Use (or unuse) the input Pickupable.
145             /**
146            @brief Check whether the input Pickupable is valid, meaning that it is in the PickupManager's list and still exists.
147            @param pickup The Pickupable.
148            @return Returns true if the input Pickupable is still valid, false if not.
149            */
150            const bool isValidPickup(uint32_t pickup) const
151                { return this->pickups_.find(pickup) != this->pickups_.end(); }
152            // tolua_end
153
154            static void dropPickupNetworked(uint32_t pickup); //!< Helper method to drop the input pickup on the server.
155            static void usePickupNetworked(uint32_t pickup, bool use); //!< Helper method to use (or unuse) the input Pickupable on the server.
156
157        private:
158            static PickupManager* singletonPtr_s;
159            static const std::string guiName_s; //!< The name of the PickupInventory
160            bool guiLoaded_; //!< Whether the PickupInventory GUI has been loaded, yet.
161            uint32_t pickupHighestIndex_; //!< The highest pickup index currently in use. (not taking wrap-around into account)
162
163            PickupRepresentation* defaultRepresentation_; //!< The default PickupRepresentation.
164
165            std::map<const PickupIdentifier*, PickupRepresentation*, PickupIdentifierCompare> representations_; //!< Map linking PickupIdentifiers (representing types of Pickupables) and PickupRepresentations.
166            std::map<uint32_t, PickupRepresentation*> representationsNetworked_; //!< Map linking the PickupRepresentation's objectId to the PickupRepresentation itself. It is used for networking purposes.
167
168            std::map<uint32_t, PickupInventoryContainer*> pickupInventoryContainers_; //!< Map linking a number identifying a Pickupable to a PickupInventoryContainer, which contains all necessary information about that Pickupable.
169            std::map<uint32_t, PickupInventoryContainer*>::iterator pickupsIterator_; //!< An iterator pointing to the current Pickupable in pickupsList_.
170
171            std::map<uint32_t, WeakPtr<Pickupable>*> pickups_; //!< Map linking a number identifying a Pickupable to a weak pointer of a Pickupable.
172            std::map<Pickupable*, uint32_t> indexes_;//!< Map linking Pickupable to the number identifying it.
173
174            void updateGUI(void); //!< Updates the PickupInventory GUI.
175            uint32_t getPickupIndex(void); //!< Get a new index for a Pickupable.
176
177    }; // tolua_export
178
179} // tolua_export
180
181#endif // _PickupManager_H__
Note: See TracBrowser for help on using the repository browser.