README for CS 248: Project 4 OpenGL 3D video game ============================================ G E M S T O N E S Eric Chan Jy-Ying Janet Chen ============================================ Platform and System Requirements: - Mac OS 8.0 or higher - 300-MHz G3 processor or higher - 50 MB of available RAM - 100 MB of available hard drive space - Apple OpenGL 1.1.2 (downloadable from their web site) - ATI Rage Pro or higher 3D video accelerator (ATI Rage 128 recommended) Platform/System on which we gave our presentation: - Mac OS 8.6 - 350-MHz G3 processor - 128 MB of RAM - Apple OpenGL 1.1.2 - ATI Rage 128 with 16 MB of SDRAM ============================================ How to install/run our game: We couldn't submit our project with the submit script because it was too large. So, you can find it at This is a compressed archive which you must expand using Stuffit Expander 5.x or higher on Mac OS. When you have decompressed this archive, you should see a folder named "Gemstones" ; inside this folder, you will find the executable called "G E M S T O N E S". Double-click this to run the game! You should run it at 800 x 600. ============================================ How to create a new build from the source files: You will need Metrowerks CodeWarrior 5.0. Inside the folder "Gemstones_project", you will find a file called "gemstones.proj". Double-click this to open the project file in CodeWarrior. From the "Project" menu in CodeWarrior, choose the "Make" option. This builds the binary. ============================================ Objective of the game: [brief] You must recover gemstones by navigating a hovercraft through a space system created by the evil Empire. In particular, you need to find three special Diamonds while avoiding obstacles like crushing blocks, lava plates, and shooting boxes. [full] In ages long past in another world, there was a magical, prosperous land known as Acres Wood. The land drew its magic from three precious Diamonds created by the benevolent god Eeyore at the land's creation. Over time other gemstones emerged and these were rumored to imbue their owner with special powers, though few knew how to use them. Few from the outside world knew of Acres Wood because of the land's magical protection. To most, Acres Wood was mythical, and thus there was no reason to trouble it. In this manner, the land prospered for ages without outside disturbance. Over time, a large group of Mysterious Beings came to power and perceived Acres Wood as a threat to their Empire. They decided to invade the land to steal its precious gems. Using remarkable hovercrafts, agents of the Empire navigated through a grid-like space of their creation known as Windows. They went from world to world, brainwashing inhabitants and searching for Acres Wood. As time passed, the smaller worlds became more and more dependent on the Empire. In time, the agents found Acres Wood and invaded. Tux, the wise, courageous, and slightly plump king of Acres Wood prepared to summon a magnificent resistance using the power of the gemstones. He had to ensure that the shrine of Eeyore, in which the three Diamonds were embedded, was not destroyed. But the agents and their hovercrafts were too quick. They stole the three Diamonds and every other gem they could find. The agents tried to assimilate the inhabitants of Acres Wood but found them remarkably resistant, so they decided to capture Tux. However, this was not easy. The agents had never seen an angry penguin charging at them in excess of a hundred miles per hour! Tux managed to destroy an agent but eventually succumbed to sheer numbers. The agents captured him and sped away, leaving the inhabitants of Acres Wood without their beloved king. The inhabitants saw an opportunity to rescue Tux -- the dead agent's hovercraft was still in Acres Wood! They selected their most valiant warrior to pilot the hovercraft and navigate through the evil system of the Empire to recover the three Diamonds and to rescue Tux. ============================================ How to play Gemstones: When the game starts, you will see a long introduction sequence. Once the sequence has started, you can jump to the end of the sequence by pressing a key. You are in a hovercraft -- a sort of space vehicle -- with the ability to move forward and back, from side to side, up and down, and to turn left and right. In addition, you can shoot crystal shards and fireballs, and activate special items. In our game, there are three levels to complete. The objective for each level is to find the Diamond. You cannot complete the level until you have found the Diamond on that level. When you finish Level 3, you win the game! ============================================ Keyboard commands: NAVIGATION KEYS: I - forward K - backward U - sidestep left O - sidestep right J - turn left L - turn right A - move up Z - move down ATTACK KEYS: space - shoot two crystal shards shift - shoot fireball MISCELLANEOUS KEYS: return - activate special item (you can blow up certain color-coded doors if you have the appropriate item) F - show frames/sec counter CHEATS: 1 - go to level 1 2 - go to level 2 3 - go to level 3 4 - give yourself many more lives! ============================================ Gemstones Gameplay Design/Details: Each of the three levels is designed differently, i.e., you have to do different things in each level to retrieve that level's Diamond. The following items will help you on your way: - regular crystals: if you pick these up, you can go to the Bonus Level at the end of level 1 or level 2, where you will have the chance to get extra lives; be careful, though -- shooting a regular crystal will shatter it so you can't pick it up any more - red crystals: picking these up will increase your firepower by 10 points; you need firepower in order to shoot the crystal shards (space-bar) - green crystals: picking these up will increase your shields by 10 points; in this manner, you cannot achieve shields higher than the full 100 points; without any shields, your hovercraft takes a plunge and you lose a life - red gem: picking up one of these will completely restore your firepower; in addition, you acquire three fireballs (see below) - green gem: picking up one of these will increase your shields by 100 points; furthermore, any shield points you receive that would increase your shield level above 100 are turned into extra shield points. For example, if you had shields 37 and then picked up a green gem, you would then have full shields (100) plus 37 bonus shield points. If you then suffered damage somehow, the damage would affect the bonus shield points first, until you had no more bonus shield points, and then it would affect your regular shield level. - blue crystal: there are five of these in Level 1. Rumor suggests that you need all five in order to unlock the Diamond in Level 1. - Diamond: you must have the Diamond for the current level in order to complete that level. The following are obstacles intended to hinder your progress: - Shooting Bill: a rotating box with a cyborg-version of Bill Gates; he shoots repeatedly at you; it takes three crystal shards to destroy this box - Moving/crushing columns: whenever you see a large body of matter moving, chances are it does damage to your hovercraft; avoid these! - lava plates: when you move over the plate, a strong magnetic field drags your hovercraft towards the plate. Touching the plate incurs a great deal of damage. - agent of the Empire: he guards the Diamond in Level 3 and shoots fireballs at you. He is impervious to crystal shard attacks; you need fireballs to destroy him. ============================================ The Game Levels: Level 1: The Diamond in this level is sealed in a room that can only be accessed if you have five special Blue Crystals. The map is shaped like a pentagon with a Blue Crystal at each vertex. Each such crystal is guarded in a unique and special way. You may shoot the Windows boxes to retrieve valuable items and pick up regular crystals along the way. Once you have retrieve the Diamond, you must use the clues presented at locations where you retrieved the Blue Crystals to solve the final puzzle -- a set of five switches controlling seven gates that protect the exit teleporter. Level 2: This level is very different. You cannot turn left or right, nor can you move backwards. You are caught in a magnetic field that drives you forward, so you must use the up/down/left/right keys to avoid obstacles. Head-on collision with obstacles spells instant explosion for your hovercraft! You can use the forward key in addition to the magnetic field to give yourself a turbo boost -- this can be very helpful when timing how you avoid obstacles. As before, you can pick up valuable gems and crystals ... and you must pay attention to the visual cues (hint: colors) to choose the proper path to the finish. You must also rely on your reflexes, since the map is filled with traps. There are also a number of shortcuts and tricks that one can take advantage of in order to find a shorter path to the end of this level. Level 3: This level is short ... but is harder than it looks. You must defeat an agent of the Empire using fireballs. Good luck! Bonus Level: You will be sent to the Bonus Level if you complete either level 1 or level 2 with at least one crystal and at least some firepower left. The purpose of the Bonus Level is to give you a chance to acquire extra lives. In the Bonus Level, crystals will fly at you one at a time from the distance. The total number of crystals that appear is equal to the number of regular crystals in your possession. You cannot move up/down/forward/back/left/right. You can only turn left/right and shoot. With each crystal you shoot, you gain an extra life! ============================================ Complete List of Game Features: NOTES: In addition to using GLUT, we used the Macintosh Toolbox (OS-specific libraries) to implement certain features, including the entire sound engine, the hiding of the cursor and the menus, the full-screen display, the gamma fades, and the full-screen static images (intro sequences, in particular). Graphics/Visuals: - texture mapping and lighting - fog - fireball smoke effect, billboarding of smoke polygon - flames: dynamic texture-generation - teleport effect: playing with viewing frustum coordinates - full screen game and level introduction sequences - screen gamma fades (before/between/after levels) using Apple DrawSprockets - frustum-culling and collision detection - implemented using a 2D-array of buckets: each object falls into only a few buckets at most (determined by its bounding box -- x and z coordinates); when determining what to draw and what objects to check for collision, we simply iterated through the closets buckets and checked the objects only in those buckets -- very fast, easy to implement - 2D game panel - basic particle system for explosions - moving light source for fireball - full-screen lightning Environment/Maps: - basic file format for storing maps and object definitions - .xpm texture reading code - four levels (described above) Game engine: - can use multiple keys simultaneously - trailoff: after letting go of movement key, hovercraft drifts a bit - ship bob: ship moves dynamically up and down (time-based) - tilt/jitter/pitch engine: to simulate disturbance when the hovercraft collides with something - dynamic objects (boxes, primarily), which can translate along any axis and can be tied to certain events: - updates: update function called once per frame - shooting: function called when you shoot the item - colliding: function called when you collide with it - pick up: function called if you try to pick it up - activated: function called if you try to activate it - lava plates: attract your ship when you move over it - agent/enemy ship: - basic dodging of obstacles Sound engine: - dedicated music channel - 8 separate stereo, 16-bit, 44-kHz sound sprite channels - distance-based sound: sound intensity falls off with distance ==================================== DEVELOPMENT SOFTWARE/HARDWARE USED: SOURCES OF GAME CONTENT / ETC. development software: - platform: Mac OS 8.6 - libraries: Apple OpenGL 1.1.2, Apple DrawSprockets 1.7 - CodeWarrior Pro 5, Metrowerks - Photoshop 5, Adobe Systems - GraphicConverter 3.8, Thorsten Lemke - ResEdit 2.1, Apple Computer - SoundEdit 16 v2.0, Macromedia - SoundApp 2.5, Norman Franke development hardware: Apple Computer: - Power Macintosh G3, 350 MHz, 64 MB RAM, ATI Rage 128 with 16 MB - Power Macintosh G3, 350 MHz, 128 MB RAM, ATI Rage 128 with 16 MB - iBook, 300 MHz, 96 MB RAM, ATI Rage Mobility with 4 MB Power Computing: - PowerTower Pro, 400 MHz, 288 MB RAM, 3dfx Voodoo3 2000 with 16 MB demonstration hardware: Apple Computer: - Power Macintosh G3, 350 MHz, 64 MB RAM, ATI Rage 128 with 16 MB sources of game inspiration: Marathon, Marathon Infinity, Marathon Evil, Bungie Software Myst, Cyan Riven, Cyan Unreal, Epic Games Quake 3 Arena, id Software Spectre VR, Velocity Super Mario Bros. 3 Descent, Graphic Simulations Bolo, Stuart Cheshire Tux, Linus Torvalds Winnie-the-Pooh sources of game content: Textures: Marathon, Marathon Infinity, custom Sounds: Marathon, Marathon Infinity, Chiral, Maelstrom, Myst, Spectre VR, Super Mario Bros. 3, Quake 3 Arena, Unreal Thanks to Gustav Taxen for his sample particle system code. Our particle system code was based on it. Music: Marathon Infinity, Marathon Evil, Loony Labyrinth ============================================= December 7, 1999