Design Document

***UPDATE 11/15***

Design goals of project

Over the last few days, we have streamlined our API to make it easier to use. The new Sprite class, formerly named GameEntitySprite, has been moved to the vooga core package. This is the Sprite class that should be used from now on instead of the Golden-T built-in Sprite. To do this, only import statements must be changed to point to the vooga core Sprite instead of the Golden-T sprite.

The two key features of the enhanced Sprite class are as follows:
     * The option to switch between renderable images (using any image or animation to represent the Sprite on screen)
     * Any attributes in the form of a Stat (Sprite holds a map of names to Stats, which can be any object that Sprite needs to contain)

Our examples can be found in the vooga.examples.player package. The example is designed as a sample game that can be run to demonstrate the Sprite features. It contains the XML level file that gives an example of how to construct a Sprite with various attributes through the LevelParser. The PlayerEnemyCollision is a possible implementation of a collision between a player and an enemy. When the example game is run, you can use keys specified to switch the state of the player (from left to right). There is also an example that is not initialized from an XML file called GameExample. All the initialization should normally be done through the Level XML, but the other methods found in this example game are a good model of how to use the Sprite features.

The associated documentation has been updated and clarified to make Sprite easier to use.

At this time, we have decided to eliminate PlayerSprite and ItemSprite. All of the functionality that PlayerSprite provided has been moved up to Sprite. ItemSprite did not provide a great deal of functionality as we have reconsidered what an Item is--non-visible “Items” should be considered Rules, and visible Items can simply be represented with a Sprite. This should be a minor change for those groups that used these two classes; simply replace all references to PlayerSprite with Sprite. Also, if you did utilize the inventory (itemList) feature in PlayerSprite, we recommend you create an inventory class that can be passed into a Stat.








***Original Version of Design Document***

Design goals of project

Our project was designed to provide the game developer a comprehensive player and item system to simplify the management of these aspects of a game. Both PlayerSprite and ItemSprite derive from GameEntitySprite. GameEntitySprite implements a great feature: multiple sprite representation. This allows the developer to use different sprites to represent different states any GameEntitySprite object might be in. Our PlayerSprite class derives from GameEntitySprite and handles all the basic data associated with a game player--rank, health, lives, score, and item list. ItemSprite is also an extension of GameEntitySprite and is very similar to a GameEntitySprite but contains an act() method to allow for causing a change in the game. ItemSprite is meant to be overridden and functionality added to the act() method. One of the most important goals we had in developing our package was to ensure that our package worked seamlessly with all of the other functions that Golden-T provides, such as collision detection, SpriteGroup management, and input detection. For this reason, we made several important decisions that are documented in section three.

How to add new features to you project

Adding new features to our project is relatively simple--all of our classes can be extended to make new classes. For example, if there is a new aspect to Player that needs to be kept track of, such as kill count, the PlayerSprite class could be extended, retaining all the functionality of GameEntitySprite and PlayerSprite. Other features that could easily be added are different player controllers. We defined an interface for controlling the movement of a player--it contains four methods that must be implemented. It should be relatively simple to add a controller that takes inputs from the network, or a controller that takes input from a joystick, by using this interface.

Major design choices made in project

A major design choice made this week, that has been in debate since last week, was making the GameEntitySprite class extend Sprite. Before the class was called GameEntity and contained a Sprite object. The idea was to have the GameEntity class and one of its subclasses (Player or Item) describe what the GameEntity was and only use the Sprite to display a picture. With this design we were forced to rewrite all of the methods inside of Sprite in GameEntity so that we could keep track of the Sprites location and other variables. This implementation proved difficult to keep track of the current Sprite and made it very difficult to use more than one Sprite per GameEntity. Also, the collision detection in Golden T is completely based on Sprites, so instead of rewriting the collision detection class to handle a GameEntity it was much simpler to extend the Sprite class, making a GameEntitySprite. Although it seems confusing to extend Sprite and also have a Sprite in the same class it makes things like collision detection and having multiple Sprites per GameEntity possible. The idea of controls being linked to a Player was conceived during the first week of the High Level Engine project, but was implemented this week. An interface named IPlayerController mandates four methods deltaX(), deltaY(), deltaVelocityX() and deltaVelocityY(). KeyboardController and MouseController implement this interface and each class defines how that specific controller functions. The MovementKeys class was created to simplify mapping keys to define movement of a Player. This class is appropriate because movement is relevant to nearly every video game.

Assumptions or decisions made to simplify or resolve ambiguities in project's functionality

One of the great features of our GameEntitySprite class is that it can contain multiple Sprites. Included in this functionality is also the ability to use different kinds of Sprites, such as AnimatedSprites or PatternSprites. However, our class does not provide the ability to extract and modify these kinds of Sprites after they have been passed to the GameEntitySprite object. The developer will have to make sure that all parameters for these special kinds of Sprites are set before using these special Sprites as part of a GameEntitySprite. We also assume that the developer understands how to use casting to enhance functionality. This is particularly important in the CollisionManager classes that the developer may use. Because our PlayerSprite can act as a Sprite, it can be passed to the CollisionManager. Within the collided method, if you have a collision with a player that should cause a change in the playerŐs lives, for example, since you know which Sprite is going to be the player (s1 or s2), you can simply cast that Sprite as a PlayerSprite and update the playerŐs score, all from within the CollisionManager.