TWS Minigolf Game 2008

Transcription

1 TWS Minigolf Game 2008 Based on TWS Minigolf Game Engine 2008 Study MTG-T Course Engine Programming 2008 Instructor: Arnav Jhala Name CPR Thomas Willer Sandberg xxxx

2 Table of contents 1 Summary of Features Code Organization Class structure Execution Flow Code Details Math class MyVector Physics and Collision FileHandler How the FileHandler works Rendering Scoring Player highscore Xmlhandler User Interface Menus HUD Debug features and keys Future thoughts for improvements in the game engine TWS Minigolf Game Rules of the minigolf game Controls in the minigolf game References Books Web pages Class diagram (Appendix) Summary of Features 2

3 1 Summary of Features Rendering o Camera view from different angles. o o o Lightning effects. Renders multiple tiles with three or more edges. Supports 2D Text rendering. Support creation of GLUT menus (right click menus). XML Handler o Support writing readable and well-formed XML files. Could be used for high scores, levels etc. o Reads well-formed XML files (XML version 1.0) File Handler: o Supports reading different minigolf course files after a specific syntax1, and then render them. (Key Board Handler) o Supports Keyboard handling for specific keys, but the handler is inside the main class, so if this should be used for other games, the keyboard handler should be moved to an individual class. Basic physics engine: o The physics engine can handle ball movement, collision with tile edges like walls or hills, some gravity handling for when a ball is pulled down a hill. Programming o Uses Visual C with OpenGL/GLUT features. o Target is windows PC platforms using Microsoft Visual Studio Summary of Features 3

4 2 Code Organization 2.1 Class structure This section explains the different classes in my Minigolf Engine. Every class except for the main class is placed in folders to make it easier to navigate and find the right classes you want in Visual Studio. In the explanation of the classes below the folders are represented in parentheses after each class/struct name. The class diagram (UML diagram) can be found in Section 6 page 21. MinigolfMain This class is where the Main function is and is the class that brings everything together and starts the engine. The lighting, camera, keyboard input handling and menus are setup here. The main function starts and calls an instance of MyMinigolfGame with an opportunity for the user to specify which coursefile to load from. If there are none arguments, then the engine will load the standard course.db. So MinigolfMain contains the course, but also the actual hole and physics. MinigolfGame / MyMiniGolfGame The MinigolfGame represents all the important data for a minigolf game and makes the base for implementing different kinds of minigolf games. Every method in MinigolfGame is Virtual, so the derived classes have the possibility to redefine them. MyMinigolfGame implements/is derived from MinigolfGame and specifies all the specific rules for TWS Minigolf Game MyMinigolfGame is a one player game and has a special rule, which says that if a player has not put the ball in the cup by 8 strokes, the player will be punished 2. These rules are maybe contrary with other minigolf games, but these games can just implement MinigolfGame, and then define their own rules about number of players, how to count points, winning conditions etc. 2 For a full list of the rules for TWS Minigolf Game, see section 4.1 Code Organization 4

5 TextHandler (Handlers) This handler handles all texts in the game. For instance the MenuText, highscoretext, HUDText etc. FileHandler (Handlers) This handler handles the reading of a complete course layout from a text file and saves all items into objects. XMLHandler (Handlers) This class is a handler for reading and writing player highscore XML-files. See more about this class in section on page 14. Highscore Represents the high score of a game. The highsore class consists of a playername (String^), the high score (integer) and a date (DateTime) for when the high score was achieved. This class inherits the interface IComparable, and implements the method CompareTo(object o), to make it possible to compare different highscores with each other, and then sort them. TextString2D (Render) Represents 2D bitmap texts/fonts in a 3D world. These fonts will have no thickness and can't be rotated or scaled, only translated. The font will always face the viewer. 3 Physics (Physics) Represents the physics of the game engine. This class controls the movement of the ball/balls, testing for collisions between the ball/balls and edges of tiles (inherits from plane), for instance walls, is checking for when the ball is on a hill, calculates slopes for the ball and calculates the gravity of the ball. MyVector (Math) This is a math class/library to support a lot of different calculations for vectors, like subtraction, addition, cross product, scalar product etc. 4 3 Inspiration from: Code Organization 5

6 Course (Building_Blocks) A minigolf course represents a collection of between one and eighteen minigolf holes. A course also has a course title that can be set. Hole (Building_Blocks) Represents all the information about a hole in a course. That is the name of the hole, par, a collection of tiles which represent the entire surface of the hole, the cup/cups (depended on which type of game, there can be more than one cup), the tee, where the ball starts and the ball/balls itself. The class contains methods for drawing all these elements. Player (Highscore) Represents a player. A player has name, points for each hole in a course and total points for all holes in a course. The player class inherits the interface IComparable, and implements the method CompareTo(object o), to make it possible to compare different players with each other, and then sort them. All players can then be sorted on their playername alphabetically, with a first. Plane (Math) Represents a plane in a 3D space. Both Tile and TileEdge class inherits from this class. The equation of a plane is Ax+By+Cz+D=0, and the plane can be calculated through 3 points that the plane is passing through in a 3D space. Ball (Building_Blocks) Represents a ball with a position, speed and direction. A ball has a reference to a tile and knows which tile it is placed on. 4 For the vector class, I have found inspiration from : Code Organization 6

7 Tile (Building_Blocks) Represents a tile in a 3D space. A tile is a planar convex surface with a friction. A tile has three or more edges. TileEdge (Building_Blocks) Represents an edge of a tile. The edge can be either a Wall or a FreePass, where objects like a ball for instance will be able to pass. Inherits from plane. Tee (Building_Blocks) Represents the position where the ball starts. Cup (Building_Blocks) Represents the location of the cup where the player is trying to put the ball. Line (Building_Blocks) Represents a line in a 3D space. A line is a straight geometrical object that goes from one 3D point to another. Point (Building_Blocks) Represents a point in a 3D space, where you can get and set the x, y, z coordinates. Code Organization 7

8 2.2 Execution Flow Below you see a rough figure that should give an overview over the execution flow in the complete game. Figure 1: Execution flow of the complete game. Code Organization 8

9 3 Code Details 3.1 Math class MyVector MyVector class consists of three coordinates x, y, z and can be used for the following types of calculations 5 : Addition between between two vectors. Subtraction between between two vectors. Subtraction between between a vector and a Point. Calculation of a dot product between two vectors. Calculation of a cross product between two vectors. Calculation of a Scalar Product (a Vector multiplied with a double). Normalize a vector (Unit vector). Calculation of a normal vector. Generate the normal vector from 3 different vectors. Calculate the length of vectors. Calculate the angle between Vectors. Calculate the direction of a vector. 5 MyVector class is made with inspiration from Code Details 9

10 3.2 Physics and Collision All the ball movement and collision detection is handled in the Physics class. The physics class uses the MyVector class for most of the calculations. The most important method in the physics class is the MoveBall. MoveBall is called all the time for every frame, from when a Minigolf Game is started until the end of the minigolf game, when the highscore is showed. This is necessary to give the ball a gliding effect; instead if this method was not called in every frame, it would look like the ball was teleporting itself. If the ball has no speed, the only thing this method does, is calculating the direction of the ball. When the HitBall method is called, the ball gets a speed and the MoveBall method starts to check if the ball is on the same tile where the cup is. If this is true, then the method CupCollisionCheck will be called, to check if the ball collides with the cup, if it does the Boolean variable inhole will be set to true and the Main Class will afterward take care of points (number of strokes), changing level etc. If the ball didn t hit the cup, the MoveBall method will run through all tiles to find the tile the ball is on and then call the CheckCollisionsWithEdges. The CheckCollisionsWithEdges runs though all edges of the tile the ball is on, to check if the ball collides with an edge. To calculate this, the helping method TestIntersectionWall 6 is called. If the ball collides with an edge, the method then checks if the edge is a wall or a FreePass 7. If it s a wall the CalculateNewBallDirection is called, to calculate the balls new direction after collision with the wall. If the edge collision was a FreePass, the CalculateSlope is called. This method calculates the slope of the ball. After those calculations, the next position of the ball will be set. These steps iterates until the ball is stopped. The ball will slow down after each call of the MoveBall, because of the friction of the tiles or because of the gravity when the ball is on its way up a hill. 6 NEHE s Collision Detection tutorial: has been used as an inspiration for the TestIntersectionWall method. 7 A FreePass is when a ball collides with an edge of a tile, where there is no wall. Code Details 10

11 3.3 FileHandler The FileHandler in the engine is used to read all input data about a complete course from a text file, and then handle it, so all the items will be saved into different objects, that will be used to build up a complete minigolf game. The text file has the following syntax: course "A Single Hole Course" 1 begin_hole name "Simple Little Minigolf Hole" par 2 tile tile tile tile tee cup end_hole The FileHandler can only be used by external classes that operates with the same type of objects (tiles, tee, cup and par value) that is listed in the before mentioned text file example. So if an external level builder program could create minigolf courses with the same syntax, you could easily use this engine and FileHandler to render the course. But if the text file has different types of object, or syntax, this FileHandler would not be able to parse it. It would then be necessary to extend the FileHandler with more code, or completely rewrite the handler, to make it work HOW THE FILEHANDLER WORKS The FileHandler starts with the first line and uses substr to remove the first 8 characters and the last 3 characters, and then saves the last remaining characters, which is the course name. The File- Handler doesn t save the number of holes (the last number in the first line), because you can get the same information by calling Holes->Count. Afterwards the FileHandler looks for the name, which symbolizes the name of the hole. The same procedure as for finding the course name is used. Code Details 11

12 The FileHandler then continues with the following lines and calls the HandleFigures for each line until it reach the line that contains the end_hole. The HandleFigures takes one argument, which should be a text string that contains one line with one of the before mentioned objects. The method checks if it s a tile, cup, tee or par value and then saves them into each representative object types. The FileHandler ends up having a List of holes, a List of tiles, a Tee, a Cup and a CourseName. 3.4 Rendering The overall render method is placed in the MinigolfMain class. The render function is called in every frame and calls the helping method draw. The method draw handles the functionality to find out what to show on the screen, for instance text, menu or the game with the HUD etc. Every building block like tile, tee and cup etc., has their own draw methods. The hole has a draw all method, which calls every draw method for all the building blocks there can be drawn. These methods are called from the draw method in the MinigolfMain class, and would also be possible to use from external classes that wanted to use this engine. All texts in the game are created using the engines TextHandler class. The most important method in the TextHandler class is the createtext that displays a 2d text on the screen and takes 4 arguments, an x and y coordinate for where the text should be placed on the screen, a font type and the text that should be displayed. The TextHandler class uses the TextString2D class to render the texts in 2D on the screen 8. The TextString2D contains 3 methods: setorthographicprojection()- that sets the Orthographic Projection. After calling this function, it is very important to remember to call the resetperspectiveprojection, to restore the original perspective so that the next frame is rendered correctly. resetperspectiveprojection() - Resets/restore the original perspective projection, so that the next frame is rendered correctly. renderbitmapstring - Renders a string starting at the specified raster position in the arguments of the method. 8 With of inspiration from the web page: Code Details 12

13 3.5 Scoring Figure 2: Screenshot from the highscore in the game. The high score table is always showing the 10 best results in the game. If there are two players with the same score, the high score class will prioritize the player who got the high score first. As in the screenshot in Figure 2, you will see 3 equal scores on 61 strokes, but with different dates. The score that was obtained first is placed on top of the others with newer dates. This is done by making the highscore class implement the IComparable interface, which will allow a user specified ordered sort of objects of the same type that implement the interface. In this case it is a high score class, but to do this the class needs to include the CompareTo method, to tell the system what to sort after. In the code below you will see the implementation of the CompareTo method from the highscore class. 9 int Highscore::CompareTo(Object^ obj) { int hscore = highscore1 - ((Highscore^) obj)->highscoreplayer; int d = (int) date1->compareto(((highscore^) obj)->date); if(hscore!= 0) return hscore; else return d; } The first thing that happens in this method is that two Highscores will be compared on the score. If the two Highscores subtracted are zero, then they are equal, and the date check will be made. 9 How to Compare DateTimes : Code Details 13

14 In the date check, if the output of the date comparison is less than zero, the Highscore objects date we check with is received earlier, and should be placed first. If the result is greater than zero, then the compared highscore is received later, and should be placed last. At last if its zero, they are equal, and will not be sorted. Afterwards Highscore objects can be compared and sorted. The sorting is done in the UpdateHighscores() method in the XMLHandler, which will be explained in the next subsection PLAYER HIGHSCORE XMLHANDLER The XMLhandler in the engine is used to create/save the player high scores in XML and read the XML to store the data into Lists. There is one List with all players and one list with all the high scores with a reference to the name of the player that have received the highscore. The XML files for storing player highscore, has the following syntax: <?xml version="1.0" encoding="utf-8"?> <Players date=" :58:17"> <Player name="thomas Sandberg"> <HighScore date=" :18:59">49</HighScore> </Player> <Player name="birgitte"> <HighScore date=" :10:40">53</HighScore> </Player> <Player name="hans" /> </Players> To create a player high score XMLFile, you have to parse a filename for the XMLHandler. If the filename doesn t exist already, the XMLhandler will automatically create the XMLfile with the following syntax (The date represents the date for when the file was created): <?xml version="1.0" encoding="utf-8"?> <Players date=" :31:07" /> If a new player is added (calling the AddPlayer method), then the XMLhandler will add a new node with the following syntax <Player name="name" /> Code Details 14

15 If the player already exists the player will not be added again, and false is returned. When a new highscore is achieved, the AddHighScore method will be called with the name and highscore for the player. The XMLhandler will then add a new node with the following syntax: <HighScore date=" :00:00">99</HighScore> The date represents the date for when the player achieved the high score and the number between the brackets, is the actual high score. 3.6 User Interface Figure 3: Screenshot from the start page text and menu text. The user interface in the game consists of a start text, which explains what the user can do, a start menu, a game menu and a transparent HUD (head-up display) MENUS The menus in the game are all right-click menus, and the GLUT library is used to create them. In the start menu, the user can choose between: starting the game, if a user is loaded (else an error pop-up screen will appear, see Figure 4), create a Figure 4: Error message Code Details 15

16 new user, which automatically will be loaded to be the actual player, if no player is loaded yet (if another player is already loaded, a pop-up warning will appear and ask the player if he/she wants to change the active player, see Figure 5). Figure 5: Warning message In the menu you can also Load User, which is a sorted list of player profiles, the sorting was done by implementing the IComparable and override the CompareTo method in the Player class, like with the Highscore class explained earlier in section 3.5. The last options in the start menu is help, that in Windows will open the readme.txt file in Notepad, which is done by using the ShellExecute command 10. About shows some extra game info; the last menu option exits the game HUD The HUD displays important information to the player as part of the game's user interface during the game. The information in the HUD is, as seen in Figure 6, the course name, the name of the current hole, par value that is the average number of strokes it should take to play each hole, the player name, the number of Figure 6: The HUD in the game. hits pr. hole, hits total and the speed of the ball, where 10 is MAX SPEED. 3.7 Debug features and keys All classes in the minigolf engine is based on manage typed c++, besides the two classes minigolfmain and TextString2D. To compile all classes it is necessary to compile it with Common Language Runtime Support (/clr). This can be setup in Visual Studio under project -> properties -> general -> Common Language Runtime support. What it basic means, is that it is then possible to use a lot of predefined types from the.net framework like List, Dictionaries, XMLDoc and so on. Another advantage in using CLR compiling, is that data security and program reliability is greatly enhanced, because dynamic memory allocation and 10 Code Details 16

17 release for data is fully automatic but also because code for a program is comprehensively checked and validated before a program executes. 11 Some people may say that managed c++ always will be slower than native c++, but that will not always be true, because we get faster and faster computers and CLR has for instance Just In Time (JIT) compilation, that allows optimized code, before execution, to run against and take advantages of the current machine configuration and CPU. Another performance advantage for managed c++ in proportion to native C++ is the before mentioned dynamic memory allocation, which allocates memory in a much different and faster way than the native C++ memory allocation scheme Future thoughts for improvements in the game engine If it should be possible to use this engine to other types of games, the physics class should then be able to calculate collisions between several of different objects, for instance when a ball collides with the surface, with another ball or when a ball hits another obstacle on a level/hole. If the engine for instance should be used for making a billiard game, these collision types would be necessary to implement. Another necessary change could be to give the ball class a reference to a tee, so if there were more than one ball, every ball could start different places. As it is now every ball would start at the same position, which would be a problem in billiard. Gravity should also work when the ball is off the ground, and should pull down the ball until it hits the ground, and then maybe bounce, depended on the speed of the ball. To make this work the MoveBall method should maybe be rewritten, so the gravity somehow could be added to the speed/velocity of the ball, before the balls MoveSpeed check, in the start of the method. Besides these improvements it should be possible to use the physics class from external classes in other types of games, like billiard, other types of minigolf games or in ordinary golf, but then it would be very important that the before mentioned improvements were implemented. 11 Chapter 1 in Visual Studio C (book reference 1, page 14) 12 See web reference 8, page 14 Code Details 17

18 Another improvement to a future version of the engine could be to combine the XMLHandler with the FileHandler, so XML also would be used for reading and writing courses. It would be more standardized than working with a text file, and would be easier to make a level design tool working with XML than with a none standardized text file. A smaller improvement of the FileHandler could be to make it able to save multiple tees and cups. The FileHandler should also have a complete course, instead of just containing the Course name. The Mainclass should in a future version not have so much responsibility as it has in this version. The keyboard, mouse, camera/rendering and menu handling, should be moved to their separate individual classes, which would give a better overview and also better reuse of the code, so they easily could be reached from external classes. At the moment it is not possible for classes to use this functionality, when the code is inside the main class. Another improvement could be to move the responsibility of the active course and hole from the main class to the MinigolfGame class, where it would be more intuitive to have it. Cups on sloping tiles should have the same slope. Code Details 18

19 4 TWS Minigolf Game Rules of the minigolf game 1. TWS Minigolf Game is a 1 player game with one course and 18 holes. 2. At every level you start with the ball on the Tee, and the player should try to put the ball into the Cup in as few attempts as possible, by shooting the ball in a specific direction. 3. If a player has not put the ball in the cup by 8 strokes, the player will be punished and 10 strokes will be recorded for that hole. Afterwards the game continues on the next hole. 4. Every hit counts. 5. In some of the holes, there is more than one way to get to the cup. It is up to the player to find the shortest way. 6. After the player has finished all 18 holes, the game ends and the player will be presented for the high score list, with the 10 best performances. 4.2 Controls in the minigolf game KEY LEFT - Moves the camera to the left. KEY RIGHT - Moves the camera to the right. KEY UP - Moves the camera forward. KEY DOWN - Moves the camera backward. KEY PAGE UP - Moves the camera up. KEY PAGE DOWN - Moves the camera down. KEY A KEY D KEY W KEY S KEY Z Key X SPACE KEY, KEY. KEY M KEY L KEY F1 KEY Esc - Turns the camera around the minigolf level to the left. - Turns the camera around the minigolf level to the right. - Turns the camera up. - Turns the camera down. - Change One Minigolf Hole/Level back. - Get next Minigolf Hole/Level. - Hit the Ball with a default Velocity/speed. - Increase the Angle of the ball. - Descrease the Angle of the ball. - More speed of the ball. - Less speed of the ball. - Change Full Screen / window mode. - Exit program. TWS Minigolf Game

20 5 References 5.1 Books 1. Horton s, Ivor (2008): Visual C , Wrox (Wiley Publishing, Inc.) 2. 3D Game Engine Programming, Stefan Zerbst, and Oliver Duvel, Course Technology PTR (Game Development Series). 3. Computer Graphics: Principles and Practice Second Edition in C, J. Foley, A. van Dam, S. Feiner, and J. Hughes, Addison-Wesley Longman, Inc. 4. Beginning OpenGL Game Programming, Dave Astle, and Kevin Hawkins, Course Technology PTR. 5. Interactive Computer Graphics, A Top-Down Approach with OpenGL (Fifth edition), E. Angel, Addison-Wesley, Inc. (Pearson International Ed.) 6. Computer Graphics with OpenGL (3rd Edition), D. Hearn and M. P. Baker, Prentice Hall, Inc. 7. OpenGL Programming Guide: The Official Guide to Learning OpenGL, Version 2.1 (Sixth Edition), D. Shreiner, M Woo, J. Neider, and T. Davis, Addison-Wesley, Inc. 5.2 Web pages Math Vector algebra 1. htm Course homepage (assignments) 2. OpenGL programming guide (Red Book 1.1) 3. Neon-Helium Tutorials on OpenGL 4. More OpenGL Tutorials Managed c++ vs native c++ performance 8. References 20

21 6 Class diagram (Appendix)