Project: The Watson Game - Binghamton



Project: The Watson Game

Function: Web Client

Subsystem: Prototype

Author: Steve Dittmar

Date: May 8, 2005

1 Introduction 3

1.1 Goals and objectives 3

1.2 Statement of scope 3

1.3 Software context 3

1.4 Major constraints 3

2 Data design 3

2.1 Internal software data structure 3

2.2 Global data structure 4

2.3 Temporary data structure 4

2.4 Database descriptio 4

3 Architectural and component-level design 4

3.1 Program Structure 4

3.1.1 Architecture diagram 4

3.1.2 Alternatives 4

3.2 Description for Component n 4

3.2.1 Processing narrative (PSPEC) for component n 5

3.2.2 Component n interface description. 5

3.2.3 Component n processing detail 5

3.3 Software Interface Description 5

3.3.1 External machine interfaces 5

3.3.2 External system interfaces 6

3.3.3 Human interface 6

4 User interface design 6

4.1 Description of the user interface 6

4.1.1 Screen images 6

4.1.2 Objects and actions 6

4.2 Interface design rules 6

4.3 Components available 6

4.4 UIDS description 7

5 Restrictions, limitations, and constraints 7

6 Testing Issues 7

6.1 Classes of tests 7

6.2 Expected software response 7

6.3 Performance bounds 7

6.4 Identification of critical components 7

7 Appendices 8

7.1 Requirements traceability matrix 8

7.2 Packaging and installation issues 8

7.3 Design metrics to be used 8

7.4 Supplementary information (as required) 8

SOFTWARE DESIGN SPECIFICATION

Introduction

1 Goals and objectives

The Watson Adventure Game (WAG) is intended to be a demonstration of the abilities and quality of the Computer Science program at Binghamton University. The game attempts to demonstrate this through a first person 3D game that allows players to walk through a replica of the Watson School of Engineering Building. Along the way, the player is presented with challenges in many fields of study that the Watson School provides as well as challenges that college life often initiates. Through this interaction WAG can act as an advertisement for the Computer Science program.

WAG uses a client/server design intended to be played over a network. Localized client playability is available as well and the beginning of a web client has been introduced this semester. Development of WAG will span many semesters before completion and hopefully be a strong recruiter for Binghamton University in future semesters.

2 Statement of scope

A proof-of-concept style prototype web client will be developed that will allow users on many/all platforms to have access to WAG through their web browsers. This prototype aims to demonstrate that a 3D world can be displayed and navigated inside a user’s web browser and that the code written for this can communicate with the server allowing the game to reach a broader audience more easily.

3 Software context

As a recruiting tool for Binghamton University, WAG must be able to reach as many potential students as possible. As it is uncertain which operating systems these potential students may be using, we must include a cross-platform client that will give access to the broadest breadth of people. Continued funding for WAG can more easily be justified with the broadening of the potential user base.

4 Major constraints

Development of the web client will always be difficult since the web based 3D technologies, protocols, and graphics are not a part of the core CS curriculum. With new people working on WAG each semester, the learning curve for most of them will be relatively steep causing a longer development time for these features as compared to the client and server features. The technologies being used, Java3D and Xj3D, are fairly new themselves and will undoubtedly be changing each semester as well, furthering the degree of difficulty.

Data design

1 Internal software data structure

N/A

2 Global data structure

N/A

3 Temporary data structure

N/A

4 Database description

N/A

Architectural and component-level design

1 Program Structure

The architecture chosen relies on internet access through a Java enabled web browser. A user can open up the web client web page, which contains an Applet tag. The applet tag will load the WAGApplet class from within a signed jar file, WAGApplet.jar, once they have granted it permissions, which should be a prompt displayed to them via the web browser. The WAGApplet class will initialize the WAGLoader class, from within the same jar, which will load and display the 3D world in a JFrame to the user.

1 Web Client Architecture diagram

[pic]

2 Alternatives

A few other options exist for creating a web client. One option, which could be easily used, is to use X3D as the world definition language instead of VRML97. X3D is backward compatible with VRML97 and loaders exist in the Xj3D classes to load X3D instead of VRML97. X3D is also a newer language that is more robust, offers consistency across all X3D players, and allows for encryption, and compression of the X3D binaries. This should be done in the future, however a VRML to X3D conversion tool could not be found that appropriately produced an X3D file able to be loaded by the X3D loaders in Xj3D.

Another option is to use a 3rd party VRML viewing application with a web browser plug-in instead of Java3D/Xj3D. This could provide easier navigation and a pre-built user interface around the world, but would result in two layers of controls (one for the world viewer application and one for the actual WAG window). This could be confusing to users, look cluttered, and it could ruin the feel of consistency with colors, images and layouts that exist in the rest of the WAG. Furthermore, by using Java directly we enable the web client to have more power more easily and allow it to integrate with the Java WAG server seamlessly.

Lastly, a third alternative was to use the DirectX version of Java3D instead of the OpenGL version. The OpenGL version was chosen because it was unclear to the team whether non-Microsoft platforms like Linux and Mac have implemented DirectX (or implemented them well), a Microsoft technology, yet. Also, OpenGL is used in the stand alone client so we thought it might feel a little more consistent.

2 Description for WAGApplet & WAGLoader classes

1 Processing narrative (PSPEC) for WAGApplet & WAGLoader classes

The WAGApplet class is initialized via the init method from a browser running it as an Applet. The init method creates a WAGLoader object and calls the WAGLoader constructor giving it the filename of the world to be loaded.

When the WAGLoader class constructor is called, a JFrame is created and setup. The graphics and viewing platform settings are initialized. The setupNavigation method is called which defines the mouse navigation settings which are then added to scene’s definitions. The frame is made visible and the loadFile method is called to load the 3D world. The 3D world loader is initialized and a URL object is created to locate the 3D world file which is then attempted to be loaded. If successful it is added to the scene and the setViewpoint and setLighting methods are called. The setViewpoint method defines the initial viewpoint values and the setLighting method defines the lighting values.

A main method exists primarily for testing purposes, but it should successfully run on its own when outside the applet environment such as from a command line. The main method then initializes a WAGLoader object sending it the supplied filename.

2 WAGApplet & WAGLoader class interface description

The WAGApplet class has only one interface via its init method which is runnable only as an Applet.

WAGLoader’s constructor requires a filename that is the location of the 3D world to be loaded during initialization of the class. The main method requires a 3D world filename as an argument if the class is being accessed outside of the Applet environment.

3 WAGApplet & WAGLoader class processing detail

1 Interface description

2 Algorithmic model (e.g., PDL)

public class WAGWebClient extends Applet {

public void init() {

WAGLoader ld = new WAGLoader("watson_v2.wrl");

}

}

public class WAGLoader extends JFrame{

/**

* Create a new loader

*

* @param initLocation The world to load

*/

public WAGLoader(String filename)

/**

* Setup the navigation system. We use a simple examine behavior

*/

private void setupNavigation()

/**

* Load the given file into the scene.

*

* @param filename The name of the file or the URL to load

*/

private void loadFile(String file)

/**

* Setup the scene's view

*/

private void setViewpoint()

/**

* Setup the worlds lighting. If none is provided in the VRML file then

* we create a simple headlight

*

* @param scene The scene to source the lights from

*/

private void setupLighting(Scene scene)

/**

* A main body for running as an application

*

* @param args The arugment array (requires 3D filename to load)

*/

public static void main(String[] args)

} //End WAGLoader class

3 Restrictions/limitations

Applets require that files be accessed within the same domain as the classes being executed. At this point, all files are located within the same jar. I have read that it is possible to retrieve information and files from other domains if multiple class loaders, one per domain, are used.

I have also read, but cannot confirm or give details, that the Class.getResource() method used to retrieve files from the jar does not work in Netscape and instead you have to use Class.getResourceStream() and grab and assemble the files yourself in the code. I cannot confirm.

4 Local data structures

There are no data structures used in the WAGApplet class, but the major data structures of WAGLoader are:

/** Flag to say if this should be a static load of files */

private static boolean staticLoad = false;

/** The J3D universe to hold everything */

private SimpleUniverse universe;

/** A canvas that can display timing information */

private Canvas3D canvas;

/** The whole scenegraph's root */

private BranchGroup sceneRoot;

/** A transform for examine navigation style */

private TransformGroup examineGroup;

/* A group to hold the loaded scene */

private BranchGroup sceneGroup;

/* A transform for the viewer position */

private TransformGroup vpTransGroup;

/* Status flag to indicate success of file load, init, etc */

private static int status;

// User interface variables

/** A label for the URL field */

private Label urlLabel;

5 Performance issues

There is a bug with ATI drivers for ATI based graphics cards and Java3D OpenGL version. Please see section 6.3.

It is also not recommended to maximize the frame displaying the 3D world if an older machine is being used. One can judge roughly how large they can make their screen by monitoring their CPU usage. Once it reaches near 100% it will make it nearly impossible to navigate.

6 Design constraints

When designing the web based client, consideration was given to try and keep it as simple as possible while also refraining from including anything that might restrict the web client’s ability to emulate the stand alone client. I believe this has been achieved to a satisfactory level with the chosen technologies. The advantages of using Java will be obvious when communication begins between the server and the web client and the look and feel can remain nearly identical with access to almost the entire Java Framework for future development.

4 Software Interface Description

1 External machine interfaces

The machine running the web client will need to have an internet connection available to it in order to be able to download/run the applet and to be able to, eventually, connect/login with the WAG server.

2 External system interfaces

The web client should be able to use Java sockets to communicate with external machines such as the WAG server.

3 Human interface

The current human interface for the web client revolves around navigation. The navigation is setup when the setupNavigation() method of the WAGLoader class is called. Currently, the navigation is defined as follows:

To move up or down on the Y-axis or left or right on the X-axis:

Hold the right mouse button. Then, drag the mouse “up” or “down” the screen to change elevation up/down the Y-axis. Or, drag the mouse left/right to slide left/right on the X-axis.

To move forward or backward on the Z-axis:

Hold the Alt key down and click and hold the left mouse button down. Then, drag the mouse “down” the screen to zoom in on the Z-axis, or push the mouse “up” the screen to zoom out on the Z-axis.

To rotate around the Y-axis or to tilt around the X-axis:

Click and hold the left mouse button down. Drag the mouse “up”/”down” the screen to tilt up/down around the X-axis. Drag the mouse left/right to rotate around the Y-axis.

User interface design

1 Description of the user interface

The user interface of the web client includes the web browser being used to access the applet, the frame drawn to display the 3D world, and the navigational settings available to the user.

1 Screen images

The request to grant permissions to the applet from within the browser:

[pic]

The applet once loaded and initiated (with textures not working yet):

[pic]

The applet WITH textures working (via a workaround hack that is not feasible to ask the user to do):

[pic]

The world as rendered from the appletviewer program (no textures for same reason as above applet w/o textures:

[pic]

The world as rendered from the WAGLoader class by itself, outside of the applet environment, run from command line:

[pic]

2 Objects and actions

See section 3.3.3.

2 Interface design rules

No specific design standards or rules were used while designing this interface as the web client is just a prototype proof of concept at this stage.

3 Components available

No new GUI components were added outside of the Java3D package.

4 UIDS description

Refer to the links for Java3D and Xj3D in section 7.4.

Restrictions, limitations, and constraints

Time was the biggest restriction on this development process as the web client team only had a few weeks to research as much as possible about the otherwise unknown, to the team, topics of 3D on the web and applets. As well, heavy work loads from other courses impacted our ability to devote time to this project.

Another limitation was the quality of documentation online concerning Java3D, Xj3D, and VRML/X3D. Java3D is still not an official release and so the javadoc is not nearly as helpful and inclusive as what can be found for the JFC. This also meant that small obscure bugs were still lingering such as a driver issue that prevents display on ATI graphics cards with hardware acceleration enabled as normal.

Testing Issues

1 Classes of tests

Black box testing was done on the WAGLoader to load the 3D world in a standalone, non-applet, JVM. After this, the jar containing the WAGApplet class was created and referenced in an html file in order to test the code in an Applet format from within a java enabled browser.

2 Expected software response

It was expected that the WAGLoader would successfully load the 3D world including textures and allow navigation via the mouse within it. The same was expected of the test involving the WAGApplet class as referenced from within the html file.

3 Performance bounds

It has been determined that a bug concerning the use of Java3D (OpenGL version) with ATI video drivers does exist in the version of Java3D that was used for this web client. The remedy to this is lowering the machine’s video card acceleration setting to the level indicating that DirectDraw and Direct3D as well as cursor and advanced drawing accelerations will be disabled. [See TODO below for instructions on changing graphics acceleration settings in Windows] Another workaround is simply using a machine with a non-ATI graphics card in it, such as an NVIDIA graphics card.

Also, Memory may become a problem as the world of the WAG grows larger to encompass more than just the 3rd floor of the building. At this point, it is probably best to consider loading one floor at a time such that while in transit in the elevator the game could load the next needed floor.

4 Identification of critical components

When testing, it is imperative that the Java3D and Xj3D packages be installed and visible to the JVM.

It is also important to have the VRML world file in the same directory as the texture files. If the must be in a different directory, the VRML file must be altered to look for the files in another directory instead of just in the same directory.

When testing as an applet, it is important that the applet is granted appropriate Java2 permissions, which implies building the classes into a jar and signing that jar with the jarsigner application and the appropriate keystore and alias.

Appendices

1 Web Client Requirements traceability matrix

|Requirement (by Mantis ID) |Requirement |Location Addressed |

|56 |Develop a web client prototype for WAG possibly by | |

| |using VRML or Java Applet |Section 3 & 4 |

2 Packaging and installation issues

The web client requires some components to be installed on the client side (only) in order to function correctly. Java 1.5+, Java3D 1.3.1 (OpenGL version) and Xj3D Build M10 are the most current stable releases as of May 8th, 2005, and were used in the development of this web client. Java’s JRE and SDK do NOT include Java3D nor Xj3D in them at this point. As of the same date, they can be downloaded at the following locations on the internet:

Java JRE/SDK:



Java3D 1.3.1 (OpenGL)



Xj3D M10 for Windows



It would be ideal if an installer program was created in the next semester to automatically install Java3D and Xj3D in the correct locations as Xj3D is an especially manual and sometimes confusing install (especially if the user has more than one JRE installed).

3 Design metrics to be used

N/A

4 Supplementary information (as required)

1 Links, notes, hints to help future developers

Notes:

-----

To install Xj3D, must execute the installation jar file

(not just double clicking like the usual install programs)

i.e. java -jar Xj3D-M10-Windows.jar

The jar file used in the applet must be signed. You must use the jarsigner to sign it and that requires a certificate/alias in a keystore:

To create a keystore with an alias/certificate:

keytool –genkey –keystore -alias

To sign the jar with jarsigner:

jarsigner –keystore

This will sign the jar for 6 months, after which the certificate will be seen as expired by anyone loading/viewing it. By signing the jar the user will receive a prompt asking them to grant the applet privileges based on the certificate included which guarantees integrity of the applet and gives a small but unofficial level of authenticity unless it is filed with an official certificate company.

The jar file should include in it:

1) The necessary .class files

2) The 3D world file (.wrl if VRML or .x3d if X3D)

3) The texture jpg files used in the world

Textures and the 3D world should be in the root, jar file access sometimes has trouble with directories inside the jar.

Make sure the WAGLoader is defined to be the “main” class if desire to run the class outside of the applet environment, but from within the jar.

Installation of Xj3D: This includes a jar called vecmath that already exists either by installation of Java3D or that is already in the SDK normally. You do not need to overwrite the vecmath jar in the JRE lib/ext with that of Xj3D.

Development Software:

--------------------

Xj3D build M10 for Windows

Java3D 1.3.1 (OpenGL version)

[Both were the most current stable builds at the time]

Sun's NetBeans IDE 4.0 (Build 200412081800)

Java SDK 1.5.0_01 (command line calls ran on Java JRE 1.5.0_02)

Internet Explorer 6.0.2900.2180.xpsp_sp2.gdr.050301-1519

Windows XP Pro SP2

Development Machine:

-------------------

MSI MS-StarForce [NVIDIA] GeForce Ti4200 w/128MB RAM

Intel P4 2.25GHz

768 MB RAM

Implementation Machine:

----------------------

Machine for Tuesday class in room N7 of the Watson Engineering Building

Download URLs:

-------------

Java3D Download (Read closely, don't HAVE to register to D/L)



Xj3D Download



NetBeans Download (Links on right and left of page for current versions)



Information/Helpful URLs:

------------------------

Java3D 1.3.1 JavaDoc



Java3D Homepage



Java3D Community (Installation help, collision detection, etc.)



Xj3D Homepage



Using Xj3D as a loader in Java3D



Xj3D tutorials



NetBeans Homepage



Web3D Consortium (focus mostly on VRML/X3D and Xj3D)



Java3D Overlay Package



2 Issues Requiring Future Solutions

Currently, the rotation navigation is all relative to the starting point (the 0,0,0 coordinate). The farther the user moves from that 0-point the more sensitive the rotations are to movement. Rotation seems to be rendered as if moving on the surface of a sphere centered at the 0-point and the rotation amount by degree, so the further away from the center the more movement a single degree makes. This may not be an issue for tilting up/down since a player wouldn’t normally be given this movement, but it is an issue for rotating left/right around the Y-axis.

Lastly, textures from within the jar are not loading correctly when executing the applet. Possible solutions are somehow making Java3D use the Class.getResource() method to extract it from the jar as is done for the 3D world file, or trying to use multiple class loaders so that multiple domains can be used as sources of information. These are only suggestions and I cannot verify that they are the answer.

5 Mantis Bug Tracker

Mantis was a helpful tool, but I think it lacked some details that could make it nicer. Namely I noticed that assigning a task to someone did not automatically change the status of the bug to “assigned.” I think that it also should have another field or another step in the ladder to represent who owns the bug separate from who is assigned the task of investigating/solving it. I know from experience that often one person might be in charge of a bug while another person is actually doing the work on it and may submit the resulting solutions.

It might also have been nicer if it was more inclusive and more like the real systems used in industry. By that I mean a bug tracking system that is integrated with a versioning system. Programs like CMVC can do this, and I think CVS is a free and open-source alternative to CMVC, also. The learning curve would be a tad steeper, but I think it could be successfully taught on a basic level in a single lecture.

I also think Mantis needs to implement paths and notations for features. In resolving a “feature bug” I had to choose “fixed” as the closest option to anything that implied that the feature was designed and implemented successfully.

6 SubVersion

N/A

-----------------------

Java-enabled Web Browser

(IE, FireFox, etc)



WAGApplet.jar

WAGLoader.class

WAGApplet.class

Signature File (.sf)

Signature Block File (.dsa)

JFrame

User presented with option to grant signed jar permissions

Class will access the world file

WAG Server

Other Player

Other Player

Java sockets over network

Not implemented

VRML World & JPG Textures

3D World will load texture files

................
................

In order to avoid copyright disputes, this page is only a partial summary.

Google Online Preview   Download