• Main Page
  • Classes
  • Files
  • File List
  • File Members

code/include/Powerup.h

Go to the documentation of this file.
00001 /*
00002  * TetriCycle
00003  * Copyright (C) 2009, 2010 Cale Scholl
00004  *
00005  * This file is part of TetriCycle.
00006  *
00007  * TetriCycle is free software: you can redistribute it and/or modify
00008  * it under the terms of the GNU Lesser General Public License as published
00009  * by the Free Software Foundation, either version 3 of the License, or
00010  * (at your option) any later version.
00011  *
00012  * TetriCycle is distributed in the hope that it will be useful,
00013  * but WITHOUT ANY WARRANTY; without even the implied warranty of
00014  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
00015  * GNU Lesser General Public License for more details.
00016  *
00017  * You should have received a copy of the GNU Lesser General Public License
00018  * along with TetriCycle.  If not, see <http://www.gnu.org/licenses/>.
00019  */
00020 
00021 /** @file Powerup.h
00022  * @brief Defines the Powerup class, the base class for powerups.
00023  * @author Cale Scholl / calvinss4
00024  *
00025  * Powerups must extend this class and implement all the pure virtual methods.
00026  *
00027  * @page powerupcreationpage Powerup Creation
00028  *
00029  * @section powerupnamesection Powerup Name
00030  * Choose a clever name for your powerup, such as 'clevername'.
00031  *
00032  * @section powerupimgsection Powerup Image
00033  * <ul>
00034  * <li>Select a PNG image to represent your powerup. Try to keep it small 
00035  * (in order to reduce the size of the executable). \n 
00036  * Resize the image to 32x32; if it doesn't look good, try 64x64.</li>
00037  * <li>Name the file 'powerup_clevername.png' and put the file in the following 
00038  * directory: \n
00039  * @b /ext/libwiigui/images</li>
00040  * <li>Now you must add a declaration for your powerup image. 
00041  * Open the following file: \n
00042  * <b>/ext/libwiigui/filelist.h</b> \n
00043  * Look for the comment 'powerup image declarations go here' and add the 
00044  * following lines: \n (note: please keep powerups in alphabetical order)
00045  *   <ul>
00046  *     <li><b>extern const u8   powerup_clevername_png[];</b></li>
00047  *     <li><b>extern const u32  powerup_clevername_png_size;</b></li>
00048  *   </ul>
00049  * </li>
00050  * </ul>
00051  *
00052  * @section powerupsoundsection Powerup Sound (optional)
00053  * Selecting a sound to represent your powerup is optional; if you don't 
00054  * provide one, a default sound will be played.
00055  * <ul>
00056  * <li>Select a sound to represent your powerup. The sample should be no more 
00057  * than a couple seconds long.</li>
00058  * <li>Convert your sound sample to the following format: \n
00059  * <b>PCM signed 16 bit, big endian, stereo (raw) at 44100 Hz</b></li>
00060  *   <ul>
00061  *     <li>GoldWave is a good program for converting to .pcm format.</li>
00062  *     <li>If converting from .wav to .pcm, you may have to resample at 44100 Hz.</li>
00063  *     <li>I found that if I convert from .wav to .ogg or .mp3, then convert 
00064  *         to .pcm, it's automatically sampled at the correct frequency.</li>
00065  *   </ul>
00066  * <li>Name the file 'powerup_clevername.pcm' and put the file in the following 
00067  * directory: \n
00068  * @b /ext/libwiigui/sounds</li>
00069  * <li>Now you must add a declaration for your powerup sound. 
00070  * Open the following file: \n
00071  * <b>/ext/libwiigui/filelist.h</b> \n
00072  * Look for the comment 'powerup sound declarations go here' and add the 
00073  * following lines: \n (note: please keep powerups in alphabetical order)
00074  *   <ul>
00075  *     <li><b>extern const u8   powerup_clevername_pcm[];</b></li>
00076  *     <li><b>extern const u32  powerup_clevername_pcm_size;</b></li>
00077  *   </ul>
00078  * </li>
00079  * </ul>
00080  *
00081  * @section powerupcodefilessection Powerup Code Files
00082  * Now you're ready to write the header file and source file. There are 
00083  * templates located in: \n
00084  * <b>/templates/Powerup</b> \n
00085  * You could copy these templates and modify them by hand, but I wrote a 
00086  * script that does it for you; simply run <b>Powerup.exe</b> and follow 
00087  * the on-screen instructions (if you're paranoid, you can compile the 
00088  * program from the source).
00089  * - Move the generated header file to: \n
00090  * <b>/code/include/powerups</b>
00091  * - Move the generated source file to: \n
00092  * <b>/code/source/powerups</b>
00093  * - If you added a sound for your powerup, uncomment the optional sound code
00094  *   in the header file and source file.
00095  * - The only functions you need to implement are StartEffect and StopEffect 
00096  *   (located in the source file).
00097  * - Your powerup is automagically added to the game menu.
00098  *
00099  * @section powerupoverridessection Optional Overrides
00100  * By default powerups last for 10000 milliseconds and only affect one player. 
00101  * You can override this default behavior by providing definitions for
00102  * the GetDuration and GetTargetType functions in the powerup header file. \n
00103  * There are 3 target types: \n
00104  * - <b>POWERUP_TARGET_ONE</b> - Affects the target player.
00105  * - <b>POWERUP_TARGET_ALL</b> - Affects all players.
00106  * - <b>POWERUP_TARGET_ALL_BUT_ONE</b> - Affects all but the target player.
00107  *
00108  * @section powerupbehaviorsection Powerup Behavior
00109  * Now comes the hardest part: implementing the actual powerup behavior. 
00110  * As mentioned previously, you only need to implement the StartEffect and 
00111  * StopEffect functions in the powerup source file. Look at the other powerup 
00112  * classes for examples. In general, you will have to add a state flag to 
00113  * Player::PlayerPowerupData. StartEffect will turn the flag on, and StopEffect 
00114  * will turn the flag off; some piece of game logic will operate differently 
00115  * while the flag is turned on. Good luck, you can do it!
00116  */
00117 
00118 #pragma once
00119 #ifndef __POWERUP_H__
00120 #define __POWERUP_H__
00121 
00122 #include <ogc/lwp_watchdog.h> // for gettime, ticks_to_millisecs
00123 #include <string>
00124 #include <vector>
00125 
00126 #include "defines_Powerup.h"
00127 
00128 class GuiImageData;
00129 class GuiSound;
00130 
00131 using std::string;
00132 using std::vector;
00133 
00134 /// The base class for powerups.
00135 class Powerup
00136 {
00137   friend class PowerupUtils;
00138 
00139 public:
00140   /// Initiates this powerup on the target player(s).
00141   bool Initiate(u8 targetPlayer);
00142 
00143   /// Updates the timer and terminates this powerup if its duration has been exceeded.
00144   void Update()
00145   {
00146     u64 currTime = gettime();
00147     elapsedTime += ticks_to_millisecs(currTime - startTime);
00148     startTime = currTime;
00149     if (elapsedTime >= GetDuration())
00150       Terminate();
00151   }
00152 
00153   // MUST OVERRIDE:
00154   virtual PowerupId GetPowerupId() = 0;     ///< The unique PowerupId representing this powerup.
00155   virtual GuiImageData* GetImageData() = 0; ///< The image associated with this powerup.
00156   virtual string* GetHelpText() = 0;        ///< A description of this powerup used in the menu.
00157 
00158   // OVERRIDE IF NECESSARY:
00159   virtual GuiSound* GetSound() { return defaultSound; } ///< The sound associated with this powerup.
00160 
00161 protected:
00162   Powerup() : elapsedTime(0) { }
00163   virtual ~Powerup() { } 
00164 
00165   // MUST OVERRIDE:
00166   virtual Powerup* GetInstance() = 0;      ///< Returns a new powerup instance.
00167   virtual void StartEffect(u8 player) = 0; ///< The powerup state change goes here.
00168   virtual void StopEffect(u8 player) = 0;  ///< Reverts the state back to normal.
00169 
00170   // OVERRIDE IF NECESSARY:
00171   virtual u32 GetDuration() { return DEFAULT_POWERUP_DURATION; }       ///< The duration of this powerup, in milliseconds.
00172   virtual PowerupTarget GetTargetType() { return POWERUP_TARGET_ONE; } ///< Determines what players are the target of this powerup.
00173 
00174   /// Returns the global Powerup vector.
00175   /** This vector contains a static instance of every Powerup. */
00176   static vector<Powerup *>& GetVector()
00177   {
00178     static vector<Powerup *> powerupVector;
00179     return powerupVector;
00180   }
00181 
00182 private:
00183   u64 startTime;
00184   u32 elapsedTime;
00185   static GuiSound *defaultSound;
00186 
00187   void Terminate(); ///< Called automatically when a powerup's duration expires.
00188   void ResetStartTime() { startTime = gettime(); }
00189 };
00190 
00191 #endif // __POWERUP_H__

Generated on Wed Oct 20 2010 17:06:58 for TetriCycle by  doxygen 1.7.1