Taken and slightly
adapted from the book:
Braude, E., “Software Engineering -
An Object Oriented Perspective”, John Wiley and sons, 2001
Software
Design Document for Encounter Role-Playing Game
History of versions of this
document.
NN/NN/NN K. Peters: Initial draft
NN/NN/NN K. Peters: outline
completed
NN/NN/NN E. Braun: detection
of defects
NN/NN/NN K. Peters:
incorporated comments by E. Braun
NN/NN/NN K. Peters: added
decomposition by use case model and state model
25. July 2004 Update: Živana
Komlenov (
1. Introduction
1.1 Purpose
This document describes the
design of the Encounter role-playing game.
1.2 Scope
This design is for the
prototype version of Encounter, which is a demonstration of
architecture, detailed design, and documentation techniques. The architecture
is intended as the basis for interesting versions in the future. This
description excludes the framework classes, whose design is provided in
document SDD NN.
1.3 Definitions, acronyms and abbreviations
none
2. References
"Role-Playing Game
Architecture Framework".
Braude, E. J., Software
Engineering: an Object-oriented perspective
UML: The Unified Modeling
Language User Guide by G. Booch, J. Rumbaugh and I. Jacobson, Addison-Wesley
Pub Co; ISBN: 0-201-57168-4
IEEE standard 1016-1987
(reaffirmed 1993) guidelines for generating a Software Design Document
3. Decomposition description[1]
The Encounter
application is provided using three models: use case, class (object) model, and
state. In addition, the relationship between the domain packages of Encounter
and the framework will be shown.
3.1 Module decomposition (object model)
The package architecture for
Encounter is shown in figure 5.49.
Figure
5.49 Architecture and Modularization of Encounter Role-Playing Game
The three packages are EncounterGame,
EncounterCharacters and EncounterEnvironment. These have facade
classes EncounterGame, EncounterCast, and EncounterEnvironment
respectively. The facade class of each package has exactly one
instantiation, and is an interface through which all dealings with the package
take place. The remaining classes are not accessible from outside the package.
(See section 3.2.1 and [Ga] for a complete description of the Facade design
pattern.)
3.1.1 EncounterGame package
The EncounterGame
package consists of the classes controlling the progress of the game as a
whole. The package is designed to react to user actions (events).
3.1.2 EncounterCharacters package
The EncounterCharacters
package encompasses the characters involved in the game. These include
character(s) under the control of the player, together with the foreign
characters.
3.1.3 EncounterEnvironment package
The EncounterEnvironment package
describes the physical layout of Encounter, including the areas and the
connections between them. It does not include moveable items, if any.
3.2 Concurrent process decomposition
There are two concurrent
processes in Encounter. The first is the main action of the game, in
which the player manually moves the main character from area to adjacent area.
The second consists of the movement of the foreign character from area to
adjacent areas.
3.3 Data decomposition
The data structures flowing
among the packages are defined by the Area, EncounterCharacter,
and EncounterAreaConnection classes.
3.4 State model decomposition
Encounter consists of the states shown in figure 5.50.
Figure
5.50 Encounter State-Transition Diagram
3.5 Use case model decomposition[2]
Encounter consists of three use cases: Initialize
and Engage Foreign Character, as shown in figure 5.51.
Figure
5.51 Encounter use cases
These use cases are
explained in detail in the SRS, sections 2.2, and are detailed later in this
document.
4. Dependency description[3]
This section describes the
dependencies for the various decompositions described in section 3.
4.1 Inter-module dependencies (object model)
The dependencies among
package interfaces are shown in figure
5.52.
Figure
5.52 Architecture of Encounter
The EncounterGame
package depends on all of the other Encounter packages.
The EncounterEnvironment
package is designed to depend on the EncounterCharacters
package. This is because the game's character interaction takes place only
in the context of the environment. In particular, Area objects are
responsible for determining the presence of the player's character together
with the foreign character.
Dependencies among
non-interface classes are explained later in this document.
4.2 Inter-process dependencies
When an engagement takes
place, the process of moving the main character about, and the process
controlling the movement of the foreign character, interact.
4.3 Data dependencies
The data structures flowing
among the packages are defined by the classes, whose mutual dependencies are
described in section six of this document.
4.4 State dependencies
Each state is related to the
states into which the game can transition from it.
4.5 Layer dependencies
The Encounter
application depends on the Role-playing game framework as shown in figure 5.53.
Figure
5.53 Framework / Application Dependency
Each application package
uses exactly one framework package.
5. Interface Description
This section describes the
interfaces for the object model. Note that several of the classes described are
defined in the design description of the Role-playing Game Framework.
5.1 Module interfaces
5.1.1 Interface to the EncounterGame
package
The interface to the EncounterGame
package is provided by the theEncounterGame object of the EncounterGame
facade class. It consists of the following.
1.
EncounterGame getTheEncounterGame() // gets the only instance
2.
GameState getState() // current state of the EncounterGame instance
3.
void setState( GameState ) // -- of the EncounterGame instance
//
Any event affecting the single EncounterGame instance:
4.
void handleEvent( AWTEvent )
5.1.2 Interface to the EncounterCharacters
package
The interface to the EncounterCharacters
package is provided by the theEncounterCast object of the EncounterCast
facade class. It consists of the following.
1.
EncounterCast getTheEncounterCast() // gets the single instance
2.
GameCharacter getThePlayerCharacter() // i.e., the unique character
3.
GameCharacter getTheForeignCharacter() // the unique character
5.1.3 Interface to EncounterEnvironment
package
The interface to the EncounterEnvironment
package is provided by the theEncounterEnvironment object of the EncounterEnvironment
facade class. It consists of the following.
1.
EncounterEnvironment getTheEncounterEnvironment() // gets the facade object
5.2 Process interface
5.2.1 Player character
movement process
The interfaces to the process
which moves the player's character about the game, consists of the graphical
user interfaces specified in the SRS. The process reacts to events described in
section 3.4, and these are handled by the EncounterGame package, in
accordance with its specification, described later in this document.
5.2.2 Foreign character
movement process
The process of moving the
foreign character is a separate process associated with, and controlled by the CharacterMovement
object. This process is controlled by the methods inherited from java.lang.Thread.
6. Detailed design for Encounter
The overall architecture
showing the relationships among the packages, and the domain classes, described
in this section is shown in figure 6.52.
Figure
6.52 Video Game Architecture Packages, Showing Domain Classes
6.1 Module detailed design for Encounter
6.1.1 The EncounterGame package
The state diagram for Encounter
is shown in chapter three. To realize these states and transitions, the EncounterGame
package object model is designed as in
figure 6.53.
Figure
6.53 Detailed Design of EncounterGame Package
There is exactly one
instance of the EncounterGame class. The states of this object reflect
the states and sub-states shown in the above state-transition diagram. The Engaging
state aggregates an Engagement object that encapsulates the engagement
of the game characters. The Engagement class aggregates a display called
EngagementDisplay. The latter is mouse-sensitive, registering with an RPGMouseEventListener
object. When the Encounter game is executed, this listener object
references the EncounterGame object (an RPGame object). This
enables EncounterGame to handle all events according to its state using
the State design pattern. The EncounterGame package has the
responsibility of directing the movement of the foreign character over time.
This is performed by methods of the class CharacterMovement, which is a
thread class.
State classes need to
reference other packages in order to implement handleEvent(), and this
is done through the facade objects EncounterCast and EncounterEnvironment.
6.1.1.1 The EncounterGameDisplays
sub-package of the EncounterGame package
Displays corresponding to
some of the states are handled by a separate sub-package, EncounterGameDisplays,
which is shown in figure 6.54.
Figure
6.54 Detailed Design of EncounterGameDisplays Sub-Package
QualListDispl is a list box consisting of the
qualities of Encounter characters. QualValueDispl is a read-only
text box for displaying the value of a quality. SetQualValueDispl is an
editable text box for setting the value of a quality. EncounterDisplayItem
abstracts the properties and methods of displayable Encounter items such as
these.
EngagementDisplay is designed to display the current
value of any selected quality. SetQualityDisplay is designed to enable
the player to set the value of any quality. EncounterDisplay abstracts
the properties of these displays, and is a mediator base class.
This document does not
provide further details of the design of these classes.
6.1.1.2 Sequence diagrams for event handling
6.1.1.2.1 Player dismisses engagement
display event
Figure 6.55 shows the sequence involved in dismissing
the engagement display. (This dismissal event is shown on the state transition
diagram.)
Figure
6.55 Sequence Diagram for Dismiss Engagement Display
6.1.1.2.2 Player completes setup
event
Figure 6.56 shows the sequence involved in setup
completing.
Figure 6.56 Sequence Diagram for Player Completes Setup
6.1.1.2.3 Player moves to adjacent area
event
Figure 6.57 shows the sequence when the player moves to
an adjacent area by clicking on a connection hyperlink. (This dismissal event
is shown on the state transition diagram.)
Figure
6.57 Sequence Diagram for Player Moves to Adjacent Area
6.1.1.2.4 Sequence diagrams for remaining
events
The remaining events are
handled very similarly to those described in sections 6.1.1.1through 6.1.1.3.
6.1.1.CM The CharacterMovement class
This class controls the
movement of the foreign character.
Inheritance
This
class inherits from java.lang.Thread.
Methods of
CharacterMovement
public static EncounterGame run();
Starts
the foreign character in the dungeon. Moves the foreign character from area to
area via area connections, changing areas to a randomly selected neighbor, at
random times averaging every two seconds.
6.1.1.EG The EncounterGame class
This is the facade singleton
for the EncounterGame package.
Inheritance
This class inherits from RPGame
in the framework.
Attributes of EncounterGame
EncounterGame encounterGameS: This is the singleton EncounterGame
object
Constructors of
EncounterGame
private EncounterGame():
Preconditions:
none.
Postconditions:
creates an EncounterGame instance.
Methods of EncounterGame
public static EncounterGame
getTheEncounterGame();
Preconditions:
none.
Postconditions:
encounterGameS not null
Returns:
encounterGameS
6.1.1.EN The Engagement class
This class encapsulates
engagements between the player's character and the foreign character, and
corresponds to requirement 3.2.EN.
Methods
public void engage(); // corresponds to requirement
3.2.EN.3.1
Preconditions:
the player's character and the foreign character are in the same area.
Postconditions:
the values of the characters' qualities are as required by SRS requirement
3.2.EN.3.1; the player's character and the foreign character are in random, but
different areas.
6.1.1.ZZ The Engaging, Waiting,
Preparing, and Reporting classes
[The "ZZ"
numbering is used to collect classes that are not specified individually.]
Inheritance
These classes inherit from GameState
in the framework package. Each of these classes implements its handleEvent()
method in accordance with the sequence diagrams of section 6.1.1.1
6.1.2 The EncounterCharacters package
The design of the EncounterCharacters
package is shown in figure 6.58. It is implemented by the Facade
design pattern, with EncounterCast as the facade object.
Figure
6.58 EncounterCharacters Package
6.1.2.EC The EncounterCharacter class
This class encapsulates the
requirements for Encounter characters that are not covered by RPGameCharacters.
It satisfies requirements SRS 3.2.EC.
Class invariant: The values
of qualValueI are non-negative (see
"attributes" below for the definitions of qualValueI).
Inheritance
This
class inherits from GameCharacter in the framework package.
Attributes of EncounterCharacter
These satisfy requirement
SRS 3.2.EC.1
private static final String[] qualityTypeS
This
represents the qualities that Encounter characters possess. These are
concentration, stamina, intelligence, patience, and strength.
private String imageFileI
Contains
the gif image of the character
Private float[] qualValueI
This is an array
containing the values of the qualities.
Private float[] oldValueI
This is an array
containing the previous quality values
Constructor of EncounterCharacter
These satisfy requirements
3.2.EC.3 of the SRS
Null constructor
Postcondition:
the qualities are all equal fractions of 100.
protected EncounterCharacter( String nameP )
Postconditions:
(1)
the qualities are all equal fractions of 100.
(2)
the character's name is NameP
Methods of EncounterCharacter
public
void showCharacter()
Displays the character, facing left or right as
specified.
Known defect: facing right vs. left is performed
algorithmically: should be different images.
public float getQualityValue( String qualityP
)
public synchronized void adjustQuality(
String qualityP, float qualityValueP )
This
method satisfies requirement 3.2.EC.3.2.
Invariants:
none
Preconditions:
qualityP is in qualityTypesS[]
AND
qualityValueP >=0
AND
qualityValueP <= the sum of the quality values
Postconditions:
qualityP has the value qualityValueP
AND
the
remaining quality values are in the same proportion as prior to invocation,
except
that values less than 0.5 are zero.
The
following is the pseudocode for the method adjustQuality().
Set
the stated quality to the desired amount
IF
the caller adjusts the only non-zero quality value,
divide
the adjustment amount equally among all other qualities.
ELSE
change the remaining qualities, retaining their mutual proportion,
Set
each quality whose value is now less than 0.5 to zero
public float getQualityValue( String qualityP
)
Preconditions:
qualityP is a valid quality string
Returns:
the value of qualityP
public float getOldValue( String qualityP )
Preconditions:
qualityP is a valid quality string
Returns:
the value of oldQualityP
public float getTolerance()
Returns:
the value below which quality values cannot go
protected int maxNumCharsInName()
Returns:
the maximum number of characters in the names of Encounter characters.
public float sumOfQualities()
Returns:
the sum of the values of the qualities
This
method satisfies requirement 3.2.EC.3.2
public void showCharacter( Component
componentP, Graphics drawP, Point posP, int heightPixP, boolean faceLeftP )
Displays
the character in componentP,
with
center at posP, with height heightPixP, facing left if faceLeftP
true
This
method satisfies requirements 3.2.PC.1 and 3.2.PQ.1
private void setQuality( String qualityP,
float valueP )
Preconditions:
qualityP is a valid quality string
Sets
the quality indicated by the parameter to valueP if the latter is >=
0.5, otherwise sets valueP to zero.
This
method satisfies requirement 3.2.EC.2 (lower limit on nonzero quality values)
6.1.2.ES The EncounterCast class
The method specifications
for this singleton, interface class is given in section 5 of this document.
6.1.2.FC The ForeignCharacter class
This class is analogous to PlayerCharacter,
described next, and is designed to satisfy the SRS 3.2.FC
6.1.2.PC The PlayerCharacter class
This class is designed to
satisfy the requirements 3.2.PC.
Inheritance
This class inherits from EncounterCharacter.
Attributes:
private static final PlayerCharacter
playerCharacterS;
This
is the singleton object representing the player's character.
Methods:
public static final PlayerCharacter
getPlayerCharacter();
This
method returns playerCharacterS.
6.1.3 The EncounterEnvironment
package
The classes of this package
describe the environment in which the game takes place. It is shown in figure 6.59.
Figure
6.59 EncounterEnvironment Package
6.1.3.AR Area class
This class encapsulates the
places in which the characters exist, and corresponds to requirement 3.2.AR.
Inheritance
This class inherits from GameArea.
Attributes:
private String nameI; // corresponding to requirement
3.2.AR.1.1
private Image imageI; // corresponding to requirement
3.2.AR.1.2
private String[] qualitiesI; // corresponding to requirement
3.2.AR.1.3
private Vector connectionHyperlinksI;
Methods:
public void display() shows the area object's image on the
monitor.
public static Area getArea( String areaNameP
) returns the area
corresponding to areaNameP according to requirement 3.2.AR.2.2
public static AreaConnection
getAreaConnection( String areaConnectionNameP ) returns the areaConnection
object corresponding to areaConnectionNameP according to requirement 3.2.AR.2.2
6.1.3.CO EncounterAreaConnection class
This class encapsulates the
ways to get from areas to adjacent areas. It inherits from AreaConnection,
and corresponds to requirement 3.2.CO.
Inheritance
This class inherits from GameAreaConnection
in the framework package.
Attributes:
private Area firstAreaI; // corresponding to requirement
3.2.CO.1.1
private Area secondAreaI; // corresponding to requirement
3.2.CO.1.1
Methods: these are accessors for the
attributes above.
6.1.3.EE EncounterEnvironment class
This is the facade class for
the EncounterEnvironment package.
Attributes:
private EncounterEnvironment
encounterEnvironmentS; //
the singleton Facade object
// [Area name][Area
connection name]["North" | "South" | "East" |
"West" ]:
private String[3] layoutS;
Methods:
public static EncounterEnvironment
getEncounterEnvironment ()
Returns:
encounterEnvironmentS
public static String[3] getLayout()
Returns:
layoutS
The remaining methods are
specified by section 5 of this document.
6.1.3.CH ConnectionHyperlink class
This class encapsulates the
ways to get from areas to adjacent areas. It corresponds to requirement 3.2.CH.
This class implements the MouseListener interface.
Attributes:
private Connection connectionI; // the corresponding connection
Methods:
The only meaningful method
is mouseClick().
6.1.3.TH ThumbnailMap class
This class provides an image
of the areas in the immediate vicinity of the player character.
Currently, the entire game
environment is hard coded.
Methods:
drawMap() draws the thumbnail picture in the Component
parameter provided, scaling itself to the size of the component.
6.2 Data detailed design
There are no data structures
besides those mentioned as part of the classes in section 6.1.