The Yard - Installation + User Guide

guitarchanceSoftware and s/w Development

Aug 15, 2012 (4 years and 10 months ago)

513 views








THE YARD


INSTALLATION + USER GUIDE

© 2011 | TEAM ONE

1



TABLE OF CONTENTS


Background

Software Overview












2

Source Code













2

Client Requirements












2


Installation

Server Requirements











3

Deployment













3

Interface
Customisation











5

Map Customisation












6

Authentication Customisation










8


User Guide

Signing In













9

Creating
a Game












10

Joining
a Game












11

Starting a Game












12


Gameplay

Objective













14

User Interface












15

Stations













18

Tickets













18

Controlling the Map












19

Making a Move












19

Winning the Game












20





2


BACKGROUND


Software Overview

The Yard

is based on
Scotland Yard
, a board game available from
Milton Bradley.
It is a web
a
pplication; with the server written in Java, using servlets and JSPs, with an HTML5 compliant
client using JavaScript
and CSS3. The client uses the Google Maps JavaScript API v3.6 and
Open ID authentication to provide a secure login service to users.

The client also uses JQuery 1.6
which contributes to an intuitive user experience.


Source Code

The Yard

is open source un
der the GNU GPL v3 licence.

Source code can be obtained free of

charge at
http://code.google.com/p/team
-
1
-
scotland
-
yard/
. It can be compiled using NetBeans
6.9.1

with Java SE Development Kit
1.6.0
. The resulting .
WAR

file can then be easily deployed
onto Apache Tomcat
(page 4
).


Client Requirements

Playing
The Yard

requires
a minimum screen resolution of 1024x768, as well as
an HTML5
compliant web browser.
The Yard
has been tested
using the

fo
llowing:



Google Chrome 14



Mozilla Firefox
7



Microsoft Internet Explorer 9



Opera 11



Safari
5



NOTE:

Performance may depend on the speed and quality of your network connection, and
can vary between browsers.



3



INSTALLATION


Server Requirements

The Yard
has been tested to run on Apache Tomcat 7.0.14 and Sun
Java SE Development Kit

1.6.0, on a machine running Windows Server 2008 R2.

In practice, any modern computer should
be capable of hosting
The Yard,

with the following software:



Apache Tomcat 6
.9+



Sun Java SE Development Kit 1.6.0+


Deployment

The Yard

is designed to be deployed onto a server running Apache Tomcat
6
. Once the user has
compiled the source code (page 2), the resulting .WAR file can be easily deployed using
Tomcat
Web Application M
anager
,

which is

included in your Tomcat installation.


Click the
Browse
button to bring up a file selection dialog to select the .WAR file.


4




Navigate to the file, select it, then click
Open,
followed by the
Deploy
button. This will upload the
.WAR
file to your Tomcat server.


The Yard

has now be
en

successfully deployed on your Tomcat server. The
Applications
list allows
you to start, stop, reload or undeploy
The Yard.

You are also able to view session information and
expire session which are in prog
ress, effectively removing users from the game.

NOTE:

Please refer to the Apache Tomcat documentation for further information about the use
of
Tomcat Web Application Manger
.



5


Interface
Customisation

The Yard
provides limited customisation options
, such as changing fonts, colours and images.
This can be achieved once deployed by editing
default.css

which is located in the
\
webapps
\
theyard
\

folder of your Tomcat installation. The CSS file may be edited using either
Netbeans or any other text
-
based e
ditor.

Fonts and colours may be changed by editing
the
following CSS parameters:

Images can also be changed, by editing or replacing the images in the
\
webapps
\
theyard
\
images
\

folder of your Tomcat installation. This folder contains images for player icons
, as well as tickets,
stations and all other user interface elements. Altered image files should be small in size to
maintain performance, and must have the same filename as the image which it is intended to
replace.





font
-
family:

Helvetica, sans
-
serif;

font
-
weight
:
bold;

font
-
size:
60pt;

text
-
transform:
uppercase;

text
-
align:
right;

border
-
color:
whitesmoke;

border
-
style:
none;

border
-
width:
0px;

background
-
color:
black;

color:

whitesmoke;



WARNING:

Altering functionality bey
ond this is not recommended; as further alterations may
either break the client at runtime, or render the web app unusable.


NOTE:

When any interface modification is applied, a browser refresh will be required, and in
some cases it may be necessary to
clear the browser’s cache.


6


Map Customisation

The map may also be customised, by editing the
XMLmap.xml

file in the
\
webapps
\
theyard
\

folder
of your Tomcat installation.
The stations on the map are referred to as
nodes

in this file, and
contain the following elements:



nodeID: a unique identifier.



l
atlong: co
-
ordinates on the map where the node is located.



taxiEdges: a comma separated list containing the nodeIDs of nodes connected to it by taxi.



busEdges: a comma separat
ed list containing the nodeIDs of nodes connected to it by bus.



undergroundEdges: a comma separated list containing the nodeIDs

of nodes connected to
it by underground.










It is possible to add as man
y nodes as you like; h
owever they must be subject to the following
constraints:



Each node must have a unique nodeID and latlong.



Each node must contain at least one taxi edge.



Each node which contains an underground edge must also contain at least one bus and at
least one taxi

edge.

<map>

<node>

<nodeID>
0
</nodeID>

<latlong>
-
40.33282719642285, 175.59030113220217</
latlong>

<taxiEdges>
1
</taxiEdges>

<busEdges></busEdges>

<undergroundEdges></undergroundEdges>

</node>

<node>

<nodeID>
1
</nodeID>

<latlong
>
-
40.34489768056728, 175.5772119522095
</latlong>

<taxiEdges>
0
</taxiEdges>

<busEdges>
1
</busEdges>

<undergroundEdges></undergroundEdges>

</node>


</map>


NOTE:

Nodes do not need to be linked to each other (2
-
way edges) in this file;

as the server will automatically generate the necessary 2
-
way edges.



7




Each node which contains a bus edge must also contain at least one taxi edge.



A node may not be connected to itself.



A node’s location must be valid.



A node may not be placed on water.



NOTE:

The Yard

will need to be restarted using the
Tomcat Web Application Manager

before
these changes take effect.


WARNING:

Failure to follow these constraints may cause unexpected server behaviour, and
possibly cause the server to crash.


8


Authentication Customisation

Authenticat
ion is carried out using
openid4j
ava

library
. Other OpenID login services can be
used
by changing the OpenI
D

en
dpoint

in
index.jsp
,
or by adding a link to another sequence.


Any sequence must
have

the following properties:



Fname
: the URL

for the storage of the
Name

attribute for the player
;



Return to url
: Should be

return.jsp
.


The
return

to url

should ensure that the login sequence returns the user to the lobby of the game
and validates the player session
.














9



USER GUIDE


Signing In

The Yard
uses Open ID to authenticate players via Google ID.

B
efore playing a game, each user
is required to

sign in using their Google account.


Clicking the
SIGN IN

button will start the authentication process.


The user is redirected to
Google’s sign in
page, where the user enters their Google
email and password or is invited to sign
up if they do not have one.

Once the user
has signed in, they will be automatically
redirected to the game lobby.



Creating
a Game

10



Once the user has signe
d in using
their Google account,
they are redirected to the game lobby. To
create a new game, simply type a name
for your new game
into the text box, then click
CREATE
.





NOTE:

Game names may only contain alphanumeric characters (A
-
Z, 0
-
9). If
non
-
alphanumeric characters are entered, they are automatically deleted.



11


Joining

a Game


The
GAME LOBBY

shows a list of games which the user can join.

If there are no available games,
the user is prompted to create a new one or wait until a new game becomes available.


Available games are shown in a table, indicating the name of each game followed by indicators
displaying wh
ich players have already joi
ned:




Indicates
Mr
.

X has joined




Indicates detectives who have joined


To join a game, simply select and click a game in from the list.



NOTE:

Games may contain up to 6
PLAYERS
, and can only start after at least 3 players have
joined.


NOTE:

The player who creates a game will automatically play as Mr.

X. All players who join
will play as detectives.


12


Starting a Game

Once the user has either joined or created a new game, they are redirected to

the following
screen:


The game displays
a loading message, and begins loading the map in the background and starts
positioning players and stations.


Once the game has loaded, a list of players is displayed. The game will not begin unless three
players have joined. Clicking the
LOBBY

button will remove you from this game and return you to
the lobby.


WARNING:

The loading sequence may take some time depending on your hardware or
browser. Please do not refresh your browser during this time.



13


Once three or more players have joined, the game can start. The game will start as soon as the
first player, Mr.

X, makes a move. Pressing the
START GAME

button will remove the list of
players, showing more of the map. The list will remove automatically on
ce the first player makes a
move.





WARNING:

Leaving the game once it has started will mean you cannot return. If you are
playing as Mr. X and you leave, the game will be over.



14



GAMEPLAY


Objective

The objective of
The Yard

is for the detectives to catch Mr.

X, and for Mr.

X to evade the
detectives for as long as possible.



The game map contains many different stations; with which players take turns moving between.
Player locations are shown on the map, indicated by the fol
lowing icons:


Indicates Mr. X’s location




Indicates detectives’ locations


䡯eeve爬⁴re ca瑩tn of⁍ ⸠u⁩猠 o琠a汷ay猠v楳ib汥l瑯⁴he dete捴楶e献s䡩猠汯捡瑩tn



on汹⁳ ownn
h楳⁴i楲d⁴u牮Ⱐthen⁥ve特⁦楦瑨⁴u牮⁡晴e爠rhat⸠ae瑥捴楶e猠seed 瑯⁵se⁴he⁣汵e猠
p牯r楤id

楮⁴he
HISTORY

tab, which shows which ticket he has used on each move and lists his previous
known
locations. Detectives need to work together to wor
k out a strategy to locate and capture Mr. X.






15


User Interface


The in
-
game menu is located on the left side of the screen.



EXIT

leaves the game and returns to the lobby.


HELP

displays the in
-
game help menu.



CHAT

displays the Google Chat window.



HISTORY

d
isplays a list of
move
s

which Mr. X has made.




TICKETS

displays a list of all remaining tickets for all other players.


16



The map is the most important element,
which displays all the stations, their

connections, and the locations of players. The station which
contai
ns the player whose turn it is
bounces.

Player icons are located right next to their station.




A list of your tickets. Each ticket shows how many of each
you have left. The darkened tic
kets are not availble for use
at your current position.



To select a ticket, simply click on the ticket you wish to use.
It will slide down indicating it has been selected.


When you select or move your mouse over a ticket

or
station
, the map will highli
ght possible stations which you
can move to from your current position using that tick
et

type
.


17



The current player indicator displays the name of the player whose turn it currently is. It is located
in the bottom right of the screen. If it is your turn,
it will turn red to alert you.




The
TICKETS

tab shows all the remaining tickets for all other
players. This will help you form a strategy about how best to
catch Mr. X, or evade the detectives.















The
HISTORY

tab displays a
list of all the moves which Mr. X
has made so far. This will help
detectiv
es work out the location
of Mr. X.

The moves in which Mr. X is visible are highlighted in red.


NOTE:

The
HISTORY

tab only shows detectives the location of Mr. X on his third turn and
then every fifth turn after that. Mr. X can see his entire history at all times.



18


Stations

There are three types of stations in
The Yard
:




Taxi station

Bus and taxi station

Underground, bus and taxi
station

The type of station
indicates the type of connections it has to other stations near it, and which
tickets you can use to move between stations.


Tickets

There are five different tickets available in
The Yard.
A number indicating how many of each ticket
you have remaining is
shown on the left of the ticket when a game is in progress.




Taxi ticket

Bus ticket

Underground ticket


Detectives may only use these three tickets to move about the map.




Wildcard ticket

Double Move ticket


Mr.

X can use the same tickets as the
Detectives; however he can also use
the Wildcard and
Double move tickets.

He starts with two double move tickets, as well as one Wildcard ticket for
each detective player.


C
ontrolling the Map

The map can be panned by clicking and dragging any po
int of the map. The map can also be
zoomed in by double
-
clicking, or by rolling the scroll wheel of your mouse.


NOTE:

Whenever a detective uses a ticket, that ticket is gained by Mr. X. If a detective runs
out of tickets which are needed to move from his current station, his turn will be skipped.



10

8

4

3

2

19


Clicking the cur
rent player indicator will cent
e
r

the map on the current player, and clicking your
name at the top right of the screen will centre the map to your location. Also, clicking any of the

player names in the
TICKETS

tab will center

the map onto the clicked player.


Making a Move

When it is your turn, click the red
YOUR TURN

box to centre the map on your location. Now roll
your mouse over one of the tickets at the top of the screen to see t
he possible stations which you
can move to from your current location.


Once you have decided on the best station to move to, simply click the ticket you wish to use and
then click the station you wish to move to. The map will automatically update your lo
cation and it
will become the next player’s turn.




NOTE:

Clicking the player turn indicator or Mr. X’s name in the
TICKETS

tab will only re
-
cent
e
r

the map if his location is visible to the detectives.



20


Winning the Game

To capture Mr. X, a detective needs to simply move to the station which he thinks Mr. X is located.
If Mr. X is present at this station, that detective will win the game.


However, if M
r. X manages to evade the detectives for 24 turns

-

or all the detectives run out of
tickets,

he will win the game.


A
message will be displayed showing the winner. You have the option of viewing the map, or
returning to the game lobby.

NOTE:

If Mr. X moves to a station where a detective is located, he will turn himself in and that
detective will win the game.