Planet
navi homePPSaboutscreenshotsdownloaddevelopmentforum

Ignore:
Timestamp:
Mar 23, 2011, 12:13:34 PM (14 years ago)
Author:
dafrick
Message:

More documentation for Pong.

Location:
code/branches/tetris/src/modules/pong
Files:
7 edited

Legend:

Unmodified
Added
Removed

  • code/branches/tetris/src/modules/pong/Pong.h

    r8104 r8105  
    4848    @brief
    4949        Implements a Pong minigame.
    50 
    51         //TODO: Add details to different classes used and how.
     50        It connects the different entities present in a game of Pong.
     51       
     52        //TODO: List and add details to different classes used and how.
    5253        PongBall, is the ball, PongBats are the things that can be moved by the players (ControllableEntities), PongCenterpoint is the playing field. (x-z area)
    5354

  • code/branches/tetris/src/modules/pong/PongBall.cc

    r8104 r8105  
    101101    @brief
    102102        Is called every tick.
    103         //TODO: Explain in detail what happens here.
     103        Handles the movement of the ball and its interaction with the boundaries and bats.
    104104    @param dt
    105105        The time since the last tick.
    … …  
    226226    /**
    227227    @brief
    228         Set the
     228        Set the bats for the ball.
     229    @param bats
     230        An array (of size 2) of weak pointers, to be set as the new bats.
    229231    */
    230232    void PongBall::setBats(WeakPtr<PongBat>* bats)
    231233    {
    232         if (this->bDeleteBats_)
     234        if (this->bDeleteBats_) // If there are already some bats, delete them.
    233235        {
    234236            delete[] this->bat_;
    … …  
    237239
    238240        this->bat_ = bats;
     241        // Also store their object IDs, for synchronization.
    239242        this->batID_[0] = this->bat_[0]->getObjectID();
    240243        this->batID_[1] = this->bat_[1]->getObjectID();
    241244    }
    242245
     246    /**
     247    @brief
     248        Get the bats over the network.
     249    */
    243250    void PongBall::applyBats()
    244251    {
    245         if (!this->bat_)
     252        // Make space for the bats, if they don't exist, yet.
     253        if (this->bat_ == NULL)
    246254        {
    247255            this->bat_ = new WeakPtr<PongBat>[2];

  • code/branches/tetris/src/modules/pong/PongBall.h

    r8104 r8105  
    4747    /**
    4848    @brief
    49         This class manages the ball for Pong.
     49        This class manages the ball for @ref orxonox::Pong "Pong".
    5050
    51         //TODO: Describe what it's responnsibilities are.
    52         Only moves in x-z area.
     51        It is responsible for both the movement of the ball in the x,z-plane as well as its interaction with the boundaries of the playing field (defined by the @ref orxonox::PongCenterpoint "PongCenterpoint") and the @ref orxonox::PongBat "PongBats". Or more precisely, it makes the ball bounce off then upper and lower delimiters of the playing field, it makes the ball bounce off the bats and also detects when a player scores and takes appropriate measures.
    5352
    5453    @author
    … …  
    6564            virtual void tick(float dt);
    6665
     66            /**
     67            @brief Set the dimensions of the playing field.
     68            @param width The width of the playing field.
     69            @param height The height of the playing field.
     70            */
    6771            void setFieldDimension(float width, float height)
    6872                { this->fieldWidth_ = width; this->fieldHeight_ = height; }
     73            /**
     74            @brief Get the dimensions of the playing field.
     75            @param dimension A vector with the width as the first and height as the second component.
     76            */
    6977            void setFieldDimension(const Vector2& dimension)
    7078                { this->setFieldDimension(dimension.x, dimension.y); }
     79            /**
     80            @brief Get the dimensions of the playing field.
     81            @return Returns a vector with the width as the first and height as the second component.
     82            */
    7183            Vector2 getFieldDimension() const
    7284                { return Vector2(this->fieldWidth_, this->fieldHeight_); }
    7385
    74             void setSpeed(float speed);
     86            void setSpeed(float speed); //!< Set the speed of the ball (in x-direction).
     87            /**
     88            @brief Get the speed of the ball (in x-direction).
     89            @return Returns the speed of the ball (in x-direction).
     90            */
    7591            float getSpeed() const
    7692                { return this->speed_; }
    7793
     94            /**
     95            @brief Set the acceleration factor of the ball.
     96            @param factor The factor the acceleration of the ball is set to.
     97            */
    7898            void setAccelerationFactor(float factor)
    7999                { this->accelerationFactor_ = factor; }
     100            /**
     101            @brief Get the acceleration factor of the ball.
     102            @return Returns the acceleration factor of the ball.
     103            */
    80104            float getAccelerationFactor() const
    81105                { return this->accelerationFactor_; }
    82106
     107            /**
     108            @brief Set the length of the bats.
     109            @param batlength The length of the bats (in z-direction) as percentage of the height of the playing field.
     110            */
    83111            void setBatLength(float batlength)
    84112                { this->batlength_ = batlength; }
     113            /**
     114            @brief Get the length of the bats.
     115            @return Returns the length of the bats (in z-direction) as percentage of the height of the playing field.
     116            */
    85117            float getBatLength() const
    86118                { return this->batlength_; }
    87119
    88             void setBats(WeakPtr<PongBat>* bats);
    89             void applyBats();
     120            void setBats(WeakPtr<PongBat>* bats); //!< Set the bats for the ball.
     121            void applyBats(); //!< Get the bats over the network.
    90122
     123            // TODO: What is this exactly?
    91124            static const float MAX_REL_Z_VELOCITY;
    92125
    … …  
    94127            void registerVariables();
    95128
    96             float fieldWidth_;
    97             float fieldHeight_;
    98             float speed_;
    99             float accelerationFactor_;
    100             float batlength_;
    101             WeakPtr<PongBat>* bat_;
    102             bool bDeleteBats_;
    103             unsigned int* batID_;
    104             float relMercyOffset_;
     129            float fieldWidth_; //!< The width of the playing field.
     130            float fieldHeight_; //!< The height of the playing field.
     131            float speed_; //!< The speed (in x-direction) of the ball.
     132            float accelerationFactor_; //!< The acceleration factor of the ball.
     133            float batlength_; //!< The length of the bats (in z-direction) as percentage of the height of the playing field.
     134            WeakPtr<PongBat>* bat_; //!< An array with the two bats.
     135            bool bDeleteBats_; //!< Bool, to keep track, of whether bat_ exists or not.
     136            unsigned int* batID_; //!< The object IDs of the bats, to be able to synchronize them over the network.
     137            float relMercyOffset_; //!< Offset, that makes the player not loose, when, in all fairness, he would have.
    105138    };
    106139}

  • code/branches/tetris/src/modules/pong/PongBat.cc

    r5781 r8105  
    2727 */
    2828
     29/**
     30    @file PongBat.cc
     31    @brief Implementation of the PongBat class.
     32*/
     33
    2934#include "PongBat.h"
    3035
    … …  
    3641    CreateFactory(PongBat);
    3742
     43    /**
     44    @brief
     45        Constructor. Registers and initializes the object.
     46    */
    3847    PongBat::PongBat(BaseObject* creator) : ControllableEntity(creator)
    3948    {
    … …  
    5059    }
    5160
     61    /**
     62    @brief
     63        Registers variables to be synchronized over the network.
     64    */
    5265    void PongBat::registerVariables()
    5366    {
    … …  
    5770    }
    5871
     72    /**
     73    @brief
     74        Is called each tick.
     75        //TODO detailed
     76    @param dt
     77        The time since last tick.
     78    */
    5979    void PongBat::tick(float dt)
    6080    {
     81        // If the bat is controlled (but not over the network).
    6182        if (this->hasLocalController())
    6283        {
    6384            if (this->movement_ != 0)
    6485            {
     86                // The absolute value of the movement is restricted to be lesser or equal than the speed of the bat.
    6587                this->movement_ = clamp(this->movement_, -1.0f, 1.0f) * this->speed_;
    6688
     89                //TODO What does this?
    6790                if (this->bMoveLocal_)
    6891                    this->setVelocity(this->getOrientation() * Vector3(this->movement_, 0, 0));
    … …  
    84107        SUPER(PongBat, tick, dt);
    85108
     109        // Restrict the position of the bats, for them to always be between the upper and lower delimiters. i.e. the bats stall if they reach the upper or lower boundary.
    86110        Vector3 position = this->getPosition();
    87111        if (position.z > this->fieldHeight_ / 2 - this->fieldHeight_ * this->length_ / 2)
    … …  
    96120    }
    97121
     122    /**
     123    @brief
     124        Overloaded the function to steer the bat up and down.
     125    @param value
     126        A vector whose first component is the inverse direction in which we want to steer the bat.
     127    */
    98128    void PongBat::moveFrontBack(const Vector2& value)
    99129    {
    … …  
    102132    }
    103133
     134    /**
     135    @brief
     136        Overloaded the function to steer the bat up and down.
     137    @param value
     138        A vector whose first component is the direction in which we wnat to steer the bat.
     139    */
    104140    void PongBat::moveRightLeft(const Vector2& value)
    105141    {
    … …  
    108144    }
    109145
     146    /**
     147    @brief
     148        Is called when the player changed.
     149    */
    110150    void PongBat::changedPlayer()
    111151    {

  • code/branches/tetris/src/modules/pong/PongBat.h

    r7163 r8105  
    2727 */
    2828
     29/**
     30    @file PongBat.h
     31    @brief Declaration of the PongBat class.
     32    @ingroup Pong
     33*/
     34
    2935#ifndef _PongBat_H__
    3036#define _PongBat_H__
    3137
    3238#include "pong/PongPrereqs.h"
     39
    3340#include "worldentities/ControllableEntity.h"
    3441
    3542namespace orxonox
    3643{
     44
     45    /**
     46    @brief
     47        The PongBat class manages the bats for @ref orxonox::Pong "Pong", which are the elements controlled by the player.
     48       
     49        It is responsible for the movement (controlled by the players) of the bat.
     50       
     51    @author
     52        Fabian 'x3n' Landau
     53       
     54    @ingroup Pong
     55    */
    3756    class _PongExport PongBat : public ControllableEntity
    3857    {
    3958        public:
    40             PongBat(BaseObject* creator);
     59            PongBat(BaseObject* creator); //!< Constructor. Registers and initializes the object.
    4160            virtual ~PongBat() {}
    4261
    4362            virtual void tick(float dt);
    4463
    45             virtual void moveFrontBack(const Vector2& value);
    46             virtual void moveRightLeft(const Vector2& value);
     64            virtual void moveFrontBack(const Vector2& value); //!< Overloaded the function to steer the bat up and down.
     65            virtual void moveRightLeft(const Vector2& value); //!< Overloaded the function to steer the bat up and down.
    4766
    48             virtual void changedPlayer();
     67            virtual void changedPlayer(); //!< Is called when the player changed.
    4968
     69            /**
     70            @brief Set the speed of the bat.
     71            @param speed The speed to be set.
     72            */
    5073            void setSpeed(float speed)
    5174                { this->speed_ = speed; }
     75            /**
     76            @brief Get the speed of the bat.
     77            @return Returns the speed of the bat.
     78            */
    5279            float getSpeed() const
    5380                { return this->speed_; }
    5481
     82            /**
     83            @brief Set the height of the playing field.
     84            @param height The height of the playing field.
     85            */
    5586            void setFieldHeight(float height)
    5687                { this->fieldHeight_ = height; }
     88            /**
     89            @brief Get the height of the playing field.
     90            @return Returns the height of the playing field.
     91            */
    5792            float getFieldHeight() const
    5893                { return this->fieldHeight_; }
    5994
     95            /**
     96            @brief Set the length of the bat.
     97            @param length The length of the bat (in z-direction) as percentage of the height of the playing field.
     98            */
    6099            void setLength(float length)
    61100                { this->length_ = length; }
     101            /**
     102            @brief get the length of the bat.
     103            @return Returns the length of the bat (in z-direction) as percentage of the height of the playing field.
     104            */
    62105            float getLength() const
    63106                { return this->length_; }
    64107
    65108        private:
    66             void registerVariables();
     109            void registerVariables(); //!< Registers variables to be synchronized over the network.
    67110
    68             float movement_;
    69             bool bMoveLocal_;
    70             float speed_;
    71             float length_;
    72             float fieldHeight_;
    73             bool bSteadiedPosition_;
     111            float movement_; //!< The amount (and direction), in z-direction, of movement of the bat.
     112            bool bMoveLocal_; //TODO ???
     113            float speed_; //!< The movementspeed of the bat.
     114            float length_; //!< The length of the bat (in z-direction) as percentage of the height of the playing field.
     115            float fieldHeight_; //!< The height of the playing field.
     116            bool bSteadiedPosition_; //TODO: ???
    74117    };
    75118}

  • code/branches/tetris/src/modules/pong/PongCenterpoint.cc

    r5929 r8105  
    2727 */
    2828
     29/**
     30    @file PongCenterpoint.cc
     31    @brief Implementation of the PongCenterpoint class.
     32*/
     33
    2934#include "PongCenterpoint.h"
    3035
    3136#include "core/CoreIncludes.h"
    3237#include "core/XMLPort.h"
     38
    3339#include "Pong.h"
    3440
    … …  
    3743    CreateFactory(PongCenterpoint);
    3844
     45    /**
     46    @brief
     47        Constructor. Registers and initializes the object and checks whether the gametype is actually Pong.
     48    */
    3949    PongCenterpoint::PongCenterpoint(BaseObject* creator) : StaticEntity(creator)
    4050    {
    … …  
    5161    }
    5262
     63    /**
     64    @brief
     65        Method to create a PongCenterpoint through XML.
     66    */
    5367    void PongCenterpoint::XMLPort(Element& xmlelement, XMLPort::Mode mode)
    5468    {
    … …  
    6478    }
    6579
     80    /**
     81    @brief
     82        Is called when the gametype has changed.
     83    */
    6684    void PongCenterpoint::changedGametype()
    6785    {
    6886        SUPER(PongCenterpoint, changedGametype);
    6987
     88        // Check, whether it's still Pong.
    7089        this->checkGametype();
    7190    }
    7291
     92    /**
     93    @brief
     94        Checks whether the gametype is Pong and if it is, sets its centerpoint.
     95    */
    7396    void PongCenterpoint::checkGametype()
    7497    {
    75         if (this->getGametype() && this->getGametype()->isA(Class(Pong)))
     98        if (this->getGametype() != NULL && this->getGametype()->isA(Class(Pong)))
    7699        {
    77             Pong* pong_gametype = orxonox_cast<Pong*>(this->getGametype().get());
    78             pong_gametype->setCenterpoint(this);
     100            Pong* pongGametype = orxonox_cast<Pong*>(this->getGametype().get());
     101            pongGametype->setCenterpoint(this);
    79102        }
    80103    }

  • code/branches/tetris/src/modules/pong/PongCenterpoint.h

    r5929 r8105  
    2727 */
    2828
     29/**
     30    @file PongCenterpoint.h
     31    @brief Declaration of the PongCenterpoint class.
     32    @ingroup Pong
     33*/
     34
    2935#ifndef _PongCenterpoint_H__
    3036#define _PongCenterpoint_H__
    … …  
    3339
    3440#include <string>
     41
    3542#include <util/Math.h>
     43
    3644#include "worldentities/StaticEntity.h"
    3745
    3846namespace orxonox
    3947{
     48   
     49    /**
     50    @brief
     51        The PongCenterpoint implements the playing field @ref orxonox::Pong "Pong" takes place in and allows for many parameters of the minigame to be set.
     52        The playing field resides in the x,z-plane, with the x-axis being the horizontal axis and the z-axis being the vertical axis.
     53       
     54        Various parameters can be set:
     55        - The <b>dimension</b> is a vector, that defines the width and height of the playing field. The default is <em>(200, 120)</em>.
     56        - The <b>balltemplate</b> is a template that is applied to the @ref orxonox::PongBall "PongBall", it can be used to attach different things to it, e.g. its @ref orxonox::Model "Model". See below for a usage example.
     57        - The <b>battemplate</b> is a template that is applied to the @ref orxonox::PongBall "PongBat", it can be used to attach different things to it, e.g. its @ref orxonox::Model "Model". See below for a usage example.
     58        - The <b>ballspeed</b> is the speed with wich the @ref orxonox::PongBall "PongBall" moves. The default is <em>100</em>.
     59        - The <b>ballaccfactor</b> is the acceleration factor for the @ref orxonox::PongBall "PongBall". The default is <em>1.0</em>.
     60        - The <b>batspeed</b> is the speed with which the @ref orxonox::PongBat "PongBats" move. The default is <em>60</em>.
     61        - The <b>batlength</b> is the length of the @ref orxonox::PongBat "PongBats" as the percentage of the height of the playing field. The default is <em>0.25</em>.
     62       
     63        An example in XML of the PongCenterpoint would be:
     64       
     65        First the needed templates:
     66        The template for the @ref orxonox::PongBall "PongBall".
     67        @code
     68        <Template name="pongball">
     69          <PongBall>
     70            <attached>
     71              <Model mesh="sphere.mesh" scale="2" />
     72              <ParticleSpawner name="hiteffect" position="0,0,0" source="Orxonox/sparks2" lifetime="0.01" autostart="0" mainstate="spawn" />
     73            </attached>
     74            <eventlisteners>
     75              <EventTarget target="hiteffect" />
     76            </eventlisteners>
     77          </PongBall>
     78        </Template>
     79        @endcode
     80        As can be seen, a sphere is attached as the @ref orxonox::Model "Model" for the @ref orxonox::PongBall "PongBall", and also an @ref orxonox::EventListener "EventListener" that triggers a @ref orxonox::ParticleSpawner "ParticleSpawner", whenever the ball hits the boundaries is attached.
     81       
     82        Additionally the template for the @ref orxonox::PongBat "PongBat".
     83        @code
     84        <Template name="pongbatcameras" defaults="0">
     85          <PongBat>
     86            <camerapositions>
     87              <CameraPosition position="0,200,0" pitch="-90" absolute="true" />
     88            </camerapositions>
     89          </PongBat>
     90        </Template>
     91
     92        <Template name="pongbat">
     93          <PongBat camerapositiontemplate=pongbatcameras>
     94            <attached>
     95              <Model position="0,0,3" mesh="cube.mesh" scale3D="14,2,2" />
     96            </attached>
     97          </PongBat>
     98        </Template>
     99        @endcode
     100        As can be seen, there are actually two templates. The first template is needed to set the camera for the @ref orxonox::PongBat "PongBat". The second template ist the actual template for the @ref orxonox::PongBat "PongBat", the template for the camera position is added and a @ref orxonox::Model "Model" for the @ref orxonox::PongBat "PongBat" is attached.
     101       
     102        Finally the PongCenterpoint is created.
     103        @code
     104        <PongCenterpoint name="pongcenter" dimension="200,120" balltemplate="pongball" battemplate="pongbat" ballspeed="200" ballaccfactor="1.0" batspeed="130" batlength="0.25">
     105          <attached>
     106            <Model position="0,0,60" mesh="cube.mesh" scale3D="105,1,1" />
     107            <Model position="0,0,-60" mesh="cube.mesh" scale3D="105,1,1" />
     108          </attached>
     109        </PongCenterpoint>
     110        @endcode
     111        All parameters are specified. And also two @ref orxonox::Model "Models" (for the upper and lower boundary) are attached.
     112       
     113        For a more elaborate example, have a look at the <code>pong.oxw</code> level file.
     114   
     115    @author
     116        Fabian 'x3n' Landau
     117       
     118    @ingroup Pong
     119    */
    40120    class _PongExport PongCenterpoint : public StaticEntity
    41121    {
    42122        public:
    43             PongCenterpoint(BaseObject* creator);
     123            PongCenterpoint(BaseObject* creator); //!< Constructor. Registers and initializes the object and checks whether the gametype is actually Pong.
    44124            virtual ~PongCenterpoint() {}
    45125
    46             virtual void XMLPort(Element& xmlelement, XMLPort::Mode mode);
    47 
    48             virtual void changedGametype();
    49 
     126            virtual void XMLPort(Element& xmlelement, XMLPort::Mode mode); //!< Method to create a PongCenterpoint through XML.
     127
     128            virtual void changedGametype(); //!< Is called when the gametype has changed.
     129
     130            /**
     131            @brief Set the template for the ball. (e.g. to attach the model of the ball, but also to attach an EventListener to it to detect, when it hits the boundaries, and e.g. display some ParticleEffets, when it does.)
     132            @param balltemplate The name of the template to be set.
     133            */
    50134            void setBalltemplate(const std::string& balltemplate)
    51135                { this->balltemplate_ = balltemplate; }
     136            /**
     137            @brief Get the template of the ball.
     138            @return Returns the name of the template of the ball.
     139            */
    52140            const std::string& getBalltemplate() const
    53141                { return this->balltemplate_; }
    54142
     143            /**
     144            @brief Set the template for the bats. (e.g. to attach the model of the bat, but also to attach CameraPositions to it, to be able to view the game from the bats perspective)
     145            @param battemplate The name of the template to be set.
     146            */
    55147            void setBattemplate(const std::string& battemplate)
    56148                { this->battemplate_ = battemplate; }
     149            /**
     150            @brief Get the template of the bats.
     151            @return Returns the name of the template of the bats.
     152            */
    57153            const std::string& getBattemplate() const
    58154                { return this->battemplate_; }
    59155
     156            /**
     157            @brief Set the dimensions of the playing field.
     158            @param dimension A vector with the width of the playing field as first component and the height as second.
     159            */
    60160            void setFieldDimension(const Vector2& dimension)
    61161                { this->width_ = dimension.x; this->height_ = dimension.y; }
     162            /**
     163            @brief Get the dimensions of the playing field.
     164            @return Returns a vector with the width of the playing field as first component and the height as second.
     165            */
    62166            Vector2 getFieldDimension() const
    63167                { return Vector2(this->width_, this->height_); }
    64168
     169            /**
     170            @brief Set the speed of the ball.
     171            @param ballspeed The speed of the ball.
     172            */
    65173            void setBallSpeed(float ballspeed)
    66174                { this->ballspeed_ = ballspeed; }
     175            /**
     176            @brief Get the speed of the ball.
     177            @return Returns the speed of the ball.
     178            */
    67179            float getBallSpeed() const
    68180                { return this->ballspeed_; }
    69181
     182            /**
     183            @brief Set the ball's acceleration factor.
     184            @param ballaccfactor The ball's acceleration factor.
     185            */
    70186            void setBallAccelerationFactor(float ballaccfactor)
    71187                { this->ballaccfactor_ = ballaccfactor; }
     188            /**
     189            @brief Get the ball's acceleration factor
     190            @return Returns the ball's acceleration factor.
     191            */
    72192            float getBallAccelerationFactor() const
    73193                { return this->ballaccfactor_; }
    74194
     195            /**
     196            @brief Set the speed of the bats.
     197            @param batspeed The speed of the bats.
     198            */
    75199            void setBatSpeed(float batspeed)
    76200                { this->batspeed_ = batspeed; }
     201            /**
     202            @brief Get the speed of the bats.
     203            @return Returns the speed of the bats.
     204            */
    77205            float getBatSpeed() const
    78206                { return this->batspeed_; }
    79207
     208            /**
     209            @brief Set the length of the bats.
     210            @param batlength The length of the bats (in z-direction) as a percentage of the height of the playing field.
     211            */
    80212            void setBatLength(float batlength)
    81213                { this->batlength_ = batlength; }
     214            /**
     215            @brief Get the length of the bats.
     216            @return Returns the length of the bats (in z-direction) as a percentage of the height of the playing field.
     217            */
    82218            float getBatLength() const
    83219                { return this->batlength_; }
    84220
    85221        private:
    86             void checkGametype();
    87 
    88             std::string balltemplate_;
    89             std::string battemplate_;
    90 
    91             float ballspeed_;
    92             float ballaccfactor_;
    93             float batspeed_;
    94             float batlength_;
    95 
    96             float width_;
    97             float height_;
     222            void checkGametype(); //!< Checks whether the gametype is Pong and if it is, sets its centerpoint.
     223
     224            std::string balltemplate_; //!< The template for the ball.
     225            std::string battemplate_; //!< The template for the batts.
     226
     227            float ballspeed_; //!< The speed of then ball.
     228            float ballaccfactor_; //!< The acceleration factor of the ball.
     229            float batspeed_; //!< The speed of the bat.
     230            float batlength_; //!< The length of the bat (in z-direction) as a percentage of the height of the playing field.
     231
     232            float width_; //!< The height of the playing field.
     233            float height_; //!< The width of the playing field.
    98234    };
    99235}
Note: See TracChangeset for help on using the changeset viewer.