The Yard - Installation + User Guide

THE YARD


INSTALLATION + USER GUIDE

© 2011 | TEAM ONE

1



TABLE OF
CONTENTS


Background

Software
Overview

Source Code

Client Requirements


Installation

Server
Requirements

Deployment

Interface
Customisation

Map Customisation

Authentication Customisation


User Guide

Signing In

Creating
a Game

Joining
a Game

Starting a Game


Gameplay

Objective

User Interface

Game Start

Stations

Tickets

Making a Move

Winning the
Game


BACKGROUND


Software Overview

2


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 under the G
NU 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 7.0.1

with Java SE Development Kit
1.6.0.260
.

The
resulting .
WAR

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


Client Requirements

Playing
The Yard

requires
a minimum screen resolution of 1024x768, as well as an
HTML5 compliant web browser; and

has been tested
using the

following:



Google Chrome 14



Mozilla Firefox 3.6



Microsoft Internet Explorer 9



Opera 11



Safari X


INSTALLATION


Server Requirements

The Yard
has been

tested to run on Apache Tomcat 7.0.14 and Sun JVM 1.6.0, on
a machine running Windows Server 2008 R2.


The recommended hardware requirements are as follows:



x86/x64
2GHz Pentium Dual Core or equivalent



2GB RAM

NOTE
:

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




3





4


Deployment

The Yard

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

which is

included in your Tomcat installation.


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


NOTE
:

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




5




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 progress,
effectively removing users from the game.

Interface
Customisation

6


The Yard
provides limited customisation options
, such as changing fonts, colours
and images. This can be achieve
d 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 editor.

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 ico
ns, 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 beyond 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
.


7


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 separated 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; however they must be subject to
the following
constraints:



Each node must have a unique nodeID and latlong.

<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>

<tax
iEdges>
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.




8




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.



Each node which contains a bus edge mu
st 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.



9


Authentication 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.



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



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



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




NOTE
:

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

as the server wi
ll automatically generate the necessary 2
-
way edges.




10




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
automaticall
y redirected to the
game lobby.

11


Creating
a Game


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





NOTE
:

Game names may onl
y contain alphanumeric characters (A
-
Z, 0
-
9).

If non
-
alphanumeric characters are entered, they are automatically deleted.



12


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.

Starting a Game

NOTE
:

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



13


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.



14



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
wil
l remove the list of players, showing more of the map. The list will remove
automatically once 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.



15



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
following icons:


Indicates Mr. X’s location




Indicates detectives’ locations


䡯睥癥爬 瑨攠t潣慴o潮o潦o䵲M 堠楳i湯n a汷a祳y癩獩扬攠瑯 瑨攠摥瑥捴t癥献s䡩猠s潣慴楯n

楳

潮汹 獨潷渠n渠桩猠s桩牤h瑵牮t 瑨敮 e癥v礠晩晴栠h畲渠u晴敲 瑨t琮 䑥瑥捴a癥猠n敥搠d漠
畳攠eh攠捬略猠
灲p癩摥d

楮i瑨攠
HISTORY

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






16


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.


17



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
man
y of each you have left. The darkened tickets
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, the map will highlight possible stations
which you can move to from your current
position using that tick
et.


18



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.



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.



19


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.

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 the possible stations which you can move to from your current loc
ation.

20



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 location and it will become the next player’s turn.


Winning the G
ame

To capture Mr. X, a detective needs to simply move to the station which he thinks
Mr. X is located. This will result in a win for that detective.


However, if Mr. X manages to evade the detectives for 24 turns, 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.